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方法。

選項類型

內建Option類型如下：

 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的選項。該類別必須至少包含 1 個方法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 ：