ame 0.1.1 → 1.0.1

data/lib/ame-1.0/flag.rb

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+
+# Represents a boolean option to a {Method} that doesn’t take an argument,
+# though an argument is actually allowed if it’s made explicit by following the
+# option name with a ‘=’ character and the argument value.  Does the potential
+# processing of the argument or simply returns the inverse {#default} value of
+# the flag.
+# @api developer
+class Ame::Flag
+  # @api internal
+  # @param [String] short
+  # @param [String] long
+  # @param [Boolean] default
+  # @param [String] description
+  # @yield [?]
+  # @yieldparam [Hash<String, Object>] options
+  # @yieldparam [Boolean] value
+  # @raise [ArgumentError] If SHORT and LONG are #strip#empty?
+  # @raise [ArgumentError] If SHORT#strip#length > 1
+  def initialize(short, long, default, description, &validate)
+    @short, @long, @default, @description, @validate =
+      (s = short.strip).empty? ? nil : s, (l = long.strip).empty? ? nil : l,
+      default, description, validate || proc{ |_, a| a }
+    raise ArgumentError, 'both short and long can’t be empty' if
+      @short.nil? and @long.nil?
+    raise ArgumentError, 'short can’t be longer than 1: %s' % @short if
+      @short and @short.length > 1
+  end
+
+  # Invokes the optional block passed to the receiver when it was created for
+  # additional validation and parsing after optionally parsing one or more of
+  # the ARGUMENTS passed to it (see subclasses’ {#parse} methods for their
+  # behaviour).
+  # @api internal
+  # @param [Hash<String, Object>] options
+  # @param [Array<String>] arguments
+  # @param [String] name
+  # @raise [MissingArgument] If a required argument to an option is missing
+  # @raise [MalformedArgument] If an argument to an option can’t be parsed
+  # @return [Boolean]
+  def process(options, arguments, name, explicit)
+    @validate.call(options, parse(arguments, explicit))
+  rescue Ame::MalformedArgument, ArgumentError, TypeError => e
+    raise Ame::MalformedArgument, '%s: %s' % [name, e]
+  end
+
+  # Invokes {#process} with arguments depending on whether REMAINDER, which is
+  # any content following a short option, should be seen as an argument to the
+  # receiver or not (see subclasses’ {#process_combined} methods for their
+  # behaviour), returning the result of {#process} and REMAINDER if it was
+  # used, or an empty String if it was.
+  # @api internal
+  # @param (see #process)
+  # @param [String] remainder
+  # @return [[Boolean, String]]
+  def process_combined(options, arguments, name, remainder)
+    [process(options, arguments, name, nil), remainder]
+  end
+
+  # @return [String] The long or short name of the option
+  def name
+    @name ||= names.first
+  end
+
+  # @return [Array<String>] The long and/or short name of the option
+  def names
+    @names ||= [long, short].reject{ |e| e.nil? }
+  end
+
+  # @return True if the receiver shouldn’t be included in the Hash of option
+  #   names and their values
+  def ignored?
+    default.nil?
+  end
+
+  # @return [String] The short name of the receiver
+  attr_reader :short
+
+  # @return [String] The long name of the receiver
+  attr_reader :long
+
+  # @return [Boolean] The default value of the receiver
+  attr_reader :default
+
+  # @return [String] The description of the receiver
+  attr_reader :description
+
+  private
+
+  # Returns the parsed value of EXPLICIT, or the inverse of {#default} if nil.
+  # Should be overridden by subclasses that want different behaviour for
+  # missing arguments.
+  # @api internal
+  # @param [Array<String>] arguments
+  # @param [String, nil] explicit
+  # @return [Boolean]
+  # @raise [MalformedArgument] If EXPLICIT is non-nil and can’t be parsed
+  def parse(arguments, explicit)
+    explicit ? Ame::Types[TrueClass].parse(explicit) : !default
+  end
+end

data/lib/{ame → ame-1.0}/help.rb

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
 
+# Namespace for help output.
 module Ame::Help
-  autoload :Console, 'ame/help/console'
 end

data/lib/ame-1.0/help/delegate.rb

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+
+# Delegates help output requests to another help output.
+# @api internal
+class Ame::Help::Delegate
+  def initialize(help)
+    @help = help
+  end
+
+  def dispatch(method, klass)
+    @help.dispatch method, klass
+    self
+  end
+
+  def method(method)
+    @help.method method
+    self
+  end
+end

data/lib/ame-1.0/help/terminal.rb

@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+
+# Outputs help requests to a pair of IO objects, defaulting to `$stdout` and
+# `$stderr`.  An instance of this class is used by default for outputting help
+# requests from {Root}, but can be overridden by invoking {Root.help} with
+# another object (such as an instance of this class that’s been constructed
+# with different parameters).
+# @api developer/user
+class Ame::Help::Terminal
+  # Sets up help requests to be made to OUTPUT ({#dispatch}, {#method}, and
+  # {#version}) and ERROR ({#error}), as well as specifying whether to
+  # EXIT_ON_ERROR or not, see {#error}.
+  # @param [#puts] output
+  # @param [#puts] error
+  # @param [Boolean] exit_on_error
+  def initialize(output = $stdout, error = $stderr, exit_on_error = true)
+    @output, @error, @exit_on_error = output, error, exit_on_error
+  end
+
+  # Outputs a help request for a {Class.dispatch} METHOD to KLASS, displaying
+  # all options and arguments to the method and listing the possible dispatch
+  # methods.
+  # @param [Method] method
+  # @param [Class] klass
+  # @return [self]
+  def dispatch(method, klass)
+    output(method_s(method).tap{ |result|
+      append_group result, 'Methods', klass.methods.sort_by{ |m| m.name } do |m|
+        m.name
+      end
+    })
+  end
+
+  # Outputs a help request for METHOD, displaying all its options and
+  # arguments.
+  # @param [Method] method
+  # @return [self]
+  def method(method)
+    output(method_s(method))
+  end
+
+  # Outputs VERSION information for METHOD.
+  # @param [Method] method
+  # @param [String] version
+  # @return [self]
+  def version(method, version)
+    output('%s %s' % [method.name, version])
+  end
+
+  # Outputs ERROR that occurred while processing METHOD.
+  # @raise [SystemExit] If exit_on_error was given as true to the receiver’s
+  #   constructor
+  # @raise [error] If exit_on_error wasn’t given as true to the receiver’s
+  #   constructor
+  def error(method, error)
+    errput '%s: %s' % [method, error]
+    exit 1 if @exit_on_error
+    raise error
+  end
+
+  private
+
+  def output(string)
+    @output.puts string
+    self
+  end
+
+  def errput(string)
+    @error.puts string
+    self
+  end
+
+  def method_s(method)
+    ['Usage:'].tap{ |result|
+      append result, ' ', method.qualified_name
+      append result, ' ', method.options.count > 0 ? '[OPTIONS]...' : ''
+      append result, ' ', method.arguments.map{ |a|
+        case a
+        when Ame::Splat then '[%s]...'
+        when Ame::Splus then '%s...'
+        when Ame::Optional then '[%s]'
+        else '%s'
+        end % a
+      }.join(' ')
+      result << "\n"
+      append result, '  ', method.description
+      append_group result, 'Arguments', method.arguments do |argument|
+        case argument
+        when Ame::Splat then '[%s]...' % argument
+        when Ame::Splus then '%s...' % argument
+        when Ame::Optional then '[%s=%s]' % [argument, argument.default]
+        else argument.to_s
+        end
+      end
+      os = method.options.select{ |o| o.description }.sort_by{ |o| (o.short or o.long).to_s }
+      short = os.any?{ |o| o.short }
+      append_group result, 'Options', os do |o|
+        case o
+        when Ame::Multioption then '%s*' % option(o, short)
+        when Ame::Option then option(o, short)
+        when Ame::Switch then '%s[=%s]' % [flag(o, short), o.argument]
+        else flag(o, short)
+        end
+      end
+    }.join('')
+  end
+
+  def append(result, prefix, string)
+    result << prefix << string unless string.empty?
+  end
+
+  def append_group(result, heading, objects)
+    strings = objects.map{ |o| [o, yield(o)] }
+    longest = strings.map{ |_, s| s.length }.max
+    append result, "\n\n%s:\n" % heading,
+      strings.map{ |o, s| '  %-*s  %s' % [longest, s, o.description] }.join("\n")
+  end
+
+  def flag(option, short)
+    if option.short and option.long
+      '-%s, --%s' % [option.short, option.long]
+    elsif option.short
+      '-%s' % option.short
+    else
+      '%s--%s' % [short ? '    ' : '', option.long]
+    end
+  end
+
+  def option(option, short)
+    '%s%s%s' % [flag(option, short), option.long ? '=' : '', option.argument]
+  end
+end

data/lib/ame-1.0/method.rb

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+
+# A method in its defined state.
+# @api developer
+class Ame::Method
+  class << self
+    # @param [String] name
+    # @return [Symbol] The Ruby version of NAME, possibly the name of the
+    #   method given on the command-line, replacing any ‘-’ with ‘_’.
+    def ruby_name(name)
+      name.gsub('-', '_').to_sym
+    end
+
+    # @param [Symbol] ruby_name
+    # @return [String] The command-line version of RUBY_NAME, replacing any ‘_’
+    #   with ‘-’
+    def name(ruby_name)
+      ruby_name.to_s.gsub('_', '-')
+    end
+  end
+
+  def initialize(ruby_name, klass, description, options, arguments)
+    @ruby_name, @class, @description, @options, @arguments =
+      ruby_name, klass, description, options, arguments
+  end
+
+  # Process ARGUMENTS as a set of {Options} and {Arguments}, then {#call} the
+  # receiver’s method on INSTANCE with them.
+  # @api internal
+  # @param [Class] instance
+  # @param [Array<String>] arguments
+  # @raise (see Options#process)
+  # @raise (see Arguments#process)
+  # @return [self]
+  def process(instance, arguments)
+    options, remainder = @options.process(arguments)
+    call(instance, @arguments.process(options, remainder), options)
+  end
+
+  # Call the receiver’s method on INSTANCE with ARGUMENTS and OPTIONS,
+  # retrieving any default values for them if they’re nil.
+  # @api internal
+  # @param [Class] instance
+  # @param [Array<Object>, nil] arguments
+  # @param [Hash<String, Object>] options
+  # @raise (see Options#process)
+  # @raise (see Arguments#process)
+  # @return [self]
+  def call(instance, arguments = nil, options = nil)
+    options, _ = @options.process([]) unless options
+    arguments ||= @arguments.process(options, [])
+    instance.send @ruby_name, *(arguments + (options.empty? ? [] : [options]))
+    self
+  end
+
+  # @return [String] The description of the receiver
+  attr_reader :description
+
+  # @return [Options] The options of the receiver
+  attr_reader :options
+
+  # @return [Arguments] The arguments of the receiver
+  attr_reader :arguments
+
+  # @return [String] The command-line name of the receiver
+  def name
+    @name ||= self.class.name(@ruby_name)
+  end
+
+  # @return [String] The full command-line name of the receiver, including the
+  #   class that this method belongs to’s {Class.fullname}
+  def qualified_name
+    [@class.fullname, name].reject(&:empty?).join(' ')
+  end
+end

data/lib/ame-1.0/method/undefined.rb

@@ -0,0 +1,184 @@
+# -*- coding: utf-8 -*-
+
+# A {Method} in its undefined state.  This class is used to construct the
+# method before it gets defined, setting up a description, specifying that
+# options_must_precede_arguments, adding flags, toggles, switches, options,
+# multioptions, arguments, optional arguments, splats, spluses, and finally
+# defining it.
+# @api developer
+class Ame::Method::Undefined
+  # Sets up an as yet undefined method on KLASS.
+  # @api internal
+  # @param [Class] klass
+  def initialize(klass)
+    @class = klass
+    @description = nil
+    @options = Ame::Options::Undefined.new
+    @arguments = Ame::Arguments::Undefined.new
+  end
+
+  # Sets the DESCRIPTION of the method, or returns it if DESCRIPTION is nil.
+  # The description is used in help output and similar circumstances.
+  # @api internal
+  # @param [String, nil] description
+  # @return [String]
+  def description(description = nil)
+    return @description unless description
+    @description = description
+    self
+  end
+
+  # Forces options to the method to precede any arguments to be processed
+  # correctly.
+  # @api internal
+  # @return [self]
+  def options_must_precede_arguments
+    @options.options_must_precede_arguments
+    self
+  end
+
+  # Delegates {Class.flag} to {Options::Undefined#flag}.
+  # @api internal
+  # @param (see Options::Undefined#flag)
+  # @yield (see Options::Undefined#flag)
+  # @yieldparam (see Options::Undefined#flag)
+  # @raise (see Options::Undefined#flag)
+  # @return [self]
+  def flag(short, long, default, description, &validate)
+    @options.flag short, long, default, description, &validate
+    self
+  end
+
+  # Delegates {Class.toggle} to {Options::Undefined#toggle}.
+  # @api internal
+  # @param (see Options::Undefined#toggle)
+  # @yield (see Options::Undefined#toggle)
+  # @yieldparam (see Options::Undefined#toggle)
+  # @raise (see Options::Undefined#toggle)
+  # @return [self]
+  def toggle(short, long, default, description, &validate)
+    @options.toggle short, long, default, description, &validate
+    self
+  end
+
+  # Delegates {Class.switch} to {Options::Undefined#switch}.
+  # @api internal
+  # @param (see Options::Undefined#switch)
+  # @yield (see Options::Undefined#switch)
+  # @yieldparam (see Options::Undefined#switch)
+  # @raise (see Options::Undefined#switch)
+  # @return [self]
+  def switch(short, long, argument, default, argument_default, description, &validate)
+    @options.switch short, long, argument, default, argument_default, description, &validate
+    self
+  end
+
+  # Delegates {Class.option} to {Options::Undefined#option}.
+  # @api internal
+  # @param (see Options::Undefined#option)
+  # @yield (see Options::Undefined#option)
+  # @yieldparam (see Options::Undefined#option)
+  # @raise (see Options::Undefined#option)
+  # @return [self]
+  def option(short, long, argument, default, description, &validate)
+    @options.option short, long, argument, default, description, &validate
+    self
+  end
+
+  # Delegates {Class.multioption} to {Options::Undefined#multioption}.
+  # @api internal
+  # @param (see Options::Undefined#multioption)
+  # @yield (see Options::Undefined#multioption)
+  # @yieldparam (see Options::Undefined#multioption)
+  # @raise (see Options::Undefined#multioption)
+  # @return [self]
+  def multioption(short, long, argument, type, description, &validate)
+    @options.multioption short, long, argument, type, description, &validate
+    self
+  end
+
+  # Delegates {Class.argument} to {Arguments::Undefined#argument}.
+  # @api internal
+  # @param (see Arguments::Undefined#argument)
+  # @yield (see Arguments::Undefined#argument)
+  # @yieldparam (see Arguments::Undefined#argument)
+  # @raise (see Arguments::Undefined#argument)
+  # @raise (see Arguments::Optional#argument)
+  # @raise (see Arguments::Complete#argument)
+  # @return [self]
+  def argument(name, type, description, &validate)
+    @arguments.argument(name, type, description, &validate)
+    self
+  end
+
+  # Delegates {Class.argument} to {Arguments::Undefined#optional} or
+  # {Arguments::Optional#optional}.
+  # @api internal
+  # @param (see Arguments::Undefined#optional)
+  # @yield (see Arguments::Undefined#optional)
+  # @yieldparam (see Arguments::Undefined#optional)
+  # @param (see Arguments::Undefined#optional)
+  # @raise (see Arguments::Undefined#optional)
+  # @raise (see Arguments::Complete#optional)
+  # @return [self]
+  def optional(name, default, description, &validate)
+    @arguments = @arguments.optional(name, default, description, &validate)
+    self
+  end
+
+  # Delegates {Class.argument} to {Arguments::Undefined#splat}.
+  # @api internal
+  # @param (see Arguments::Undefined#splat)
+  # @option (see Arguments::Undefined#splat)
+  # @yield (see Arguments::Undefined#splat)
+  # @yieldparam (see Arguments::Undefined#splat)
+  # @raise (see Arguments::Undefined#splat)
+  # @raise (see Arguments::Complete#splat)
+  # @return [self]
+  def splat(name, type, description, &validate)
+    @arguments = @arguments.splat(name, type, description, &validate)
+    self
+  end
+
+  # Delegates {Class.argument} to {Arguments::Undefined#splus}.
+  # @api internal
+  # @param (see Arguments::Undefined#splus)
+  # @option (see Arguments::Undefined#splus)
+  # @yield (see Arguments::Undefined#splus)
+  # @yieldparam (see Arguments::Undefined#splus)
+  # @raise (see Arguments::Undefined#splus)
+  # @raise (see Arguments::Optional#splus)
+  # @raise (see Arguments::Complete#splus)
+  # @return [self]
+  def splus(name, type, description, &validate)
+    @arguments = @arguments.splus(name, type, description, &validate)
+    self
+  end
+
+  # @api internal
+  # @return [Method] The method RUBY_NAME after adding a “help” flag that’ll
+  #   display help via {Class.help}#method and raise {AbortAllProcessing}
+  def define(ruby_name)
+    flag '', 'help', nil, 'Display help for this method' do
+      @class.help.method @class.methods[Ame::Method.name(ruby_name)]
+      throw Ame::AbortAllProcessing
+    end unless @options.include? 'help'
+    Ame::Method.new(ruby_name, @class, @description, @options.define, @arguments.define)
+  end
+
+  # @param [String] option
+  # @return [Boolean] True if OPTION has been defined on the receiver
+  def option?(option)
+    @options.include? option
+  end
+
+  # @return [Boolean] True if any arguments have been defined on the receiver
+  def arguments?
+    not @arguments.empty?
+  end
+
+  # @return [Boolean] True if a description has been defined on the receiver
+  def valid?
+    not description.nil?
+  end
+end