cri 2.15.1 → 2.15.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13bfd2fd90ec81e8bcc39c154881b0e54ac05696fce5a237cf17d3204b543c9c
-  data.tar.gz: d14b7481ce82280b035fd0f20a78e62c417e47efe545d24bebf5302b1668fb3d
+  metadata.gz: 4ffb3eac4152f6f8450a1cafad2a319cc3946420de5c5a2d03d2330ac05714a9
+  data.tar.gz: 914f27475515b0fcad6023ec2ab70ad08b3245e0a4e24ed07130f1c472ee46b5
 SHA512:
-  metadata.gz: 06ba0a5ab7632765e40bcf3b3245418f90e414b106fad162cbd4b59e50af3152bfed637da0fb9ed3b074922dcecb8e78d6d7501a849a6763d980be3030aee7b4
-  data.tar.gz: 273ef37de868f8b546d084b48073a8f13d67b7fb57f765b4764bf4305c5992e863b46e016e45fbf4888b48291dc017a1892d6394a564374402a0466cafdb1e41
+  metadata.gz: a1f0c7fe961d41ac672b11364037fc2f05c3263966b662aa8d439300812c2a7a5f5a932f7f213cf4d28cd96d43e9b159c32badb696d33adf050aad70a7473a27
+  data.tar.gz: 88a32db01b1c5b2c0c5b0e3967f779f1e99f6ef355f586b6dd94a7b05b0c06cb7873539002af644f45a0575d8f4574dd5d4ff76796a2cc57896ba0481012c86a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cri (2.15.1)
+    cri (2.15.2)
       colored (~> 1.2)
 
 GEM
@@ -25,7 +25,7 @@ GEM
     powerpack (0.1.2)
     rainbow (3.0.0)
     rake (12.3.1)
-    rubocop (0.58.2)
+    rubocop (0.59.2)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
       parser (>= 2.5, != 2.5.1.1)
@@ -42,7 +42,7 @@ GEM
     term-ansicolor (1.6.0)
       tins (~> 1.0)
     thor (0.19.4)
-    tins (1.16.3)
+    tins (1.17.0)
     unicode-display_width (1.4.0)
     yard (0.9.16)
 
@@ -59,4 +59,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   1.16.4
+   1.16.2

data/NEWS.md

@@ -1,5 +1,11 @@
 # Cri News
 
+## 2.15.2
+
+Fixes:
+
+* Fixed option propagation for two levels or more (#85, #86)
+
 ## 2.15.1
 
 Fixes:

data/README.md

@@ -105,32 +105,109 @@ flag   nil, :more,  'do even more stuff'
 option :s,  :stuff, 'specify stuff to do', argument: :required
 ```
 
-Options can be defined using the following methods:
-
-* `Cri::CommandDSL#option` or `Cri::CommandDSL#opt` (include an `argument` parameter: `:required` or `:optional` that specifies if the option requires or allows an argument)
-* `Cri::CommandDSL#flag` (implies no arguments passed to option)
-
-The following _deprecated_ methods can also be used to define options:
-
-* `Cri::CommandDSL#required` (implies an option that requires an argument -- deprecated because `#required` suggests that the option is required, wich is incorrect; the _argument_ is required.)
-* `Cri::CommandDSL#optional` (implies an option that can optionally include an argument -- deprecated because `#optional` looks too similar to `#option`.)
-
-All these methods take these arguments:
+The most generic way of definition an option is using either `#option` or `#opt`. It takes the following arguments:
 
 1. a short option name
 2. a long option name
 3. a description
 4. optional extra parameters
+    * `argument:` (default: `:forbidden`)
+    * `transform:`
+    * `default:`
+    * `multiple:` (default: `false`)
+5. optionally, a block
+
+In more detail:
+
+* The short option name is a symbol containing one character, to be used in single-dash options, e.g. `:f` (corresponds to `-f`). The long option name is a symbol containing a string, to be used in double-dash options, e.g. `:force` (corresponds to `--force`). Either the short or the long option name can be nil, but not both.
+
+* The description is a short, one-line text that shows up in the command’s help. For example, the `-v`/`--version` option might have the description `show version information and quit`.
+
+* The extra parameters, `argument:`, `multiple:`, `default:`, and `transform:`, are described in the sections below.
+
+* The block, if given, will be executed when the option is found. The arguments to the block are the option value (`true` in case the option does not have an argument) and the command.
+
+There are several convenience methods that are alternatives to `#option`/`#opt`:
+
+* `#flag` sets `argument:` to `:forbidden`
+* (**deprecated**) `#required` sets `argument:` to `:required` -- deprecated because `#required` suggests that the option is required, wich is incorrect; the _argument_ is required.)
+* (**deprecated**) `#optional` sets `argument:` to `:optional` -- deprecated because `#optional` looks too similar to `#option`.
+
+#### Forbidden, required, and optional arguments (`argument:`)
+
+The `:argument` parameter can be set to `:forbidden`, `:required`, or `:optional`.
+
+*   `:forbidden` means that when the option is present, the value will be set to `true`, and `false` otherwise. For example:
+
+    ```ruby
+    option :f, :force, 'push with force', argument: :forbidden
+
+    run do |opts, args, cmd|
+      puts "Force? #{opts[:force]}"
+    end
+    ```
+
+    ```sh
+    % ./push mypackage.zip
+    Force? false
+
+    % ./push --force mypackage.zip
+    Force? true
+    ```
+
+    `:argument` is set to `:forbidden` by default.
+
+*   `:required` means that the option must be followed by an argument, which will then be treated as the value for the option. It does not mean that the option itself is required. For example:
 
-Either the short or the long form can be nil, but not both (because that
-would not make any sense). In the example above, the `--more` option has no
-short form.
+    ```ruby
+    option :o, :output, 'specify output file', argument: :required
+    option :f, :fast, 'fetch faster', argument: :forbidden
 
-Each of the above methods also take a block, which will be executed when the
-option is found. The arguments to the block are the option value (`true` in
-case the option does not have an argument) and the command.
+    run do |opts, args, cmd|
+      puts "Output file: #{opts[:output]}"
+    end
+    ```
+
+    ```sh
+    % ./fetch http://example.com/source.zip
+    Output file: nil
+
+    % ./fetch --output example.zip http://example.com/source.zip
+    Output file: example.zip
+
+    % ./fetch http://example.com/source.zip --output
+    fetch: option requires an argument -- output
+
+    % ./fetch --output --fast http://example.com/source.zip
+    fetch: option requires an argument -- output
+    ```
+
+*   `:optional` means that the option can be followed by an argument. If it is, then the argument is treated as the value for the option; if it isn’t, the value for the option will be `true`. For example:
+
+    ```ruby
+    option :o, :output, 'specify output file', argument: :optional
+    option :f, :fast, 'fetch faster', argument: :forbidden
+
+    run do |opts, args, cmd|
+      puts "Output file: #{opts[:output]}"
+    end
+    ```
+
+    ```sh
+    % ./fetch http://example.com/source.zip
+    Output file: nil
+
+    % ./fetch --output example.zip http://example.com/source.zip
+    Output file: example.zip
 
-#### Transforming options
+    % ./fetch http://example.com/source.zip --output
+    Output file: true
+
+    % ./fetch --output --fast http://example.com/source.zip
+    Output file: true
+    ```
+
+#### Transforming options (`transform:`)
 
 The `:transform` parameter specifies how the value should be transformed. It takes any object that responds to `#call`:
 
@@ -166,7 +243,7 @@ Default values are not transformed:
 option :p, :port, 'set port', argument: :required, default: 8080, transform: PortTransformer.new
 ```
 
-#### Options with default values
+#### Options with default values (`default:`)
 
 The `:default` parameter sets the option value that will be used if the option is passed without an argument or isn't passed at all:
 
@@ -182,10 +259,9 @@ OPTIONS
     -a --animal[=<value>]      add animal (default: giraffe)
 ```
 
-#### Multivalued options
+#### Multivalued options (`multiple:`)
 
-Each of these four methods take a `:multiple` parameter. When set to true, multiple
-option valus are accepted, and the option values will be stored in an array.
+The `:multiple` parameter allows an option to be specified more than once on the command line. When set to `true`, multiple option valus are accepted, and the option values will be stored in an array.
 
 For example, to parse the command line options string `-o foo.txt -o bar.txt`
 into an array, so that `options[:output]` contains `[ 'foo.txt', 'bar.txt' ]`,
@@ -234,7 +310,7 @@ that is passed to your `run` block will be empty and the `args` array will be
 
 ### Argument parsing
 
-Cri also supports parsing arguments, outside of options. To define the
+Cri supports parsing arguments, as well as parsing options. To define the
 parameters of a command, use `#param`, which takes a symbol containing the name
 of the parameter. For example:
 
@@ -257,7 +333,46 @@ end
 The command in this example has one parameter named `filename`. This means that
 the command takes a single argument, named `filename`.
 
-If no parameters are specified, Cri performs no argument parsing or validation; any number of arguments is allowed. To explicitly specify that a command has no parameters, use `#no_params`:
+As with options, parameter definitions take `transform:`, which can be used for transforming and validating arguments:
+
+```ruby
+param :port, transform: method(:Integer)
+```
+
+(*Why the distinction between argument and parameter?* A parameter is a name, e.g. `filename`, while an argument is a value for a parameter, e.g. `kitten.jpg`.)
+
+### Allowing arbitrary arguments
+
+If no parameters are specified, Cri performs no argument parsing or validation;
+any number of arguments is allowed.
+
+```ruby
+command = Cri::Command.define do
+  name        'publish'
+  usage       'publish [filename...]'
+  summary     'publishes the given file(s)'
+  description 'This command does a lot of stuff, but not option parsing.'
+
+  flag :q, :quick, 'publish quicker'
+
+  run do |opts, args, cmd|
+    args.each do |arg|
+      puts "Publishing #{arg}…"
+    end
+  end
+end
+```
+
+```bash
+% my-tool publish foo.zip bar.zip
+Publishing foo.zip…
+Publishing bar.zip…
+%
+```
+
+### Forbidding any arguments
+
+To explicitly specify that a command has no parameters, use `#no_params`:
 
 ```ruby
 name        'reset'
@@ -281,14 +396,6 @@ Resetting…
 
 A future version of Cri will likely make `#no_params` the default behavior.
 
-As with options, parameter definitions take `transform:`, which can be used for transforming and validating arguments:
-
-```ruby
-param :port, transform: method(:Integer)
-```
-
-(*Why the distinction between argument and parameter?* A parameter is a name, e.g. `filename`, while an argument is a value for a parameter, e.g. `kitten.jpg`.)
-
 ### The run block
 
 The last part of the command defines the execution itself:
@@ -308,10 +415,43 @@ The +Cri::CommandDSL#run+ method takes a block with the actual code to
 execute. This block takes three arguments: the options, any arguments passed
 to the command, and the command itself.
 
-Instead of defining a run block, it is possible to declare a class, the
-_command runner_ class (`Cri::CommandRunner`) that will perform the actual
-execution of the command. This makes it easier to break up large run blocks
-into manageable pieces.
+### The command runner
+
+Instead of defining a run block, it is possible to declare a class, the _command runner_ class that will perform the actual execution of the command. This makes it easier to break up large run blocks into manageable pieces.
+
+```ruby
+name 'push'
+option :f, :force, 'force'
+param :filename
+
+class MyRunner < Cri::CommandRunner
+  def run
+    puts "Pushing #{arguments[:filename]}…"
+    puts "… with force!" if options[:force]
+  end
+end
+
+runner MyRunner
+```
+
+To create a command runner, subclass `Cri::CommandRunner`, and define a `#run` method with no params. Inside the `#run` block, you can access `options` and `arguments`. Lastly, to connect the command to the command runner, call `#runner` with the class of the command runner.
+
+Here is an example interaction with the example command, defined above:
+
+```
+% push
+push: incorrect number of arguments given: expected 1, but got 0
+
+% push a
+Pushing a…
+
+% push -f
+push: incorrect number of arguments given: expected 1, but got 0
+
+% push -f a
+Pushing a…
+… with force!
+```
 
 ### Subcommands
 

data/lib/cri/command.rb

@@ -311,7 +311,7 @@ module Cri
         return if subcommand.nil?
 
         # Run
-        subcommand.run(opts_and_args_after_subcmd, opts_before_subcmd, hard_exit: hard_exit)
+        subcommand.run(opts_and_args_after_subcmd, parent_opts.merge(opts_before_subcmd), hard_exit: hard_exit)
       end
     rescue CriExitException => e
       exit(e.error? ? 1 : 0) if hard_exit

data/lib/cri/version.rb

@@ -2,5 +2,5 @@
 
 module Cri
   # The current Cri version.
-  VERSION = '2.15.1'
+  VERSION = '2.15.2'
 end

data/test/test_command.rb

@@ -858,5 +858,42 @@ module Cri
       assert_equal [], lines(out)
       assert_equal [], lines(err)
     end
+
+    def test_propagate_options_two_levels_down
+      cmd_a = Cri::Command.define do
+        name 'a'
+        flag :t, :test, 'test'
+      end
+
+      cmd_b = cmd_a.define_command('b') do
+      end
+
+      cmd_b.define_command('c') do
+        run do |opts, _args|
+          puts "test? #{opts[:test].inspect}!"
+        end
+      end
+
+      # test -t last
+      out, err = capture_io_while do
+        cmd_a.run(%w[b c -t])
+      end
+      assert_equal ['test? true!'], lines(out)
+      assert_equal [], lines(err)
+
+      # test -t mid
+      out, err = capture_io_while do
+        cmd_a.run(%w[b -t c])
+      end
+      assert_equal ['test? true!'], lines(out)
+      assert_equal [], lines(err)
+
+      # test -t first
+      out, err = capture_io_while do
+        cmd_a.run(%w[-t b c])
+      end
+      assert_equal ['test? true!'], lines(out)
+      assert_equal [], lines(err)
+    end
   end
 end

data/test/test_parser.rb

@@ -455,6 +455,7 @@ module Cri
       port = Class.new do
         def call(str)
           raise unless str.is_a?(String)
+
           Integer(str)
         end
       end.new

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cri
 version: !ruby/object:Gem::Version
-  version: 2.15.1
+  version: 2.15.2
 platform: ruby
 authors:
 - Denis Defreyne
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-31 00:00:00.000000000 Z
+date: 2018-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colored