flex_args 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef1ef86d73320f89eba86a8e982f3b7d24724ccdfe0d085ac2a9ac674485b79e
-  data.tar.gz: 0f554da437841db0d31aee39352d15db3e6480b95bcbcf8755ac5dcf77d84cbb
+  metadata.gz: 5700aa1d881f51e7f2f44d30075e68367202e010ec71779193042f7efea70d95
+  data.tar.gz: aa46d04734fed4cf7776c3fe0c18c8fad391f5dc66a446c4fc664b8284deec79
 SHA512:
-  metadata.gz: f745f4e480196273b41b4db03742f3ba1a8d1a1d4b645d81b2aa976a30b7709c7971871ab6edea421d0575878c24de931055c60a39b20f54adbb1dc8bba201b9
-  data.tar.gz: 74e53271bf7ca6699ea7dbf47b2bf31602e3ae2a8b8fbb1595d58d0e94ddb1970f1ff1087b83946f0169af025c0d4e346cb81f66a8b5f4c878c9f226587c8b2c
+  metadata.gz: bc38f0a24e8d3589adacadabfeac2e1dfa7ce84ec2bd7b9def3fa6d2ef5bc2159ac1856136da273ea8a0f34c072ecfbb7008925544f9c27dec93edbf37206791
+  data.tar.gz: c349ad91b2f10bb6b463d88388cd34c7f48fba0c736de18754545b88f6aa0f02f5ec60e39ea685537046cf6629bae9188b12531935a98f2bd7db37b8902223da

data/.rdoc_options

@@ -0,0 +1,27 @@
+---
+encoding: UTF-8
+static_path: []
+rdoc_include: []
+page_dir:
+apply_default_exclude: true
+autolink_excluded_words: []
+charset: UTF-8
+class_module_path_prefix:
+embed_mixins: false
+exclude: [tmp/*]
+file_path_prefix:
+hyperlink_all: false
+line_numbers: false
+locale_dir: locale
+locale_name:
+main_page:
+markup: markdown
+output_decoration: true
+show_hash: false
+skip_tests: true
+tab_width: 8
+template_stylesheets: []
+title:
+visibility: :protected
+warn_missing_rdoc_ref: true
+webcvs:

data/lib/flex_args/constraint.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+class FlexArgs
+  class Constraint
+
+    attr_reader :name
+
+    ##
+    # ## Creates a new constraint for the value argument named `name`
+    #
+    # Constraints can be many, which is indicated by the first element
+    # in the `constraints` list, or a constraint can be indicated by
+    # a custom made block.
+    #
+    # The available constraints are:
+    #
+    # ### `Regexp` constraint
+    #
+    # These rdoc_specs show the interface that the `FlexArgs::Parser` uses
+    # to validate constraints, the class is therefore part of the public
+    # API and can be used in isolation where it serves.
+    #
+    # ```spec # regexp
+    #     new(:for_some_value, %r{x}).("x") => [:ok, "x"]
+    #     new(:for_some_value, %r{x}).("y") => [:error, "regexp constraint for_some_value: (?-mix:x) violated by value \"y\""]
+    # ```
+    #
+    # ### `Range` constraint
+    #  
+    # ```spec # range
+    #     new(:for_some_int, 1..9).("1") => [:ok, 1]
+    #     new(:for_some_int, 1..9).("0") => [:error, "range constraint for_some_int: 1..9 violated by value \"0\""]
+    #     new(:for_some_int, 1..9).("y") => [:error, "range constraint for_some_int: 1..9 violated by value \"y\""]
+    #     
+    # ```
+    # ### Custom constraint
+    #
+    # This is easily implemented by passing a block which will return a pair as described above, but also note
+    # two more features of the custom constraint
+    #
+    # - exceptions will be caught and transformed into an error, thusly simplyfing the code block:
+    # - and values can be transformed
+    #
+    # ```spec # custom
+    #    constraint = new :even do
+    #      value = Integer(it)
+    #      value.even? ? [:ok, value / 2] : [:error, "not even"]
+    #    end
+    #
+    #    expect(constraint.("84")).to eq([:ok, 42])
+    #    expect(constraint.("21")).to eq([:error, "custom constraint even: violated by value \"21\" with message: \"not even\""])
+    #   
+    #    exception_message = '"invalid value for Integer(): \\"abc\\" (ArgumentError)"'
+    #    complete_message = "custom constraint even: violated by value \"abc\" with message: #{exception_message}"
+    #    expect(constraint.("abc")).to eq([:error, complete_message])
+    # ```
+    #
+    # Also note that the correct format of the block's return value is important
+    #
+    # ```spec # enforce correct format of custom constraint's block
+    #    constraint = new(:bad) { 42 }
+    #    
+    #    expect { constraint.(nil) }
+    #     .to raise_error(ArgumentError, "badly formatted custom block for custom constraint bad returned 42, needed [:ok|:error, value_or_message]")
+    # ```
+    #
+    def initialize(name, *constraints, &block)
+      @name = name
+      case constraints
+      in [Regexp => constraint]
+        _init_regexp(name, constraint)
+      in [Range => range]
+        _init_range(name, range)
+      else
+        raise ArgumentError,
+          "illegal constraint spec #{constraints.inspect} for value #{name}" unless block
+        _init_custom(name, &block)
+      end
+    end
+
+    def call(value)
+      @constrainer.(value)
+    end
+
+    private
+
+    def _init_custom(name, &block)
+      bad_format = false
+      @constrainer = -> value do
+        case block.(value)
+        in [:error, message]
+          _make_error(:custom, name, nil, value, message)
+        in [:ok, _] => result
+          result
+        in result 
+          bad_format = true
+          raise ArgumentError, "badly formatted custom block for custom constraint #{name} returned #{result.inspect}, needed [:ok|:error, value_or_message]"
+        end
+      rescue Exception => e
+        raise if bad_format
+        _make_error(:custom, name, nil, value, "#{e.message} (#{e.class})")
+      end
+    end
+
+    def _init_range(name, range)
+      @constrainer = -> value do
+        case _to_int(value)
+        in [:ok, int_val]
+          if range === int_val
+            [:ok, int_val]
+          else
+            _make_error(:range, name, range, value)
+          end
+        else
+          _make_error(:range, name, range, value)
+        end
+      end
+    end
+
+    def _init_regexp(name, constraint)
+      @constrainer = -> value do
+        if constraint.match?(value)
+          [:ok, value]
+        else
+          [:error, "regexp constraint #{name}: #{constraint} violated by value #{value.inspect}"]
+        end
+      end
+    end
+
+    def _make_error(type, name, constraint_desc, value, message = nil)
+      message = [
+        type,
+        "constraint",
+        "#{name}:",
+        constraint_desc,
+        "violated by value",
+        value.inspect,
+        (message ? "with message: #{message.inspect}" : nil)
+      ].compact.join(" ")
+      [:error, message]
+    end
+
+    def _to_int(value)
+      [:ok, Integer(value)]
+    rescue ArgumentError
+      :error
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/flex_args/enumerable.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Enumerable
+  def reduce_while(init, tag=nil, &block)
+    result = 
+      reduce(init) do |i, e|
+        case block.(i, e)
+        in [:halt, value]
+          return value
+        in [:cont, value]
+          value
+        end
+      end
+
+    tag ? [tag, result] : result
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/flex_args/parser.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative 'enumerable'
+
+class FlexArgs
+  class Parser
+    attr_reader :args, :errors, :flags, :flex_args, :positionals, :values_from_args
+
+    ESCAPED_COMMA = "a4ey8NGnXIVhsV"
+    DIGITS = %r{\A [-+]? \d+ \z}x
+    MANY_FLAGS = %r{\A - (.*) \z}x
+    RANGE = %r{\A [-+]? \d+ \.\. [-+]? \d+ \z}x
+    SINGLE_FLAG = %r{\A -- (.*) \z}x
+    VALUE = %r{\A ([[:alpha:]][[:alnum:]_]*) : (.*) \z}x
+
+    def parse(args)
+      init_values
+      args.each { parse_arg it }
+      return [:ok, result] if errors.empty?
+
+      [:error, errors]
+    end
+
+    private
+    def initialize(flex_args)
+      @flex_args = flex_args
+      init_values
+    end
+
+    def add_flags(shorts)
+      shorts.each do
+        flag = flex_args.alias_definitions.fetch(it, it)
+        flags << flag.to_sym
+      end
+    end
+
+    def add_value(matches)
+      matches => [key, value]
+      key = key.to_sym
+      check_allowed!(key)
+      case check_constraints!(key, value)
+      in [:error, message]
+        errors << message
+      in [:ok, value]
+        values_from_args
+          .update(key => cast_all(value)) do |k, o, n|
+            Array(o) << n
+          end
+      end
+    end
+
+    def cast(value)
+      case value
+      when RANGE
+        Range.new(*value.split("..").map(&:to_i))
+      when DIGITS
+        value.to_i
+      else
+        value.gsub(ESCAPED_COMMA, ",")
+      end
+    end
+
+    def cast_all(value)
+      return value unless String === value
+      value = value.gsub(",,", ESCAPED_COMMA)
+      values =
+        value
+        .split(",")
+        .map { cast it }
+      values.one? ? values.first : values
+    end
+
+    def check_allowed!(key)
+      errors << "unallowed value arg #{key}:" unless flex_args.allowed?(key)
+    end
+
+    def check_constraints!(key, value)
+      constraints = flex_args.constraints(key)
+      constraints.reduce_while(value, :ok) do |v, constraint|
+        case constraint.(v)
+        in [:ok, val]
+          [:cont, val]
+        in [:error, message]
+          [:halt, [:error, message]]
+        end
+      end
+    end
+
+    def init_values
+      @errors = []
+      @flags = Set.new
+      @positionals = []
+      @values_from_args = Hash.new
+    end
+
+    def parse_arg(arg)
+      # require "debug"; binding.break
+      case arg
+      when SINGLE_FLAG
+        flags << Regexp.last_match[1].to_sym
+      when MANY_FLAGS
+        add_flags(Regexp.last_match[1].grapheme_clusters)
+      when VALUE
+        add_value(Regexp.last_match)
+      else
+        positionals << arg
+      end
+    end
+
+    def result
+      OpenStruct.new(
+        positionals: positionals,
+        flags: flags,
+        values: values,
+      )
+    end
+
+    def values
+      flex_args
+        .default_values
+        .merge(values_from_args)
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/flex_args/version.rb

@@ -2,7 +2,7 @@
 
 class FlexArgs
   module Version
-    VERSION="0.1.0"
+    VERSION="0.1.2"
   end
 end
 # SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/flex_args.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'ostruct'
+require_relative 'flex_args/constraint'
+require_relative 'flex_args/parser'
 
 ##
 # ## Abstract
@@ -14,11 +16,11 @@ require 'ostruct'
 # ### Positional arguments
 #
 # Are all arguments that do not:
-#   
+#
 #   - start with a `-`
 #   - contain any of the following characters: `:,`
 #   - contain the string `".."`
-# 
+#
 # Therefore the following arguments will be parsed as
 #
 # ```spec # Only default positional arguments
@@ -31,7 +33,7 @@ require 'ostruct'
 # ```spec # Flags and positionals
 #   args = parse(%w[hello --verbose -world 42])
 #   expect(args.positionals).to eq(%w[hello 42])
-#   expect(args.flags).to eq(Set.new(["verbose", "w", "o", "r", "l", "d"]))
+#   expect(args.flags).to eq(Set.new(%i[verbose w o r l d]))
 # ```
 # ### Value arguments
 #
@@ -52,7 +54,7 @@ require 'ostruct'
 #   parsed = parse(input)
 #   expect(parsed.positionals).to eq(["a/b.rb"])
 #   expect(parsed.values).to eq(range: -2..3, offset: 3)
-#   expect(parsed.flags).to eq(Set.new(["V"]))
+#   expect(parsed.flags).to eq(Set.new([:V]))
 # ```
 #
 # #### Lists
@@ -96,21 +98,19 @@ require 'ostruct'
 #
 class FlexArgs
 
-  ESCAPED_COMMA = "a4ey8NGnXIVhsV" 
-  DIGITS = %r{\A [-+]? \d+ \z}x
-  MANY_FLAGS = %r{\A - (.*) \z}x
-  RANGE = %r{\A [-+]? \d+ \.\. [-+]? \d+ \z}x
-  SINGLE_FLAG = %r{\A -- (.*) \z}x
-  VALUE = %r{\A ([[:alpha:]][[:alnum:]_]+) : (.*) \z}x
-
-  attr_reader :alias_definitions, :flags, :positionals, :result, :values
+  attr_reader :alias_definitions, :default_values, :result
 
   def parse(args)
-    init_values
-    args.each { parse_arg it }
-    result
+    result = Parser.new(self).parse(args)
+    case result
+    in [:ok, result1]
+      result1
+    in [:error, errors]
+      raise ArgumentError, errors.join("\n")
+    end
   end
 
+
   ##
   #
   # ## Aliases are defined by passing a hash
@@ -136,78 +136,140 @@ class FlexArgs
     self
   end
 
-  private
-  def initialize
-    @alias_definitions = Hash.new
-    init_values
+  ##
+  # ## Allowed values and flags
+  #
+  # As soon as this method is called the parser will
+  # check that **all** values in args are allowed
+  #
+  # Values are either identified by their name (a `Symbol`)
+  # or by their name and default value (a pair of `Symbol` and
+  # any value
+  #
+  # ```spec
+  #   parser = FlexArgs
+  #     .new
+  #     .allow(:min, [:max, 3])
+  #
+  #   expect(parser.parse(%w[min:1]).values)
+  #     .to eq(min: 1, max: 3)
+  # ```
+  # 
+  # Therefore the following args are illegal and an `ArgumentError`
+  # is raised
+  #
+  # ```spec # Argument Error for unallowed value
+  #   expect do
+  #     FlexArgs
+  #       .new
+  #       .allow(:n)
+  #       .parse(%w[a:2])
+  #   end
+  #     .to raise_error(
+  #       ArgumentError,
+  #       "unallowed value arg a:"
+  #     )
+  #   
+  # ```
+  # 
+  def allow(*values)
+    values.each { allow_value it }
+    self
   end
 
-  def add_flags(shorts)
-    shorts.each do
-      flag = alias_definitions.fetch(it, it)
-      flags << flag
-    end
+  def allowed?(value)
+    return true unless @allowed_values
+    @allowed_values.member?(value)
   end
 
-  def add_value(matches)
-    matches => [key, value]
-    values
-      .update(key.to_sym => cast_all(value)) do |k, o, n|
-        Array(o) << n
-      end
-  end
+  def constraints(key) = @constraints[key]
 
-  def cast(value)
-    case value
-    when RANGE
-      Range.new(*value.split("..").map(&:to_i))
-    when DIGITS
-      value.to_i
-    else
-      value.gsub(ESCAPED_COMMA, ",")
-    end
+  ##
+  # ## Constraints
+  #
+  #  Constraints are defined with the `constraint` method.
+  #  
+  #  **N.B.** defined Constraints **after** allow unless you
+  #  want to explicitly add the value arg with `allow`
+  #  
+  # ### Simple forms
+  #
+  # #### Regexp constraint
+  #
+  # ```spec # regexp constraints
+  #    parser = FlexArgs
+  #               .new
+  #               .constrain(:n, %r{\A \d+ \z}x)
+  #
+  #   expect(parser.parse(%w[n:42]).values).to eq(n: 42)
+  #
+  #   expect { parser.parse(%w[n:42a]) }
+  #     .to raise_error(ArgumentError, 'regexp constraint n: (?x-mi:\A \d+ \z) violated by value "42a"')
+  #
+  # ```
+  #
+  # #### Range constraints
+  #
+  # ```spec # range constraints
+  #     parser = FlexArgs
+  #                .new
+  #                .constrain(:n, 2..3)
+  #
+  #   expect(parser.parse(%w[n:2]).values).to eq(n: 2)
+  #
+  #   expect { parser.parse(%w[n:42a]) }
+  #     .to raise_error(ArgumentError, 'range constraint n: 2..3 violated by value "42a"')
+  #
+  #   expect { parser.parse(%w[n:42]) }
+  #     .to raise_error(ArgumentError, 'range constraint n: 2..3 violated by value "42"')
+  #
+  # ```
+  #
+  # Please find the documentation about more constraints [here](Constraint.html)
+  #
+  def constrain(value, *constraints, &block)
+    @allowed_values << value.to_sym if @allowed_values
+    @constraints[value.to_sym] << Constraint.new(value, *constraints, &block)
+    self
   end
 
-  def cast_all(value)
-    value = value.gsub(",,", ESCAPED_COMMA)
-    values = 
-      value
-      .split(",")
-      .map { cast it }
-    values.one? ? values.first : values
+  ##
+  #
+  # Just returns the parsed values, or their default values if
+  # a default was provided and the value was not present in
+  # the provided arguments.
+  def values
+    default_values.merge(values_from_args)
   end
 
-  def define_alias(short, long)
-    alias_definitions.update(short => long)
+  private
+  def initialize
+    @alias_definitions = Hash.new
+    @allowed_values = nil
+    @constraints = Hash.new { |h, k| h[k] = [] }  
+    @default_values = Hash.new
   end
 
-  def init_values
-    @positionals = []
-    @flags = Set.new
-    @values = Hash.new
+  def add_default_value(name, value)
+    default_values.update(name => value)
   end
 
-
-  def parse_arg(arg)
-    # require "debug"; binding.break
-    case arg
-    when SINGLE_FLAG
-      flags << Regexp.last_match[1]
-    when MANY_FLAGS
-      add_flags(Regexp.last_match[1].grapheme_clusters)
-    when VALUE
-      add_value(Regexp.last_match)
-    else
-      positionals << arg
+  def allow_value(value_def)
+    @allowed_values ||= Set.new
+    case value_def
+    in Symbol
+      @allowed_values << value_def
+    in [Symbol => value_name, default_value]
+      @allowed_values << value_name
+      add_default_value(value_name, default_value)
+    in _
+      raise ArgumentError, "arg must be of format Symbol or [Symbol, value], but was #{value_def}"
     end
   end
 
-  def result
-    OpenStruct.new(
-      positionals: positionals,
-      flags: flags,
-      values: values,
-    )
+  def define_alias(short, long)
+    alias_definitions.update(short => long)
   end
+
 end
 # SPDX-License-Identifier: AGPL-3.0-or-later

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flex_args
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Robert Dober
@@ -31,9 +31,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".rdoc_options"
 - LICENSE
 - README.md
 - lib/flex_args.rb
+- lib/flex_args/constraint.rb
+- lib/flex_args/enumerable.rb
+- lib/flex_args/parser.rb
 - lib/flex_args/version.rb
 homepage: https://codeberg.org/lab419/flex_args
 licenses: