argy 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: '01379049c1a1d66874589c09735fba37dbfbf39b'
-  data.tar.gz: fb593767af624cc2c3dc06ec32a8c2286fea7f9d
+  metadata.gz: 39b5a23a831916297c03424c7b40e43991a0b69c
+  data.tar.gz: c0d027d704e117f89016d8d512ab3b59c801f856
 SHA512:
-  metadata.gz: 3addec730a4dce220927c0518d52a1e2188fc27ff67de5ffddc89f0e91956b62dd31d7204968de26ff14b654e5b10cd9cc10f202a00f178e6a64819ce1f9b4f4
-  data.tar.gz: f034dc884c0b9bad616f2daedba4068cfcf1ea8adfc27862466e6afd2c80446b880e1a36e19b5a1e7bc44d588b71ce435bbf8565398da64b109dbb7942f7a381
+  metadata.gz: 83a1ec9cad3de44f46233287df5487ffe0fd1d4eb7d19ee9a0922c05ea494f999b692ba72d040e55a409fb7b1465c806e8e7b088689e809870c279adc78d7592
+  data.tar.gz: a4ff6936385c154d67a2f33a2197dd2c7c201f39a5a7c2b61964f2fff76245dd5f9dfa44a3ba9fe68c231855893f78e59fa991fed67b3922ad2636fc654c867e

data/.yardopts

@@ -0,0 +1,6 @@
+--output-dir=doc/api
+--embed-mixins
+--protected
+--no-private
+--markup-provider=redcarpet
+--markup=markdown

data/lib/argy.rb

@@ -2,11 +2,21 @@ require "argy/version"
 require "argy/parser"
 
 module Argy
+  # Base class for all of Argy's errors.
   Error = Class.new(StandardError)
+
+  # An error that is raised when an option
+  # cannot be coerced to the correct type
   CoersionError = Class.new(Error)
+
+  # An error that is raised when an option
+  # is not valid.
   ValidationError = Class.new(Error)
 
+  # An error that is raised when parsing fails.
   class ParseError < Error
+    # The original error from OptionParser.
+    # @return [OptionParser::ParseError]
     attr_reader :original
 
     def initialize(original)
@@ -15,10 +25,26 @@ module Argy
     end
   end
 
+  # Define a new parser.
+  # @see Parser
+  # @example
+  #   parser = Argy.new do |o|
+  #     o.argument :input, desc: "the input file"
+  #     o.option :verbose, type: :boolean
+  #   end
+  #
+  #   options = parser.parse(ARGV)
   def self.new(&block)
     Argy::Parser.new(&block)
   end
 
+  # Define a parser and return the options in one go.
+  # @see Parser
+  # @example
+  #   options = Argy.parse do
+  #     o.argument :input, desc: "the input file"
+  #     o.option :verbose, type: :boolean
+  #   end
   def self.parse(argv: ARGV, &block)
     new(&block).parse(argv)
   end

data/lib/argy/argument.rb

@@ -1,7 +1,10 @@
 require "argy/parameter"
 
 module Argy
+  # An positional argument to be parsed from the command line
   class Argument < Parameter
+    # The display label for the argument
+    # @return [String]
     def label
       name.to_s.upcase
     end

data/lib/argy/help.rb

@@ -1,11 +1,18 @@
 module Argy
+  # Builds help information
   class Help
+    # Create a new Help
+    # @param parser [Parser] the parser to generate help for
+    # @param column [Integer] the column width of the help
+    # @param color [TrueClass,FalseClass] whether or not to print with color
     def initialize(parser, column: 30, color: $stdout.tty?)
       @parser = parser
       @column = column
       @color = color
     end
 
+    # The help information
+    # @return [String]
     def to_s
       out = []
 
@@ -19,10 +26,18 @@ module Argy
       out.join("\n") + "\n"
     end
 
+    # Format the title of a custom section
+    # @return [String]
     def section(title)
       bold "\n#{title}"
     end
 
+    # Format an entry of a section
+    # @param name [String] left column of the entry
+    # @param desc [String] right column of the entry
+    # @param required [TrueClass,FalseClass] whether or not the entry is required
+    # @param default [Object] default value for the entry
+    # @return [String]
     def entry(name, desc: nil, required: false, default: nil)
       out = "  #{name.ljust(column)}"
       out += dim("#{desc} ") if desc

data/lib/argy/option.rb

@@ -1,14 +1,26 @@
 require "argy/parameter"
 
 module Argy
+  # An option to be parsed from the command line
   class Option < Parameter
+    # A list of alternative flags
+    # @return [Array<String>]
     attr_reader :aliases
 
+    # Create a new Option
+    # @param name [Symbol] name of the parameter
+    # @param aliases [Array<String>] a list of alternative flags
+    # @param desc [String,nil] description for the parameter
+    # @param type [Symbol,#call] type of parameter
+    # @param default [Object] default value for the parameter
+    # @param required [TrueClass,FalseClass] whether or not the field is required
     def initialize(*args, aliases: [], **opts)
       super(*args, **opts)
       @aliases = aliases
     end
 
+    # The display label for the argument
+    # @return [String]
     def label
       case type
       when :boolean
@@ -18,6 +30,7 @@ module Argy
       end
     end
 
+    # @private
     def to_option_parser
       options = []
       options << aliases.join(" ") unless aliases.empty?

data/lib/argy/options.rb

@@ -1,17 +1,32 @@
 module Argy
+  # The resulting options that were parsed from the command line.
+  # @example Getting a value
+  #   options = Options.new(foo: "bar")
+  #   options.foo #=> "bar"
+  # @example Querying for a value's truthiness
+  #   options = Options.new(foo: "bar")
+  #   options.foo? #=> true
   class Options
+    # Create a new Options
+    # @param values [Hash{Symbol => Object}]
     def initialize(values)
       @values = values
     end
 
+    # The values as a hash
+    # @return [Hash{Symbol => Object}]
     def to_h
       @values
     end
 
+    # Get a value by key
+    # @see Hash#[]
     def [](key)
       @values[key]
     end
 
+    # Fetch a value by key or provide a default.
+    # @see Hash#fetch
     def fetch(*args, &block)
       @values.fetch(*args, &block)
     end

data/lib/argy/parameter.rb

@@ -2,9 +2,30 @@ require "pathname"
 require "argy/parameter"
 
 module Argy
+  # @abstract Subclasses must implement {#label}
   class Parameter
-    attr_reader :name, :type, :default, :desc
+    # The name of the parameter
+    # @return [String]
+    attr_reader :name
 
+    # The type of the parameter
+    # @return [String]
+    attr_reader :type
+
+    # The default value for the parameter
+    # @return [Object]
+    attr_reader :default
+
+    # The description for the parameter
+    # @return [String]
+    attr_reader :desc
+
+    # Create a new Parameter
+    # @param name [Symbol] name of the parameter
+    # @param desc [String,nil] description for the parameter
+    # @param type [Symbol,#call] type of parameter
+    # @param default [Object] default value for the parameter
+    # @param required [TrueClass,FalseClass] whether or not the field is required
     def initialize(name, desc: nil, type: :string, default: nil, required: false)
       @name = name
       @type = type
@@ -13,20 +34,33 @@ module Argy
       @required = required
     end
 
+    # The display label for the paramter
+    # @abstract
+    # @return [String]
     def label
       raise NotImplementedError, __method__
     end
 
+    # Check if the parameter is required
+    # @return [TrueClass,FalseClass]
     def required?
       @required
     end
 
+    # Validates a value.
+    # @return [Object] the value
+    # @raise [ValidationError] if the valid is invalid
     def validate(value)
       if required? && value.nil?
         raise ValidationError, "`#{label}` is a required parameter"
       end
+
+      value
     end
 
+    # Coerces a value to the correct type.
+    # @param value [Object] the value to coerce
+    # @raise [CoersionError] if the value cannot be coerced
     def coerce(value)
       case type
       when :string, :boolean

data/lib/argy/parser.rb

@@ -5,8 +5,23 @@ require "argy/argument"
 require "argy/options"
 
 module Argy
+  # Parses command line arguments.
   class Parser
-    attr_reader :examples, :arguments, :options, :flags
+    # The examples that were declared
+    # @return [Array<String>]
+    attr_reader :examples
+
+    # The arguments that were declared
+    # @return [Array<Argument>]
+    attr_reader :arguments
+
+    # The options that were declared
+    # @return [Array<Option>]
+    attr_reader :options
+
+    # The flags that were declared
+    # @return [Array<Array(Array<String>, Proc)>]
+    attr_reader :flags
 
     def initialize
       @usage = $0
@@ -18,40 +33,89 @@ module Argy
       yield self if block_given?
     end
 
+    # Gets or sets the usage for your program. If the
+    # provided usage is nil, the usage will not change.
+    # @param usage [String,nil] sets the usage if not nil
+    # @return [String] usage
+    # @example
+    #   Argy.new do |o|
+    #     o.usage "example [INPUT]"
+    #   end
     def usage(usage = nil)
       @usage = usage if usage
       @usage
     end
 
+    # Gets or sets a description for your program. If the
+    # provided description is nil, the description will
+    # not change.
+    # @param description [String,nil]
+    # @return [String]
+    # @example
+    #   Argy.new do |o|
+    #     o.description "a really useful program"
+    #   end
     def description(description = nil)
       @description = description if description
       @description
     end
 
+    # Adds an example
+    # @example
+    #   Argy.new do |o|
+    #     o.example "$ example foo"
+    #   end
     def example(example)
       @examples << example
     end
 
+    # Adds an argument
+    # @see Argument#initialize
+    # @example
+    #   Argy.new do |o|
+    #     o.argument :input
+    #   end
     def argument(*args)
       @arguments << Argument.new(*args)
     end
 
+    # Adds an option
+    # @see Option#initialize
+    # @example
+    #   Argy.new do |o|
+    #     o.option :verbose, type: :boolean
+    #   end
     def option(*args)
       @options << Option.new(*args)
     end
 
+    # Adds a flag
+    # @example
+    #   Argy.new do |o|
+    #     o.on "-v", "--version" do
+    #       puts Example::VERSION
+    #       exit
+    #     end
+    #   end
     def on(*args, &action)
       @flags << [args, action]
     end
 
+    # All parameters that are defined
+    # @return [Array<Argument, Option>]
     def parameters
       arguments + options
     end
 
+    # Generate help for this parser.
+    # @see Help#initialize
+    # @return [Help]
     def help(**opts)
       Help.new(self, **opts)
     end
 
+    # Build the default values for the declared paramters.
+    # @return [Hash{Symbol => Object}]
     def default_values
       parameters.reduce(unused_args: []) do |acc, opt|
         acc[opt.name] = opt.default
@@ -59,6 +123,12 @@ module Argy
       end
     end
 
+    # Build the default values for the declared paramters.
+    # @param argv [Array<String>] the command line arguments to parse
+    # @param strategy [Symbol,nil] can be either `:order` or `:permute`. See
+    #   `OptionParser#order!` and `OptionParser#permute!` for more info.
+    # @raise [ParseError] when the arguments can't be parsed
+    # @return [Hash{Symbol => Object}]
     def parse(argv, strategy: nil)
       argv = argv.dup
       values = default_values
@@ -79,6 +149,10 @@ module Argy
       raise ParseError.new(error)
     end
 
+    # Validate the values
+    # @param values [Hash{Symbol => Object}]
+    # @return [Hash{Symbol => Object}]
+    # @raise [ValidationError] when the input is invalid
     def validate!(values)
       parameters.each do |param|
         param.validate(values[param.name])

data/lib/argy/version.rb

@@ -1,3 +1,3 @@
 module Argy
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: argy
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Ray Zane
@@ -62,6 +62,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock