ex_aequo 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0499472f115bf5da195d99bdd428ba149cdfdd9aaafa9fcc3142bed9666912c8'
-  data.tar.gz: c5f216790f1eff9d99e779c6e2ca1560f02add2714e7e49286467bdf0a49d34a
+  metadata.gz: 2aaf57df3f78e7ecdd11fdf189a6dbd0942a68d9ec41213713583bebd533c5dd
+  data.tar.gz: 799c05c0d0b4e4f20d736de98017c960e40fc370fabbfce0d3fe5827499cdafa
 SHA512:
-  metadata.gz: e37bb04b1113d2f9dd82736382d3616bccd46e279be3a588bbdb113a34a6788d289d4baf4e2d7c4eaed2340cd4db3b2ea0e4950c278ad6f3435ce6530b7e1e21
-  data.tar.gz: 498f891d7209f9942a121db3d0ee7ae63f7e07399d4a0503ae2880acbf24df4795cdfdd1a75f4f2273a61268db251cf1f565aeb62fcfd6ee4435ddfdf19c6e15
+  metadata.gz: c4ee1ab2d221d3fe055f3e9a4d27c76fef3237af11718a3fef986702f5a08511cb43a30a439fd3e896b8a86d785691d3aab01327dbbca8d54026f6c87292b390
+  data.tar.gz: e038d29057424cf6f2f45139562c060b76221eca5fe6c55eaf3ae0bb0bf58b9b68666122e11d5eedf8aff396c241b1e11f1fa87892ee710e85dd02cdfd883812

data/README.md

@@ -3,15 +3,138 @@
 [![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
+
+... 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 includion 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")
+```
+
 
-Some Tools
 
 
 
-##
 
 ## LICENSE
 

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/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/version.rb

@@ -2,7 +2,7 @@
 
 module ExAequo
   module Version
-    VERSION = '0.1.4'
+    VERSION = '0.2.0'
   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.0
 platform: ruby
 authors:
 - Robert Dober
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-21 00:00:00.000000000 Z
-dependencies: []
+date: 2023-03-26 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,6 +35,8 @@ 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
@@ -32,6 +48,8 @@ files:
 - 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/version.rb
 homepage: https://gitlab.com/robert_dober/rb_ex_aequo
 licenses:
@@ -52,7 +70,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