porolog 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 595dfcb99ad8db28a4aa8b5a71b0f63c4e417dd4b2036ec0e7559c7bf0523438
-  data.tar.gz: dc8d09f758aea19d636bd593e3e6a9a9283027e44424ad6cc88ce78445afec64
+  metadata.gz: 536a3d026aa1bec9bfbd2ead7d114eaad2e80073b85be0719fd100308c8429fc
+  data.tar.gz: 0fd27e6e5e621d5490c8db18d65950fad59352b913c07a13530eccae83e5dffb
 SHA512:
-  metadata.gz: 88889f2063831ca8b5a6358e96727c1ad3805a5721d6b39e6b931af584ea24ac12b5dc89bdf18eeff81eed1e93e04b8637f27a1fe62db2a08d126e1e208a16e1
-  data.tar.gz: c564320bd055721a1de3a4af742c81f69c51574c88a84207373208870655452508aed97c21c567ba4a0205d4ae4944f9e824fc5b206043facf112f9c799150bc
+  metadata.gz: 5e3f448233128166af31c06aefe940654b651cdd92669c1f74fa7e0f7cf2f65ba8c2e3f52683e8c04cfe2787ea9bb851265baa6c026756e400b73717268f98dc
+  data.tar.gz: 1df194f8edc97a02f3f6be5420908ab5f81ac1f6f04738a493b770b91404a2f4f6352e18ec9fc4f630c050c238766d14eb1ada179992f90fbdaa0f4fc46ac33f

data/README.md

@@ -1,5 +1,7 @@
 # porolog
 
+<img src="https://repository-images.githubusercontent.com/131847563/b3754100-636a-11e9-995b-20d409b992c9" width="240" height="120" align="right" />
+
 Plain Old Ruby Objects Prolog
 
 [![Gem Version](https://badge.fury.io/rb/porolog.svg)](https://badge.fury.io/rb/porolog)
@@ -20,7 +22,7 @@ Ruby objects could be passed in and Ruby objects were passed back.
 ## Dependencies
 
 The aim of `porolog` is to provide a logic engine with a minimal footprint.
-Thus `porolog` has no dependencies.
+The only dependency is Yard for documentation.
 
 ## Installation
 

data/Rakefile

@@ -5,6 +5,7 @@
 #
 
 require 'rake/testtask'
+require 'yard'
 
 
 # -- Run All Tests Task --
@@ -25,6 +26,11 @@ Dir['test/porolog/*_test.rb'].each do |test_file|
   end
 end
 
+# -- Documentation Task --
+YARD::Rake::YardocTask.new('doc') do |task|
+  task.stats_options = ['--list-undoc']
+end
+
 # -- Tasks --
 task default: :test
 
@@ -33,6 +39,7 @@ task :help do
   puts <<-EOF
     Porolog is a Ruby library.
     See README.md for more information.
+    See doc/index.html for documentation.
     Run
       rake -T
     for other tasks.

data/lib/porolog/error.rb

@@ -7,6 +7,7 @@
 
 module Porolog
 
+  # Error class to enable rescuing or detecting any Porolog error.
   class PorologError < RuntimeError ; end
 
 end

data/lib/porolog/predicate.rb

@@ -5,25 +5,29 @@
 #       created
 #
 
-# Porolog::Predicate
-#
-#   A Porolog::Predicate corresponds to a Prolog predicate.
-#   It contains rules (Porolog::Rule) and belongs to a Porolog::Scope.
-#   When provided with arguments, it produces a Porolog::Arguments.
-#
-
 module Porolog
   
+  # A Porolog::Predicate corresponds to a Prolog predicate.
+  # It contains rules (Porolog::Rule) and belongs to a Porolog::Scope.
+  # When provided with arguments, it produces a Porolog::Arguments.
+  # @author Luis Esteban
+  # @!attribute [r] name
+  #   Name of the Predicate.
+  # @!attribute [r] rules
+  #   Rules of the Predicate.
   class Predicate
     
+    # Error class for rescuing or detecting any Predicate error.
     class PredicateError < PorologError   ; end
+    # Error class indicating an error with the name of a Predicate.
     class NameError      < PredicateError ; end
     
     attr_reader :name, :rules
     
-    @@current_scope        = Scope[:default]
-    @builtin_predicate_ids = {}
-    
+    # Returns the current scope, or sets the current scope if a paramter is provided
+    # (creating the new scope if necessary).
+    # @param scope_name [Object] the name (or otherwise object) used to register a scope.
+    # @return [Porolog::Scope] the current Scope.
     def self.scope(scope_name = nil)
       if scope_name
         @@current_scope = Scope[scope_name] || Scope.new(scope_name)
@@ -32,23 +36,35 @@ module Porolog
       end
     end
     
+    # Sets the current scope (creating the new scope if necessary.
+    # @param scope_name [Object] the name (or otherwise object) used to register a scope.
+    # @return [Porolog::Scope] the current Scope.
     def self.scope=(scope_name)
       if scope_name
         @@current_scope = Scope[scope_name] || Scope.new(scope_name)
       end
+      @@current_scope
     end
     
+    # Resets the current scope to default and deregisters builtin predicates.
+    # @return [Porolog::Scope] the current Scope.
     def self.reset
       scope(:default)
       @builtin_predicate_ids = {}
     end
     
+    # Looks up a Predicate in the current scope by its name.
+    # @param name [Object] the name (or otherwise object) used to register a scope.
+    # @return [Porolog::Predicate] the Predicate with the given name.
     def self.[](name)
       @@current_scope[name]
     end
     
     reset
     
+    # Initializes a Porolog::Predicate and registers it by its name.
+    # @param name [#to_sym] the input object to read from
+    # @param scope_name the name of the scope in which to register the Predicate; if omitted, defaults to the name of the current scope
     def initialize(name, scope_name = Predicate.scope.name)
       @name  = name.to_sym
       @rules = []
@@ -59,23 +75,35 @@ module Porolog
       scope[@name] = self
     end
     
+    # Creates a new Predicate, or returns an existing Predicate if one already exists with the given name in the current scope.
+    # @return [Porolog::Predicate] a new or existing Predicate.
     def self.new(*args)
       name, _ = *args
       scope[name.to_sym] || super
     end
     
+    # Create Arguments for the Predicate.
+    # Provides the syntax options:
+    # * p.(x,y,z)
+    # @return [Porolog::Arguments] Arguments of the Predicate with the given arguments.
     def call(*args)
       Arguments.new(self,args)
     end
     
+    # Create Arguments for the Predicate.
     def arguments(*args)
       Arguments.new(self,args)
     end
     
+    # Add a Rule to the Predicate.
+    # @param rule [Object] the name (or otherwise object) used to register a scope.
+    # @return [Array<Porolog::Rule>] the Predicate's rule.
     def <<(rule)
       @rules << rule
     end
     
+    # A pretty print String of the Predicate.
+    # @return [String] the Predicate as a String.
     def inspect
       lines = []
       
@@ -91,6 +119,9 @@ module Porolog
       lines.join("\n")
     end
     
+    # Return a builtin Predicate based on its key.
+    # @param key [Symbol] the name (or otherwise object) used to register a scope.
+    # @return [Porolog::Predicate] a Predicate with the next id based on the key.
     def self.builtin(key)
       @builtin_predicate_ids[key] ||= 0
       @builtin_predicate_ids[key]  += 1

data/lib/porolog/scope.rb

@@ -5,28 +5,32 @@
 #       created
 #
 
-# == Porolog::Scope ==
-#
-#   A Porolog::Scope is a container for Porolog::Predicates.
-#   Its purpose is to allow a Ruby program to contain multiple Prolog programs
-#   without the Prolog programs interfering with each other.
-#
-
 module Porolog
 
+  # A Porolog::Scope is a container for Porolog::Predicates.
+  # Its purpose is to allow a Ruby program to contain multiple Prolog programs
+  # without the Prolog programs interfering with each other.
+  # @author Luis Esteban
+  # @!attribute [r] name
+  #   Name of the Scope.
   class Scope
     
+    # Error class for rescuing or detecting any Scope error.
     class ScopeError        < PorologError ; end
+    # Error class indicating a non-Predicate was assigned to a Scope.
     class NotPredicateError < ScopeError   ; end
     
     attr_reader :name
     
-    @@scopes = {}
-    
+    # Creates a new Scope unless it already exists.
+    # @param name [Object] the name (or otherwise object) used to register a scope.
+    # @return [Porolog::Scope] new or existing Scope.
     def self.new(name)
       @@scopes[name] || super
     end
     
+    # Initializes and registers the Scope.
+    # @param name [Object] the name (or otherwise object) used to register a scope.
     def initialize(name)
       @name       = name
       @predicates = {}
@@ -34,6 +38,8 @@ module Porolog
       @@scopes[@name] = self
     end
     
+    # Clears all scopes and re-creates the default Scope.
+    # @return [Porolog::Scope] the default Scope.
     def self.reset
       @@scopes = {}
       new(:default)
@@ -41,23 +47,38 @@ module Porolog
     
     reset
     
+    # Looks up a Scope by its name.
+    # @param name [Object] the name (or otherwise object) used to register a scope.
+    # @return [Porolog::Scope] the default Scope.
     def self.[](name)
       @@scopes[name]
     end
     
+    # Returns the names of all registered Scopes.
+    # @return [Array<Symbol>,Array<Object>] the names.
     def self.scopes
       @@scopes.keys
     end
     
+    # Looks up a Predicate in the Scope by its name.
+    # @param name [Object] the name (or otherwise object) used to register a scope.
+    # @return [Porolog::Predicate] the Predicate indicated by the name.
     def [](name)
       @predicates[name.to_sym]
     end
     
+    # Assigns a Predicate to the Scope by its name.
+    # @param name [Object] the name (or otherwise object) used to register a scope.
+    # @param predicate [Porolog::Predicate] a Predicate to be assigned to the Scope.
+    # @return [Porolog::Predicate] the Predicate assigned to the Scope.
+    # @raise [NotPredicateError] when provided predicate is not actually a Predicate.
     def []=(name,predicate)
       raise NotPredicateError.new("#{predicate.inspect} is not a Predicate") unless predicate.is_a?(Predicate)
       @predicates[name.to_sym] = predicate
     end
     
+    # Returns the Predicates contained in the Scope.
+    # @return [Array<Porolog::Predicate>] Predicates assigned to the Scope.
     def predicates
       @predicates.values
     end

data/lib/porolog.rb

@@ -7,9 +7,16 @@
 
 module Porolog
 
-  VERSION      = '0.0.2'
-  VERSION_DATE = '2019-04-20'
+  # The most recent version of the Porolog gem.
+  VERSION      = '0.0.3'
+  # The most recent date of when the VERSION changed.
+  VERSION_DATE = '2019-04-21'
   
+  # A convenience method to create a Predicate, along with a method
+  # that returns an Arguments based on the arguments provided to
+  # the method.
+  # @param names [Array<#to_sym>] names of the Predicates to create.
+  # @return [Porolog::Predicate|Array<Porolog::Predicate>] Predicate or Predicates created
   def predicate(*names)
     names = [names].flatten
     

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: porolog
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Luis Esteban
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-20 00:00:00.000000000 Z
+date: 2019-04-21 00:00:00.000000000 Z
 dependencies: []
 description: Implements a Prolog inference engine using Plain Old Ruby Objects
 email: