ame 0.1.1 → 1.0.1

data/lib/ame-1.0/splat.rb

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+
+# Represents a splat argument to a {Method}, which works just like a {Splus},
+# except that it won’t fail if there are no more arguments left.
+# @api developer
+class Ame::Splat < Ame::Splus
+  # Processes each argument in ARGUMENTS via {Argument#process}.
+  # @api internal
+  # @param (see Argument#process)
+  # @raise [Ame::MalformedArgument] If the receiver couldn’t be parsed or
+  #   validated
+  # @return [Array<Object>]
+  def process(options, processed, arguments)
+    arguments.empty? ? [] : super
+  end
+end

data/lib/ame-1.0/splus.rb

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+
+# Represents a splus argument to a {Method}, which works just like a normal
+# {Argument}, except that it’ll process all remaining arguments.
+# @api developer
+class Ame::Splus < Ame::Argument
+  # Processes each argument in ARGUMENTS via {Argument#process}.
+  # @api internal
+  # @param (see Argument#process)
+  # @raise [Ame::MissingArgument] If ARGUMENTS#empty?
+  # @raise [Ame::MalformedArgument] If the receiver couldn’t be parsed or
+  #   validated
+  # @return [Array<Object>]
+  def process(options, processed, arguments)
+    super options, processed, arguments if arguments.empty?
+    [].tap{ |r|
+      until arguments.empty?
+        r << super(options, processed, arguments)
+      end
+    }
+  end
+end

data/lib/ame-1.0/switch.rb

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+
+# Represents an option to a {Method} that takes an optional argument.  If an
+# explicit (‘=’-separated) argument is given, it’ll be used, otherwise a
+# default value, which differs from the default value used if the option isn’t
+# given at all, will be used.
+# @api developer
+class Ame::Switch < Ame::Flag
+  # @api internal
+  # @param (see Flag#initialize)
+  # @param [String] argument
+  # @param [Object] default
+  # @param [Object] argument_default
+  # @yield (see Flag#initialize)
+  # @yieldparam [Hash<String, Object>] options
+  # @yieldparam [Object] value
+  # @raise (see Flag#initialize)
+  # @raise [ArgumentError] If the type of ARGUMENT_DEFAULT or, if
+  #   ARGUMENT_DEFAULT is nil, DEFAULT isn’t one that Ame knows how to parse
+  def initialize(short, long, argument, default, argument_default, description, &validate)
+    @argument = argument.upcase
+    @type = Ame::Types[[argument_default, default, String].reject(&:nil?).first]
+    @argument_default = @type.respond_to?(:default) ? @type.default : argument_default
+    super short, long, default, description, &validate
+  end
+
+  # @return [String] The name of the argument to the receiver
+  attr_reader :argument
+
+  private
+
+  # @api internal
+  # @param (see Flag#parse)
+  # @return [Object] The parsed value of EXPLICIT, if non-nil, the default
+  #   argument value otherwise
+  def parse(arguments, explicit)
+    explicit ? @type.parse(explicit) : @argument_default
+  end
+end

data/lib/ame-1.0/types.rb

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+
+# Types registered with Ame for parsing command-line arguments into Ruby
+# values.  By default, Ruby classes TrueClass, FalseClass, Float, Integer,
+# String, and Symbol are registered, as well as an {Enumeration} type for
+# limiting a Symbol to one of a fixed set.
+module Ame::Types
+  @types = {}
+
+  class << self
+    # Registers TYPE for parsing command-line arguments for Ruby values whose
+    # class is any of CLASSES.  The TYPE should respond to #parse(String),
+    # which should convert its String argument into a Ruby value, and may
+    # optionally respond to #default, which should return the default value of
+    # the TYPE, if any.
+    # @param [#parse, #default] type
+    # @param [::Class, …] classes
+    # @return [self]
+    # @example Registering a New Type
+    #   require 'pathname'
+    #
+    #   module My::Pathname
+    #     Ame::Types.register self, Pathname
+    #
+    #     def parse(argument)
+    #       Pathname(argument)
+    #     end
+    #   end
+    # @example Using a New Type as a Type
+    #   class Rm < Ame::Root
+    #     …
+    #     splus 'FILE', My::Pathname, 'File to remove'
+    #     def rm(pathnames)
+    #       pathnames.each do |e| e.rmtree end
+    #     end
+    #   end
+    # @example Using a New Types as a Default
+    #   class My < Ame::Root
+    #     optional 'CONFIG', Pathname('/etc/my/config'), 'Configuration file to use'
+    def register(type, *classes)
+      classes.each do |c|
+        @types[c] = type
+      end
+      self
+    end
+
+    # @api developer
+    # @return [Object] The type registered to parse arguments into values of
+    #   CLASS_OR_VALUE or of the class of CLASS_OR_VALUE, alternatively using
+    #   CLASS_OR_VALUE itself if it responds to #parse
+    # @raise [ArgumentError] If a type that handles CLASS_OR_VALUE hasn’t been
+    #   registered
+    def [](class_or_value)
+      type = @types[class_or_value] and return type
+      pair = @types.find{ |c, t| class_or_value.is_a? c } and return pair.last
+      class_or_value.respond_to? :parse and return class_or_value
+      raise ArgumentError, 'unknown type: %p' % [class_or_value]
+    end
+  end
+end

data/lib/ame-1.0/types/boolean.rb

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+
+module Ame::Types::Boolean
+  Ame::Types.register self, TrueClass, FalseClass
+
+  def self.parse(argument)
+    case argument
+    when 'true', 'yes', 'on' then true
+    when 'false', 'no', 'off' then false
+    else raise Ame::MalformedArgument, 'not a boolean: %s' % argument
+    end
+  end
+end

data/lib/ame-1.0/types/enumeration.rb

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+
+# Enumeration type for limiting a Symbol argument to one in a fixed set.  It
+# also has a {#default}, which will be the first symbol passed to its
+# constructor.
+# @example Using an Enumeration
+#   class Git::CLI::Git::FormatPatch < Ame::Class
+#     switch '', 'thread', 'STYLE', nil,
+#       Ame::Types::Enumeration[:shallow, :deep],
+#       'Controls addition of In-Reply-To and References headers'
+class Ame::Types::Enumeration
+  class << self
+    # Alias for .new.
+    alias [] new
+  end
+
+  # Creates an Enumeration of valid Symbols FIRST, SECOND, and REST for an
+  # argument and sets {#default} to FIRST.
+  # @param [#to_sym] first
+  # @param [#to_sym] second
+  # @param [#to_sym, …] rest
+  def initialize(first, second, *rest)
+    @default = first
+    @names = ([first, second] + rest).map(&:to_sym)
+  end
+
+  # @api internal
+  # @param [String] argument
+  # @return [Symbol] The result of ARGUMENT#to_sym
+  # @raise [MalformedArgument] If ARGUMENT#to_sym isn’t included among the
+  #   valid Symbols
+  def parse(argument)
+    @names.include?(s = argument.to_sym) ? s :
+      raise(Ame::MalformedArgument, 'must be one of %s, not %s' %
+            [@names.join(', '), argument])
+  end
+
+  # @return [Symbol] The Symbol to use if no argument has been given
+  attr_reader :default
+end

data/lib/ame-1.0/types/float.rb

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+
+module Ame::Types::Float
+  Ame::Types.register self, Float
+
+  def self.parse(argument)
+    Float(argument)
+  rescue ArgumentError
+    raise Ame::MalformedArgument, 'not a float: %s' % argument
+  end
+end

data/lib/{ame → ame-1.0}/types/integer.rb

@@ -3,9 +3,9 @@
 module Ame::Types::Integer
   Ame::Types.register self, Integer
 
-  def self.parse(value)
-    Integer(value)
+  def self.parse(argument)
+    Integer(argument)
   rescue ArgumentError
-    raise Ame::MalformedArgument, 'not an integer: %s' % value
+    raise Ame::MalformedArgument, 'not an integer: %s' % argument
   end
 end

data/lib/{ame → ame-1.0}/types/string.rb

@@ -3,7 +3,7 @@
 module Ame::Types::String
   Ame::Types.register self, String
 
-  def self.parse(value)
-    value
+  def self.parse(argument)
+    argument
   end
 end

data/lib/ame-1.0/types/symbol.rb

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+
+module Ame::Types::Symbol
+  Ame::Types.register self, Symbol
+
+  def self.parse(argument)
+    argument.to_sym
+  end
+end

data/lib/ame-1.0/version.rb

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+
+require 'inventory-1.0'
+
+module Ame
+  Version = Inventory.new(1, 0, 1){
+    authors{
+      author 'Nikolai Weibull', 'now@disu.se'
+    }
+
+    homepage 'http://disu.se/software/ame-1.0/'
+
+    licenses{
+      license 'LGPLv3+',
+              'GNU Lesser General Public License, version 3 or later',
+              'http://www.gnu.org/licenses/'
+    }
+
+    def dependencies
+      super + Inventory::Dependencies.new{
+        development 'inventory-rake', 1, 6, 0
+        development 'inventory-rake-tasks-yard', 1, 4, 0
+        development 'lookout', 3, 0, 0
+        development 'lookout-rake', 3, 1, 0
+        development 'yard', 0, 8, 0
+        development 'yard-heuristics', 1, 2, 0
+      }
+    end
+
+    def package_libs
+      %w[argument.rb
+         arguments.rb
+         arguments/undefined.rb
+         arguments/optional.rb
+         arguments/complete.rb
+         class.rb
+         flag.rb
+         help.rb
+         help/terminal.rb
+         help/delegate.rb
+         method.rb
+         method/undefined.rb
+         methods.rb
+         switch.rb
+         option.rb
+         multioption.rb
+         optional.rb
+         options.rb
+         options/undefined.rb
+         root.rb
+         splus.rb
+         splat.rb
+         types.rb
+         types/boolean.rb
+         types/enumeration.rb
+         types/float.rb
+         types/integer.rb
+         types/string.rb
+         types/symbol.rb]
+    end
+  }
+end

data/test/unit/ame-1.0.rb

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+Expectations do
+end

data/test/unit/ame-1.0/argument.rb

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+
+Expectations do
+  expect 'a' do Ame::Argument.new('a', String, 'd').name end
+
+  expect 'd' do Ame::Argument.new('a', String, 'd').description end
+
+  expect 'A' do Ame::Argument.new('a', String, 'd').to_s end
+
+  expect Ame::MissingArgument do Ame::Argument.new('a', String, 'd').process({}, [], []) end
+  expect 'string' do Ame::Argument.new('a', String, 'd').process({}, [], ['string']) end
+
+  expect 1 do Ame::Argument.new('a', Integer, 'd').process({}, [], ['1']) end
+  expect Ame::MalformedArgument.new('A: not an integer: junk') do
+    Ame::Argument.new('a', Integer, 'd').process({}, [], ['junk'])
+  end
+
+  expect TrueClass do Ame::Argument.new('a', TrueClass, 'd').process({}, [], ['true']) end
+  expect Ame::MalformedArgument.new('A: not a boolean: junk') do
+    Ame::Argument.new('a', TrueClass, 'd').process({}, [], ['junk'])
+  end
+
+  expect FalseClass do Ame::Argument.new(:a, FalseClass, 'd').process({}, [], ['false']) end
+  expect Ame::MalformedArgument.new('A: not a boolean: junk') do
+    Ame::Argument.new('a', FalseClass, 'd').process({}, [], ['junk'])
+  end
+
+  expect :a => 1 do
+    options = nil
+    Ame::Argument.new('a', Integer, 'd'){ |o, p, a| options = o }.process({:a => 1}, [1], ['2'])
+    options
+  end
+  expect [1] do
+    processed = nil
+    Ame::Argument.new('a', Integer, 'd'){ |o, p, a| processed = p }.process({:a => 1}, [1], ['2'])
+    processed
+  end
+  expect 2 do
+    argument = nil
+    Ame::Argument.new('a', Integer, 'd'){ |o, p, a| argument = a }.process({:a => 1}, [1], ['2'])
+    argument
+  end
+  expect 3 do
+    Ame::Argument.new('a', Integer, 'd'){ |o, p, a| 3 }.process({:a => 1}, [1], ['2'])
+  end
+end

data/test/unit/ame-1.0/arguments.rb

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+
+Expectations do
+  expect Enumerable do Ame::Arguments::Undefined.new.define end
+
+  expect Ame::MissingArgument do
+    Ame::Arguments::Undefined.new.
+      argument('a', String, 'd').
+      define.
+      process({}, [])
+  end
+
+  expect [] do
+    Ame::Arguments::Undefined.new.
+      define.
+      process({}, [])
+  end
+
+  expect [1] do
+    Ame::Arguments::Undefined.new.
+      argument('a', Integer, 'd').
+      define.
+      process({}, %w[1])
+  end
+
+  expect [1, TrueClass] do
+    Ame::Arguments::Undefined.new.
+      argument('a', Integer, 'd').
+      argument('b', FalseClass, 'd').
+      define.
+      process({}, %w[1 true])
+  end
+
+  expect Ame::MissingArgument do
+    Ame::Arguments::Undefined.new.
+      argument('a', 'd', :type => Integer).
+      splus('b', String, 'd').
+      define.
+      process({}, %w[1])
+  end
+
+  expect [1, []] do
+    Ame::Arguments::Undefined.new.
+      argument('a', Integer, 'd').
+      splat('b', String, 'd').
+      define.
+      process({}, %w[1])
+  end
+
+  expect [1, [2, 3]] do
+    Ame::Arguments::Undefined.new.
+      argument('a', Integer, 'd').
+      splus('b', Integer, 'd').
+      define.
+      process({}, %w[1 2 3])
+  end
+
+  expect Ame::SuperfluousArgument do
+    Ame::Arguments::Undefined.new.
+      define.
+      process({}, %w[1])
+  end
+end

data/test/unit/ame-1.0/arguments/complete.rb

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+Expectations do
+end

data/test/unit/ame-1.0/arguments/optional.rb

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+Expectations do
+end

data/test/unit/ame-1.0/arguments/undefined.rb

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+
+Expectations do
+  expect ArgumentError.new("argument 'b', … may not follow optional 'a', …") do
+    Ame::Arguments::Undefined.new.
+      optional('a', nil, 'd').
+      argument('b', String, 'd')
+  end
+
+  expect ArgumentError.new("splus 'b', … may not follow optional 'a', …") do
+    Ame::Arguments::Undefined.new.
+      optional('a', nil, 'd').
+      splus('b', String, 'd')
+  end
+
+  expect ArgumentError.new("argument 'b', … may not follow splat 'a', …") do
+    Ame::Arguments::Undefined.new.
+      splat('a', String, 'd').
+      argument('b', String, 'd')
+  end
+
+  expect ArgumentError.new("optional 'b', … may not follow splat 'a', …") do
+    Ame::Arguments::Undefined.new.
+      splat('a', String, 'd').
+      optional('b', String, 'd')
+  end
+
+  expect ArgumentError.new("splat 'b', … may not follow splat 'a', …") do
+    Ame::Arguments::Undefined.new.
+      splat('a', String, 'd').
+      splat('b', String, 'd')
+  end
+
+  expect ArgumentError.new("splus 'b', … may not follow splat 'a', …") do
+    Ame::Arguments::Undefined.new.
+      splat('a', String, 'd').
+      splus('b', String, 'd')
+  end
+
+  expect ArgumentError.new("argument 'b', … may not follow splus 'a', …") do
+    Ame::Arguments::Undefined.new.
+      splus('a', String, 'd').
+      argument('b', String, 'd')
+  end
+
+  expect ArgumentError.new("optional 'b', … may not follow splus 'a', …") do
+    Ame::Arguments::Undefined.new.
+      splus('a', String, 'd').
+      optional('b', String, 'd')
+  end
+
+  expect ArgumentError.new("splat 'b', … may not follow splus 'a', …") do
+    Ame::Arguments::Undefined.new.
+      splus('a', String, 'd').
+      splat('b', String, 'd')
+  end
+
+  expect ArgumentError.new("splus 'b', … may not follow splus 'a', …") do
+    Ame::Arguments::Undefined.new.
+      splus('a', String, 'd').
+      splus('b', String, 'd')
+  end
+end