ark-cli 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 40d1e78d63af56864533187b51ab27bdf514cdcd
-  data.tar.gz: 7cc02dba83f021e537314dfccc03bc77592e39c4
+  metadata.gz: a54741976deb70204c112ab5ee3ec996463ddaf6
+  data.tar.gz: bf135aed0b692a6d591dff1160773a83b896ad32
 SHA512:
-  metadata.gz: b80df1a67863e975e5d46633e9128a6fd6392a2bd1233e0b905e09d5b1158c347185ec12987561a6cc16229a8fa947dbacf1b7e3fd7a501e191e248280d7329b
-  data.tar.gz: c710c95aed57880c6a3f5cf01331f859ab766ef10850950466567725b1a14c36718ba0226ed08b30479fb86f78367df3b59ce75be726d265190e16906d92eccf
+  metadata.gz: b84c3e4562701df554ab07d821140ff4cb02c765c6aebe8d633f4a54f30e595b8d5f7eda3bf0c3b6046f2c4bca6c03eee032c790139cdcc5b431f7ef72207811
+  data.tar.gz: 819682f6427f6d4e0397a43f11ae91cb83ad54b6e4ef411dacded492c7384a6bfa43af917248cb9b1ff6f4fd8a57986f31ee3debb82f3ba59ad5242aa26b95c2

data/README.md

@@ -32,9 +32,9 @@ r = Ark::CLI.report do |s|
 end
 
 r.args       # Get all arguments received, including trailing args
-r.arg[:host] # Get the value of the `host` argument
-r.opt[:port] # Get the value of the `port` option
-r.count[:v]  # Get the number of times an option was toggled
+r.arg(:host) # Get the value of the `host` argument
+r.opt(:port) # Get the value of the `port` option
+r.count(:v)  # Get the number of times an option was toggled
 ```
 
 The `CLI.report` method yields a `Spec` instance, which we'll call `s`. Calls to
@@ -72,7 +72,7 @@ Arguments with default values are optional - no error will be raised if they
 aren't given.
 
 ```ruby
-s.args 'file:~/.dcf'
+s.args 'file:/tmp/foo'
 s.args 'host', 'port:22', "user:#{ENV['USER']}"
 ```
 
@@ -122,21 +122,21 @@ host, path = r.args
 Get the value of a named argument with the `r.arg` method:
 
 ```ruby
-host = r.arg[:host]
-path = r.arg[:path]
+host = r.arg(:host)
+path = r.arg(:path)
 ```
 
 Inspect the value of an option with `r.opt`:
 
 ```ruby
-verbose = r.opt[:v]
-port = r.opt[:port]
+verbose = r.opt(:v)
+port = r.opt(:port)
 ```
 
 Get a count of the number of times a flag was specified with `r.count`:
 
 ```ruby
-verbosity = r.count[:verbose]
+verbosity = r.count(:verbose)
 ```
 
 Get an array of trailing arguments with `r.trailing`:
@@ -156,7 +156,7 @@ CLI declaration.
 
 Usage information for the above declaration would look like this:
 
-    example [OPTION...] HOST PATH
+    example [-p --port NUMBER] [-v --verbose] [-h --help] HOST PATH
 
         An example demonstrating usage of ark-cli
 

data/lib/ark/cli.rb

@@ -28,12 +28,14 @@ module Ark # :nodoc:
 
 # A library for handling options and arguments from the command line.
 #
-# Call #begin to define a new interface and parse the command line. See
+# Call #report to define a new interface and parse the command line. See
 # +README.md+ or +example/hello.rb+ for more information.
 module CLI
-  # Convenience method for interface declarations. Yields the CLI instance and
-  # then returns it after parsing. Equivalent to instantiating a CLI instance
-  # with #new, modifying it, and then calling #parse
+  # :call-seq:
+  # report(input=ARGV) { |spec| ... } => Report
+  #
+  # Convenience method for interface declarations. Yields a +Spec+ instance and
+  # returns a +Report+ instance for inspection.
   #
   # +args+ is an array of strings, which defaults to ARGV
   def self.report(args=ARGV, &block)

data/lib/ark/cli/interface.rb

@@ -1,12 +1,21 @@
-module Ark
+module Ark # :nodoc:
 module CLI
 
+# Main class for ark-cli. Defines a +Spec+, parses the command line and returns
+# +Report+ objects.
 class Interface
 
   # Raised when the command line is malformed
   class SyntaxError < ArgumentError
   end
 
+  # Raised when a required argument is not given
+  class InterfaceError < ArgumentError
+  end
+
+  # :call-seq:
+  # rebuild(input=ARGV) { |spec| ... } => Interface
+  #
   # Initialize an Interface instance.
   #
   # +args+ must be an array of strings, like ARGV
@@ -14,8 +23,11 @@ class Interface
     self.rebuild(args, &block)
   end
 
+  # The +Report+ object for this interface, for inspecting information parsed
+  # from the command line.
   attr_reader :report
 
+  # Rebuild the interface with a new spec and args
   def rebuild(input=ARGV, &block)
     @input = input
     @spec = Spec.new
@@ -30,7 +42,11 @@ class Interface
     last_opt = nil
     refargs = @spec.get_args.clone
 
-    @report = Report.new()
+    args = []
+    trailing = []
+    named = {}
+    options = {}
+    counts = {}
 
     @input.each do |word|
       dbg "Parsing '#{word}'"
@@ -66,36 +82,47 @@ class Interface
         else
           dbg "Parsed output arg", 1
           taking_options = false
-          @report.args << word
+          args << word
           key = refargs.shift
           if key
             if key == @spec.get_variad
-              @report.arg[key] = []
-              @report.arg[key] << word
+              named[key] = []
+              named[key] << word
             else
-              @report.arg[key] = word
+              named[key] = word
             end
           elsif @spec.is_variadic?
-            @report.arg[@spec.get_variad] << word
+            named[@spec.get_variad] << word
           else
-            @report.trailing << word
+            trailing << word
           end
         end
       end
     end
+    if @spec.trailing_error && !trailing.empty?
+      raise InterfaceError, "Error: got trailing option(s): #{trailing.join(', ')}"
+    end
     @spec.get_opts.each do |name, opt|
-      @report.opt[name] = opt.value
-      @report.count[name] = opt.count
+      options[name] = opt.value
+      counts[name]  = opt.count
     end
     @spec.get_args.each do |name|
-      if @report.arg[name].nil?
+      if named[name].nil?
         if @spec.has_default?(name)
-          @report.arg[name] = @spec.get_default(name)
-          @report.args << @report.arg[name]
+          named[name] = @spec.get_default(name)
+          args << named[name]
+        else
+          unless @spec.is_variadic? && @spec.get_variad == name
+            raise InterfaceError, "Required argument '#{name.upcase}' was not given."
+          end
         end
       end
     end
-    if @report.opt[:help]
+    if @spec.is_variadic?
+      named[@spec.get_variad] ||= []
+    end
+    @report = Report.new(args, named, trailing, options, counts)
+    if @report.opt(:help)
       self.print_usage()
     end
   end
@@ -166,7 +193,8 @@ class Interface
     puts self.usage
     exit 0
   end
-end
+
+end # class Interface
 
 end # module CLI
 end # module Ark

data/lib/ark/cli/option.rb

@@ -9,14 +9,15 @@ class Option
   # [+keys+] A list of names this option will be identified by
   # [+args+] A list of argument named this option will expect
   # [+desc+] A short description of this option
-  def initialize(long, short=nil, args=nil, desc=nil)
-    @long  = long
-    @short = short
-    @args  = args || []
-    @vals  = []
-    @flag  = false
-    @count = 0
-    @desc  = desc || ''
+  def initialize(long, short=nil, args=nil, defaults=nil, desc=nil)
+    @long     = long
+    @short    = short
+    @args     = args || []
+    @defaults = defaults || {}
+    @vals     = []
+    @flag     = false
+    @count    = 0
+    @desc     = desc || ''
   end
 
   # A count of how many times this option has been given on the command line.
@@ -85,7 +86,11 @@ class Option
       elsif self.full?
         return @vals
       else
-        return nil
+        if !@defaults.compact.empty?
+          return @defaults.length > 1 ? @defaults : @defaults.first
+        else
+          return nil
+        end
       end
     end
   end

data/lib/ark/cli/report.rb

@@ -1,29 +1,40 @@
-module Ark
+module Ark # :nodoc:
 module CLI
 
+# Stores information parsed from the command line for later inspection
 class Report
-  def initialize()
-    @args = []
-    @named_args = {}
-    @trailing_args = []
-    @counts = {}
-    @options = {}
+  # Initialize a bare +Report+ object
+  def initialize(args, named, trailing, options, counts)
+    @args     = args
+    @named    = named
+    @trailing = trailing
+    @options  = options
+    @counts   = counts
   end
   
+  # Return an array of all args parsed
   def args
     return @args
   end
-  def arg
-    return @named_args
+
+  # Get an argument by +name+
+  def arg(name)
+    return @named[name.to_s]
   end
+
+  # Return an array of any arguments without names
   def trailing
-    return @trailing_args
+    return @trailing
   end
-  def opt
-    return @options
+
+  # Get the value of an option by +name+
+  def opt(name)
+    return @options[name.to_s]
   end
-  def count
-    return @counts
+
+  # Get the toggle count for an option by +name+
+  def count(name)
+    return @counts[name.to_s]
   end
 end
 

data/lib/ark/cli/spec.rb

@@ -1,6 +1,10 @@
-module Ark
+module Ark # :nodoc:
 module CLI
 
+# The +Spec+ class defines the properties of an interface, namely its expected
+# arguments and option definitions, as well as the program name and
+# description. The +Spec+ instance forms the DSL used for interface declarations
+# with the methods +name+, +desc+, +args+, and +opt+.
 class Spec
 
   # Raised when a nonexistent option is received
@@ -11,7 +15,7 @@ class Spec
   class ArgumentSyntaxError < ArgumentError
   end
 
-  # Initialize a bare interface spec
+  # Initialize a bare interface +Spec+
   def initialize()
     @args = []
     @options = {}
@@ -29,22 +33,28 @@ class Spec
 
   private
 
+  # Strip any special syntax from a given argument. Used when parsing arguments
   def strip(arg)
     return arg[/^(\S+?)(:|\.\.\.|$)/, 1]
   end
 
+  # Return +true+ if the given argument has a default value, like +'arg:defaultvalue'+
   def defaulted?(arg)
     return !arg[/^\S+?:.+/].nil?
   end
 
+  # Parse the default value from an arg with one
   def parse_default(arg)
     return arg[/^.+?:(.+)/, 1]
   end
 
+  # Return +true+ if the given argument is a glob, like +'arg...'+
   def variadic?(arg)
     return !arg[/\.\.\.$/].nil?
   end
 
+  # Parse a given argument, interpreting any special syntax, and storing
+  # argument information as needed
   def parse_arg(arg, default: nil, last: false)
     stripped = strip(arg)
     @args << stripped
@@ -64,55 +74,66 @@ class Spec
 
   public
 
+  # Get the name defined for this spec
   def get_name
     return @name
   end
 
+  # Get the description defined for this spec
   def get_desc
     return @desc
   end
 
+  # Get an array of argument names defined for this spec
   def get_args
     return @args
   end
 
+  # Return +true+ if this interface has any options defined for it
   def has_options?
     @options.values.uniq.length > 1
   end
 
+  # Get a hash of any options defined on this spec
   def get_opts
     return @options
   end
 
-  # Get an Option object for the given option +name+
+  # Get an +Option+ object for the given option +name+
   def get_opt(name)
-    name = name.to_sym
+    name = name.to_s
     if !@options.keys.member?(name)
       raise NoSuchOptionError, "Error, no such option: '#{name}'"
     end
     return @options[name]
   end
 
+  # Return +true+ if this interface is variadic
   def is_variadic?
     return @variadic
   end
 
+  # Return the argument name of the variadic argument
   def get_variad
     return @variad
   end
 
+  # Return +true+ if the given argument +arg+ has a default value
   def has_default?(arg)
     @defaults.key?(arg.to_s)
   end
 
+  # Return a hash of all default values
   def get_defaults
     return @defaults
   end
 
+  # Return the default value of the given argument +arg+
   def get_default(arg)
     @defaults[arg.to_s]
   end
 
+  # Return +true+ if this interface has any arguments defined
   def has_args?
     @args.length > 0
   end
@@ -143,6 +164,7 @@ class Spec
     @defaults = {}
 
     input.flatten.each_with_index do |item, i|
+      item = item.to_s
       last = (input.length - (i + 1)) == 0
       parse_arg(item, last: last)
     end
@@ -155,11 +177,23 @@ class Spec
   # [+args+] A list of arguments the option expects
   # [+desc+] A short description of the option, used to provide usage info
   def opt(long, short=nil, args: nil, desc: nil)
-    long = long.to_sym
-    short = short.to_sym if short
+    long = long.to_s
+    short = short.to_s if short
     args = [args] if args.is_a?(String)
-    args.map!(&:to_sym) if args
-    o = Option.new(long, short, args, desc)
+    defaults = []
+    if args
+      args.map! do |arg|
+        arg = arg.to_s
+        if defaulted?(arg)
+          defaults << parse_default(arg)
+          arg = strip(arg)
+        else
+          defaults << nil
+        end
+        arg
+      end
+    end
+    o = Option.new(long, short, args, defaults, desc)
     @options[long] = o
     @options[short] = o if short
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ark-cli
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Macquarie Sharpless
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-07 00:00:00.000000000 Z
+date: 2015-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ark-util