kdict 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 495fd2e9c4e09c817dde4723b7f6aa49ebfb16827514fa5a644b1ef55aae7473
+  data.tar.gz: b256e6b5abf92224ebac083ac5e68a3eab341f521666c9c240ee679364436fac
+SHA512:
+  metadata.gz: bab14be49b5d1c74a372e66c79af2aeaf70e4269590fb2cc26d1948f5b18f7d4930b6df4579a1c7ae22a9f9731c7acda5e469549fb588b37bd145307afd37b34
+  data.tar.gz: 7f01a700d43f2593b05997519cfa2ae9b0112fbc90b8a88bfc9fe3c8db2b7e7fc9ed1dc409161498b00427a3d8e8ca698b38faefa75c7f5196d060779f2ebd59

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/pkg/
+/spec/reports/
+/tmp/
+
+/testing.rb
+/testing2.rb
+/kdict.code-workspace
+/startup.md
+/.directory
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.2
+before_install: gem install bundler -v 2.0.1

data/.yardopts

@@ -0,0 +1,3 @@
+-
+--output-dir docs
+docs/Example1.md

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at stkterry@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in kdict.gemspec
+gem 'pry'
+gem 'yard'
+gemspec

data/Gemfile.lock

@@ -0,0 +1,43 @@
+PATH
+  remote: .
+  specs:
+    kdict (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.2)
+    diff-lcs (1.3)
+    method_source (0.9.2)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rake (10.5.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    yard (0.9.19)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  kdict!
+  pry
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  yard
+
+BUNDLED WITH
+   2.0.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 atomyc-py
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,301 @@
+# KDict - A Kwarg Dictionary
+
+KDict allows you to quickly create powerful Keyword-Argument Dictionaries.  Each
+entry can be used to validate a user's input against it, and is built from a
+generic type defintion (*typedef*) and a unique structure (*struct*).
+
+With the included *typedefs* users can create simple to complex validaters in
+just a single line of code.
+
+Examples avaible here in the README don't offer up the full scope of usefulness,
+so take the time to look at the example documentation in the full docs page.
+
+View full docs at: https://stkterry.github.io/KDict/
+
+View source code at: https://github.com/stkterry/KDict/
+
+{file:doc/Example1.md}
+
+*Note: I'm very new to Ruby, less than a month in, as it were.  I suspect this thing might change quite a bit
+  as I better familiarize myself with everything.*
+
+***
+
+### KwargDict
+This class defines a new, empty dictionary which can be filled with KwargModels.
+The class inherits Hash.
+#### Initialization:
+```ruby
+kdict = KwargDict.new
+```
+
+#### Adding Models to the Dictionary:
+Each entry in the dictionary gets a name and the appropriate parameters used to
+construct a KwargModel.
+As an example the following definitions might be used in an app where the user is
+allowed to modify a label, it's fontsize, it's color, and x_data for a graph.
+
+```ruby
+kdict[:label] = :typeof, String
+kdict[:fontsize] = :typeof, Integer
+kdict[:rgb] = :formof, [Integer]*3, Proc.new { |n| n.ibetween?(0, 255) }
+kdict[:x_data] = :arrayof, Float
+
+# Or if you prefer a single command
+kdict.add([:one, :typeof, Bool], [:two, :kwargsof, anotherKwargModel],
+  [:three, :anyof, ['this', 'or', 'that']]) # ... etc.
+```
+#### KwargModel Structure
+Each entry in the dictionary is defined by its name and by two or three parameters.
+
+  * **type** - The model's generic type
+  * **struct** - The model's structure/definition
+  * **prc** - An optional Proc that increases specificity of the model's defintion.
+    * *not all typedefs allow for an optional Proc*
+
+#### Checking Input Against the Dictionary:
+In the user's main code, one need only provide a single line to test input
+
+```ruby
+kdict.check(:label, "Is This A Good Label?") # => true
+kdict.check(:lable, "A mispelled kword") # => false
+kdict.check(:fontsize, 16) # => true
+kdict.check(:fontsize, '16') # => false
+kdict.check(:rgb, [125, 0, 223]) # => true
+kdict.check(:rgb, [256, 0, 192]) # => false
+kdict.check(:rgb, [125, 0]) # => false
+kdict.check(:x_data, [1.3, 2.5, 4.0, 11.1]) # => true
+#... etc.
+```
+***
+
+### Where Is This Useful?
+Any application that might have a large number of optional parameters across
+several different methods, such as graphing libs and user-databases.
+
+#### Example Implementation Snippet:
+A user made want to format strings and pass them on to an interpreter or other application.
+
+```ruby
+class MyFigure
+  include TextKwargs # <- A predefined KwargDict (text_dict) would be included in this module.
+  attr_reader :my_params
+  def initialize(title)
+    @title = title
+    @my_params = {}
+  end
+
+  def set_some_params(*kwords_vals)
+    kwords_vals.each_slice(2) do |kword, val|
+      @my_params[kword] = val if text_dict.check(kword, val)
+    end
+  end
+end
+
+fig = MyFigure.new("It Came From Outer Space!")
+fig.set_some_params(:fontsize, 11, :fontfamily, 'sans', :bold, true, :fontname, 'Georiga')
+```
+How users treat validated or failed parameters from here is left to the imagination.
+
+***
+
+### Anatomy of a KwargModel:
+#### Typedef and Struct
+
+Each *typedef* is actually a method built to handle a particular kind of *struct*, while
+each *struct* is what makes an instance of KwargModel unique.  Some *typedefs* will
+only allow for a specific set of *struct* values while others are more flexible.  There are just
+eight *typedef* methods, though you can easily make your own.
+
+#### ***:typeof*** 
+Your *struct* contains a singular value of exactly one datatype.
+
+* ***structs*** - Some of Ruby's built-in types plus *Bool*, an added datatype for 
+  true/false collectively.  Acceptable *struct* arguments then, are: **Numeric, Float, Integer, Bool, String, Symbol**
+* Can accept a Proc that must also return true for successful validation
+
+```ruby
+my_dict[:example] = :typeof, Bool
+my_dict.check(:example, false) # => true
+my_dict.check(:example, true) # => true
+
+my_dict[:proc_example] = :typeof, Float, Proc.new { |n| n > 5.3 }
+my_dict.check(:proc_example, 2.1) # => false
+my_dict.check(:proc_example, 5.4) # => true
+my_dict.check(:proc_example, 6) # => false ... note that 6 > 5.3 but 6 is not datatype Float
+```
+***
+
+#### ***:arrayof***
+Your *struct* contains an array of any length but contains only one datatype.
+
+* ***structs*** - Again some of Ruby's built-in types plus Bool: **Numeric, Float, Integer, Bool, String, Symbol**
+* Multi-dimensional arrays will be treated as flattened and all values will still
+be checked against the given *struct*
+* Can accept a Proc that must return true for ALL values in the array.
+
+```ruby
+my_dict[:example] = :arrayof, Strings
+my_dict.check(:example, ['This', 'will', 'return', 'true']) # => true
+my_dict.check(:example, ['This', 'is', 'false', 4.7]) # => false
+
+my_dict[:proc_example] = :arrayof, Strings, Proc.new { |s| s.length > 2 }
+my_dict.check(:proc_example, ['This', 'will', 'return', 'true']) # => true
+my_dict.check(:proc_example, ['This', 'is', 'still', 'false']) # => false
+```
+***
+
+#### ***:anyof***
+Your *struct* contains a singular element that can be found in an array.
+
+* ***structs*** - An array of any mix of things you'd like, EXCEPT other instances of KwargModels or KwargDicts.
+* Will not accept a Proc and must not contain generic datatype symbols.
+
+```ruby
+my_dict[:example] = :anyof, ['xx-small', 'x-small', 'large', 3.2]
+my_dict.check(:example, 'x-small') # => true
+my_dict.check(:example, 3.2) # => true
+my_dict.check(:example, 'xx-large') # => false
+```
+***
+
+#### ***:anyNof***
+Your *struct* contains an element AND specific datatypes in an array.
+
+* ***structs*** - An array of any mixed things you'd like plus generic datatype keywords **Numeric, Float, Integer, Bool, String, Symbol**
+* Can accept a Proc that will only operate on a given value if it's identified by a generic datatype in *struct* after a check for explicit existence in the array
+
+```ruby
+my_dict[:example] = :anyNof, [Integer, 'red', 'blue', 'magenta']
+my_dict.check(:example, 'red') # => true
+my_dict.check(:example, 34) # => true
+
+my_dict[:proc_example] = :anyNof, [Float, 'green', 3.1], Proc.new { |n| n > 5 }
+my_dict.check(:proc_example, 'green') # => true
+my_dict.check(:proc_example, 6.1) # => true
+my_dict.check(:proc_example, 3.1) # => true
+# Again note that :anyNof's Proc is operating only on values NOT explicitly listed in the array.
+```
+***
+
+#### ***:formof***
+Your *struct* contains an array of exact length, you expect each element to be contained in a 
+specific order and be a generic datatype
+
+* ***structs*** - An array of set length containing generic datatype keywords **Numeric, Float, Integer, Bool, String, Symbol**, in 
+a specific order.  Will return false if user input appears out of order with respect
+to the *struct*.
+* Can accept a Proc that must return true for ALL values in the array.
+
+```ruby
+my_dict[:example] = :formof, [Bool, Float, String]
+my_dict.check(:example, [false, 3.1, "Holly Dolly"]) # => true
+my_dict.check(:example, [false, 3.1]) # => false
+my_dict.check(:example, ["Holly Dolly", 3.1, false]) # => false
+
+my_dict[:proc_example] = :formof, [Integer, Float, Float], Proc.new { |n| n.between?(1, 3) }
+my_dict.check(:proc_example, [2, 1.1, 1.2]) # => true
+my_dict.check(:proc_example, [1.1, 2, 1.4]) # => false
+```
+
+***
+
+#### ***:kwargsof***
+Your *struct* contains a hash that corresponds to another KwargDict
+
+* ***structs*** - Can only be another KwargDict instance.
+* Will not accept a Proc
+* Input hash need not contain every *kword* from the nested KwargDict to return true
+* Will return true only if every key-arg pair in input hash is valid in nested KwargDict
+
+```ruby
+another_dict.add([:one, :typeof, Float], [:two, :arrayof, String], [:three, :typeof, Bool],
+  [:and, :anyof, ['partridge', 'in', 'a', 'pear', 'tree']])
+
+my_dict[:example] = :kwargsof, another_dict
+my_dict.check(:example, {one:3.1, three:false, and:'in'}) # => true
+my_dict.check(:example, {two:['this', 'works'], four:'without this'}) # => false
+my_dict.check(:example, {two:['see?']}) # => true
+```
+***
+
+#### ***:adv_formof***
+Your *struct* contains an array of exact length, each of whom's elements has its own subset of
+*typedef*, *struct*, and possibly *prc*
+
+* ***structs*** - Must be an array of exact length, each element of which is a sub array
+containing *typedef*, *struct*, and an optional *prc*, in that order.  Can accept
+**:typeof, :arrayof, :anyof, :anyNof, :formof**, and **:adv_formof**.
+* Will NOT accept *:kwargsof* or *:and_kwargsof*.
+* Will return false if user input appears out of order with respect to the *struct*.
+* Will not accept a Proc outside of a sub *typedef*.  Each element in *struct* may
+have its own unique Proc, however, if allowed for that *typedef*.
+
+```ruby
+my_dict[:example] = :adv_formof, [[:typeof, Float], [:arrayof, Integer]]
+my_dict.check(:example, [3.1, [1, 2, 3, 4, 5]]) # => true
+my_dict.check(:example, [3.1, ['1', '2', '3']]) # => false
+
+my_dict[:proc_example] = :adv_formof, [[:typeof, String, Proc.new { |s| s.length > 5 }],
+  [:formof, [Float]*3 , Proc.new { |n| n.ibetween?(0,1) }]]
+my_dict.check(:proc_example, ["Longer", [0.25, 0.5, 1.0]]) # => true
+my_dict.check(:proc_example, ["Longer", [-0.25, 0.5, -1.0]]) # => false
+my_dict.check(:proc_example, ["Short", [0.25, 0.5, 1.0]]) # => false
+```
+
+***
+
+#### ***:and_kwargsof***
+Your *struct* is structured like *:adv_formof* but the last element MUST be a *:kwargsof* *typedef*
+
+* ***structs*** - MUST be an array in the form of *:adv_formof*, but the last sub *typedef* MUST
+be *:kwargsof*
+* Will return true if given a single value that returns true from the first sub *typedef* in the array.
+* Will return true if given an array of values in the order they appear in *struct*, without skipping one, and each
+returns true from its respective sub *typedef*
+* Will return true if the previous statement is true but the given array also includes a hash that corresponds
+to the last sub *typedef* in the *struct*, which again must always be *:kwargsof*.
+* Will return false if only a hash is present, even if the hash elements are all valid to its
+nested KwargDict
+* Each sub *typedef* may receive a Proc if allowed for that *typedef*
+
+```ruby
+another_dict.add([:one, :typeof, Float], [:two, :arrayof, String])
+my_dict[:example] = :and_kwargsof, [[:typeof, String], [:typeof, Bool], [:kwargsof, another_dict]]
+
+my_dict.check(:example, 'It works!') # => true
+my_dict.check(:example, ['And this.']) # => true
+my_dict.check(:example, ['This too.', true]) # => true
+my_dict.check(:example, ['As does this.', false, {two:['Super!']}]) # => true
+my_dict.check(:example, ['Even this works.', {two:['Yep.'], one:3.1}]) # => true
+
+my_dict.check(:example, true) # => false | Skips the first element of :example
+my_dict.check(:example, [true, 'It broke!']) # => false | Elements appear out of order
+my_dict.check(:example, {one:'Nope'}) # => false | Contains only the hash
+```
+
+### ToDo:
+
+* Add more examples.
+
+* Modify the typedefs *:kwargsof* and *:and_kwargsof* to return a mapping of true
+  and false values.  Write a method #granular_check into KwargDict to return
+  those arrays of Bools and re-write #check to return a singular Bool based on whether
+  any Bool in the array from #granular_check is false.
+
+* Concerning the above, may re-rewrite those typedefs to return hashes of Bools,
+  which may make it even easier for the user to decide what to do with the returned
+  validation data.
+
+* The RSPEC files do not yet check every detail of the KwargTypes as they should.
+
+* Add another module that check's most aspects of a definition itself.
+  In other words, checking that the *struct* a user wishes to assign to a
+  definition in a KwargDict fits within the boundaries set by it's associated
+  *typedef*.  No assigning the datatype keyword 'Array' to a *:typeof* model,
+  for instance.
+
+* Better documentation?
+
+* Build a method into KwargDict that allows the user to easily merge specific
+  entries from different dictionaries.

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+YARD::Rake::YardocTask.new

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "kdict"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "pry"
+Pry.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here