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 

ข้อโต้แย้ง

เป็นเรื่องปกติที่เราต้องการดึงอาร์เรย์ของอาร์กิวเมนต์ที่ไม่ได้ถูกประมวลผลโดย parser (เช่น ตัวเลือกหรืออาร์กิวเมนต์ที่ใช้ไป) คุณสามารถทำได้โดยใช้วิธี 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 :

 puts opts.to_s(prefix: "  ")

มันจะจัดการกับการจัดแนวคำอธิบายของคุณตามแฟล็กตัวเลือกที่ยาวที่สุด

นี่คือตัวอย่างการเพิ่มตัวเลือกความช่วยเหลือของคุณเอง:

 o . on '--help' do
  puts o
  exit
end 

คำสั่ง

Slop ไม่รองรับคำสั่งย่อยสไตล์ git อีกต่อไป