slop

منحدر

Slop هو محلل خيارات بسيط مع بناء جملة سهل التذكر وواجهة برمجة تطبيقات سهلة الاستخدام.

تثبيت

 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 . نرحب بالاقتراحات أو طلبات السحب لمزيد من الأنواع.

الاستخدام المتقدم

هذا المثال هو في الواقع مجرد وصف لكيفية عمل واجهة برمجة التطبيقات الأساسية. إنها ليست بالضرورة أفضل طريقة للقيام بذلك.

 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 :

 puts opts.to_s(prefix: "  ")

سوف يتعامل مع محاذاة الأوصاف الخاصة بك وفقًا لعلامة الخيار الأطول.

فيما يلي مثال لإضافة خيار المساعدة الخاص بك:

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

الأوامر

لم يعد Slop يدعم الأوامر الفرعية ذات نمط git.