slop

Agua sucia

Slop es un analizador de opciones simple con una sintaxis fácil de recordar y una API amigable.

Instalación

 gem install slop

Uso

 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 }

Tenga en cuenta que el bloque que agregamos al indicador --version se ejecutará durante el tiempo de análisis. Por lo tanto, estos bloques deben reservarse para reaccionar inmediatamente ante la presencia de una bandera. Si desea acceder a otras opciones o cambiar valores, consulte la sección "Tipos de opciones personalizadas" a continuación e implemente el método #finish .

Tipos de opciones

Los tipos de opciones integradas son los siguientes:

 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

Puede ver todos los tipos integrados en slop/types.rb . Se aceptan sugerencias o solicitudes de extracción para más tipos.

Uso avanzado

En realidad, este ejemplo es solo para describir cómo funciona la API subyacente. No es necesariamente la mejor manera de hacerlo.

 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 

Argumentos

Es común querer recuperar una serie de argumentos que no fueron procesados ​​por el analizador (es decir, opciones o argumentos consumidos). Puedes hacerlo con el método 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`

Esto es particularmente útil al escribir scripts con ARGF :

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

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

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

matrices

Slop tiene un ArrayOption incorporado para manejar valores de matriz:

 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 desea deshabilitar la división de cadenas incorporada, establezca el delimitador en nil .

Tipos de opciones personalizadas

Slop utiliza clases de tipos de opciones para cada nueva opción agregada. Su valor predeterminado es NullOption . Cuando escribes o.array Slop busca una opción llamada Slop::ArrayOption . Esta clase debe contener al menos 1 método, call . Este método se ejecuta en el momento del análisis y el valor de retorno de este método se utiliza para el valor de la opción. Podemos usar esto para crear tipos de opciones personalizadas:

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

Las opciones personalizadas también pueden implementar un método finish . Este método por defecto no hace nada, pero se ejecuta una vez que se han analizado todas las opciones. Esto nos permite regresar y mutar el estado sin tener que depender de que las opciones se analicen en un orden particular. He aquí un ejemplo:

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

Errores

Slop generará errores para lo siguiente:

• Una opción utilizada sin argumento cuando espera uno: Slop::MissingArgument
• Se utiliza una opción que Slop no conoce: Slop::UnknownOption
• Una opción marcada como required cuando no se proporciona: Slop::MissingRequiredOption
• Una opción marcada como validate_types , con un argumento que no coincide con su tipo (es decir, bla para integer ): Slop::InvalidOptionValue

Estos errores se heredan de Slop::Error , por lo que puedes rescatarlos todos. Alternativamente, puedes suprimir estos errores con la opción de configuración 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 

Tipos de validación

De forma predeterminada, Slop no valida si un argumento es un valor válido para una opción determinada; en cambio, si la opción tiene un valor predeterminado, se utilizará sobre el argumento no válido proporcionado. Para que los tipos (como integer y float ) validen e indiquen que el valor proporcionado no es válido, se puede proporcionar una opción adicional al argumento en sí o a su conjunto de opciones:

 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) 

Ayuda para imprimir

El valor de retorno de Slop.parse es Slop::Result que proporciona una buena cadena de ayuda para mostrar sus opciones. Simplemente puts opts o llama 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

Producción:

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

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

Este método toma un valor prefix opcional, cuyo valor predeterminado es " " * 4 :

 puts opts.to_s(prefix: "  ")

Se ocupará de alinear sus descripciones de acuerdo con el indicador de opción más largo.

A continuación se muestra un ejemplo de cómo agregar su propia opción de ayuda:

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

Comandos

Slop ya no tiene soporte integrado para subcomandos de estilo git.