ex_aequo 0.1.4 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0499472f115bf5da195d99bdd428ba149cdfdd9aaafa9fcc3142bed9666912c8'
-  data.tar.gz: c5f216790f1eff9d99e779c6e2ca1560f02add2714e7e49286467bdf0a49d34a
+  metadata.gz: ecfee3b816360cda72ebf826ecd5f17301eafad003962b860711e8195b7f6ee5
+  data.tar.gz: 80500186030dab2c7ad0cbf37c1dbff0c067a88b90cbb3422c3f2da121f1c45b
 SHA512:
-  metadata.gz: e37bb04b1113d2f9dd82736382d3616bccd46e279be3a588bbdb113a34a6788d289d4baf4e2d7c4eaed2340cd4db3b2ea0e4950c278ad6f3435ce6530b7e1e21
-  data.tar.gz: 498f891d7209f9942a121db3d0ee7ae63f7e07399d4a0503ae2880acbf24df4795cdfdd1a75f4f2273a61268db251cf1f565aeb62fcfd6ee4435ddfdf19c6e15
+  metadata.gz: 950e811e86bcc7d34882ab1a1a00ef9e9d82bfada7cdf98dab119e7df76e4101c8c6b6418f13d05c99dc831149c8e7263c558b2bd642efa9ff80ea137d887d6e
+  data.tar.gz: f395398d33a331e996bb571ee3368aee8a0c648629b77eb9a0e30f87eab841b4dddc5897e5177fdc5a4e6fdfaaef977446f2e772764a54b663b05c03e0eebaba

data/README.md

@@ -3,19 +3,153 @@
 [![Gem Version](https://badge.fury.io/rb/ex_aequo.svg)](http://badge.fury.io/rb/ex_aequo)
 [![Gem Downloads](https://img.shields.io/gem/dt/ex_aequo.svg)](https://rubygems.org/gems/ex_aequo)
 
-# ExAequo
 
-    gem install ex_aequo
+# Some Tools
 
-Some Tools
+... which tools?
 
+Let us [speculate about](https://github.com/RobertDober/speculate_about) that:
 
 
-##
+## Context: MyStruct
+
+All the goodies of `OpenStruct` without the badies:
+
+- Immutable
+- Deconstructable (→ _Patternmatchable_)
+- _Hashy_ Interface (`fetch`, `merge`, `slice`...)
+
+Given an instance of `MyStruct` constructed from a `Hash`
+```ruby
+  require 'ex_aequo/my_struct'
+  let(:from_hash) { MyStruct.new(a: 1, b: 2) }
+```
+And an instance constructed by a reducer
+```ruby
+    let(:incremented) { MyStruct.from_reduce(%i[a b c d e], 0) { _1.succ } }
+```
+Then they can be accessed like a `Hash` or `OpenStruct`
+```ruby
+    expect(from_hash[:a]).to eq(1)
+    expect(from_hash.fetch(:b)).to eq(2)
+    expect(incremented[:e]).to eq(5)
+```
+
+And they are immutable
+```ruby
+  expect { from_hash[:c] = 3 }
+    .to raise_error(MyStruct::ImmutableError, 'cannot change values with []= in immutable instance of MyStruct')
+```
+
+And _mutable_ operations just create new objects
+```ruby
+  expect(from_hash.merge(c: 3)).to eq(MyStruct.new(a: 1, b: 2, c: 3))
+  expect(from_hash.to_h).to eq(a: 1, b: 2)
+```
+
+And the _hashy_ methods observer the same interface
+```ruby
+    expect { from_hash.fetch(:c) }
+      .to raise_error(KeyError, 'key :c not found in #<MyStruct a=1, b=2> and no default given to #fetch')
+
+    expect(from_hash.fetch(:c, 42)).to eq(42)
+    expect(from_hash.fetch(:c) { 43 }).to eq(43)
+
+    expect(incremented.slice(:a, :c, :e)).to eq(MyStruct.new(a: 1, c: 3, e: 5))
+```
+
+## Context: ArgsParser and Args
+
+An expressive, yet simple argument parser that takes full advantage of Ruby 3
+and returns a modern Args struct (with modern I mean MyStruct) as a result.
+
+Given a simple example like this on
+```ruby
+  let(:simple_parser) do
+    ExAequo::ArgsParser.new(
+      allowed: %w[alpha: beta: :help :verbose],
+      aliases: {h: :help, v: :verbose, a: :alpha}
+    )
+  end
+```
+
+Then, as northing is required we can successfully parse empty arguments
+```ruby
+  result = simple_parser.parse([])
+
+  expect(result).to be_ok
+  expect(result.missing).to be_empty
+  expect(result.superflous).to be_empty
+  expect(result.positionals).to be_empty
+  expect(result.keywords).to eq(MyStruct.new)
+```
+
+And, we can also provide allowed values (N.B. ruby sytnax is default)
+```ruby
+  result = simple_parser.parse(%w[alpha: 42 43])
+
+  expect(result).to be_ok
+  expect(result.missing).to be_empty
+  expect(result.superflous).to be_empty
+  expect(result.positionals).to eq(%w[43])
+  expect(result.keywords).to eq(MyStruct.new(alpha: '42'))
+```
+
+## Context: Colors
+
+Given the inclusion of the `Color` module
+```ruby
+  include ExAequo::Color
+```
+
+
+Then we can create ansi colored strings
+```ruby
+  expect(ansi(:red)).to eq("\e[31m")
+```
+
+Or we can create 256 color strings
+```ruby
+  expect(ansi256(100)).to eq("\e[38;5;100m")
+```
+
+Or we can use RGB colors
+```ruby
+  expect(rgb(96,32,16)).to eq("\e[38;2;96;32;16m")
+  expect(rgb('#602010')).to eq("\e[38;2;96;32;16m")
+```
+
+### Context: Colorize Helper
+
+And
+```ruby
+  expect(colorize('red', ansi: :green)).to eq("\e[32mred\e[0m")
+```
+
+Or we can omit the reset
+```ruby
+  expect(colorize('red', ansi: :green, reset: false)).to eq("\e[32mred")
+```
+
+### Context: Colorize Text
+
+Given we include the Color::Text module
+```ruby
+  require 'ex_aequo/color/text'
+  include ExAequo::Color::Text
+```
+
+Then we can obtain a colored text as follows
+```ruby
+   expect(colorized_text(:red, 'green', :yellow, 'blue', :reset, 'white'))
+    .to eq("\e[31mgreen\e[33mblue\e[0mwhite")
+```
+
+## Other Tools are described [here](/speculations)
 
 ## LICENSE
 
-Copyright 2022 Robert Dober robert.dober@gmail.com
+Copyright 202[2,3] Robert Dober robert.dober@gmail.com
 
 Apache-2.0 [c.f LICENSE](LICENSE)
 <!-- SPDX-License-Identifier: Apache-2.0 -->

data/lib/ex_aequo/args.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'my_struct'
+
+module ExAequo
+  class Args
+
+    attr_reader :missing, :positionals, :superflous
+
+    def add_illegal_kwd(kwd)
+      errors << ["Illegal kwd #{kwd}"]
+    end
+
+    def add_kwd(kwd, value)
+      # Constraint Checks would go here
+      @keywords[kwd.to_sym] = value
+      self
+    end
+
+    def add_positional(arg)
+      positionals << arg
+      self
+    end
+
+    def errors
+      @__errors__ ||= []
+    end
+
+    def keywords
+      MyStruct.new(@keywords)
+    end
+
+    def ok?
+      missing.empty? && errors.empty?
+    end
+
+    def set_flag(flag)
+      @keywords[flag.to_sym] = true
+      self
+    end
+
+    private
+
+    attr_reader :aliases, :allowed, :required
+
+    def initialize(aliases: [], allowed: [], required: [])
+      @required = required
+      @allowed  = allowed
+      @required = required
+
+      @bad_syntax = false
+      @keywords   = {}
+      @missing    = []
+      @positionals = []
+      @superflous = []
+    end
+
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/ex_aequo/args_parser.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative 'args'
+
+module ExAequo
+  class ArgsParser
+
+    FlagRgx = %r{\A : .*}x.freeze
+    KwdRgx  = %r{.* : \z}x.freeze
+    def parse(args)
+      result = Args.new(aliases:, allowed:, required:)
+      args.inject([state, result], &_parse).last
+    end
+
+    private
+
+    attr_reader :aliases, :allowed, :posix, :required, :state
+
+    def initialize(aliases: [], allowed: [], posix: false, required: [])
+      @aliases  = aliases
+      @allowed  = allowed
+      @posix    = posix
+      @required = required
+
+      @state    = nil
+    end
+
+    def _parse
+      ->((state, result), arg) do
+        case state
+        in nil
+          _parse_nil(result, arg)
+        in kwd
+          _parse_kwd(kwd, result, arg)
+        end
+      end
+    end
+
+    def _parse_new_flag(flag, result)
+      if allowed.include?(flag)
+        [nil, result.set_flag(flag[1..-1])]
+      else
+        [nil, result.add_illegal_kwd(flag)]
+      end
+    end
+
+    def _parse_new_kwd(kwd, result)
+      if allowed.include?(kwd)
+        [kwd[0...-1], result]
+      else
+        [nil, result.add_illegal_kwd(kwd)]
+      end
+    end
+
+    def _parse_kwd(kwd, result, arg)
+      [nil, result.add_kwd(kwd, arg)]
+    end
+
+    def _parse_nil(result, arg)
+      case arg
+      when FlagRgx
+        _parse_new_flag(arg, result)
+      when KwdRgx
+        _parse_new_kwd(arg, result)
+      else
+        [nil, result.add_positional(arg)]
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/ex_aequo/color/text.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ExAequo
+  module Color
+    module Text extend self
+      
+      AnsiColors =  ExAequo::Color::Ansi::AnsiColorEscape.keys.freeze
+
+      def put_col(*segments, to: $stdout)
+        to.puts(colorized_text(segments))
+      end
+
+      def colorized_text(*segments)
+        if ENV['NO_COLOR']
+          segments.flatten.filter { String === _1 }.join
+        else
+          segments.flatten.map(&_color_or_text).join
+        end
+      end
+
+      private
+
+
+      def _color_or_text
+        -> color_or_text do
+          case color_or_text
+          when Symbol
+            _colorize(color_or_text)
+          else
+            color_or_text
+          end
+        end
+      end
+
+      def _colorize(color)
+        case ExAequo::Color::Ansi::AnsiColorEscape[color]
+        when nil
+          if color == :reset
+            ExAequo::Color.reset
+          else
+            raise ArgumentError, "#{color} not yet implemented"
+          end
+        else
+          ExAequo::Color::Ansi.ansi(color)
+        end
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/ex_aequo/my_struct/class_methods.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class MyStruct < OpenStruct
+  module ClassMethods
+    def from_reduce(keys, acc, &reducer)
+      new(**_from_reduce(keys, acc, &reducer))
+    end
+
+    private
+
+    def _from_reduce(keys, acc, &reducer)
+      keys.map do |key|
+        reducer.(acc, key) => acc
+        [key, acc]
+      end.to_h
+    end
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/ex_aequo/my_struct.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'my_struct/class_methods'
+require 'forwarder'
+class MyStruct < OpenStruct
+  class ImmutableError < RuntimeError; end
+
+  extend ClassMethods
+  extend Forwarder
+
+  # forward :fetch, to: :to_h
+
+  def[]=(*)
+    raise ImmutableError, "cannot change values with []= in immutable instance of #{self.class}"
+  end
+
+  def fetch(*args, &blk)
+    to_h.fetch(*args, &blk)
+  rescue KeyError
+    raise KeyError,
+      "key #{args.first.inspect} not found in #{self} and no default given to #fetch"
+  end
+
+  def merge(with)
+    self.class.new(to_h.merge(with.to_h))
+  end
+
+  def slice(*args)
+    self.class.new(to_h.slice(*args.flatten))
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/ex_aequo/tools/text_scanner.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ExAequo
+  module Tools
+    module TextScanner extend self
+      def scan(str, rgx: '/', ws_at_end: true)
+        r = Regexp === rgx ? r : Regex.compile(rgx)
+        _scan(str, rgx: r, ws_at_end:)
+      end
+
+      private
+      def _scan(str, rgx:, ws_at_end:)
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/ex_aequo/version.rb

@@ -2,7 +2,7 @@
 
 module ExAequo
   module Version
-    VERSION = '0.1.4'
+    VERSION = '0.2.2'
   end
 end
 # SPDX-License-Identifier: Apache-2.0

data/lib/ex_aequo.rb

@@ -2,6 +2,7 @@
 
 module ExAequo
 end
+require_relative 'ex_aequo/args_parser'
 require_relative 'ex_aequo/color'
 require_relative 'ex_aequo/version'
 # SPDX-License-Identifier: Apache-2.0

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: ex_aequo
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.2
 platform: ruby
 authors:
 - Robert Dober
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-21 00:00:00.000000000 Z
-dependencies: []
+date: 2023-04-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: forwarder3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 description: 'Some tools
 
   '
@@ -21,17 +35,23 @@ files:
 - LICENSE
 - README.md
 - lib/ex_aequo.rb
+- lib/ex_aequo/args.rb
+- lib/ex_aequo/args_parser.rb
 - lib/ex_aequo/color.rb
 - lib/ex_aequo/color/ansi.rb
 - lib/ex_aequo/color/ansi256.rb
 - lib/ex_aequo/color/colorizer.rb
 - lib/ex_aequo/color/modifiers.rb
 - lib/ex_aequo/color/rgb.rb
+- lib/ex_aequo/color/text.rb
 - lib/ex_aequo/color/web.rb
 - lib/ex_aequo/colors.rb
 - lib/ex_aequo/kernel.rb
 - lib/ex_aequo/kernel/access.rb
 - lib/ex_aequo/kernel/fn.rb
+- lib/ex_aequo/my_struct.rb
+- lib/ex_aequo/my_struct/class_methods.rb
+- lib/ex_aequo/tools/text_scanner.rb
 - lib/ex_aequo/version.rb
 homepage: https://gitlab.com/robert_dober/rb_ex_aequo
 licenses:
@@ -52,7 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: Some tools