cri 2.10.1 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f6c63bf18c481c1f172a325ebba098b530bf687c
-  data.tar.gz: 0a82eb5bcfa077de4f3df0b6d62a315b5af10803
+SHA256:
+  metadata.gz: cc4daab3e3ba10d21d0545fab6a7ab99dc8ad125b3ca3acd3691326b164ba4ca
+  data.tar.gz: 686ac2c2324893fbaabc650fe42858355f643eea90af8b6acff986207fb183ca
 SHA512:
-  metadata.gz: 412df43765fd893929df701fcaea57d44f80d04ef29203e7f578d877b53cd9f090961c7718e2fdc8df9c210ec00e3f31f4006dfa6b688bbff55bdcfeadc5658b
-  data.tar.gz: d2358da6e375295b76cb5bfc8a68114665710c6e191ec616b5946dcc2d186518622723ede0143117265e23a757e32ba546fc88f5b7ae5da66c805d73f77f77f5
+  metadata.gz: 0cc8b4aadbde4cae477feb33d2578287d23dc77aea4700dae5115ee06d19e1234ba5625db2f3cd053bfa941e425cc50d0ac0c6836ffcb1b807b92f3aa3055470
+  data.tar.gz: 55c6c0dd76ab840f11f73568de6fa5105dfd934b4602d1fb55bc9f506d4bd001b9bb890110fee0b68bc23ca6824547f33b757855fda126bca27dd72f656d6164

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec

data/Gemfile.lock

@@ -1,50 +1,51 @@
 PATH
   remote: .
   specs:
-    cri (2.10.1)
+    cri (2.11.0)
       colored (~> 1.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    asciidoctor (1.5.6.1)
-    ast (2.3.0)
+    asciidoctor (1.5.7.1)
+    ast (2.4.0)
     colored (1.2)
-    coveralls (0.8.21)
+    coveralls (0.8.22)
       json (>= 1.8, < 3)
-      simplecov (~> 0.14.1)
+      simplecov (~> 0.16.1)
       term-ansicolor (~> 1.3)
       thor (~> 0.19.4)
       tins (~> 1.6)
-    docile (1.1.5)
+    docile (1.3.1)
+    jaro_winkler (1.5.1)
     json (2.1.0)
-    minitest (5.10.3)
-    parallel (1.12.0)
-    parser (2.4.0.0)
-      ast (~> 2.2)
-    powerpack (0.1.1)
-    rainbow (2.2.2)
-      rake
-    rake (12.2.1)
-    rubocop (0.51.0)
+    minitest (5.11.3)
+    parallel (1.12.1)
+    parser (2.5.1.2)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    rainbow (3.0.0)
+    rake (12.3.1)
+    rubocop (0.58.2)
+      jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
-      parser (>= 2.3.3.1, < 3.0)
+      parser (>= 2.5, != 2.5.1.1)
       powerpack (~> 0.1)
-      rainbow (>= 2.2.2, < 3.0)
+      rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (~> 1.0, >= 1.0.1)
     ruby-progressbar (1.9.0)
-    simplecov (0.14.1)
-      docile (~> 1.1.0)
+    simplecov (0.16.1)
+      docile (~> 1.1)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
     term-ansicolor (1.6.0)
       tins (~> 1.0)
     thor (0.19.4)
-    tins (1.15.0)
-    unicode-display_width (1.3.0)
-    yard (0.9.9)
+    tins (1.16.3)
+    unicode-display_width (1.4.0)
+    yard (0.9.15)
 
 PLATFORMS
   ruby
@@ -60,4 +61,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   1.15.4
+   1.16.3

data/NEWS.md

@@ -1,6 +1,12 @@
 Cri News
 ========
 
+## 2.11.0
+
+Features:
+
+* Added support for transforming option values (#68)
+
 ## 2.10.1
 
 Fixes:

data/{README.adoc → README.md}

@@ -1,19 +1,19 @@
-= Cri =
+# Cri
 
-link:http://rubygems.org/gems/cri[image:http://img.shields.io/gem/v/cri.svg[]]
-link:https://travis-ci.org/ddfreyne/cri[image:http://img.shields.io/travis/ddfreyne/cri.svg[]]
-link:https://coveralls.io/r/ddfreyne/cri[image:http://img.shields.io/coveralls/ddfreyne/cri.svg[]]
-link:https://codeclimate.com/github/ddfreyne/cri[image:http://img.shields.io/codeclimate/github/ddfreyne/cri.svg[]]
-link:http://inch-ci.org/github/ddfreyne/cri/[image:http://inch-ci.org/github/ddfreyne/cri.svg[]]
+[![Gem](http://img.shields.io/gem/v/cri.svg)](http://rubygems.org/gems/cri)
+[![Travis](http://img.shields.io/travis/ddfreyne/cri.svg)](https://travis-ci.org/ddfreyne/cri)
+[![Coveralls](http://img.shields.io/coveralls/ddfreyne/cri.svg)](https://coveralls.io/r/ddfreyne/cri)
+[![Codeclimate](http://img.shields.io/codeclimate/github/ddfreyne/cri.svg)](https://codeclimate.com/github/ddfreyne/cri)
+[![Inch](http://inch-ci.org/github/ddfreyne/cri.svg)](http://inch-ci.org/github/ddfreyne/cri/)
 
 Cri is a library for building easy-to-use command-line tools with support for
 nested commands.
 
-== Requirements ==
+## Requirements
 
-Cri requires Ruby 2.1 or newer.
+Cri requires Ruby 2.3 or newer.
 
-== Usage ==
+## Usage
 
 The central concept in Cri is the _command_, which has option definitions as
 well as code for actually executing itself. In Cri, the command-line tool
@@ -21,8 +21,7 @@ itself is a command as well.
 
 Here’s a sample command definition:
 
-[source,ruby]
---------------------------------------------------------------------------------
+```ruby
 command = Cri::Command.define do
   name        'dostuff'
   usage       'dostuff [options]'
@@ -46,21 +45,20 @@ command = Cri::Command.define do
     end
   end
 end
---------------------------------------------------------------------------------
+```
 
 To run this command, invoke the `#run` method with the raw arguments. For
 example, for a root command (the command-line tool itself), the command could
 be called like this:
 
-[source,ruby]
---------------------------------------------------------------------------------
+```ruby
 command.run(ARGV)
---------------------------------------------------------------------------------
+```
 
 Each command has automatically generated help. This help can be printed using
 `Cri::Command#help`; something like this will be shown:
 
---------------------------------------------------------------------------------
+```
 usage: dostuff [options]
 
 does stuff
@@ -72,20 +70,19 @@ options:
     -h --help      show help for this command
        --more      do even more stuff
     -s --stuff     specify stuff to do
---------------------------------------------------------------------------------
+```
 
-=== General command metadata ===
+### General command metadata
 
 Let’s disect the command definition and start with the first five lines:
 
-[source,ruby]
---------------------------------------------------------------------------------
+```ruby
 name        'dostuff'
 usage       'dostuff [options]'
 aliases     :ds, :stuff
 summary     'does stuff'
 description 'This command does a lot of stuff. I really mean a lot.'
---------------------------------------------------------------------------------
+```
 
 These lines of the command definition specify the name of the command (or the
 command-line tool, if the command is the root command), the usage, a list of
@@ -95,31 +92,33 @@ the supercommand, because the latter will be automatically prepended.
 
 Aliases don’t make sense for root commands, but for subcommands they do.
 
-=== Command-line options ===
+### Command-line options
 
 The next few lines contain the command’s option definitions:
 
-[source,ruby]
---------------------------------------------------------------------------------
+```ruby
 flag   :h,  :help,  'show help for this command' do |value, cmd|
   puts cmd.help
   exit 0
 end
 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`
+* `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)
-* `Cri::CommandDSL#required` (implies required argument)
-* `Cri::CommandDSL#optional` (implies optional argument)
+
+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:
 
-1. a short option
-2. a long option
+1. a short option name
+2. a long option name
 3. a description
 4. optional extra parameters
 
@@ -128,27 +127,62 @@ would not make any sense). In the example above, the `--more` option has no
 short form.
 
 Each of the above methods also take a block, which will be executed when the
-option is found. The argument to the block are the option value (`true` in
+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.
 
-==== Options with default values ====
+#### Transforming options
+
+The `:transform` parameter specifies how the value should be transformed. It takes any object that responds to `#call`:
+
+```ruby
+option :p, :port, 'set port', argument: :required,
+  transform: -> (x) { Integer(x) }
+```
+
+The following example uses `#Integer` to transform a string into an integer:
+
+```ruby
+option :p, :port, 'set port', argument: :required, transform: method(:Integer)
+```
+
+The following example uses a custom object to perform transformation, as well as validation:
+
+```ruby
+class PortTransformer
+  def call(str)
+    raise ArgumentError unless str.is_a?(String)
+    Integer(str).tap do |int|
+      raise unless (0x0001..0xffff).include?(int)
+    end
+  end
+end
+
+option :p, :port, 'set port', argument: :required, transform: PortTransformer.new
+```
+
+Default values are not transformed:
+
+```ruby
+option :p, :port, 'set port', argument: :required, default: 8080, transform: PortTransformer.new
+```
+
+#### Options with default values
 
-The `:default` parameter sets the option value that will be used if no explicit value is provided:
+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:
 
-[source,ruby]
---------------------------------------------------------------------------------
-optional :a, :animal, 'add animal', default: 'giraffe'
---------------------------------------------------------------------------------
+```ruby
+option :a, :animal, 'add animal', default: 'giraffe', argument: :optional
+```
 
 In the example above, the value for the `--animal` option will be the string
 `"giraffe"`, unless otherwise specified:
 
---------------------------------------------------------------------------------
+```
 OPTIONS
     -a --animal[=<value>]      add animal (default: giraffe)
---------------------------------------------------------------------------------
+```
 
-==== Multivalued options ====
+#### Multivalued options
 
 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.
@@ -157,10 +191,9 @@ 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' ]`,
 you can use an option definition like this:
 
-[source,ruby]
---------------------------------------------------------------------------------
+```ruby
 option :o, :output, 'specify output paths', argument: :required, multiple: true
---------------------------------------------------------------------------------
+```
 
 This can also be used for flags (options without arguments). In this case, the
 length of the options array is relevant.
@@ -169,19 +202,17 @@ For example, you can allow setting the verbosity level using `-v -v -v`. The
 value of `options[:verbose].size` would then be the verbosity level (three in
 this example). The option definition would then look like this:
 
-[source,ruby]
---------------------------------------------------------------------------------
+```ruby
 flag :v, :verbose, 'be verbose (use up to three times)', multiple: true
---------------------------------------------------------------------------------
+```
 
-==== Skipping option parsing ====
+#### Skipping option parsing
 
 If you want to skip option parsing for your command or subcommand, you can add
 the `skip_option_parsing` method to your command definition and everything on your
 command line after the command name will be passed to your command as arguments.
 
-[source,ruby]
--------------------------------------------------------------------------------
+```ruby
 command = Cri::Command.define do
   name        'dostuff'
   usage       'dostuff [args]'
@@ -195,18 +226,17 @@ command = Cri::Command.define do
     puts args.inspect
   end
 end
--------------------------------------------------------------------------------
+```
 
 When executing this command with `dostuff --some=value -f yes`, the `opts` hash
 that is passed to your `run` block will be empty and the `args` array will be
 `["--some=value", "-f", "yes"]`.
 
-=== The run block ===
+### The run block
 
 The last part of the command defines the execution itself:
 
-[source,ruby]
---------------------------------------------------------------------------------
+```ruby
 run do |opts, args, cmd|
   stuff = opts.fetch(:stuff, 'generic stuff')
   puts "Doing #{stuff}!"
@@ -215,7 +245,7 @@ run do |opts, args, cmd|
     puts 'Doing it even more!'
   end
 end
---------------------------------------------------------------------------------
+```
 
 The +Cri::CommandDSL#run+ method takes a block with the actual code to
 execute. This block takes three arguments: the options, any arguments passed
@@ -226,7 +256,7 @@ _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.
 
-=== Subcommands ===
+### Subcommands
 
 Commands can have subcommands. For example, the `git` command-line tool would be
 represented by a command that has subcommands named `commit`, `add`, and so on.
@@ -236,27 +266,38 @@ dispatched to a subcommand (or none, if no subcommand is found).
 To add a command as a subcommand to another command, use the
 `Cri::Command#add_command` method, like this:
 
-[source,ruby]
---------------------------------------------------------------------------------
+```ruby
 root_cmd.add_command(cmd_add)
 root_cmd.add_command(cmd_commit)
-root.cmd.add_command(cmd_init)
---------------------------------------------------------------------------------
+root_cmd.add_command(cmd_init)
+```
+
+You can also define a subcommand on the fly without creating a class first
+using `Cri::Command#define_command` (name can be skipped if you set it inside
+the block instead):
+
+```ruby
+root_cmd.define_command('add') do
+  # option ...
+  run do |opts, args, cmd|
+    # ...
+  end
+end
+```
 
 You can specify a default subcommand. This subcommand will be executed when the
 command has subcommands, and no subcommands are otherwise explicitly specified:
 
-[source,ruby]
---------------------------------------------------------------------------------
+```ruby
 default_subcommand 'compile'
---------------------------------------------------------------------------------
+```
 
-== Contributors ==
+## Contributors
 
 * Bart Mesuere
 * Ken Coar
 * Tim Sharpe
 * Toon Willems
 
-Thanks for Lee “injekt” Jarvis for link:https://github.com/injekt/slop[Slop],
+Thanks for Lee “injekt” Jarvis for [Slop](https://github.com/injekt/slop),
 which has inspired the design of Cri 2.0.

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # encoing: utf-8
 
 require 'rake/testtask'

data/cri.gemspec

@@ -1,5 +1,6 @@
-$LOAD_PATH.unshift(File.expand_path('../lib/', __FILE__))
-require 'cri/version'
+# frozen_string_literal: true
+
+require_relative 'lib/cri/version'
 
 Gem::Specification.new do |s|
   s.name        = 'cri'
@@ -15,12 +16,12 @@ Gem::Specification.new do |s|
   s.files = Dir['[A-Z]*'] + Dir['{lib,test}/**/*'] + ['cri.gemspec']
   s.require_paths = ['lib']
 
-  s.required_ruby_version = '~> 2.1'
+  s.required_ruby_version = '~> 2.3'
 
   s.add_dependency('colored', '~> 1.2')
 
   s.add_development_dependency('bundler', '~> 1.6')
 
-  s.rdoc_options     = ['--main', 'README.adoc']
-  s.extra_rdoc_files = ['LICENSE', 'README.adoc', 'NEWS.md']
+  s.rdoc_options     = ['--main', 'README.md']
+  s.extra_rdoc_files = ['LICENSE', 'README.md', 'NEWS.md']
 end