shellopts 2.0.0.pre.14 → 2.0.0

data/lib/shellopts/parser.rb

@@ -0,0 +1,293 @@
+
+module ShellOpts
+  module Grammar
+    class Node
+      def parse() end
+
+      def self.parse(parent, token)
+        this = self.new(parent, token)
+        this.parse
+        this
+      end
+
+      def parser_error(token, message) raise ParserError, "#{token.pos} #{message}" end
+    end
+
+    class IdrNode
+      # Assumes that @name and @path has been defined
+      def parse
+        @ident = @path.last || :!
+        @attr = ::ShellOpts::Command::RESERVED_OPTION_NAMES.include?(ident.to_s) ? nil : ident
+        @uid = parent && @path.join(".").sub(/!\./, ".") # uid is nil for the Program object
+      end
+    end
+
+    class Option
+      SHORT_NAME_RE = /[a-zA-Z0-9]/
+      LONG_NAME_RE = /[a-zA-Z0-9][a-zA-Z0-9_-]*/
+      NAME_RE = /(?:#{SHORT_NAME_RE}|#{LONG_NAME_RE})(?:,#{LONG_NAME_RE})*/
+
+      def parse
+        token.source =~ /^(-|--|\+|\+\+)(#{NAME_RE})(?:=(.+?)(\?)?)?$/ or 
+            parser_error token, "Illegal option: #{token.source.inspect}"
+        initial = $1
+        name_list = $2
+        arg = $3
+        optional = $4
+
+        @repeatable = %w(+ ++).include?(initial)
+
+        @short_idents = []
+        @short_names = []
+        names = name_list.split(",")
+        if %w(+ -).include?(initial)
+          while names.first&.size == 1
+            name = names.shift
+            @short_names << "-#{name}"
+            @short_idents << name.to_sym
+          end
+        end
+
+        names.each { |name| 
+          name.size > 1 or 
+              parser_error token, "Long names should be at least two characters long: '#{name}'"
+        }
+
+        @long_names = names.map { |name| "--#{name}" }
+        @long_idents = names.map { |name| name.tr("-", "_").to_sym }
+
+        @name = @long_names.first || @short_names.first
+        @path = command.path + [@long_idents.first || @short_idents.first]
+
+        @argument = !arg.nil?
+
+        named = true
+        if @argument
+          if arg =~ /^([^:]+)(?::(.*))/
+            @argument_name = $1
+            named = true
+            arg = $2
+          elsif arg =~ /^:(.*)/
+            arg = $1
+            named = false
+          end
+
+          case arg
+            when "", nil
+              @argument_name ||= "VAL"
+              @argument_type = StringType.new
+            when "#"
+              @argument_name ||= "INT"
+              @argument_type = IntegerArgument.new
+            when "$"
+              @argument_name ||= "NUM"
+              @argument_type = FloatArgument.new
+            when "FILE", "DIR", "PATH", "EFILE", "EDIR", "EPATH", "NFILE", "NDIR", "NPATH"
+              @argument_name ||= arg.sub(/^(?:E|N)/, "")
+              @argument_type = FileArgument.new(arg.downcase.to_sym)
+            when /,/
+              @argument_name ||= arg
+              @argument_type = EnumArgument.new(arg.split(","))
+            else
+              named && @argument_name.nil? or parser_error token, "Illegal type expression: #{arg.inspect}"
+              @argument_name = arg
+              @argument_type = StringType.new
+          end
+          @optional = !optional.nil?
+        else
+          @argument_type = StringType.new
+        end
+        super
+      end
+
+    private
+      def basename2ident(s) s.tr("-", "_").to_sym end
+    end
+
+    class Command
+      def parse
+        if parent
+          path_names = token.source.sub("!", "").split(".")
+          @name = path_names.last
+          @path = path_names.map { |cmd| "#{cmd}!".to_sym }
+        else
+          @path = []
+          @name = token.source
+        end
+        super
+      end
+    end
+
+    class Program
+      def self.parse(token)
+        super(nil, token)
+      end
+    end
+
+    class ArgSpec
+      def parse # TODO
+        super
+      end
+    end
+  end
+
+  class Parser
+    using Stack
+    using Ext::Array::ShiftWhile
+
+    # AST root node
+    attr_reader :program
+
+    # Commands by UID
+    attr_reader :commands
+
+    def initialize(tokens)
+      @tokens = tokens.dup # Array of token. Consumed by #parse
+      @nodes = {}
+    end
+
+    def parse()
+      @program = Grammar::Program.parse(@tokens.shift)
+      oneline = @tokens.first.lineno == @tokens.last.lineno
+      nodes = [@program] # Stack of Nodes. Follows the indentation of the source
+      cmds = [@program] # Stack of cmds. Used to keep track of the current command
+
+      while token = @tokens.shift
+        # Unwind stack according to indentation
+        while token.charno <= nodes.top.token.charno
+          node = nodes.pop
+          cmds.pop if cmds.top == node
+          !nodes.empty? or parse_error(token, "Illegal indent")
+        end
+
+        case token.kind
+          when :section
+            Grammar::Section.parse(nodes.top, token)
+
+          when :option
+            # Collect options into option groups if on the same line and not in
+            # oneline mode
+            options = [token] + @tokens.shift_while { |follow| 
+              !oneline && follow.kind == :option && follow.lineno == token.lineno
+            }
+            group = Grammar::OptionGroup.new(cmds.top, token)
+            options.each { |option| Grammar::Option.parse(group, option) }
+            nodes.push group
+
+          when :command
+            parent = nil # Required by #indent
+            token.source =~ /^(?:(.*)\.)?([^.]+)$/
+            parent_id = $1
+            ident = $2.to_sym
+            parent_uid = parent_id && parent_id.sub(".", "!.") + "!"
+
+            # Handle dotted command
+            if parent_uid
+              # Clear stack except for the top-level Program object and then
+              # push command objects in the path
+              #
+              # FIXME: Move to analyzer
+#             cmds = cmds[0..0]
+#             for ident in parent_uid.split(".").map(&:to_sym)
+#               cmds.push cmds.top.commands.find { |c| c.ident == ident } or
+#                   parse_error token, "Unknown command: #{ident.sub(/!/, "")}"
+#             end
+#             parent = cmds.top
+              parent = cmds.top
+              if !cmds.top.is_a?(Grammar::Program) && token.lineno == cmds.top.token.lineno
+                parent = cmds.pop.parent
+              end
+
+            # Regular command
+            else
+              # Don't nest cmds if they are declared on the same line (as it
+              # often happens with one-line declarations). Program is special
+              # cased as its virtual token is on line 0
+              parent = cmds.top
+              if !cmds.top.is_a?(Grammar::Program) && token.lineno == cmds.top.token.lineno
+                parent = cmds.pop.parent
+              end
+            end
+
+            command = Grammar::Command.parse(parent, token)
+            nodes.push command
+            cmds.push command
+
+          when :spec
+            spec = Grammar::ArgSpec.parse(cmds.top, token)
+            @tokens.shift_while { |token| token.kind == :argument }.each { |token|
+              Grammar::Arg.parse(spec, token)
+            }
+
+          when :argument
+            ; raise # Should never happen
+
+          when :usage
+            ; # Do nothing
+
+          when :usage_string
+            Grammar::ArgDescr.parse(cmds.top, token)
+
+          when :text
+            # Text is only allowed on new lines
+            token.lineno > nodes.top.token.lineno
+
+            # Detect indented comment groups (code)
+            if nodes.top.is_a?(Grammar::Paragraph)
+              code = Grammar::Code.parse(nodes.top.parent, token) # Using parent of paragraph
+              @tokens.shift_while { |t|
+                if t.kind == :text && t.charno >= token.charno
+                  code.tokens << t
+                elsif t.kind == :blank && @tokens.first&.kind != :blank # Emit last blank line
+                  if @tokens.first&.charno >= token.charno # But only if it is not the last blank line
+                    code.tokens << t
+                  end
+                else
+                  break
+                end
+              }
+
+            # Detect comment groups (paragraphs)
+            else
+              if nodes.top.is_a?(Grammar::Command) || nodes.top.is_a?(Grammar::OptionGroup)
+                Grammar::Brief.new(nodes.top, token, token.source.sub(/\..*/, "")) if !nodes.top.brief
+                parent = nodes.top 
+              else
+                parent = nodes.top.parent
+              end
+
+              paragraph = Grammar::Paragraph.parse(parent, token)
+              while @tokens.first&.kind == :text && @tokens.first.charno == token.charno
+                paragraph.tokens << @tokens.shift
+              end
+              nodes.push paragraph # Leave paragraph on stack so we can detect code blocks
+            end
+
+          when :brief
+            parent = nodes.top.is_a?(Grammar::Paragraph) ? nodes.top.parent : nodes.top
+            parent.brief.nil? or parse_error token, "Duplicate brief"
+            Grammar::Brief.parse(parent, token)
+
+          when :blank
+            ; # do nothing
+
+        else
+          raise InternalError, "Unexpected token kind: #{token.kind.inspect}"
+        end
+
+        # Skip blank lines
+        @tokens.shift_while { |token| token.kind == :blank }
+      end
+
+      @program
+    end
+
+    def self.parse(tokens)
+      self.new(tokens).parse
+    end
+
+  protected
+    def parse_error(token, message) raise ParserError, token, message end
+  end
+end
+

data/lib/shellopts/program.rb

@@ -0,0 +1,279 @@
+
+# TODO: Create a BasicShellOptsObject with is_a? and operators defined
+#
+module ShellOpts
+  # Command represents a program or a subcommand. It is derived from
+  # BasicObject to have only a minimum of inherited member methods.
+  # Additional methods defined in Command use the  '__<identifier>__' naming
+  # convention that doesn't collide with option or subcommand names but
+  # they're rarely used in application code
+  #
+  # The names of the inherited methods can't be used as options or
+  # command namess. They are: instance_eval, instance_exec method_missing,
+  # singleton_method_added, singleton_method_removed, and
+  # singleton_method_undefined
+  #
+  # Command also defines #subcommand and #subcommand! but they can be
+  # overshadowed by an option or command declaration. Their values can
+  # still be accessed using the dashed name, though
+  #
+  # Options and subcommands can be accessed using #[]
+  #
+  # The following methods are created dynamically for each declared option
+  # with an attribute name
+  #
+  #   def <identifier>(default = nil) self["<identifier>"] || default end
+  #   def <identifier>=(value) self["<identifier>"] = value end
+  #   def <identifier>?() self.key?("<identifier>") end
+  #
+  # Options without an an attribute can still be accessed using #[] or trough
+  # #__options__ or #__options_list__):
+  #
+  # Each subcommand has a single method:
+  #
+  #   # Return the subcommand object or nil if not present
+  #   def <identifier>!() subcommand == :<identifier> ? @__subcommand__ : nil end
+  #
+  # The general #subcommand method can be used to find out which subcommand is
+  # used
+  #
+  class Command < BasicObject
+    define_method(:is_a?, ::Kernel.method(:is_a?))
+
+    # These names can't be used as option or command names
+    RESERVED_OPTION_NAMES = %w(
+        is_a
+        instance_eval instance_exec method_missing singleton_method_added
+        singleton_method_removed singleton_method_undefined)
+
+    # These methods can be overridden by an option (the value is not used -
+    # this is just for informational purposes)
+    OVERRIDEABLE_METHODS = %w(
+        subcommand
+    )
+
+    # Redefine ::new to call #__initialize__
+    def self.new(grammar)
+      object = super()
+      object.__send__(:__initialize__, grammar)
+      object
+    end
+
+    # Return command object or option argument value if present, otherwise nil
+    #
+    # The key is the name or identifier of the object or any any option
+    # alias. Eg.  :f, '-f', :file, or '--file' are all usable as option keys
+    # and :cmd!  or 'cmd' as command keys
+    #
+    # For options, the returned value is the argument given by the user
+    # optionally converted to Integer or Float or nil if the option doesn't
+    # take arguments. If the option takes an argument and it is repeatable
+    # the value is an array of the arguments. Repeatable options without
+    # arguments have the number of occurences as the value
+    #
+    def [](key)
+      case object = __grammar__[key]
+        when ::ShellOpts::Grammar::Command
+          object.ident == __subcommand__!.__ident__ ? __subcommand__! : nil
+        when ::ShellOpts::Grammar::Option
+          __options__[object.ident]
+        else
+          nil
+      end
+    end
+
+    # Assign a value to an existing option. This can be used to implement
+    # default values. #[]= doesn't currently check the type of the given
+    # value so take care. Note that the corresponding option(s) in
+    # #__option_list__ is not updated
+    def []=(key, value)
+      case object = __grammar__[key]
+        when ::ShellOpts::Grammar::Command
+          ::Kernel.raise ArgumentError, "#{key.inspect} is not an option"
+        when ::ShellOpts::Grammar::Option
+          object.argument? || object.repeatable? or
+              ::Kernel.raise ArgumentError, "#{key.inspect} is not assignable"
+          __options__[object.ident] = value
+        else
+          ::Kernel.raise ArgumentError, "Unknown option or command: #{key.inspect}"
+      end
+    end
+
+    # Return true if the given command or option is present
+    def key?(key)
+      case object = __grammar__[key]
+        when ::ShellOpts::Grammar::Command
+          object.ident == __subcommand__!.ident ? __subcommand__! : nil
+        when ::ShellOpts::Grammar::Option
+          __options__.key?(object.ident)
+        else
+          nil
+      end
+    end
+      
+    # Subcommand identifier or nil if not present. #subcommand is often used in
+    # case statement to branch out to code that handles the given subcommand:
+    #
+    #   prog, args = ShellOpts.parse("do_this! do_that!", ARGV)
+    #   case prog.subcommand
+    #     when :do_this!; prog.do_this.operation # or prog[:subcommand!] or prog.subcommand!
+    #     when :do_that!; prog.do_that.operation
+    #   end
+    #
+    # Note: Can be overridden by option, in that case use #__subcommand__ or
+    # ShellOpts.subcommand(object) instead
+    def subcommand() __subcommand__ end
+
+    # The subcommand object or nil if not present. Per-subcommand methods
+    # (#<identifier>!) are often used instead of #subcommand! to get the
+    # subcommand
+    #
+    # Note: Can be overridden by a subcommand declaration (but not an
+    # option), in that case use #__subcommand__! or
+    # ShellOpts.subcommand!(object) instead
+    #
+    def subcommand!() __subcommand__! end
+
+    # The parent command or nil. Initialized by #add_command
+    attr_accessor :__supercommand__
+
+    # UID of command/program
+    def __uid__() @__grammar__.uid end
+
+    # Identfier including the exclamation mark (Symbol)
+    def __ident__() @__grammar__.ident end
+
+    # Name of command/program without the exclamation mark (String)
+    def __name__() @__grammar__.name end
+
+    # Grammar object
+    attr_reader :__grammar__
+
+    # Hash from identifier to value. Can be Integer, Float, or String
+    # depending on the option's type. Repeated options options without
+    # arguments have the number of occurences as the value, with arguments
+    # the value is an array of the given values
+    attr_reader :__options__
+
+    # List of Option objects for the subcommand in the same order as
+    # given by the user but note that options are reordered to come after
+    # their associated subcommand if float is true. Repeated options are not
+    # collapsed
+    attr_reader :__option_list__
+    
+    # The subcommand identifier (a Symbol incl. the exclamation mark) or nil
+    # if not present. Use #subcommand!, or the dynamically generated
+    # '#<identifier>!' method to get the actual subcommand object
+    def __subcommand__() @__subcommand__&.__ident__ end
+
+    # The actual subcommand object or nil if not present
+    def __subcommand__!() @__subcommand__ end
+
+  private
+    def __initialize__(grammar)
+      @__grammar__ = grammar
+      @__options__ = {}
+      @__option_list__ = [] 
+      @__options__ = {}
+      @__subcommand__ = nil
+
+      __define_option_methods__
+    end
+
+    def __define_option_methods__
+      @__grammar__.options.each { |opt|
+        next if opt.attr.nil?
+        if opt.argument? || opt.repeatable?
+          if opt.optional?
+            self.instance_eval %(
+              def #{opt.attr}(default = nil)
+                if @__options__.key?(:#{opt.attr}) 
+                  @__options__[:#{opt.attr}] || default
+                else
+                  nil
+                end
+              end
+            )
+          elsif !opt.argument?
+            self.instance_eval %(
+              def #{opt.attr}(default = nil) 
+                if @__options__.key?(:#{opt.attr})
+                  value = @__options__[:#{opt.attr}] 
+                  value == 0 ? default : value
+                else
+                  nil
+                end
+              end
+            )
+          else
+            self.instance_eval("def #{opt.attr}() @__options__[:#{opt.attr}] end")
+          end
+          self.instance_eval("def #{opt.attr}=(value) @__options__[:#{opt.attr}] = value end")
+          @__options__[opt.attr] = 0 if !opt.argument?
+        end
+        self.instance_eval("def #{opt.attr}?() @__options__.key?(:#{opt.attr}) end")
+      }
+
+      @__grammar__.commands.each { |cmd|
+        next if cmd.attr.nil?
+        self.instance_eval %(
+          def #{cmd.attr}() 
+            :#{cmd.attr} == __subcommand__ ? __subcommand__! : nil
+          end
+        )
+      }
+    end
+
+    def __add_option__(option)
+      ident = option.grammar.ident
+      @__option_list__ << option
+      if option.repeatable?
+        if option.argument?
+          (@__options__[ident] ||= []) << option.argument
+        else
+          @__options__[ident] ||= 0
+          @__options__[ident] += 1
+        end
+      else
+        @__options__[ident] = option.argument
+      end
+    end
+
+    def __add_command__(subcommand)
+      subcommand.__supercommand__ = self
+      @__subcommand__ = subcommand
+    end
+
+    def self.add_option(subcommand, option) subcommand.__send__(:__add_option__, option) end
+    def self.add_command(subcommand, cmd) subcommand.__send__(:__add_command__, cmd) end
+  end
+
+  # The top-level command
+  class Program < Command
+  end
+
+  # Option models an option as given by the user on the subcommand line.
+  # Compiled options (and possibly aggregated) options are stored in the
+  # Command#__options__ array
+  class Option
+    # Associated Grammar::Option object
+    attr_reader :grammar
+
+    # The actual name used on the shell command-line (String)
+    attr_reader :name 
+
+    # Argument value or nil if not present. The value is a String, Integer,
+    # or Float depending the on the type of the option
+    attr_accessor :argument
+
+    forward_to :grammar, 
+        :uid, :ident,
+        :repeatable?, :argument?, :integer?, :float?,
+        :file?, :enum?, :string?, :optional?,
+        :argument_name, :argument_type, :argument_enum
+
+    def initialize(grammar, name, argument)
+      @grammar, @name, @argument = grammar, name, argument
+    end
+  end
+end