mini_kraken 0.1.13 → 0.2.04

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79ea33dd475e6dfbed71915177b1581abb5e1ca9a60db04133d11cda7dca9d42
-  data.tar.gz: 249bea4319183c929e4c291785c6b74e10606889c789c5e0f2b211197cc6f288
+  metadata.gz: 96c07c3751d0c46963e19f8e25dc429a77dbd630c22b32018914ccf36f471689
+  data.tar.gz: 26efce2c03a89fd4129c756ce64daa80783cc9bfcebc0358b493076f33ef9434
 SHA512:
-  metadata.gz: '086bf0b30750e908dfee1b7e95eb3b0c0e54dff4f7bd700d54bbf28091aaf02080d458c14508ddcaa580248e0234d1da23553869480e3bea930d46708c115d82'
-  data.tar.gz: d3ada8d056819b2ae1af0d442056008600f82633ee52ca8aa672708943fdf517adb60522bfff6673f9cea86985c1bf5ce2a7a3ea73f07504945e660f31ebee49
+  metadata.gz: 1df0d6a9397a804e35700aaedb1fcc1ae7fb91a4b3b237ffe138be5cc63b51113d1af5a57f5cd216a41217993dce5dc5186d0690ab992d2eab229995321e7dfb
+  data.tar.gz: d5af2983495e31e77e8947bffeca99a9b88b916208cb511a88e3f0e397ec2f105cd60d333d2663b78c4e943edad9e4c76c8aa7eabd07a94a733e9821d63de305

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,58 @@
+## [0.2.04] - 2020-09-02
+- Intermediate version before vast code rework.
+
+### CHANGED
+- Classes `KBoolean`, `KSymbol`, `KInteger` moved to namespace `Atomic`
+- Classes `ConsCell`, `ConsCellVisitor` moved to namespace `Composite`
+- Class `Variable` renamed to `LogVar`
+- Class `VariableRef` renamed to `LogVarRef`
+
+## [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

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