slop Unduh - slop Unduh kode sumber

Air kotor

Slop adalah parser opsi sederhana dengan sintaksis yang mudah diingat dan API yang ramah.

Instalasi

 gem install slop

Penggunaan

 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 }

Perhatikan bahwa blok yang telah kita tambahkan ke flag --version akan dieksekusi selama waktu parse. Oleh karena itu blok-blok ini sebaiknya dicadangkan untuk segera bereaksi terhadap keberadaan sebuah bendera. Jika Anda ingin mengakses opsi lain atau mengubah nilai, lihat bagian "Jenis opsi khusus" di bawah dan terapkan metode #finish .

Jenis opsi

Jenis Opsi bawaan adalah sebagai berikut:

 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

Anda dapat melihat semua tipe bawaan di slop/types.rb . Saran atau permintaan tarik untuk tipe lainnya dipersilakan.

Penggunaan Tingkat Lanjut

Contoh ini sebenarnya hanya untuk menjelaskan cara kerja API yang mendasarinya. Ini belum tentu merupakan cara terbaik untuk melakukannya.

 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

Argumen

Biasanya ingin mengambil array argumen yang tidak diproses oleh parser (yaitu opsi atau argumen yang digunakan). Anda dapat melakukannya dengan metode 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`

Ini sangat berguna ketika menulis skrip dengan ARGF :

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

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

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

Array

Slop memiliki ArrayOption bawaan untuk menangani nilai array:

 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 ""

Jika Anda ingin menonaktifkan pemisahan string bawaan, setel pembatas ke nil .

Jenis opsi khusus

Slop menggunakan kelas tipe opsi untuk setiap opsi baru yang ditambahkan. Mereka default ke NullOption . Saat Anda mengetik o.array Slop mencari opsi yang disebut Slop::ArrayOption . Kelas ini harus berisi setidaknya 1 metode, call . Metode ini dijalankan pada waktu parse, dan nilai kembalian metode ini digunakan untuk nilai opsi. Kita dapat menggunakan ini untuk membuat tipe opsi khusus:

 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:~/>

Opsi khusus juga dapat menerapkan metode finish . Metode ini secara default tidak melakukan apa pun, tetapi dijalankan setelah semua opsi diuraikan. Hal ini memungkinkan kita untuk kembali dan mengubah keadaan tanpa harus bergantung pada opsi yang diurai dalam urutan tertentu. Berikut ini contohnya:

 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"]

Kesalahan

Slop akan memunculkan kesalahan sebagai berikut:

Opsi yang digunakan tanpa argumen ketika mengharapkannya: Slop::MissingArgument
Opsi yang digunakan yang tidak diketahui Slop: Slop::UnknownOption
Opsi yang ditandai sebagai required bila tidak disediakan: Slop::MissingRequiredOption
Opsi yang ditandai sebagai validate_types , dengan argumen yang tidak cocok dengan tipenya (yaitu bla untuk integer ): Slop::InvalidOptionValue

Kesalahan ini diwarisi dari Slop::Error , sehingga Anda dapat menyelamatkan semuanya. Alternatifnya, Anda dapat menyembunyikan kesalahan ini dengan opsi konfigurasi 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

Jenis Validasi

Secara default, Slop tidak memvalidasi apakah suatu argumen merupakan nilai yang valid untuk opsi tertentu; sebaliknya, jika opsi memiliki nilai default, opsi tersebut akan digunakan pada argumen yang diberikan tidak valid. Agar tipe (seperti integer dan float ) memvalidasi dan menunjukkan bahwa nilai yang diberikan tidak valid, opsi tambahan dapat diberikan pada argumen itu sendiri, atau rangkaian opsinya:

 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)

Bantuan pencetakan

Nilai kembalian Slop.parse adalah Slop::Result yang menyediakan string bantuan yang bagus untuk menampilkan opsi Anda. Cukup puts opts atau hubungi 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

Keluaran:

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

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

Metode ini mengambil nilai prefix opsional, yang defaultnya adalah " " * 4 :