ame 0.1.1 → 1.0.1

data/lib/ame-1.0/methods.rb

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+
+# Stores {Methods#each #each} {Method} defined on a {Class}.
+# @api developer
+class Ame::Methods
+  include Enumerable
+
+  def initialize
+    @methods = {}
+  end
+
+  # Adds METHOD to the receiver
+  # @param [Method] method
+  # @return [self]
+  def <<(method)
+    @methods[method.name] = method
+    self
+  end
+
+  # @return [Method] The method NAME in the receiver
+  # @raise [UnrecognizedMethod] If NAME isn’t a method in the receiver
+  def [](name)
+    @methods[name] or
+      raise Ame::UnrecognizedMethod, 'unrecognized method: %s' % name
+  end
+
+  # @overload
+  #   Enumerates the methods.
+  #
+  #   @yieldparam [Method] option
+  # @overload
+  #   @return [Enumerator<Method>] An Enumerator over the methods
+  def each
+    return enum_for(__method__) unless block_given?
+    @methods.each_value do |method|
+      yield method
+    end
+    self
+  end
+end

data/lib/ame-1.0/multioption.rb

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+
+# Represents an option to a {Method} that takes an argument that can be given
+# any number of times.  If an explicit (‘=’-separated) argument is given, it’ll
+# be used, otherwise the following argument will be used.
+# @api developer
+class Ame::Multioption < Ame::Option
+  # @api internal
+  # @param (see Option#initialize)
+  # @param [::Class] type
+  # @yield (see Option#initialize)
+  # @yieldparam (see Option#initialize)
+  # @raise (see Flag#initialize)
+  # @raise [ArgumentError] If TYPE isn’t one that Ame knows how to parse
+  def initialize(short, long, argument, type, description, &validate)
+    super short, long, argument, nil, description, &validate
+    @type = Ame::Types[type]
+    @ignored = true
+  end
+
+  # Invokes {super} and adds it to an Array added to OPTIONS before returning
+  # it.
+  # @api internal
+  # @param (see Flag#process)
+  # @raise (see Flag#process)
+  # @return [Object]
+  def process(options, arguments, name, explicit)
+    @ignored = false
+    (options[self.name] ||= []) << super
+  end
+
+  # @return True if the receiver hasn’t been asked to process any options yet
+  def ignored?
+    @ignored
+  end
+end

data/lib/ame-1.0/option.rb

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+
+# Represents an option to a {Method} that takes an argument.  If an explicit
+# (‘=’-separated) argument is given, it’ll be used, otherwise the following
+# argument will be used.
+# @api developer
+class Ame::Option < Ame::Switch
+  # @api internal
+  # @param (see Switch#initialize)
+  # @yield (see Switch#initialize)
+  # @yieldparam (see Switch#initialize)
+  # @raise (see Flag#initialize)
+  # @raise [ArgumentError] If the type of DEFAULT isn’t one that Ame knows how
+  #   to parse
+  def initialize(short, long, argument, default, description, &validate)
+    super short, long, argument, default, nil, description, &validate
+  end
+
+  # Invokes {Flag#process} with REMAINDER as the explicit argument if it’s
+  # non-empty.
+  # @api internal
+  # @param (see Flag#process_combined)
+  # @return [[Boolean, '']]
+  def process_combined(options, arguments, name, remainder)
+    [process(options, arguments, name, remainder.empty? ? nil : remainder), '']
+  end
+
+  private
+
+  # @api internal
+  # @param (see Flag#parse)
+  # @return [Object] The parsed value of EXPLICIT, if non-nil, the next argument otherwise
+  # @raise [MissingArgument] If EXPLICIT is nil and there are no more arguments
+  def parse(arguments, explicit)
+    @type.parse(explicit || arguments.shift || raise(Ame::MissingArgument, 'missing argument: %s' % self))
+  end
+end

data/lib/ame-1.0/optional.rb

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+# Represents an optional argument to a {Method}.  It has a {#default} value
+# that will be used if no more arguments are available when it gets called upon
+# to process an argument before the method this argument is associated with
+# gets called.
+# @api developer
+class Ame::Optional < Ame::Argument
+  # @api internal
+  # @param (see Argument#initialize)
+  # @param [Object] default
+  # @yield (see Argument#initialize)
+  # @yieldparam (see Argument#initialize)
+  # @raise [ArgumentError] If the type of DEFAULT isn’t one that Ame knows how
+  #   to parse
+  def initialize(name, default, description, &validate)
+    @default = default
+    super
+  end
+
+  # @return [Object, nil] The default value of the receiver
+  attr_reader :default
+
+  private
+
+  # @api internal
+  # @return [Object] {#default} if ARGUMENTS#empty?, {super} otherwise
+  def parse(arguments)
+    arguments.empty? ? default : super
+  end
+end

data/lib/ame-1.0/options.rb

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+
+# The options to a method in its {Method defined state}.  Does the processing
+# of options to the method and also enumerates {#each} of the options to the
+# method for, for example, help output.
+# @api developer
+class Ame::Options
+  include Enumerable
+
+  def initialize(options, ordered, options_must_precede_arguments)
+    @options, @ordered, @options_must_precede_arguments =
+      options, ordered, options_must_precede_arguments
+  end
+
+  # @api internal
+  # @param [Array<String>] arguments
+  # @raise [UnrecognizedOption] If an unrecognized option has been given
+  # @raise (see Flag#process)
+  # @return [[Hash<String,Object>, Array<String>]] The {Flag#process}ed options
+  #   as a Hash mapping the {Flag#name} to the parsed value or the option’s
+  #   default after filtering out any {Flag#ignored?} options and the remaining
+  #   non-option arguments
+  def process(arguments)
+    arguments = arguments.dup
+    results = @ordered.reduce({}){ |d, o| d[o.name] = o.default; d }
+    remainder = []
+    until arguments.empty?
+      case first = arguments.shift
+      when '--'
+        break
+      when /\A-([^=-]{2,})\z/
+        combined = $1
+        until combined.empty?
+          option = self['-' + combined[0].chr]
+          results[option.name], combined = option.process_combined(results, arguments, $1, combined[1..-1])
+        end
+      when /\A(--[^=]+|-[^-])(?:=(.*))?\z/
+        option = self[$1]
+        results[option.name] = option.process(results, arguments, $1, $2)
+      else
+        remainder << first
+        break if @options_must_precede_arguments
+      end
+    end
+    [results.reject{ |n, _| self[n].ignored? }, remainder.concat(arguments)]
+  end
+
+  # @overload
+  #   Enumerates the options.
+  #
+  #   @yieldparam [Option] option
+  # @overload
+  #   @return [Enumerator<Option>] An Enumerator over the options
+  def each
+    return enum_for(__method__) unless block_given?
+    @ordered.each do |option|
+      yield option
+    end
+    self
+  end
+
+  private
+
+  def [](name)
+    @options[name.sub(/\A-+/, '')] or
+      raise Ame::UnrecognizedOption, 'unrecognized option: %s' % name
+  end
+end

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

@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+
+# The options to a method in its {Method::Undefined undefined state}.
+# @api internal
+class Ame::Options::Undefined
+  def initialize
+    @options = {}
+    @ordered = []
+    @options_must_precede_arguments = ENV.include? 'POSIXLY_CORRECT'
+  end
+
+  # Forces options to the method about to be defined to precede any arguments,
+  # lest they be seen as arguments.  If not given, the behaviour will depend on
+  # whether `ENV['POSIXLY_CORRECT']` has been set or not.
+  # @return [self]
+  def options_must_precede_arguments
+    @options_must_precede_arguments = true
+    self
+  end
+
+  # Adds a new {Flag} to the receiver.
+  # @param (see Flag#initialize)
+  # @yield (see Flag#initialize)
+  # @yieldparam (see Flag#initialize)
+  # @raise (see Flag#initialize)
+  # @raise [ArgumentError] If SHORT or LONG have already been defined
+  # @return [self]
+  def flag(short, long, default, description, &validate)
+    self << Ame::Flag.new(short, long, default, description, &validate)
+  end
+
+  # Adds a new {Flag} to the receiver.  Also adds a `--no-LONG` flag that’s the
+  # inverse of this flag.
+  # @param (see Flag#initialize)
+  # @yield (see Flag#initialize)
+  # @yieldparam (see Flag#initialize)
+  # @raise (see Flag#initialize)
+  # @raise [ArgumentError] If LONG is #strip#empty?
+  # @raise [ArgumentError] If SHORT or LONG have already been defined
+  # @return [self]
+  def toggle(short, long, default, description, &validate)
+    flag = Ame::Flag.new(short, long, default, description, &validate)
+    raise ArgumentError, 'long can’t be empty' if flag.long.empty?
+    self << flag
+    add(Ame::Flag.new('', 'no-%s' % flag.long, nil, description){ |options, argument|
+      options[flag.name] = validate ? validate.call(options, !argument) : !argument
+    })
+  end
+
+  # Adds a new {Switch} to the receiver.
+  # @param (see Switch#initialize)
+  # @yield (see Switch#initialize)
+  # @yieldparam (see Switch#initialize)
+  # @raise (see Switch#initialize)
+  # @raise [ArgumentError] If SHORT or LONG have already been defined
+  # @return [self]
+  def switch(short, long, argument, default, argument_default, description, &validate)
+    self << Ame::Switch.new(short, long, argument, default, argument_default, description, &validate)
+  end
+
+  # Adds a new {Option} to the receiver.
+  # @param (see Option#initialize)
+  # @yield (see Option#initialize)
+  # @yieldparam (see Option#initialize)
+  # @raise (see Option#initialize)
+  # @raise [ArgumentError] If SHORT or LONG have already been defined
+  # @return [self]
+  def option(short, long, argument, default, description, &validate)
+    self << Ame::Option.new(short, long, argument, default, description, &validate)
+  end
+
+  # Adds a new {Multioption} to the receiver.
+  # @param (see Multioption#initialize)
+  # @yield (see Multioption#initialize)
+  # @yieldparam (see Multioption#initialize)
+  # @raise (see Multioption#initialize)
+  # @raise [ArgumentError] If SHORT or LONG have already been defined
+  # @return [self]
+  def multioption(short, long, argument, type, description, &validate)
+    self << Ame::Multioption.new(short, long, argument, type, description, &validate)
+  end
+
+  # @param [String] name
+  # @return True if the receiver has any kind of option named NAME
+  def include?(name)
+    @options.include? name
+  end
+
+  # @return [Options] The defined version of the receiver
+  def define
+    Ame::Options.new(@options, @ordered, @options_must_precede_arguments)
+  end
+
+  protected
+
+  def <<(option)
+    @ordered << option
+    add(option)
+  end
+
+  private
+
+  def add(option)
+    option.names.each do |name|
+      self[name] = option
+    end
+    self
+  end
+
+  def []=(name, option)
+    raise ArgumentError, 'option already defined: %s' % name if include? name
+    @options[name] = option
+  end
+end

data/lib/ame-1.0/root.rb

@@ -0,0 +1,174 @@
+# -*- coding: utf-8 -*-
+
+# Root of a hierarchy of {Class}es.  This class should be subclassed by the
+# root of your command-line interface.
+# @example An rm-like Command-line Interface with Ame
+#   class Rm < Ame::Root
+#     version '1.0.0'
+#
+#     flag 'f', '', false, 'Do not prompt for confirmation'
+#     flag 'i', '', nil, 'Prompt for confirmation' do |options|
+#       options['f'] = false
+#     end
+#     flag 'R', '', false, 'Remove file hierarchies'
+#     flag 'r', '', nil, 'Equivalent to -R' do |options|
+#       options['r'] = true
+#     end
+#     splus 'FILE', String, 'File to remove'
+#     description 'Remove directory entries'
+#     def rm(files, options = {})
+#       require 'fileutils'
+#       FileUtils.send options['R'] ? :rm_r : :rm,
+#         [first] + rest, :force => options['f']
+#     end
+#   end
+#   Rm.process
+# @example A Git-like Command-line Interface With Ame
+#   module Git end
+#   class Git::CLI < Ame::Root
+#     version '1.0.0'
+#     class Git < Ame::Class
+#       description 'The stupid content tracker'
+#       def initialize; end
+#
+#       description 'Prepare patches for e-mail submission'
+#       flag   ?n, 'numbered', false, 'Name output in [PATCH n/m] format'
+#       flag   ?N, 'no-numbered', nil,
+#         'Name output in [PATCH] format' do |options|
+#         options['numbered'] = false
+#       end
+#       toggle ?s, 'signoff', false,
+#         'Add Signed-off-by: line to the commit message'
+#       switch '', 'thread', 'STYLE', nil,
+#         Ame::Types::Enumeration[:shallow, :deep],
+#         'Controls addition of In-Reply-To and References headers'
+#       flag   '', 'no-thread', nil,
+#         'Disables addition of In-Reply-To and Reference headers' do |options, _|
+#          options.delete 'thread'
+#       end
+#       option '', 'start-number', 'N', 1,
+#         'Start numbering the patches at N instead of 1'
+#       multioption '', 'to', 'ADDRESS', String,
+#         'Add a To: header to the email headers'
+#       optional 'SINCE', 'N/A', 'Generate patches for commits after SINCE'
+#       def format_patch(since = '', options = {})
+#         p since, options
+#       end
+#
+#       description 'Annotate file lines with commit information'
+#       argument 'FILE', String, 'File to annotate'
+#       def annotate(file)
+#         p file
+#       end
+#
+#       description 'Add file contents to the index'
+#       splat 'PATHSPEC', String, 'Files to add content from'
+#       def add(paths)
+#         p paths
+#       end
+#
+#       description 'Display gitattributes information'
+#       splus 'PATHNAME', String, 'Files to list attributes of'
+#       def check_attr(paths)
+#         p paths
+#       end
+#
+#       class Remote < Ame::Class
+#         description 'Manage set of remote repositories'
+#         def initialize; end
+#
+#         description 'Shows a list of existing remotes'
+#         flag 'v', 'verbose', false, 'Show remote URL after name'
+#         def list(options = {})
+#           p options
+#         end
+#
+#         description 'Adds a remote named NAME for the repository at URL'
+#         argument 'name', String, 'Name of the remote to add'
+#         argument 'url', String, 'URL to the repository of the remote to add'
+#         def add(name, url)
+#           p name, url
+#         end
+#       end
+#       dispatch Remote, :default => 'list'
+#     end
+#     dispatch Git
+#   end
+#   Git::CLI.process
+class Ame::Root < Ame::Class
+  class << self
+    # Sets the HELP object to use for displaying usage information, or returns
+    # it if HELP is nil.  The default is to use a {Help::Terminal} object.
+    # @param (see Class.help)
+    # @return [#method, #dispatch, #error, #version]
+    def help(help = nil)
+      super if help
+      @help ||= Ame::Help::Terminal.new
+    end
+
+    # Sets or returns, depending on if VERSION is nil or not, the version of
+    # the receiver.  The version may be used by {.help} to output version
+    # information.
+    # @param [String, nil] version
+    # @return [String]
+    def version(version = nil)
+      return @version = version if version
+      @version
+    end
+
+    # Process ARGUMENTS as a list of options and arguments, then call METHOD
+    # with the results of this processing on a new instance of the receiver.
+    # This method catches {AbortAllProcessing}.  Any errors will be caught and
+    # reported using {.help}#error.
+    # @param (see Class.process)
+    # @return [self]
+    def process(method = File.basename($0), arguments = ARGV)
+      catch Ame::AbortAllProcessing do
+        super
+      end
+      self
+    rescue => e
+      help.error method, e
+    end
+
+    # Call METHOD with ARGUMENTS and OPTIONS on a new instance of the receiver.
+    # This method catches {AbortAllProcessing}.
+    # @param (see Class.call)
+    # @raise (see Class.call)
+    # @return [self]
+    def call(method, arguments = nil, options = nil)
+      catch Ame::AbortAllProcessing do
+        super
+      end
+      self
+    end
+
+    # @api developer
+    # @return [String] An empty string
+    def basename
+      ''
+    end
+
+    private
+
+    # Defines the previously undefined {.method} now that it’s been added to
+    # the class after adding flag “version” that’ll call {.help}#version to
+    # output version information and then throw {AbortAllProcessing}.
+    # @api internal
+    # @param (see Class.method_added)
+    # @raise (see Class.method_added)
+    # @raise [ArgumentError] If {.version} hasn’t been set
+    # @return [self]
+    def method_added(ruby_name)
+      unless method.option? 'version'
+        raise ArgumentError, 'version not set, set it with version VERSION', caller unless defined? @version
+        flag '', 'version', nil, 'Display version information' do
+          help.version methods[Ame::Method.name(ruby_name)], self.version
+          throw Ame::AbortAllProcessing
+        end
+      end
+      super
+    rescue; $!.set_backtrace(caller[1..-1]); raise
+    end
+  end
+end