term_utils 0.3.2 → 0.5.0

data/doc/top-level-namespace.html

@@ -6,15 +6,15 @@
 <title>
   Top Level Namespace
   
-    &mdash; Documentation by YARD 0.9.20
+    &mdash; Documentation by YARD 0.9.34
   
 </title>
 
-  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/style.css" type="text/css" />
 
-  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" />
 
-<script type="text/javascript" charset="utf-8">
+<script type="text/javascript">
   pathId = "";
   relpath = '';
 </script>
@@ -100,9 +100,9 @@
 </div>
 
       <div id="footer">
-  Generated on Fri Feb  7 18:54:38 2020 by
-  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.20 (ruby-2.6.5).
+  Generated on Wed Aug  9 17:34:25 2023 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.34 (ruby-3.2.2).
 </div>
 
     </div>

data/lib/term_utils/ap/article.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
-#
-# Copyright (C) 2019 Thomas Baron
+# frozen_string_literal: true
+
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -15,6 +15,7 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with term_utils.  If not, see <https://www.gnu.org/licenses/>.
+
 module TermUtils
   module AP
     # Represents a Article.
@@ -29,6 +30,7 @@ module TermUtils
       attr_accessor :type
       # @return [String] `%d`, `%s`.
       attr_accessor :format
+
       # Constructs a new Article.
       # @param opts [Hash]
       # @option opts [Symbol] :id
@@ -41,27 +43,31 @@ module TermUtils
         @min_occurs = opts.fetch(:min_occurs, 1)
         @max_occurs = opts.fetch(:max_occurs, 1)
         @type = opts.fetch(:type, :string)
-        @format = opts.fetch(:format, "%s")
+        @format = opts.fetch(:format, '%s')
       end
+
       # Finalizes this one. Internal use.
       # @return [nil]
       def finalize!(opts = {})
-        raise TermUtils::AP::SyntaxError, "min_occurs must be equal or greater than 0" unless (@min_occurs.is_a? Integer) && (@min_occurs >= 0)
-        raise TermUtils::AP::SyntaxError, "max_occurs must be equal or greater than min_occurs" unless !occur_bounded? || (@max_occurs >= @min_occurs)
+        raise TermUtils::AP::SyntaxError, 'min_occurs must be equal or greater than 0' if !@min_occurs.is_a?(Integer) || (@min_occurs < 0)
+        raise TermUtils::AP::SyntaxError, 'max_occurs must be equal or greater than min_occurs' if occur_bounded? && (@max_occurs < @min_occurs)
+
         unless @id
           opts[:anonymous] += 1
           @id = "anonymous#{opts[:anonymous]}".intern
         end
       end
+
       # Tests whether this one has mutiple occurs.
       # @return [Boolean]
       def multiple_occurs?
-        (@max_occurs == nil) || (@max_occurs == :infinity) || ((@max_occurs.is_a? Integer) && (@max_occurs > 1))
+        (@max_occurs == nil) || (@max_occurs.is_a?(Integer) && (@max_occurs > 1))
       end
-      # Tests whether the number of occurs are fixed.
+
+      # Tests whether the number of occurs is fixed.
       # @return [Boolean]
       def occur_bounded?
-        (@max_occurs != nil) && (@max_occurs != :infinity) && (@max_occurs.is_a? Integer)
+        (@max_occurs != nil) && @max_occurs.is_a?(Integer)
       end
     end
   end

data/lib/term_utils/ap/flag.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
-#
-# Copyright (C) 2019 Thomas Baron
+# frozen_string_literal: true
+
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -15,33 +15,50 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with term_utils.  If not, see <https://www.gnu.org/licenses/>.
+
 module TermUtils
   module AP
     # Represents a Flag.
     class Flag
       # @return [String]
-      attr_accessor :label
-      # @return [Symbol] `:anchor`, `:long`, `:short`.
-      attr_accessor :flavor
+      attr_reader :label
+      # @return [Symbol] `:long`, `:short`.
+      attr_reader :flavor
+
       # Constructs a new Flag.
-      # @param opts [Hash]
-      # @option opts [String] :label
-      # @option opts [Symbol] :flavor `:anchor`, `:long`, `:short`.
-      def initialize(opts = {})
-        @label = opts.fetch(:label, nil)
-        @flavor = opts.fetch(:flavor, nil)
+      # @param label [String]
+      # @param flavor [Symbol] `:short`, `:long`.
+      def initialize(label, flavor)
+        raise TermUtils::AP::SyntaxError, 'wrong flag label' if !label.is_a?(String) || /^-+$/.match?(label) || !/^-[0-9A-Za-z_-]+$/.match?(label)
+        raise TermUtils::AP::SyntaxError, '' unless %i[short long].include?(flavor)
+
+        @label = label
+        @flavor = flavor
+      end
+
+      # Tests whether this one is equal to a given Flag.
+      def ==(other)
+        return false unless other.is_a?(TermUtils::AP::Flag)
+
+        @label == other.label
+      end
+
+      # Tests whether this one represents a long flag.
+      # @return [Boolean]
+      def long?
+        @flavor == :long
+      end
+
+      # Tests whether this one represents a short flag.
+      # @return [Boolean]
+      def short?
+        @flavor == :short
       end
+
       # Returns the string representation of this one.
       # @return [String]
       def to_s
-        case @flavor
-        when :anchor
-          @label
-        when :long
-          "--%s" % @label
-        when :short
-          "-%s" % @label
-        end
+        @label
       end
     end
   end

data/lib/term_utils/ap/parameter.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
-#
-# Copyright (C) 2019 Thomas Baron
+# frozen_string_literal: true
+
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -15,12 +15,22 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with term_utils.  If not, see <https://www.gnu.org/licenses/>.
+
 module TermUtils
   module AP
     # Represents a Parameter.
-    class Parameter < TermUtils::AP::Element
-      # @return [Array<TermUtils::AP::Article>]
+    class Parameter
+      # @return [Symbol]
+      attr_accessor :id
+      # @return [Integer]
+      attr_accessor :min_occurs
+      # @return [Integer]
+      attr_accessor :max_occurs
+      # @return [Array<Flag>]
+      attr_accessor :flags
+      # @return [Array<Article>]
       attr_accessor :articles
+
       # Constructs a new Parameter.
       # @param opts [Hash]
       # @option opts [Symbol] :id
@@ -33,42 +43,101 @@ module TermUtils
         @flags = []
         @articles = []
       end
+
       # For dup method.
       def initialize_dup(other)
-        if other.articles
-          @articles = []
-          other.articles.each do |a|
-            @articles << a.dup
-          end
-        end
-        super
+        super(other)
+        @flags = other.flags.map(&:dup) if other.flags
+        @articles = other.articles.map(&:dup) if other.articles
       end
+
       # Finalizes this one. Internal use.
       # @return [nil]
+      # @raise [SyntaxError]
       def finalize!(opts = {})
-        super
-        @articles.each do |a|
-          a.finalize!(opts)
+        raise TermUtils::AP::SyntaxError, 'min_occurs must be equal or greater than 0' if !@min_occurs.is_a?(Integer) || (@min_occurs < 0)
+        raise TermUtils::AP::SyntaxError, 'max_occurs must be equal or greater than min_occurs' if occur_bounded? && (@max_occurs < @min_occurs)
+        raise TermUtils::AP::SyntaxError, 'empty' if @flags.empty? && @articles.empty?
+
+        unless @id
+          opts[:anonymous] += 1
+          @id = "anonymous#{opts[:anonymous]}".intern
         end
+        @flags.each do |f|
+          raise TermUtils::AP::SyntaxError, 'duplicate flag label' if opts[:flag_labels].include?(f.to_s)
+
+          opts[:flag_labels] << f.to_s
+        end
+        @articles.each { |a| a.finalize!(opts) }
+        nil
+      end
+
+      # Tests whether this one has mutiple occurs.
+      # @return [Boolean]
+      def multiple_occurs?
+        (@max_occurs == nil) || (@max_occurs.is_a?(Integer) && (@max_occurs > 1))
+      end
+
+      # Tests whether the number of occurs is fixed.
+      # @return [Boolean]
+      def occur_bounded?
+        (@max_occurs != nil) && @max_occurs.is_a?(Integer)
       end
+
+      # Tests whether this one is flagged.
+      # @return [Boolean]
+      def flagged?
+        !@flags.empty?
+      end
+
+      # Adds a new Flag to this one.
+      # @param label [String]
+      # @return [Flag]
+      def define_flag(label, &block)
+        flavor = (label.length == 2) ? :short : :long
+        new_flag = TermUtils::AP::Flag.new(label, flavor)
+        raise TermUtils::AP::SyntaxError, 'duplicate flag label' if @flags.include? new_flag
+
+        @flags << new_flag
+        block.call(new_flag) if block
+        new_flag
+      end
+
       # Adds a new Article to this one.
+      # @param id [Symbol, nil]
       # @param opts [Hash]
       # @option opts [Symbol] :id
       # @option opts [Integer] :min_occurs Default value is `1`.
       # @option opts [Integer] :max_occurs Default value is `1`.
       # @option opts [Symbol] :type `:integer`, `:string`.
       # @option opts [Symbol] :format
-      # @return [TermUtils::AP::Article]
-      def define_article(opts = {}, &block)
+      # @return [Article]
+      def define_article(id = nil, opts = {}, &block)
+        if id
+          art = @articles.find { |p| p.id == id }
+          if art
+            block.call(art) if block
+            return art
+          end
+
+          opts[:id] = id
+        end
         new_article = TermUtils::AP::Article.new(opts)
         @articles << new_article
         block.call(new_article) if block
         new_article
       end
+
+      # Fetches all flags.
+      # @return [Array<Flag>]
+      def fetch_flags
+        @flags.dup
+      end
+
       # Fetches all articles.
-      # @return [Array<TermUtils::AP::Article>]
+      # @return [Array<Article>]
       def fetch_articles
-        @articles.collect { |a| a.dup }
+        @articles.collect(&:dup)
       end
     end
   end

data/lib/term_utils/ap/parser.rb

@@ -1,6 +1,6 @@
-# frozen-string-literal: true
-#
-# Copyright (C) 2019 Thomas Baron
+# frozen_string_literal: true
+
+# Copyright (C) 2023 Thomas Baron
 #
 # This file is part of term_utils.
 #
@@ -15,170 +15,197 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with term_utils.  If not, see <https://www.gnu.org/licenses/>.
+
 module TermUtils
   module AP
     # Represents the argument list parser.
     class Parser
+      # Constructs a new Parser.
       def initialize
       end
-      # Parses a given command.
-      # @param syntax [TermUtils::AP::Syntax]
-      # @param command [String]
-      # @param opts [Hash] `:program`.
-      # @option opts [Boolean] :program Whether the first argument is the program name.
-      # @return [TermUtils::AP::Result]
-      # @raise [TermUtils::AP::ParseError]
-      # @raise [TermUtils::AP::SyntaxError]
-      def parse_command(syntax, command, opts = {})
-        parse_arguments(syntax, command.split(" "), opts)
-      end
+
       # Parses a given list of arguments.
-      # @param syntax [TermUtils::AP::Syntax]
+      # @param syntax [Syntax]
       # @param arguments [Array<String>]
-      # @param opts [Hash] `:program`.
-      # @option opts [Boolean] :program Whether the first argument is the program name.
-      # @return [TermUtils::AP::Result]
-      # @raise [TermUtils::AP::ParseError]
-      # @raise [TermUtils::AP::SyntaxError]
-      def parse_arguments(syntax, arguments, opts = {})
+      # @param opts [Hash<Symbol, Object>]
+      # @option opts [Boolean] :strict Whether the Syntax must be considered as strict.
+      # @return [Result]
+      # @raise [ParseError]
+      # @raise [SyntaxError]
+      def parse_arguments(syntax, arguments, opts = {}, &block)
         syntax = syntax.dup
         syntax.finalize!
         arguments = arguments.dup
         res = TermUtils::AP::Result.new(syntax)
         catch :done do
-          parse0(res.value, syntax, arguments, opts)
+          parse0(res, syntax, arguments, opts)
         end
+        res.remaining_arguments = arguments
+        res.walk(&block) if block
         res
       end
+
+      # Tests whether a given sample matches a shortcut flag.
+      # @param shortcut_flags [Hash<String, Flag>]
+      # @param arg [String]
+      # @return [Array<String>, nil] Replacements on success, nil otherwise.
+      def self.match_shortcut_flag(shortcut_flags, arg)
+        shortcut_flags.each do |label, flag|
+          next unless arg.start_with? label
+
+          return [flag.label, arg[label.length..]]
+        end
+
+        nil
+      end
+
+      # Evaluates the added number of min occurs of a given array of articles.
+      # @param articles [Array<TermUtils::AP::Article>]
+      # @return [Integer]
+      def self.eval_article_min_occurs(articles)
+        articles.inject(0) { |acc, a| acc + a.min_occurs }
+      end
+
       private
+
       # Parses a given argument list.
-      # @param node [TermUtils::PropertyTreeNode]
-      # @param syntax [TermUtils::AP::Syntax]
+      # @param result [Result]
+      # @param syntax [Syntax]
       # @param arguments [Array<String>]
-      def parse0(node, syntax, arguments, opts = {})
-        # puts "parse0"
-        opts = opts.dup
-        if opts[:program]
-          arguments.shift
-          opts.delete :program
-        end
-        throw :done if arguments.empty?
-        flagged_elems, unflagged_params = syntax.fetch_elements
+      # @raise [ParseError]
+      def parse0(result, syntax, arguments, opts = {})
+        unflagged_params, flagged_params, shortcut_flags = syntax.fetch_parameters
         fp_occ = {}
-        syntax.elements.each { |e| fp_occ[e.id] = 0 if e.flagged? }
+        syntax.parameters.each { |p| fp_occ[p.id] = 0 if p.flagged? }
         up_occ = 0
         loop do
           break if arguments.empty?
-          # puts "# %s" % arguments.first
-          if arguments.first === "---"
-            arguments.shift
-            break
-          end
-          if flagged_elems.has_key? arguments.first
-            # Flagged parameter/level.
-            elem = flagged_elems[arguments.first]
-            raise TermUtils::AP::ParseError, "parameter reached its occur limit" if elem.occur_bounded? && (fp_occ[elem.id] >= elem.max_occurs)
-            fp_occ[elem.id] += 1
-            if elem.is_a? TermUtils::AP::Parameter
-              arguments.shift
-              sub_node = node.child_node(elem.id)
-              sub_node = node.define_node(:key => elem.id) unless sub_node
-              if elem.multiple_occurs?
-                sub_node.child_nodes = [] if sub_node.leaf?
-                idx = sub_node.child_nodes.length
-                sub_node = sub_node.define_node(:key => idx)
-              end
-              catch :param_done do
-                parse0_param(sub_node, elem, arguments, opts)
+
+          if arguments.first.start_with?('-') && !%w[- --].include?(arguments.first)
+            # Flagged
+            unless flagged_params.key? arguments.first
+              # Unknown flag
+              # Try shortcut flag
+              flag, arg = self.class.match_shortcut_flag(shortcut_flags, arguments.first)
+              if flag && arg
+                # Shortcut match
+                arguments.shift
+                arguments.unshift arg
+                arguments.unshift flag
               end
-            elsif elem.is_a? TermUtils::AP::Level
-              arguments.shift
-              sub_node = node.child_node(elem.id)
-              sub_node = node.define_node(:key => elem.id) unless sub_node
-              if elem.multiple_occurs?
-                sub_node.child_nodes = [] if sub_node.leaf?
-                idx = sub_node.child_nodes.length
-                sub_node = sub_node.define_node(:key => idx)
-              end
-              parse0(sub_node, elem.syntax, arguments, opts)
-            else
-              raise TermUtils::AP::ParseError, "internal error - wrong kind of syntax element"
             end
+            unless flagged_params.key? arguments.first
+              # Unknown flag
+              # End of parsing
+              raise TermUtils::AP::ParseError.new(message: 'flagged parameter unexpected', fault: arguments.first) if opts.fetch(:strict, false)
+
+              break
+            end
+
+            param = flagged_params[arguments.first]
+            if param.occur_bounded? && (fp_occ[param.id] >= param.max_occurs)
+              # Max occurs reached
+              raise TermUtils::AP::ParseError.new(message: 'occur limit reached', parameter: param.id, fault: arguments.first) if opts.fetch(:strict, false)
+
+              break
+            end
+
+            fp_occ[param.id] += 1
+            arguments.shift
+            param_res = TermUtils::AP::ParameterResult.new(result, param)
+            parse0_param(param_res, param, arguments)
           else
-            # Unflagged parameter.
-            raise TermUtils::AP::ParseError, "unexpected unflagged parameter" if unflagged_params.empty?
-            raise TermUtils::AP::ParseError, "unexpected flagged parameter" if arguments.first.start_with? "-"
-            elem = unflagged_params.shift
-            sub_node = node.child_node(elem.id)
-            sub_node = node.define_node(:key => elem.id) unless sub_node
-            if elem.multiple_occurs?
-              sub_node.child_nodes = [] if sub_node.leaf?
-              idx = sub_node.child_nodes.length
-              sub_node = sub_node.define_node(:key => idx)
+            # Unflagged
+            if unflagged_params.empty?
+              # End of parsing
+              raise TermUtils::AP::ParseError.new(message: 'unflagged parameter unexpected', fault: arguments.first) if opts.fetch(:strict, false)
+
+              break
             end
-            catch :param_done do
-              occ = up_occ
+
+            param = unflagged_params.first
+            if arguments.first == '--'
+              # End of parameter
+              raise TermUtils::AP::ParseError.new(message: 'parameter not consumed', parameter: param.id) if up_occ < param.min_occurs
+
+              arguments.shift
+              unflagged_params.shift
               up_occ = 0
-              parse0_param(sub_node, elem, arguments, opts)
-              up_occ = occ
-              up_occ += 1
-              if elem.multiple_occurs? && (!elem.occur_bounded? || (up_occ < elem.max_occurs))
-                unflagged_params.unshift elem
-              else
+              next
+            end
+
+            up_occ += 1
+            param_res = TermUtils::AP::ParameterResult.new(result, param)
+            case parse0_param(param_res, param, arguments)
+            when :esc_param
+              raise TermUtils::AP::ParseError.new(message: 'parameter not consumed', parameter: param.id) if up_occ < param.min_occurs
+
+              unflagged_params.shift
+              up_occ = 0
+            else
+              if !param.multiple_occurs? || (param.occur_bounded? && (up_occ >= param.max_occurs))
+                unflagged_params.shift
                 up_occ = 0
               end
             end
           end
         end # loop
+        # Check min occurs
+        syntax.parameters.each do |p|
+          next if result.find_parameters(p.id).length >= p.min_occurs
+
+          raise TermUtils::AP::ParseError.new(message: 'parameter not consumed', parameter: p.id)
+        end
       end
-      def parse0_param(node, param, arguments, opts = {})
+
+      # Parses with a given Parameter.
+      # @param result [ParameterResult]
+      # @param param [Parameter]
+      # @param arguments [Array<String>]
+      # @return [Symbol, nil] `:esc_param`, or nil.
+      def parse0_param(result, param, arguments)
         arts = param.fetch_articles
         occ = 0
         loop do
+          break if arts.empty?
+
           if arguments.empty?
-            raise TermUtils::AP::ParseError, "unexpected end of parameter" if !arts.empty? && (occ < arts.first.min_occurs)
-            raise TermUtils::AP::ParseError, "unexpected end of parameter" if !arts.empty? && (self.class.eval_article_min_occurs(arts[1..-1]) > 0)
-            throw :done
+            # End of arguments
+            raise TermUtils::AP::ParseError.new(message: 'article not consumed', parameter: param.id) if occ < arts.first.min_occurs
+            raise TermUtils::AP::ParseError.new(message: 'article not consumed', parameter: param.id) if self.class.eval_article_min_occurs(arts[1..]) > 0
+
+            break
           end
-          break if arts.empty?
-          if arguments.first == "--"
-            # End of parameter.
-            raise TermUtils::AP::ParseError, "unexpected end of parameter" if !arts.empty? && (occ < arts.first.min_occurs)
-            raise TermUtils::AP::ParseError, "unexpected end of parameter" if !arts.empty? && (self.class.eval_article_min_occurs(arts[1..-1]) > 0)
-            arguments.shift
-            throw :param_done
-          elsif arguments.first == "-"
-            # End of article.
-            raise TermUtils::AP::ParseError, "unexpected article escape" if arts.empty?
-            raise TermUtils::AP::ParseError, "unexpected end of parameter" if !arts.empty? && (occ < arts.first.min_occurs)
+
+          if arguments.first == '-'
+            # End of article
+            raise TermUtils::AP::ParseError.new(message: 'article not consumed', parameter: param.id) if occ < arts.first.min_occurs
+
             arguments.shift
             arts.shift
             occ = 0
             next
+          elsif arguments.first.start_with? '-'
+            # End of parameter
+            raise TermUtils::AP::ParseError.new(message: 'article not consumed', parameter: param.id) if occ < arts.first.min_occurs
+            raise TermUtils::AP::ParseError.new(message: 'article not consumed', parameter: param.id) if self.class.eval_article_min_occurs(arts[1..]) > 0
+
+            if arguments.first == '--'
+              arguments.shift
+              return :esc_param
+            end
+
+            break
           end
           art = arts.first
-          sub_node = node.child_node(art.id)
-          sub_node = node.define_node(:key => art.id) unless sub_node
-          if art.multiple_occurs?
-            sub_node.child_nodes = [] if sub_node.leaf?
-            idx = sub_node.child_nodes.length
-            sub_node = sub_node.define_node(:key => idx)
-          end
-          sub_node.value = arguments.shift
+          TermUtils::AP::ArticleResult.new(result, art, arguments.shift)
           occ += 1
           if !art.multiple_occurs? || (art.occur_bounded? && (occ >= art.max_occurs))
             arts.shift
             occ = 0
           end
         end # loop
-      end
-      # Evaluates the added number of min occurs of a given array of articles.
-      # @param articles [Array<TermUtils::AP::Article>]
-      # @return [Integer]
-      def self.eval_article_min_occurs(articles)
-        occs = 0
-        articles.each { |a| occs += a.min_occurs }
-        occs
+        nil
       end
     end
   end