term_utils 0.2.0 → 0.3.0

data/lib/term_utils/ap/result.rb

@@ -0,0 +1,175 @@
+# 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 parsing Result.
+    class Result
+      # @return [TermUtils::PropertyTreeNode]
+      attr_accessor :value
+      # Constructs a new Result.
+      # @param syntax [Darn::AP::Syntax] Syntax.
+      # @param element [Darn::AP::Element] Optional Element.
+      # @param value [Darn::PropertyTreeNode] Optional value.
+      def initialize(syntax, element = nil, value = nil)
+        @syntax = syntax.dup
+        @element = element ? element.dup : nil
+        if value
+          @value = value.dup
+          @value.key = nil
+        else
+          @value = TermUtils::PropertyTreeNode.new
+        end
+      end
+      # Tests whether a given level/parameter/article is present in the result value.
+      # @param id [Symbol, Array<Symbol>]
+      # @return [Boolean]
+      def present?(id)
+        if id.is_a? Symbol
+          !!@value.child_node(id)
+        elsif id.is_a? Array
+          @value.node_exists?(id)
+        end
+      end
+      # Evaluates the number of occurrences of a given level, parameter or article.
+      # @param id [Symbol, Array<Symbol>]
+      # @return [Integer]
+      def eval_occurs(id)
+        id = [id] if id.is_a? Symbol
+        obj = fetch_syntax_object(id)
+        raise TermUtils::AP::NoSuchValueError, "no such syntax object" unless obj
+        node = @value.find_node(id)
+        return 0 unless node
+        return 1 if obj.occur_bounded? && (obj.max_occurs == 1)
+        # Parameter is multiple.
+        node.child_nodes ? node.child_nodes.length : 0
+      end
+      # Fetches a value.
+      # @param id [Symbol, Array<Symbol>, nil]
+      # @param opts [Hash] `:index`, `:multi`.
+      # @option opts [Integer] :index The index of a multiple-occurrence level/parameter/article.
+      # @option opts [Boolean] :multi Whether an array of values shall be returned instead of a single value.
+      # @return [Object]
+      # @raise [TermUtils::AP::NoSuchValueError]
+      def fetch_value(id, opts = {})
+        index = opts.fetch(:index, nil)
+        multi = opts.fetch(:multi, false)
+        unless id
+          node = @value
+          if node && node.child_nodes && index
+            node = node.child_node(index)
+          end
+          raise TermUtils::AP::NoSuchValueError, "no such value" unless node
+          vals = node.collect_values
+          raise TermUtils::AP::NoSuchValueError, "no such value" if vals.empty?
+          return multi ? vals : vals.first
+        end
+        id = [id] if id.is_a? Symbol
+        obj = fetch_syntax_object(id)
+        raise TermUtils::AP::NoSuchValueError, "no such syntax object" unless obj
+        node = @value.find_node(id)
+        if node && node.child_nodes && index
+          node = node.child_node(index)
+        end
+        raise TermUtils::AP::NoSuchValueError, "no such value" unless node
+        catch :value do
+          if obj.is_a? TermUtils::AP::Parameter
+            raise TermUtils::AP::NoSuchValueError, "parameter has no article" if obj.articles.empty?
+            raise TermUtils::AP::NoSuchValueError, "no such value" if node.leaf?
+            vals = node.collect_values
+            raise TermUtils::AP::NoSuchValueError, "no such value" if vals.empty?
+            if multi
+              throw :value, vals
+            else
+              throw :value, vals.first
+            end
+          elsif obj.is_a? TermUtils::AP::Article
+            # raise TermUtils::AP::NoSuchValueError, "no such value" if node.leaf?
+            vals = node.collect_values
+            raise TermUtils::AP::NoSuchValueError, "no such value" if vals.empty?
+            if multi
+              throw :value, vals
+            else
+              throw :value, vals.first
+            end
+          end
+          raise  TermUtils::AP::NoSuchValueError, "wrong id"
+        end
+      end
+      # Shifts this one.
+      # @param id [Symbol, Array<Symbol>]
+      # @param opts [Hash] `:index`, `:multi`.
+      # @option opts [Integer] :index The index of a multiple-occurrence level/parameter/article.
+      # @return [TermUtils::AP::Result]
+      # @raise [TermUtils::AP::NoSuchValueError]
+      def shift(id, opts = {})
+        index = opts.fetch(:index, nil)
+        id = [id] if id.is_a? Symbol
+        obj = fetch_syntax_object(id)
+        raise TermUtils::AP::NoSuchValueError, "no such syntax object" unless obj
+        node = @value.find_node(id)
+        if node && node.child_nodes && index
+          node = node.child_node(index)
+        end
+        raise TermUtils::AP::NoSuchValueError, "no such value" unless node
+        catch :value do
+          if obj.is_a? TermUtils::AP::Level
+            throw :value, TermUtils::AP::Result.new(obj.syntax, nil, node)
+          elsif obj.is_a? TermUtils::AP::Parameter
+            throw :value, TermUtils::AP::Result.new(@syntax, obj, node)
+          elsif obj.is_a? TermUtils::AP::Article
+            throw :value, TermUtils::AP::Result.new(@syntax, obj, node)
+          end
+          raise  TermUtils::AP::NoSuchValueError, "wrong id"
+        end
+      end
+      private
+      # Fetches a given syntax object.
+      # @param id_path [Array<Symbol>]
+      # @return [TermUtils::AP::Level, TermUtils::AP::Parameter, TermUtils::AP::Article, nil]
+      def fetch_syntax_object(id_path)
+        id = id_path.dup
+        id = [@element.id].concat(id) if @element
+        catch :done do
+          fetch_syntax_object0(@syntax, id)
+        end
+      end
+      # Fetches a given syntax object.
+      # @param syntax [TermUtils::AP::Syntax]
+      # @param id_path [Array<Symbol>]
+      # @return [TermUtils::AP::Level, TermUtils::AP::Parameter, TermUtils::AP::Article, nil]
+      def fetch_syntax_object0(syntax, id_path)
+        id = id_path.shift
+        syntax.elements.each do |e|
+          next unless e.id == id
+          throw :done, e if id_path.empty?
+          if e.is_a? TermUtils::AP::Level
+            fetch_syntax_object0(e.syntax, id_path)
+          elsif e.is_a? TermUtils::AP::Parameter
+            throw :done if id_path.empty?
+            id = id_path.shift
+            throw :done unless id_path.empty?
+            e.articles.each do |a|
+              throw :done, a if a.id = id
+            end
+            throw :done
+          end
+        end
+      end
+    end
+  end
+end

data/lib/term_utils/ap/syntax.rb

@@ -0,0 +1,112 @@
+# 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 syntax. It holds a list of parameters and
+    # levels.
+    class Syntax
+      # @return [Array<TermUtils::AP::Element>]
+      attr_accessor :elements
+      # Constructs a new Syntax.
+      def initialize
+        @elements = []
+      end
+      # For dup method.
+      def initialize_dup(other)
+        if other.elements
+          @elements = []
+          other.elements.each do |e|
+            @elements << e.dup
+          end
+        end
+        super
+      end
+      # Finalizes this one. Internal use.
+      # @return [nil]
+      def finalize!(opts = {})
+        opts[:anonymous] = 0 unless opts.has_key? :anonymous
+        @elements.each { |e| e.finalize!(opts) }
+      end
+      # Creates and adds 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`.
+      # @return [TermUtils::AP::Parameter]
+      def define_parameter(opts = {}, &block)
+        new_parameter = TermUtils::AP::Parameter.new(opts)
+        @elements << new_parameter
+        block.call(new_parameter) if block
+        new_parameter
+      end
+      # Creates and adds 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`.
+      # @return [TermUtils::AP::Level]
+      def define_level(opts = {}, &block)
+        new_level = TermUtils::AP::Level.new(opts)
+        @elements << new_level
+        block.call(new_level) if block
+        new_level
+      end
+      # Fetches all direct flagged parameters and levels.
+      # @return [Array]
+      # @see TermUtils::AP::Syntax#fetch_flagged_elements
+      # @see TermUtils::AP::Syntax#fetch_unflagged_parameters
+      def fetch_elements
+        flagged_elems = {}
+        unflagged_params = []
+        @elements.each do |e|
+          if e.flags.empty?
+            # Parameter
+            unflagged_params << e
+          else
+            # Parameter or Level
+            e.flags.each do |f|
+              flagged_elems[f.to_s] = e
+            end
+          end
+        end
+        [flagged_elems, unflagged_params]
+      end
+      # Fetches all direct flagged parameters and levels.
+      # @return [Hash<String, TermUtils::AP::Element>]
+      def fetch_flagged_elements
+        elems = {}
+        @elements.each do |e|
+          e.flags.each do |f|
+            elems[f.to_s] = e
+          end
+        end
+        elems
+      end
+      # Fetches all direct unflagged.
+      # @return [Array<TermUtils::AP::Parameter>]
+      def fetch_unflagged_parameters
+        params = []
+        @elements.each do |e|
+          next unless e.is_a? TermUtils::AP::Parameter
+          params << e if e.flags.empty?
+        end
+        params
+      end
+    end
+  end
+end

data/lib/term_utils/ap/syntax_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
+    # Syntax error.
+    class SyntaxError < StandardError
+      def initialize(msg)
+        super
+      end
+    end
+  end
+end

data/lib/term_utils/ap.rb

@@ -0,0 +1,59 @@
+# 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/>.
+require 'term_utils/property_tree_node'
+require 'term_utils/ap/no_such_value_error'
+require 'term_utils/ap/parse_error'
+require 'term_utils/ap/syntax_error'
+require 'term_utils/ap/article'
+require 'term_utils/ap/flag'
+require 'term_utils/ap/element'
+require 'term_utils/ap/level'
+require 'term_utils/ap/parameter'
+require 'term_utils/ap/syntax'
+require 'term_utils/ap/result'
+require 'term_utils/ap/parser'
+module TermUtils
+  # The Argument Parser module provides a way to parse command arguments.
+  module AP
+    # Creates a new Syntax.
+    # @return [TermUtils::AP::Syntax]
+    def self.create_syntax(&block)
+      new_syntax = TermUtils::AP::Syntax.new
+      block.call(new_syntax) if block
+      new_syntax
+    end
+    # Parses a given command.
+    # @param syntax [TermUtils::AP::Syntax]
+    # @param command [String]
+    # @param opts [Hash]
+    # @return [TermUtils::AP::Result]
+    # @raise [TermUtils::AP::ParseError]
+    # @raise [TermUtils::AP::SyntaxError]
+    def self.parse_command(syntax, command, opts = {})
+      TermUtils::AP::Parser.new.parse_command(syntax, command, opts)
+    end
+    # Parses a given list of arguments.
+    # @param syntax [TermUtils::AP::Syntax]
+    # @param arguments [Array<String>]
+    # @param opts [Hash]
+    # @return [TermUtils::AP::Result]
+    # @raise [TermUtils::AP::ParseError]
+    # @raise [TermUtils::AP::SyntaxError]
+    def self.parse_arguments(syntax, arguments, opts = {})
+      TermUtils::AP::Parser.new.parse_arguments(syntax, arguments, opts)
+    end
+  end
+end

data/lib/term_utils/property_tree_node.rb

@@ -0,0 +1,200 @@
+# 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
+  # Represents a general-purpose tree node that holds a key-value pair.
+  class PropertyTreeNode
+    # @return [TermUtils::PropertyTreeNode]
+    attr_accessor :parent_node
+    # @return [Array<TermUtils::PropertyTreeNode>]
+    attr_accessor :child_nodes
+    # @return [Object]
+    attr_accessor :key
+    # @return [Object]
+    attr_accessor :value
+    # Creates a new node.
+    # @param opts [Hash<Symbol, Object>]
+    # option opts [Object] :key
+    # option opts [Object] :value
+    def initialize(opts = {}, &block)
+      @parent_node = nil
+      @child_nodes = nil
+      @key = opts.fetch(:key, nil)
+      @value = opts.fetch(:value, nil)
+      block.call(self) if block
+    end
+    # For dup method.
+    def initialize_dup(other)
+      @parent_node = nil
+      if other.child_nodes
+        @child_nodes = []
+        other.child_nodes.each do |n|
+          new_node = n.dup
+          new_node.parent_node = self
+          @child_nodes << new_node
+        end
+      end
+      super
+    end
+    # Tests whether this one is the head of the tree (i.e. has no parent).
+    # @return [Boolean]
+    def head?
+      @parent_node == nil
+    end
+    # Tests whether this one is a leaf of the tree (i.e. has no child).
+    # @return [Boolean]
+    def leaf?
+      @child_nodes == nil
+    end
+    # Returns the child node identified by a given key.
+    # @param key [Object]
+    # @return [TermUtils::PropertyTreeNode, nil]
+    def child_node(key)
+      if @child_nodes
+        @child_nodes.find { |n| n.key == key }
+      end
+    end
+    # Creates a new node and adds it as a child.
+    # @param opts [Hash<Symbol,Object>] key value
+    # @return [TermUtils::PropertyTreeNode]
+    def define_node(opts = {}, &block)
+      new_node = TermUtils::PropertyTreeNode.new(opts)
+      new_node.parent_node = self
+      @child_nodes = [] unless @child_nodes
+      @child_nodes << new_node
+      block.call(new_node) if block
+      new_node
+    end
+    # Builds the path of keys.
+    # @return [Array<Object>]
+    def path
+      p = @parent_node ? @parent_node.path : []
+      p << @key if @key
+      p
+    end
+    # Iterates over every node.
+    # @param opts [Hash<Symbol,Object>] `:path`, `:leaf_only`
+    # @return [nil]
+    def each_node(opts = {}, &block)
+      rpath = nil
+      if opts.has_key? :path
+        rpath = opts[:path].dup
+      end
+      dive = true
+      if @key
+        hide = false
+        if rpath
+          if rpath.shift == @key
+            unless rpath.empty?
+              hide = true
+            end
+          else
+            dive = false
+            hide = true
+          end
+        end
+        unless hide or (opts[:leaf_only] and @child_nodes)
+          if opts.has_key? :block
+            opts[:block].call(self)
+          elsif block
+            block.call(self)
+          end
+        end
+      end # if @key
+      if dive and @child_nodes
+        ropts = opts.dup
+        if rpath
+          if rpath.empty?
+            ropts.delete :path
+          else
+            ropts[:path] = rpath
+          end
+        end
+        if block
+          ropts[:block] = block
+        end
+        @child_nodes.each do |n|
+          n.each_node(ropts)
+        end
+      end
+      nil
+    end
+    # Collects nodes.
+    # @param opts [Hash<Symbol,Object>] `:path`, `:leaf_only`
+    # @return [Array<TermUtils::PropertyTreeNode>]
+    def collect_nodes(opts = {})
+      nodes = []
+      each_node(opts) do |n|
+        nodes << n
+      end
+      nodes
+    end
+    # Collects node paths.
+    # @param opts [Hash<Symbol,Object>] `:path`, `:leaf_only`
+    # @return [Array<Array<Object>>]
+    def collect_paths(opts = {})
+      paths = []
+      each_node(opts) do |n|
+        paths << n.path
+      end
+      paths
+    end
+    # Collect node values.
+    # @param opts [Hash<Symbol,Object>] `:path`, `:leaf_only`
+    # @return [Array<Object>]
+    def collect_values(opts = {})
+      vals = []
+      each_node(opts) do |n|
+        vals << n.value if n.value
+      end
+      vals
+    end
+    # Finds the node identified by a given path of keys.
+    # @param path [Array<Object>]
+    # @return [TermUtils::PropertyTreeNode]
+    def find_node(path)
+      catch :found do
+        each_node(:path => path) do |n|
+          throw :found, n
+        end
+        nil
+      end
+    end
+    # Tests whether the node identified by a given path of keys exists.
+    # @param path [Array<Object>]
+    # @return [Boolean]
+    def node_exists?(path)
+      find_node(path) != nil
+    end
+    # Evaluates the total number of nodes in the tree represented by this one.
+    # @param path [Array<Object>]
+    # @return [Integer]
+    def eval_child_count(path)
+      node = find_node(path)
+      if node
+        node.child_nodes ? node.child_nodes.length : 0
+      end
+    end
+    # Finds the node identified by a given path of keys and returns its value.
+    # @param path [Array<Object>]
+    # @return [Object]
+    def find_node_value(path)
+      node = find_node(path)
+      if node
+        node.value
+      end
+    end
+  end
+end

data/lib/term_utils.rb

@@ -13,5 +13,6 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with term_utils.  If not, see <https://www.gnu.org/licenses/>.
+require 'term_utils/ap'
 require 'term_utils/ff'
 require 'term_utils/tab'

data/term_utils.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name         = "term_utils"
-  s.version      = "0.2.0"
-  s.date         = "2019-10-17"
+  s.version      = "0.3.0"
+  s.date         = "2019-11-10"
   s.summary      = "Terminal utilities."
   s.description  = <<-EOS
 Provides terminal utilities like table formatting.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: term_utils
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Thomas Baron
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-17 00:00:00.000000000 Z
+date: 2019-11-10 00:00:00.000000000 Z
 dependencies: []
 description: 'Provides terminal utilities like table formatting.
 
@@ -24,11 +24,25 @@ files:
 - README.md
 - Rakefile
 - doc/TermUtils.html
+- doc/TermUtils/AP.html
+- doc/TermUtils/AP/Article.html
+- doc/TermUtils/AP/Element.html
+- doc/TermUtils/AP/Flag.html
+- doc/TermUtils/AP/Level.html
+- doc/TermUtils/AP/NoSuchValueError.html
+- doc/TermUtils/AP/Parameter.html
+- doc/TermUtils/AP/ParseError.html
+- doc/TermUtils/AP/Parser.html
+- doc/TermUtils/AP/Result.html
+- doc/TermUtils/AP/ResultView.html
+- doc/TermUtils/AP/Syntax.html
+- doc/TermUtils/AP/SyntaxError.html
 - doc/TermUtils/FF.html
 - doc/TermUtils/FF/Config.html
 - doc/TermUtils/FF/Cursor.html
 - doc/TermUtils/FF/Cursor/Context.html
 - doc/TermUtils/FF/Query.html
+- doc/TermUtils/PropertyTreeNode.html
 - doc/TermUtils/Tab.html
 - doc/TermUtils/Tab/Column.html
 - doc/TermUtils/Tab/Holder.html
@@ -49,10 +63,23 @@ files:
 - doc/method_list.html
 - doc/top-level-namespace.html
 - lib/term_utils.rb
+- lib/term_utils/ap.rb
+- lib/term_utils/ap/article.rb
+- lib/term_utils/ap/element.rb
+- lib/term_utils/ap/flag.rb
+- lib/term_utils/ap/level.rb
+- lib/term_utils/ap/no_such_value_error.rb
+- lib/term_utils/ap/parameter.rb
+- lib/term_utils/ap/parse_error.rb
+- lib/term_utils/ap/parser.rb
+- lib/term_utils/ap/result.rb
+- lib/term_utils/ap/syntax.rb
+- lib/term_utils/ap/syntax_error.rb
 - lib/term_utils/ff.rb
 - lib/term_utils/ff/config.rb
 - lib/term_utils/ff/cursor.rb
 - lib/term_utils/ff/query.rb
+- lib/term_utils/property_tree_node.rb
 - lib/term_utils/tab.rb
 - term_utils.gemspec
 homepage: https://git.yellowcube.net/tvb/term_utils