slop Скачать - slop Скачать исходный код

помои

Slop — это простой анализатор опций с легко запоминающимся синтаксисом и дружественным API.

Установка

 gem install slop

Использование

 opts = Slop . parse do | o |
  o . string '-h' , '--host' , 'a hostname'
  o . integer '--port' , 'custom port' , default : 80
  o . string '-l' , '--login' , required : true
  o . symbol '-m' , '--method' , default : :get
  o . bool '-v' , '--verbose' , 'enable verbose mode'
  o . bool '-q' , '--quiet' , 'suppress output (quiet mode)'
  o . bool '-c' , '--check-ssl-certificate' , 'check SSL certificate for host'
  o . bool '-k' , '--use-keychain' , 'store passphrase in OS keychain'
  o . on '--version' , 'print the version' do
    puts Slop :: VERSION
    exit
  end
end

ARGV #=> -v --login alice --host 192.168.0.1 -m post --check-ssl-certificate --use-keychain false

opts [ :host ]         #=> 192.168.0.1
opts [ :login ]        #=> alice
opts [ :method ]       #=> :post
opts [ :use_keychain ] #=> false

# We can also check if a flag was passed (this has no bearing on the options default value):
opts . use_keychain?          #=> true
opts . verbose?               #=> true
opts . quiet?                 #=> false
opts . check_ssl_certificate? #=> true

opts . to_hash  #=> { host: "192.168.0.1", port: 80, login: "alice", method: :post, verbose: true, quiet: false, check_ssl_certificate: true }

Обратите внимание, что блок, который мы добавили в флаг --version будет выполнен во время анализа. Поэтому эти блоки должны быть зарезервированы для немедленного реагирования на наличие флага. Если вы хотите получить доступ к другим параметрам или изменить значения, ознакомьтесь с разделом «Типы пользовательских параметров» ниже и реализуйте метод #finish .

Типы опционов

Встроенные типы опций следующие:

 o . string  #=> Slop::StringOption, expects an argument
o . bool    #=> Slop::BoolOption, argument optional, aliased to BooleanOption
o . integer #=> Slop::IntegerOption, expects an argument, aliased to IntOption
o . float   #=> Slop::FloatOption, expects an argument
o . array   #=> Slop::ArrayOption, expects an argument
o . regexp  #=> Slop::RegexpOption, expects an argument
o . symbol  #=> Slop::SymbolOption, expects an argument
o . null    #=> Slop::NullOption, no argument and ignored from `to_hash`
o . on      #=> alias for o.null

Вы можете увидеть все встроенные типы в slop/types.rb . Предложения или запросы на включение дополнительных типов приветствуются.

Расширенное использование

Этот пример на самом деле предназначен для описания того, как работает базовый API. Это не обязательно лучший способ сделать это.

 opts = Slop :: Options . new
opts . banner = "usage: connect [options] ..."
opts . separator ""
opts . separator "Connection options:"
opts . string "-H" , "--hostname" , "a hostname"
opts . int "-p" , "--port" , "a port" , default : 80
opts . separator ""
opts . separator "Extra options:"
opts . array "--files" , "a list of files to import"
opts . bool "-v" , "--verbose" , "enable verbose mode" , default : true

parser = Slop :: Parser . new ( opts )
result = parser . parse ( [ "--hostname" , "192.168.0.1" , "--no-verbose" ] )

result . to_hash #=> { hostname: "192.168.0.1", port: 80,
                 #     files: [], verbose: false }

puts opts # prints out help

Аргументы

Обычно требуется получить массив аргументов, которые не были обработаны анализатором (т.е. параметры или использованные аргументы). Вы можете сделать это с помощью метода Result#arguments :

 args = %w( connect --host google.com GET )
opts = Slop . parse args do | o |
  o . string '--host'
end

p opts . arguments #=> ["connect", "GET"] # also aliased to `args`

Это особенно полезно при написании сценариев с использованием ARGF :

 opts = Slop . parse do | blah |
  # ...
end

# make sure sloptions aren't consumed by ARGF
ARGV . replace opts . arguments

ARGF . each { | line |
  # ...
}

Массивы

Slop имеет встроенный ArrayOption для обработки значений массива:

 opts = Slop . parse do | o |
  # the delimiter defaults to ','
  o . array '--files' , 'a list of files' , delimiter : ','
end

# Both of these will return o[:files] as ["foo.txt", "bar.rb"]:
# --files foo.txt,bar.rb
# --files foo.txt --files bar.rb
# This will return o[:files] as []:
# --files ""

Если вы хотите отключить встроенное разделение строк, установите разделитель равным nil .

Типы пользовательских опций

Slop использует классы типов опций для каждой новой добавленной опции. По умолчанию они имеют значение NullOption . Когда вы вводите o.array , Slop ищет опцию Slop::ArrayOption . Этот класс должен содержать хотя бы один метод — call . Этот метод выполняется во время анализа, и возвращаемое значение этого метода используется в качестве значения параметра. Мы можем использовать это для создания пользовательских типов опций:

 module Slop
  class PathOption < Option
    def call ( value )
      Pathname . new ( value )
    end
  end
end

opts = Slop . parse %w( --path ~/ ) do | o |
  o . path '--path' , 'a custom path name'
end

p opts [ :path ] #=> #<Pathname:~/>

Пользовательские параметры также могут реализовывать метод finish . По умолчанию этот метод ничего не делает, но он выполняется после анализа всех параметров. Это позволяет нам вернуться назад и изменить состояние, не полагаясь на анализ параметров в определенном порядке. Вот пример:

 module Slop
  class FilesOption < ArrayOption
    def finish ( opts )
      if opts . expand?
        self . value = value . map { | f | File . expand_path ( f ) }
      end
    end
  end
end

opts = Slop . parse %w( --files foo.txt,bar.rb -e ) do | o |
  o . files '--files' , 'an array of files'
  o . bool '-e' , '--expand' , 'if used, list of files will be expanded'
end

p opts [ :files ] #=> ["/full/path/foo.txt", "/full/path/bar.rb"]

Ошибки

Slop вызовет ошибки для следующего:

Опция, используемая без аргумента, когда он ожидается: Slop::MissingArgument
Используемая опция, о которой Slop не знает: Slop::UnknownOption
Опция, помеченная как required , если она не указана: Slop::MissingRequiredOption
Опция, помеченная как validate_types , с аргументом, который не соответствует ее типу (т.е. bla для integer ): Slop::InvalidOptionValue

Эти ошибки наследуются от Slop::Error , поэтому вы можете исправить их все. В качестве альтернативы вы можете подавить эти ошибки с помощью параметра конфигурации suppress_errors :

 opts = Slop . parse suppress_errors : true do
  o . string '-name'
end

# or per option:

opts = Slop . parse do
  o . string '-host' , suppress_errors : true
  o . int '-port'
end

Проверка типов

По умолчанию Slop не проверяет, является ли аргумент допустимым значением для данной опции; вместо этого, если параметр имеет значение по умолчанию, он будет использоваться вместо предоставленного недопустимого аргумента. Чтобы типы (такие как integer и float ) проверяли и указывали, что предоставленное значение недействительно, дополнительная опция может быть предоставлена либо самому аргументу, либо его набору опций:

 opts = Slop :: Options . new
opts . int "-p" , "--port" , "a port" , default : 80 , validate_types : true

parser = Slop :: Parser . new ( opts )
result = parser . parse ( [ "--port" , "bla" ] )
# invalid value for -p, --port (Slop::InvalidOptionValue)

# Or to the option set...
opts = Slop :: Options . new ( validate_types : true )
opts . int "-p" , "--port" , "a port" , default : 80

parser = Slop :: Parser . new ( opts )
result = parser . parse ( [ "--port" , "bla" ] )
# invalid value for -p, --port (Slop::InvalidOptionValue)

Справка по печати

Возвращаемое значение Slop.parse — это Slop::Result , который предоставляет удобную справочную строку для отображения ваших параметров. Просто puts opts или вызываем opts.to_s :

 opts = Slop . parse do | o |
  o . string '-h' , '--host' , 'hostname'
  o . int '-p' , '--port' , 'port (default: 80)' , default : 80
  o . string '--username'
  o . separator ''
  o . separator 'other options:'
  o . bool '--quiet' , 'suppress output'
  o . on '-v' , '--version' do
    puts "1.1.1"
  end
end

puts opts

Выход:

 % ruby run.rb
usage: run.rb [options]
    -h, --host     hostname
    -p, --port     port (default: 80)
    --username

other options:
    --quiet        suppress output
    -v, --version

Этот метод принимает необязательное значение prefix , которое по умолчанию равно " " * 4 :