mini_kraken 0.1.12 → 0.2.03

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca30db7b93b0232f1df5321a1e00270395d908e3f7be1d24d3d5a9c19c833914
-  data.tar.gz: d64051987c0b09abf752b24604854515cabc9e99ff5ee436884c8522d6a75950
+  metadata.gz: 6ae3703cbb0a7a854af490478227c915d7d9af72715be80cbd4e3c95cb7b2c3f
+  data.tar.gz: 27e04d428e1015f176fbafba7c047a0b12c28e9150161a7a5702190c8dd2e2e9
 SHA512:
-  metadata.gz: f4fc60b256907317972c51410e52aec821553d7575c24d59b9421f4ba8dbd0136937e70ffb2f9f21556ed205b8b8d54796af68c222df0704b45ebbcf562c3ab3
-  data.tar.gz: 5caf5af0c016e8dfb5de40244ad71a083eb035e0bcb911ae7bd90e67a784789458c12e46a3cc75a96ae483fd0317d86b6610a7c339cd423050b4d57e642d6cc9
+  metadata.gz: bd9cd60953f88610ce3a5009e0cad4099e1896643ad01f1c6616a4c20fb4495a71f5c5ed11efe98873362055bda2ec9d0ba4a1ce972844588cacab528ac5333d
+  data.tar.gz: 1c9d27a9fb7fa014f9789a159aff5309bd9c03ce810e994951373ee550698518683359815c4db43b9d95b00ba889670b824af18c1019af5442f2ca3b42c795ba

data/.rubocop.yml

@@ -0,0 +1,334 @@
+AllCops:
+  Exclude:
+    - 'exp/**/*'
+
+Layout/ArgumentAlignment:
+  Enabled: false
+
+Layout/ArrayAlignment:
+  Enabled: true
+  EnforcedStyle: with_fixed_indentation
+
+Layout/CaseIndentation:
+  Enabled: false
+
+Layout/ClosingHeredocIndentation:
+  Enabled: false
+
+Layout/CommentIndentation:
+  Enabled: false
+
+Layout/ElseAlignment:
+  Enabled: false
+
+Layout/EmptyLines:
+  Enabled: false
+
+Layout/EndAlignment:
+  Enabled: false
+
+Layout/EndOfLine:
+  Enabled: true
+  EnforcedStyle: lf
+
+Layout/FirstArgumentIndentation:
+  Enabled: false
+
+Layout/IndentationWidth:
+  Enabled: false
+
+Layout/IndentationConsistency:
+  Enabled: true
+
+Layout/HeredocIndentation:
+  Enabled: false
+
+Layout/MultilineHashBraceLayout:
+  Enabled: true
+  
+Layout/MultilineMethodCallBraceLayout:
+  Enabled: true
+  EnforcedStyle: same_line  
+
+Layout/SpaceAroundOperators:
+  Enabled: true
+
+Layout/SpaceInsideParens:
+  Enabled: true
+
+Layout/IndentationStyle:
+  Enabled: true
+  
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+
+Layout/TrailingEmptyLines:
+  Enabled: true
+
+Layout/TrailingWhitespace:
+  Enabled: true
+
+Lint/Loop:
+  Enabled: true
+  
+Lint/RaiseException:
+  Enabled: true
+
+Lint/RescueException:
+  Enabled: true
+  
+Lint/StructNewOverride:
+  Enabled: true
+
+Lint/UnusedMethodArgument:
+  Enabled: true
+
+Lint/UselessAccessModifier:
+  Enabled: true
+
+Lint/Void:
+  Enabled: false
+
+Lint/UselessAssignment:
+  Enabled: true
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: true
+  Max: 350
+  
+Metrics/BlockNesting:
+  Enabled: true
+  Max: 5
+
+Metrics/ClassLength:
+  Enabled: true
+  Max: 350
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false
+  Max: 90
+
+Metrics/MethodLength:
+  Enabled: true
+  Max: 50
+
+Metrics/ModuleLength:
+  Enabled: true
+  Max: 500
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Naming/ConstantName:
+  Enabled: false
+
+Naming/ClassAndModuleCamelCase:
+  Enabled: false
+
+Naming/BlockParameterName:
+  Enabled: true
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Naming/VariableName:
+  Enabled: false
+
+Style/Alias:
+  Enabled: true
+
+Layout/HashAlignment:
+  Enabled: false
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/BarePercentLiterals:
+  Enabled: false
+
+Style/BlockComments:
+  Enabled: false
+
+Style/CharacterLiteral:
+  Enabled: false
+
+Style/ClassCheck:
+  Enabled: false
+
+Style/ClassVars:
+  Enabled: false
+
+Style/ColonMethodCall:
+  Enabled: false
+
+Style/CommentAnnotation:
+  Enabled: false
+
+Style/CommentedKeyword:
+  Enabled: false
+
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/DefWithParentheses:
+  Enabled: true
+
+Style/Documentation:
+  Enabled: false
+
+Style/ExpandPathArguments:
+  Enabled: false
+  
+Style/ExponentialNotation:
+  Enabled: true
+
+Style/GuardClause:
+  Enabled: false
+  
+Style/HashEachMethods:
+  Enabled: true
+  
+Style/HashTransformKeys:
+  Enabled: true
+  
+Style/HashTransformValues:
+  Enabled: true
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/InverseMethods:
+  Enabled: true
+  
+Style/MissingRespondToMissing:  
+  Enabled: false
+
+Style/Next:
+  Enabled: false
+
+Style/NumericLiterals:
+  Enabled: false
+
+Style/RaiseArgs:
+  Enabled: true
+
+Style/RedundantReturn:
+  Enabled: false
+
+Style/RedundantSelf:
+  Enabled: true
+
+Style/RegexpLiteral:
+  Enabled: false
+
+Style/PercentLiteralDelimiters:
+  Enabled: false
+
+Style/StderrPuts:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: true
+
+Style/TernaryParentheses:
+  Enabled: false
+
+Style/UnlessElse:
+  Enabled: false
+  
+# Rubocop complains when it doesn't find an explicit setting for the following cops:
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
+Lint/BinaryOperatorWithIdenticalOperands:
+  Enabled: true
+
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+
+Lint/DuplicateElsifCondition:
+  Enabled: true
+
+Lint/DuplicateRescueException:
+  Enabled: true
+
+Lint/EmptyConditionalBody:
+  Enabled: true
+
+Lint/FloatComparison:
+  Enabled: true
+
+Lint/MissingSuper:
+  Enabled: true
+
+Lint/MixedRegexpCaptureTypes:
+  Enabled: true
+
+Lint/OutOfRangeRegexpRef:
+  Enabled: true
+
+Lint/SelfAssignment:
+  Enabled: true
+
+Lint/TopLevelReturnWithArgument:
+  Enabled: true
+
+Lint/UnreachableLoop:
+  Enabled: true
+
+Style/AccessorGrouping:
+  Enabled: true
+
+Style/ArrayCoercion:
+  Enabled: true
+
+Style/BisectedAttrAccessor:
+  Enabled: true
+
+Style/CaseLikeIf:
+  Enabled: true
+
+Style/ExplicitBlockArgument:
+  Enabled: true
+
+Style/GlobalStdStream:
+  Enabled: true
+
+Style/HashAsLastArrayItem:
+  Enabled: true
+
+Style/HashLikeCase:
+  Enabled: true
+
+Style/OptionalBooleanParameter:
+  Enabled: true
+
+Style/RedundantAssignment:
+  Enabled: true
+
+Style/RedundantFetchBlock:
+  Enabled: true
+
+Style/RedundantFileExtensionInRequire:
+  Enabled: true
+
+Style/RedundantRegexpCharacterClass:
+  Enabled: true
+
+Style/RedundantRegexpEscape:
+  Enabled: true
+
+Style/SingleArgumentDig:
+  Enabled: true
+
+Style/SlicingWithRange:
+  Enabled: true
+
+Style/StringConcatenation:
+  Enabled: true

data/CHANGELOG.md

@@ -1,3 +1,57 @@
+## [0.2.03] - 2020-09-02
+- The DSL (Domain Specific Language) supports the `caro` relation & passes frames up to 2-8 from Chapter 2.
+
+### NEW
+- Class `ConsCellVisitor`. Its method `df_visitor` builds a Fiber that walks over a ConsCell (list/graph).
+- Method `Outcome#failure?`
+- Method `Outcome#prune!` for removing associations of transient variables.
+- Method `VariableRef#to_s` for providing a text representation of a variable reference
+- Method `Vocabulary#prune` for removing associations of transient variables.
+- Class `FreshEnvFactory` as its name implies, is used to build `FreshEnv` instances.
+
+### CHANGED
+- Method `Outcome#successful?` renamed to `Outcome#success?`
+
+### FIXED
+- Method `Equals#solver_for` now prunes associations of transient variables.
+- Method `Equals#unify_composite_terms` now copes with Conscell vs. VariableRef unification.
+
+## [0.2.02] - 2020-08-08
+- The DSL (Domain Specific Language) now supports `conde` and passes all examples from Chapter 1.
+
+### NEW
+- Method`Glue::DSL#conde` to implement conde goals.
+- Method `KBoolean#to_s` returns a text representation of a boolean value.
+
+## [0.2.01] - 2020-08-07
+- The DSL (Domain Specific Language) now supports `defrel` and boolean literals.
+
+### CHANGED
+- Constructor `DefRelation#initialize` now freezes any new class instance.  
+- Constructor `GoalTemplate#initialize` now freezes any new class instance.  
+- Mixin module `Glue::DSL` new method `defrel` to build custom relations.
+- File `.rubocop.yml` to please Rubocop 0.89
+
+## [0.2.00] - 2020-07-12
+- First release of DSL (Domain Specific Language)
+- Fix defect for fused variables that remain fresh
+
+### NEW
+- Mix-in module `Glue::DSL` hosting methods for implementing the DSL.
+- Method `ConsCell#to_s` uses the Lisp convention for representing lists.
+
+### CHANGED
+- File `README.md` Added a couple of examples of DSL use.
+- Method `AnyValue#==` can compare with symbols with format '_' + integer literal (e.g. :_0).
+
+## [0.1.13] - 2020-07-01
+- Cover all frames from Chapter One of "Reasoned Scheme" book.
+- Fix defect for fused variables that remain fresh
+
+### CHANGED
+- Method `Variable#quote` now takes into account of cases when variables are fused.
+- Method `Vocabulary#names_fused`  now copes with cases where no variable with given name can be found.
+
 ## [0.1.12] - 2020-06-29
 - Supports `conde`, that is, a relation that can take an arbitrary number of arguments.
 - Cover all frames but one from Chapter One of "Reasoned Scheme" book.

data/README.md

@@ -4,31 +4,38 @@
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](https://github.com/famished-tiger/mini_kraken/blob/master/LICENSE.txt)
 
 ### What is __mini_kraken__ ?   
-An implemention of the [miniKanren](http://minikanren.org/) relational programming language in Ruby.
+A library containing an implementation of the [miniKanren](http://minikanren.org/)   
+relational programming language in Ruby.
 *miniKanren* is a small language for relational (logic) programming.  
 Based on the reference implementation, in Scheme from the "The Reasoned Schemer" book.   
 Daniel P. Friedman, William E. Byrd, Oleg Kiselyov, and Jason Hemann: "The Reasoned Schemer", Second Edition,
 ISBN: 9780262535519, (2018), MIT Press.
 
 ### Features
+- Pure Ruby implementation, not a port from another language
+- Object-Oriented design
+- No runtime dependencies
+
+### miniKanren Features
 - [X] ==  
 - [X] run\*  
-- [X] fresh 
+- [X] fresh
+- [X] conde
 - [X] conj2  
 - [X] disj2
-- [X] defrel   
+- [X] defrel  
+- [X] caro   
 
 ### TODO
-- [ ] conde  
+
 - [ ] Occurs check
 
-List-centric relations from Chapter 2
-- [ ] caro
-- [ ] cdro
-- [ ] conso
-- [ ] nullo
-- [ ] pairo
-- [ ] singletono
+List-centric relations from Chapter 2 
+- [ ] cdro  
+- [ ] conso  
+- [ ] nullo  
+- [ ] pairo  
+- [ ] singletono  
 
 ## Installation
 
@@ -46,9 +53,84 @@ Or install it yourself as:
 
     $ gem install mini_kraken
 
-## Usage
+## Examples
+
+The following __MiniKraken__ examples use its DSL (Domain Specific Language).
+
+### Example 1
+Let's first begin with a rather simplistic example.   
+
+```ruby
+require 'mini_kraken' # Load MiniKraken library
+
+extend(MiniKraken::Glue::DSL) # Add DSL method to self (object in context)
+
+result = run_star('q', equals(q, :pea))
+puts result # => (:pea)
+```
+
+The two first lines in the above code snippet are pretty standard:  
+- The first line loads the `mini_kraken` library.
+- The second line add the DSL methods to the current object.
+
+The next line constitutes a trivial `miniKanren` program.  
+The aim of a `miniKanren` program is to find one or more solutions involving the given logical variable(s)
+and satisfying one or more goals to the `run_star method.  
+In our example, the `run_star` method instructs `MiniKraken` to find all solutions,  
+knowing that each successful solution:
+- binds a value to the provided variable `q` and
+- meets the goal `equals(q, :pea)`.
+
+The goal `equals(q, :pea)` succeeds because the logical variable `q` is _fresh_ (that is,
+  not yet bound to a value) and will be bound to the symbol `:pea` as a side effect
+  of the goal `equals`.
+
+So the above program succeeds and the only found solution is obtained by binding
+ the variable `q` to the value :pea. Hence the result of the `puts` method.
+
+### Example 2
+ The next example illustrates the behavior of a failing `miniKanren` program.
+
+ ```ruby
+ require 'mini_kraken' # Load MiniKraken library
+
+ extend(MiniKraken::Glue::DSL) # Add DSL method to self (object in context)
+
+ # Following miniKanren program fails
+ result = run_star('q', [equals(q, :pea), equals(q, :pod)])
+ puts result # => ()
+ ```
+In this example, we learn that `run_star` can take multiple goals placed in an array.
+The program fails to find a solution since it is not possible to satisfy the two `equals` goals simultaneously.  
+In case of failure, the `run_star` returns an empty list represented as `()` in the output.
+
+
+### Example 3
+ The next example shows the use two logical variables.
+
+```ruby
+# In this example and following, one assumes that DSL is loaded as shown in Example 1
+
+result = run_star(['x', 'y'], [equals(:hello, x), equals(y, :world)])
+puts result # => ((:hello :world))
+```
 
-TODO: Write usage instructions here
+This time, `run_star` takes two logical variables -`x` and `y`- and successfully finds the solution `x = :hello, y = :world`.
+
+### Example 4
+ The next example shows the use of `disj2` goals.
+ ```ruby
+ result = run_star(['x', 'y'],
+                   [
+                     disj2(equals(x, :blue), equals(x, :red)),
+                     disj2(equals(y, :sea), equals(:mountain, y))
+                   ])
+ puts result # => ((:blue :sea) (:blue :mountain) (:red :sea) (:red :mountain))
+ ```
+
+ Here, `run_star` takes two logical variables and two `disj2` goals.  
+ A `disj2` succeeds if any of its arguments succeeds.  
+ This program finds four distinct solutions for x, y pairs.
 
 ## Development