cl 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 8e6ef1ee5a1de5a6db0abe39ce38d2e2cce9acd93ea525b456fdb3a06b80022f
-  data.tar.gz: 7fb5f6eaf119649982149be1ac54a367ed85188e63acfb85d4ed422e72620e3b
+SHA1:
+  metadata.gz: d68ba1674ee398202a474abb83387fb296847aad
+  data.tar.gz: 3f410b5991158c25bc3ec7688fd9a86c56b7e11f
 SHA512:
-  metadata.gz: d8e3e6454c83f588383b713af70cf43d69f7914349eabcb07586045e45aa2ee44cae7f7be7ad86438800213270791fdae8047e52f7ec971fa36217956a093cf7
-  data.tar.gz: ebbdafe93266703989144983f919fa79325c5797c1cfe831a83b5a8e3c7a04d5042e7b2c3ab1ea5553319c105d1d916e6b8e2ab70ef711000be2e861d95fbd2d
+  metadata.gz: 26fac7251c6eead9ed449d3f5c1dfb61794eb1f6c7e008f069ac973afd912d84d93b75abaa84ca20f6f69d6642cc00694be28469b36ce8ce0a1f3d044ecb9c3d
+  data.tar.gz: 993d729a5b9fd4ae131d257601a93b57483ac6f6ba12e46409cffeda230e2a8573b1b9c22edc93392e6c7224de94f979962479fdb23d4b27df32796d84e2b685

data/CHANGELOG.md

@@ -19,6 +19,7 @@
 * Add `opt '--one STR', format: /.+/`
 * Add `opt '--one STR', enum: ['one', /\w+/]`
 * Add `opt '--one STR', downcase: true`
+* Add `opt '--one STR', upcase: true`
 * Add `opt '--one STR', internal: true`, hide internal options from help output
 * Add `opt '--one STR', example: 'foo'`
 * Add `opt '--one STR', negate: %w(skip)`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cl (0.1.28)
+    cl (1.0.0)
       regstry (~> 1.0.3)
 
 GEM

data/NOTES.md

@@ -13,3 +13,7 @@ x add yard docs
 - refactor Help::Cmd and Table so that everything goes into one big table
 - Ui classes really need to write error messages to stderr, not stdout
 - make sure option aliases define accessors and predicates (see examples/readme/alias)
+
+
+- validate and normalize type
+- validate that there can only be one arg splat

data/README.md

@@ -1,4 +1,4 @@
-# Cl [![Build Status](https://travis-ci.org/svenfuchs/cl.svg?branch=master)](https://travis-ci.com/svenfuchs/cl) [![Code Climate](https://codeclimate.com/github/svenfuchs/cl.png)](https://codeclimate.com/github/svenfuchs/cl) [![Coverage Status](https://coveralls.io/repos/github/svenfuchs/cl/badge.svg?branch=master)](https://coveralls.io/github/svenfuchs/cl?branch=master) [![Rubydocs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/svenfuchs/cl) [![Gem Version](https://img.shields.io/gem/v/cl)](http://rubygems.org/gems/cl)
+# Cl [![Build Status](https://travis-ci.org/svenfuchs/cl.svg?branch=master)](https://travis-ci.org/svenfuchs/cl) [![Code Climate](https://api.codeclimate.com/v1/badges/870e448eb8162d3e1ed7/maintainability)](https://codeclimate.com/github/svenfuchs/cl) [![Code Coverage](https://coveralls.io/repos/github/svenfuchs/cl/badge.svg?branch=master)](https://coveralls.io/github/svenfuchs/cl?branch=master) [![Gem Version](https://img.shields.io/gem/v/cl?cache=2019-08-10)](http://rubygems.org/gems/cl) [![Rubydocs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/svenfuchs/cl)
 
 OptionParser based CLI support for rapid CLI development in an object-oriented
 context.
@@ -12,6 +12,11 @@ after `gem --help`).
 
 Further documentation is available on [rubydoc.info](https://www.rubydoc.info/github/svenfuchs/cl)
 
+Examples in this README are included from [examples/readme](https://github.com/svenfuchs/cl/tree/master/examples/readme).
+More examples can be found in [examples](https://github.com/svenfuchs/cl/tree/master/examples).
+All examples are guaranteed to be up to date by the way of being [verified](https://github.com/svenfuchs/cl/blob/master/.travis.yml#L14)
+on CI.
+
 ## Table of Contents
 
 * [Basic Usage](#basic-usage)
@@ -46,7 +51,6 @@ Further documentation is available on [rubydoc.info](https://www.rubydoc.info/gi
 ## Basic Usage
 
 ```ruby
-# lib/cli/owners/add.rb
 module Owners
   class Add < Cl::Cmd
     summary 'Add one or more owners to an existing owner group'
@@ -58,48 +62,58 @@ module Owners
       [...]
     str
 
-    args :owners
+    args :owner
 
     opt '-t', '--to TO', 'An existing owner group'
 
     def run
-      # add owners as listed in `owners` to the group given in
-      # `to`, as well as `opts[:to]`.
+      # implement adding the owner as given in `owner` (as well as `args`)
+      # to the group given in `to` (as well as `opts[:to]`).
+      p owner: owner, to: to, to?: to?, args: args, opts: opts
     end
   end
 end
 
-# bin/owners
-Cl.new('owners').run(ARGV)
-```
-
-Running this, e.g. using `bin/owners add one,two --to group` will instantiate the
-class `Owners::Add`, and call the method `run` on it.
-
-Help output:
-
-```txt
-Usage: owners add [owners] [options]
-
-Summary:
+# Running this, e.g. using `bin/owners add one,two --to group` will instantiate the
+# class `Owners::Add`, and call the method `run` on it.
 
-  Add one or more owners to an existing owner group
-
-Description:
-
-  Use this command to add one or more owners to an existing
-  owner group.
+# e.g. bin/owners
+#
+# args normally would be ARGV
+args = %w(add one --to group)
 
-  These will be visible in [...]
+Cl.new('owners').run(args)
 
-Arguments:
+# Output:
+#
+#   {:owner=>"one", :to=>"group", :to?=>true, :args=>["one"], :opts=>{:to=>"group"}}
 
-  owners          type: string
+Cl.new('owners').run(%w(add --help))
 
-Options:
+# Output:
+#
+#   Usage: owners add [owner] [options]
+#
+#   Summary:
+#
+#     Add one or more owners to an existing owner group
+#
+#   Description:
+#
+#     Use this command to add one or more owners to an existing
+#     owner group.
+#
+#     [...]
+#
+#   Arguments:
+#
+#     owner           type: string
+#
+#   Options:
+#
+#     -t --to TO      An existing owner group (type: string)
+#        --help       Get help on this command
 
-  -t --to TO      An existing owner group (type: string, required: true)
-     --help       Get help on this command (type: flag)
 ```
 
 ### Command Registry
@@ -112,20 +126,17 @@ to decouple looking up command classes from their Ruby namespace.
 For example:
 
 ```ruby
-module One
-  class Cmd < Cl::Cmd
-    register :one
+module Cmd
+  class One < Cl::Cmd
   end
-end
 
-module Two
-  class Cmd < Cl::Cmd
-    register :two
+  class Two < Cl::Cmd
   end
 end
 
-Cl::Cmd[:one] # => One::Cmd
-Cl::Cmd[:two] # => Two::Cmd
+p Cl::Cmd[:one] # => Cmd::One
+p Cl::Cmd[:two] # => Cmd::Two
+
 ```
 
 Commands auto register themselves with the underscored name of the last part of
@@ -158,10 +169,10 @@ would recognize and run the following commands:
 
 ```
 $ bin/run one something else
-# instantiates One, passing the args array `["something", "else"]`, and calls `run`
+# instantiates One, passing the args array `["something", "else"]`, and calls the instance method `run`
 
-$ bin/run two something else
-# instantiates One, passing an empty args arry `[]`, and calls `run`
+$ bin/run two
+# instantiates Two, passing an empty args arry `[]`, and calls the instance method `run`
 ```
 
 The default runner also supports nested namespaces, and checks for command classes
@@ -171,47 +182,61 @@ with keys separated by colons. For instance:
 module Git
   class Pull < Cl::Cmd
     register :'git:pull'
-  end
-end
 
-module Git
-  class Push < Cl::Cmd
-    register :'git:push'
+    def run
+      p cmd: registry_key, args: args
+    end
   end
 end
-```
 
-With these classes registered (and assuming the executable that calls `Cl` is
-`bin/git`) the default runner would recognize and run the following commands:
+# With this class registered (and assuming the executable that calls `Cl` is
+# `bin/run`) the default runner would recognize and run it:
+#
+# $ bin/run git:pull master # instantiates Git::Pull, and passes ["master"] as args
+# $ bin/run git pull master # does the same
 
-```
-$ bin/git pull:master # instantiates Git::Pull, and passes ["master"] as args
-$ bin/git pull master # does the same
+Cl.new('run').run(%w(git:pull master))
+# Output:
+#
+#   {:cmd=>:"git:pull", :args=>["master"]}
+
+Cl.new('run').run(%w(git pull master))
+# Output:
+#
+#   {:cmd=>:"git:pull", :args=>["master"]}
 
-$ bin/git push:master # instantiates Git::Push, and passes ["master"] as args
-$ bin/git push master # does the same
 ```
 
 Runners are registered on the module `Cl::Runner`. It is possible to register custom
 runners, and use them by passing the option `runner` to `Cl.new`:
 
-```
-# in bin/run
-Cli.new('run', runner: :custom).run(ARGV)
-
-# anywhere in your library
-class Runner
-  Cl::Runner.register :custom, self
-
-  def initialize(ctx, args)
-    # ...
-  end
+```ruby
+module Git
+  class Pull < Cl::Cmd
+    register :'git:pull'
 
-  def run
-    const = identify_cmd_class_from_args
-    const.new(ctx, args).run
+    def run
+      p cmd: registry_key, args: args
+    end
   end
 end
+
+# With this class registered (and assuming the executable that calls `Cl` is
+# `bin/run`) the default runner would recognize and run it:
+#
+# $ bin/run git:pull master # instantiates Git::Pull, and passes ["master"] as args
+# $ bin/run git pull master # does the same
+
+Cl.new('run').run(%w(git:pull master))
+# Output:
+#
+#   {:cmd=>:"git:pull", :args=>["master"]}
+
+Cl.new('run').run(%w(git pull master))
+# Output:
+#
+#   {:cmd=>:"git:pull", :args=>["master"]}
+
 ```
 
 See `Cl::Runner::Default` for more details.
@@ -237,7 +262,7 @@ Commands are classes that are derived from the base class `Cl::Cmd`.
 
 The description, summary, and examples are used in the help output.
 
-```
+```ruby
 module Owners
   class Add < Cl::Cmd
     summary 'Add one or more owners to an existing owner group'
@@ -258,6 +283,36 @@ module Owners
     str
   end
 end
+
+Cl.new('owners').run(%w(add --help))
+
+# Output:
+#
+#   Usage: owners add [options]
+#
+#   Summary:
+#
+#     Add one or more owners to an existing owner group
+#
+#   Description:
+#
+#     Use this command to add one or more owners to an existing
+#     owner group.
+#
+#   Options:
+#
+#     --help      Get help on this command
+#
+#   Examples:
+#
+#     Adding a single user to the group admins:
+#
+#       owners add user --to admins
+#
+#     Adding a several users at once:
+#
+#       owners add one two three --to admins
+
 ```
 
 #### Abstract
@@ -831,12 +886,14 @@ end
 
 Cl.new('owners').run(%w(add --help))
 
-# Usage: owners add [options]
+# Output:
 #
-# Options:
+#   Usage: owners add [options]
 #
-#   --to GROUP      type: string, note: needs to be a group
-#   --help          Get help on this command
+#   Options:
+#
+#     --to GROUP      type: string, note: needs to be a group
+#     --help          Get help on this command
 
 ```
 

data/examples/README.md

@@ -0,0 +1,22 @@
+# Cl Examples
+
+This directory contains examples for using `cl`.
+
+Examples are executable, so you can try them out and experiment with them. E.g.:
+
+```
+git clone https://github.com/svenfuchs/cl.git /tmp/cl
+cd /tmp/cl
+examples/gem
+```
+
+Examples are generated and verified by running:
+
+```
+bundle exec bin/examples
+```
+
+This command runs on [on Travis CI](https://github.com/svenfuchs/cl/blob/master/.travis.yml#L14)
+in order to guarantee that all examples are up to date,
+but also can be run in order to add or update examples.
+

data/examples/_src/readme/basic.erb.rb

@@ -0,0 +1,70 @@
+<%= run sq(<<-'rb')
+  require 'cl'
+
+  # e.g. lib/owners/add.rb
+  module Owners
+    class Add < Cl::Cmd
+      summary 'Add one or more owners to an existing owner group'
+
+      description <<~str
+        Use this command to add one or more owners to an existing
+        owner group.
+
+        [...]
+      str
+
+      args :owner
+
+      opt '-t', '--to TO', 'An existing owner group'
+
+      def run
+        # implement adding the owner as given in `owner` (as well as `args`)
+        # to the group given in `to` (as well as `opts[:to]`).
+        p owner: owner, to: to, to?: to?, args: args, opts: opts
+      end
+    end
+  end
+  rb
+-%>
+
+# Running this, e.g. using `bin/owners add one,two --to group` will instantiate the
+# class `Owners::Add`, and call the method `run` on it.
+
+<%= run sq(<<-'rb')
+  # e.g. bin/owners
+  #
+  # args normally would be ARGV
+  args = %w(add one --to group)
+
+  Cl.new('owners').run(args)
+  rb
+-%>
+
+<%= out '{:owner=>"one", :to=>"group", :to?=>true, :args=>["one"], :opts=>{:to=>"group"}}' %>
+
+<%= run "Cl.new('owners').run(%w(add --help))" %>
+
+<%= out sq(<<-'str')
+  Usage: owners add [owner] [options]
+
+  Summary:
+
+    Add one or more owners to an existing owner group
+
+  Description:
+
+    Use this command to add one or more owners to an existing
+    owner group.
+
+    [...]
+
+  Arguments:
+
+    owner           type: string
+
+  Options:
+
+    -t --to TO      An existing owner group (type: string)
+       --help       Get help on this command
+  str
+%>

data/examples/_src/readme/description.erb.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+<%= run sq(<<-'rb')
+  require 'cl'
+
+  module Owners
+    class Add < Cl::Cmd
+      summary 'Add one or more owners to an existing owner group'
+
+      description <<~str
+        Use this command to add one or more owners to an existing
+        owner group.
+      str
+
+      examples <<~str
+        Adding a single user to the group admins:
+
+          owners add user --to admins
+
+        Adding a several users at once:
+
+          owners add one two three --to admins
+      str
+    end
+  end
+  rb
+-%>
+
+<%= run "Cl.new('owners').run(%w(add --help))" %>
+
+<%= out sq(<<-'str')
+  Usage: owners add [options]
+
+  Summary:
+
+    Add one or more owners to an existing owner group
+
+  Description:
+
+    Use this command to add one or more owners to an existing
+    owner group.
+
+  Options:
+
+    --help      Get help on this command
+
+  Examples:
+
+    Adding a single user to the group admins:
+
+      owners add user --to admins
+
+    Adding a several users at once:
+
+      owners add one two three --to admins
+  str
+%>

data/examples/_src/readme/registry.erb.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+<%= run sq(<<-'rb')
+  module Cmd
+    class One < Cl::Cmd
+    end
+
+    class Two < Cl::Cmd
+    end
+  end
+  rb
+-%>
+
+<%= run 'p Cl::Cmd[:one]' %> <%= out 'Cmd::One', short: true %>
+<%= run 'p Cl::Cmd[:two]' %> <%= out 'Cmd::Two', short: true %>

data/examples/_src/readme/runner.erb.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+<%= run sq(<<-'rb')
+  module Git
+    class Pull < Cl::Cmd
+      register :'git:pull'
+
+      def run
+        p cmd: registry_key, args: args
+      end
+    end
+  end
+  rb
+-%>
+
+# With this class registered (and assuming the executable that calls `Cl` is
+# `bin/run`) the default runner would recognize and run it:
+#
+# $ bin/run git:pull master # instantiates Git::Pull, and passes ["master"] as args
+# $ bin/run git pull master # does the same
+
+<%= run "Cl.new('run').run(%w(git:pull master))" %>
+<%= out '{:cmd=>:"git:pull", :args=>["master"]}' %>
+
+<%= run "Cl.new('run').run(%w(git pull master))" %>
+<%= out '{:cmd=>:"git:pull", :args=>["master"]}' %>

data/examples/_src/readme/runner_custom.erb.rb

@@ -0,0 +1,25 @@
+<%= run sq(<<-'rb')
+  # anywhere in your library
+
+  require 'cl'
+
+  class Runner
+    Cl::Runner.register :custom, self
+
+    def initialize(ctx, args)
+      # ...
+    end
+
+    def run
+      const = identify_cmd_class_from_args
+      const.new(ctx, args).run
+    end
+  end
+  rb
+-%>
+
+# in bin/run
+Cl.new('run', runner: :custom).run(ARGV)
+
+<% run "p Cl.new('run', runner: :custom).runner([]).class" %>
+<% out 'Runner' %>