term_utils 0.2.0 → 0.3.0

data/doc/top-level-namespace.html

@@ -100,7 +100,7 @@
 </div>
 
       <div id="footer">
-  Generated on Thu Oct 17 22:50:57 2019 by
+  Generated on Sun Nov 10 18:36:19 2019 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.20 (ruby-2.6.5).
 </div>

data/lib/term_utils/ap/article.rb

@@ -0,0 +1,68 @@
+# frozen-string-literal: true
+#
+# Copyright (C) 2019 Thomas Baron
+#
+# This file is part of term_utils.
+#
+# term_utils is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3 of the License.
+#
+# term_utils is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# 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.
+    class Article
+      # @return [Symbol]
+      attr_accessor :id
+      # @return [Integer]
+      attr_accessor :min_occurs
+      # @return [Integer]
+      attr_accessor :max_occurs
+      # @return [Symbol] `:integer`, `:string`
+      attr_accessor :type
+      # @return [String] `%d`, `%s`.
+      attr_accessor :format
+      # Constructs a new Article.
+      # @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
+      def initialize(opts = {})
+        @id = opts.fetch(:id, nil)
+        @min_occurs = opts.fetch(:min_occurs, 1)
+        @max_occurs = opts.fetch(:max_occurs, 1)
+        @type = opts.fetch(:type, :string)
+        @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)
+        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))
+      end
+      # Tests whether the number of occurs are fixed.
+      # @return [Boolean]
+      def occur_bounded?
+        (@max_occurs != nil) && (@max_occurs != :infinity) && (@max_occurs.is_a? Integer)
+      end
+    end
+  end
+end

data/lib/term_utils/ap/element.rb

@@ -0,0 +1,78 @@
+# frozen-string-literal: true
+#
+# Copyright (C) 2019 Thomas Baron
+#
+# This file is part of term_utils.
+#
+# term_utils is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3 of the License.
+#
+# term_utils is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# 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 syntax element (abstract).
+    class Element
+      # @return [Symbol]
+      attr_accessor :id
+      # @return [Integer]
+      attr_accessor :min_occurs
+      # @return [Integer]
+      attr_accessor :max_occurs
+      # @return [Array<TermUtils::AP::Flag>]
+      attr_accessor :flags
+      # For dup method.
+      def initialize_dup(other)
+        if other.flags
+          @flags = []
+          other.flags.each do |f|
+            @flags << f.dup
+          end
+        end
+        super
+      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)
+        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))
+      end
+      # Tests whether the number of occurs are fixed.
+      # @return [Boolean]
+      def occur_bounded?
+        (@max_occurs != nil) && (@max_occurs != :infinity) && (@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 opts [Hash]
+      # @option opts [String] :label
+      # @option opts [Symbol] :flavor `:anchor`, `:long`, `:short`.
+      # @return [TermUtils::AP::Flag]
+      def define_flag(opts = {}, &block)
+        new_flag = TermUtils::AP::Flag.new(opts)
+        @flags << new_flag
+        block.call(new_flag) if block
+        new_flag
+      end
+    end
+  end
+end

data/lib/term_utils/ap/flag.rb

@@ -0,0 +1,48 @@
+# frozen-string-literal: true
+#
+# Copyright (C) 2019 Thomas Baron
+#
+# This file is part of term_utils.
+#
+# term_utils is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3 of the License.
+#
+# term_utils is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# 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
+      # 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)
+      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
+      end
+    end
+  end
+end

data/lib/term_utils/ap/level.rb

@@ -0,0 +1,57 @@
+# frozen-string-literal: true
+#
+# Copyright (C) 2019 Thomas Baron
+#
+# This file is part of term_utils.
+#
+# term_utils is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3 of the License.
+#
+# term_utils is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# 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 an argument list subset. It must lead with a Flag. It has its
+    # own syntax.
+    class Level < TermUtils::AP::Element
+      # @return [TermUtils::AP::Syntax]
+      attr_accessor :syntax
+      # Constructs a new Level.
+      # @param opts [Hash]
+      # @option opts [Symbol] :id
+      # @option opts [Integer] :min_occurs Default value is `0`.
+      # @option opts [Integer] :max_occurs Default value is `1`.
+      def initialize(opts = {})
+        @id = opts.fetch(:id, nil)
+        @min_occurs = opts.fetch(:min_occurs, 0)
+        @max_occurs = opts.fetch(:max_occurs, 1)
+        @flags = []
+        @syntax = TermUtils::AP::Syntax.new
+      end
+      # For dup method.
+      def initialize_dup(other)
+        @syntax = other.syntax.dup
+        super
+      end
+      # Finalizes this one. Internal use.
+      # @return [nil]
+      def finalize!(opts = {})
+        super
+        raise TermUtils::AP::SyntaxError, "level must contain at least one flag" if @flags.empty?
+        @syntax.finalize!(opts)
+      end
+      # Defines the syntax.
+      # @return [TermUtils::AP::Syntax]
+      def define_syntax(&block)
+        block.call(@syntax) if block
+        @syntax
+      end
+    end
+  end
+end

data/lib/term_utils/ap/no_such_value_error.rb

@@ -0,0 +1,27 @@
+# frozen-string-literal: true
+#
+# Copyright (C) 2019 Thomas Baron
+#
+# This file is part of term_utils.
+#
+# term_utils is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3 of the License.
+#
+# term_utils is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# 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
+    # No such value error.
+    class NoSuchValueError < StandardError
+      def initialize(msg)
+        super
+      end
+    end
+  end
+end

data/lib/term_utils/ap/parameter.rb

@@ -0,0 +1,75 @@
+# frozen-string-literal: true
+#
+# Copyright (C) 2019 Thomas Baron
+#
+# This file is part of term_utils.
+#
+# term_utils is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3 of the License.
+#
+# term_utils is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# 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>]
+      attr_accessor :articles
+      # Constructs a new Parameter.
+      # @param opts [Hash]
+      # @option opts [Symbol] :id
+      # @option opts [Integer] :min_occurs Default value is `0`.
+      # @option opts [Integer] :max_occurs Default value is `1`.
+      def initialize(opts = {})
+        @id = opts.fetch(:id, nil)
+        @min_occurs = opts.fetch(:min_occurs, 0)
+        @max_occurs = opts.fetch(:max_occurs, 1)
+        @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
+      end
+      # Finalizes this one. Internal use.
+      # @return [nil]
+      def finalize!(opts = {})
+        super
+        @articles.each do |a|
+          a.finalize!(opts)
+        end
+      end
+      # Adds a new Article to this one.
+      # @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)
+        new_article = TermUtils::AP::Article.new(opts)
+        @articles << new_article
+        block.call(new_article) if block
+        new_article
+      end
+      # Fetches all articles.
+      # @return [Array<TermUtils::AP::Article>]
+      def fetch_articles
+        @articles.collect { |a| a.dup }
+      end
+    end
+  end
+end

data/lib/term_utils/ap/parse_error.rb

@@ -0,0 +1,27 @@
+# frozen-string-literal: true
+#
+# Copyright (C) 2019 Thomas Baron
+#
+# This file is part of term_utils.
+#
+# term_utils is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3 of the License.
+#
+# term_utils is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# 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
+    # Parse error.
+    class ParseError < StandardError
+      def initialize(msg)
+        super
+      end
+    end
+  end
+end

data/lib/term_utils/ap/parser.rb

@@ -0,0 +1,185 @@
+# frozen-string-literal: true
+#
+# Copyright (C) 2019 Thomas Baron
+#
+# This file is part of term_utils.
+#
+# term_utils is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, version 3 of the License.
+#
+# term_utils is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# 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
+      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 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 = {})
+        syntax = syntax.dup
+        syntax.finalize!
+        arguments = arguments.dup
+        res = TermUtils::AP::Result.new(syntax)
+        catch :done do
+          parse0(res.value, syntax, arguments, opts)
+        end
+        res
+      end
+      private
+      # Parses a given argument list.
+      # @param node [TermUtils::PropertyTreeNode]
+      # @param syntax [TermUtils::AP::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
+        fp_occ = {}
+        syntax.elements.each { |e| fp_occ[e.id] = 0 if e.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)
+              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
+          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)
+            end
+            catch :param_done do
+              occ = up_occ
+              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
+                up_occ = 0
+              end
+            end
+          end
+        end # loop
+      end
+      def parse0_param(node, param, arguments, opts = {})
+        arts = param.fetch_articles
+        occ = 0
+        loop do
+          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
+          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)
+            arguments.shift
+            arts.shift
+            occ = 0
+            next
+          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
+          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
+      end
+    end
+  end
+end