slop

Pente

Slop est un analyseur d'options simple avec une syntaxe facile à retenir et une API conviviale.

Installation

 gem install slop

Usage

 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 }

Notez que le bloc que nous avons ajouté à l'indicateur --version sera exécuté pendant le temps d'analyse. Ces blocs doivent donc être réservés pour réagir immédiatement à la présence d'un drapeau. Si vous souhaitez accéder à d'autres options ou modifier des valeurs, consultez la section « Types d'options personnalisées » ci-dessous et implémentez la méthode #finish .

Types d'options

Les types d'options intégrés sont les suivants :

 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

Vous pouvez voir tous les types intégrés dans slop/types.rb . Les suggestions ou demandes de tirage pour plus de types sont les bienvenues.

Utilisation avancée

Cet exemple sert simplement à décrire le fonctionnement de l'API sous-jacente. Ce n'est pas nécessairement la meilleure façon de procéder.

 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 

Arguments

Il est courant de vouloir récupérer un tableau d'arguments qui n'ont pas été traités par l'analyseur (c'est-à-dire des options ou des arguments consommés). Vous pouvez le faire avec la méthode 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`

Ceci est particulièrement utile lors de l'écriture de scripts avec ARGF :

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

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

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

Tableaux

Slop a un ArrayOption intégré pour gérer les valeurs du tableau :

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

Si vous souhaitez désactiver le fractionnement de chaîne intégré, définissez le délimiteur sur nil .

Types d'options personnalisées

Slop utilise des classes de types d'options pour chaque nouvelle option ajoutée. Ils sont par défaut NullOption . Lorsque vous tapez o.array Slop recherche une option appelée Slop::ArrayOption . Cette classe doit contenir au moins 1 méthode, call . Cette méthode est exécutée au moment de l'analyse et la valeur de retour de cette méthode est utilisée pour la valeur de l'option. Nous pouvons l'utiliser pour créer des types d'options personnalisés :

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

Les options personnalisées peuvent également implémenter une méthode finish . Cette méthode par défaut ne fait rien, mais elle est exécutée une fois que toutes les options ont été analysées. Cela nous permet de revenir en arrière et de muter l'état sans avoir à nous fier aux options analysées dans un ordre particulier. Voici un exemple :

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

Erreurs

Slop générera des erreurs pour les éléments suivants :

• Une option utilisée sans argument lorsqu'elle en attend un : Slop::MissingArgument
• Une option utilisée que Slop ne connaît pas : Slop::UnknownOption
• Une option marquée comme required lorsqu'elle n'est pas fournie : Slop::MissingRequiredOption
• Une option marquée comme validate_types , avec un argument qui ne correspond pas à son type (c'est-à-dire bla pour integer ) : Slop::InvalidOptionValue

Ces erreurs héritent de Slop::Error , vous pouvez donc toutes les récupérer. Vous pouvez également supprimer ces erreurs avec l'option de configuration 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 

Validation des types

Par défaut, Slop ne valide pas si un argument est une valeur valide pour une option donnée ; au lieu de cela, si l'option a une valeur par défaut, elle sera utilisée sur l'argument non valide fourni. Afin que les types (tels que integer et float ) valident et indiquent que la valeur fournie n'est pas valide, une option supplémentaire peut être fournie soit à l'argument lui-même, soit à son jeu d'options :

 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) 

Aide à l'impression

La valeur de retour de Slop.parse est un Slop::Result qui fournit une belle chaîne d'aide pour afficher vos options. Il suffit puts opts ou d'appeler 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

Sortir:

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

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

Cette méthode prend une valeur prefix facultative, qui est par défaut " " * 4 :

 puts opts.to_s(prefix: "  ")

Il s'agira d'aligner vos descriptions en fonction de l'indicateur d'option le plus long.

Voici un exemple d'ajout de votre propre option d'aide :

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

Commandes

Slop ne prend plus en charge les sous-commandes de style git.