mini_kraken 0.1.10 → 0.2.01

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec7b984a9f0c857f74c8a8989c5da2072398775573b7ca6679d99f96ef13eac1
-  data.tar.gz: cdebdebae82c424b9ae701f959765f0905322798a371e2aec42ed9a229e35a4f
+  metadata.gz: f51855ac3179a111a4ace328340402fa167818773086076abf90ed845c31d248
+  data.tar.gz: f6bde0d3d7b872461d7cb0b087eaab821240f14317445e95f4d832d09af51e2f
 SHA512:
-  metadata.gz: 2ce3553527adeebef7adc69ec5a861fe65f9f451e54a81e23f00769923ced6b6a6011846ae3e9a673c8b9094a7dcce6ea6f8d263d55c8f543ef0de309e34c11c
-  data.tar.gz: 90b45061cde1119ad648359063682f411f9e5705a294340976bd027561b1d94da7afbfc9d0d27dce67942e1407d4d4ea40df85cf3fe67c9fca998d22052b6187
+  metadata.gz: ae6319164a2f6212bdbdea35dd5b5befa86648b685063dea79d220b70e5852c3e8b343d2d37ebfe6584aa3966b44174e91df2866d63e03a219a0008a5b382d66
+  data.tar.gz: 70eb204ab842ea45527bd5ca8661dcd98081422cae4d6848d220bc70e080da94b3b7078f3602f1143535821a9894309b9bec39ec5f4d6c60edcfd21cfa5c8f4f

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,4 +1,58 @@
-## [0.1.10] - 2020-06-10
+## [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 `Core::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.
+
+### New
+- Class `Conde` a relation that succeeds for each of its successful arguments.
+
+### CHANGED
+- Method `Goal#validated_actuals` add into account polyadic relations (= relations with arbitrary number of arguments)
+
+## [0.1.11] - 2020-06-25
+- Supports `defrel`, that is, the capability to define new relations by combining other relations.
+- Covers frames from "The Reasoned Scheme" book up to frame [1:87]
+
+### New
+- Class `BaseArg` a generalization of goal or goal template argument.
+- Class `DefRelation` A specialization of `Relation` class aimed for user-defined relation.
+- Class `FormalArg` to represent goal template argument(s).
+- Class `FormalRef` an allusion to a formal argument in a goal template.
+- Class `GoalTemplate` a representation of a goal parametrized with formal arguments.
+- Class `KBoolean` a MiniKraken representation of a boolean value.
+
+### CHANGED
+- File `README.md` minor change: added more TODO's.
+
+## [0.1.10] - 2020-06-13
 - Supports frames from "The Reasoned Scheme" book up to frame [1:81]
 
 ### New

data/README.md

@@ -4,24 +4,39 @@
 [![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.  
+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] disj2
+- [X] defrel   
 
 ### TODO
-- [ ] defrel 
-- [ ] conde  
+
 - [ ] Occurs check
 
+List-centric relations from Chapter 2
+- [ ] caro  
+- [ ] cdro  
+- [ ] conso  
+- [ ] nullo  
+- [ ] pairo  
+- [ ] singletono  
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -38,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