campa 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6410a4621dc09f84072f8033d4497bbe49d13df0a03e3a5f6107ac27cdaffdc8
-  data.tar.gz: '0923072a54a030a5747f254a3903efa0b22909b8440b41b7086a70eaf3b40d31'
+  metadata.gz: db71a3db30c9fe5be51a2033b53adba713c4a0dd5f7fdcc0b2ae64b471792df5
+  data.tar.gz: fe74a65e008ef2575d2daf4f741563305a98b0ae28ac2830883ec0de8feb4d48
 SHA512:
-  metadata.gz: 7c45daf7fbaf5a5a6035db61a25f3607281e64ef4ffbce48b3fcf596816a6f08aad6e0bf0f902768be15a4f9e587616ce1fa6f56f5110a760ed621456f021a9d
-  data.tar.gz: a68e9021520f4efcfb4494f128a4cb67a9d0fa5f446403d26458fccc80971e704383c819b7c56786ea525ab6d51a79b4c9bfabe98c9160e5eb394fbf08ef2eee
+  metadata.gz: ef6569c0fa26a2dc886903c4689cd2ae667e0ca6a3110289c9b280a4b88602e12be2d605d88dfd09b46e046f39dc7124d3c6dcb91456eca75992455f72313674
+  data.tar.gz: 3974b56df43c387b40a7211d0c65b7ab554d66e5546a0a3e851fbbd6ad19e42d4201ee9f0735928b4b6fe044fd23c1e3b4fdaa75ec24e2ec23f86969cff33487

data/.gitattributes

@@ -0,0 +1 @@
+*.cmp linguist-language=lisp

data/Gemfile

@@ -13,3 +13,5 @@ gem "rubocop-rspec", require: false
 
 gem "pry-byebug"
 gem "simplecov", require: false
+
+gem "yard"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    campa (0.1.2)
+    campa (0.1.3)
       zeitwerk (~> 2.4)
 
 GEM
@@ -63,6 +63,7 @@ GEM
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.3)
     unicode-display_width (2.0.0)
+    yard (0.9.26)
     zeitwerk (2.4.2)
 
 PLATFORMS
@@ -77,6 +78,7 @@ DEPENDENCIES
   rubocop-rake
   rubocop-rspec
   simplecov
+  yard
 
 BUNDLED WITH
    2.2.20

data/README.md

@@ -56,7 +56,7 @@ more accessible.
 This project implements **LISP** to the point
 where all the functions exemplified by Graham's article
 run successfully. Which means one could implement *Campa* on itself
-(or they could just [go here](../blob/main/campa/core.cmp)
+(or they could just [go here](../main/campa/core.cmp)
 and see how it is done already).
 
 ## Usage
@@ -144,7 +144,7 @@ to quote an object is also implemented in the runtime.
 ### Implementation details
 
 All those functions are implemented in Ruby
-[and they live right here](../blob/4fc244d41dd6d9/lib/campa/lisp).
+[and they live right here](../3b43a21/lib/campa/lisp).
 
 ## Beyond the Roots
 
@@ -158,16 +158,16 @@ and the ones implemented on the runtime (in Ruby).
 
 ### Extras in Campa
 
-  - [(assert x y)](../blob/4fc244d41dd6d9/campa/test.cmp#L1)
+  - [(assert x y)](../3b43a21/campa/test.cmp#L1)
     Returns true if x and y are *eq*.
 
 ### Extras in Ruby (runtime)
 
-  - [(load a-file another-file)](../blob/4fc244d41dd6d9/lib/campa/core/load.rb)
+  - [(load a-file another-file)](../3b43a21/lib/campa/core/load.rb)
     Read and evaluate the files given as arguments
-  - [(print "some" "stuff" 4 '("even" "lists"))](../blob/4fc244d41dd6d9/lib/campa/core/print.rb)
+  - [(print "some" "stuff" 4 '("even" "lists"))](../3b43a21/lib/campa/core/print.rb)
     Print out a reader friendly representation of the given parameter(s).
-  - [(println stuffz here)](../blob/4fc244d41dd6d9/lib/campa/core/println.rb)
+  - [(println stuffz here)](../3b43a21/lib/campa/core/println.rb)
     Same as print but add a line break (`\n`) after each parameter.
 
 #### Tests
@@ -184,7 +184,7 @@ that starts with *test-* or *test_* (case insentive)
 and return *true* for success
 or *false* for failure.
 The core implementation for *Campa* rely on this tool
-and you can check out [some test examples here](../blob/4fc244d41dd6d9/test/core_test.cmp).
+and you can check out [some test examples here](../3b43a21/test/core_test.cmp).
 
     $ campa test test/core_test.cmp
 
@@ -194,8 +194,8 @@ and you can check out [some test examples here](../blob/4fc244d41dd6d9/test/core
 Internally this "framework" is comprised
 of the two following functions:
 
-  - [(tests-run optional-name other-optional-name)](../blob/4fc244d41dd6d9/lib/campa/core/test.rb)
-  - [(tests-report (tests-run))](../blob/4fc244d41dd6d9/lib/campa/core/test_report.rb)
+  - [(tests-run optional-name other-optional-name)](../3b43a21/lib/campa/core/test.rb)
+  - [(tests-report (tests-run))](../3b43a21/lib/campa/core/test_report.rb)
 
 ##### (tests-run)
 
@@ -237,7 +237,7 @@ This is an easy way to integrate this tool
 with CI environments or any type of "progressive" build.
 
 An example of how this is used by
-*Campa* implementation [can be found here](../blob/4fc244d41dd6d9/Rakefile#L12).
+*Campa* implementation [can be found here](../3b43a21/Rakefile#L12).
 
 
 ## Development

data/Rakefile

@@ -20,4 +20,11 @@ rescue SystemExit => e
   exit(1) if e.status != 0
 end
 
-task default: %i[spec rubocop campatest]
+require "yard"
+YARD::Rake::YardocTask.new do |t|
+  # t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+  # t.options = ['--any', '--extra', '--opts'] # optional
+  # t.stats_options = ['--list-undoc']         # optional
+end
+
+task default: %i[spec rubocop campatest yard]

data/bin/console

@@ -3,13 +3,6 @@
 
 require "bundler/setup"
 require "campa"
-
-# 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 "irb"
+
 IRB.start(__FILE__)

data/bin/setup

@@ -4,5 +4,3 @@ IFS=$'\n\t'
 set -vx
 
 bundle install
-
-# Do any other automated setup that you need to do here

data/lib/campa.rb

@@ -7,12 +7,57 @@ require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
 loader.setup
 
+# Campa is a tiny LISP implementation.
+#
+# The "benchmark" for this is to cover the specification
+# established by the Paul Graham's article
+# {http://paulgraham.com/rootsoflisp.html The Roots of Lisp}.
+#
+# So the following functions are implemented
+# in the runtime:
+#
+#   - (atom something)
+#   - (car list)
+#   - (cdr list)
+#   - (cond (some-condition value) (another-condition another-value))
+#   - (cons 'first '(second third))
+#   - (defun fun-name (parameters list) 'body)
+#   - (eq a-thing another-thing)
+#   - (label meaning-of-life 42)
+#   - (quote (some stuff))
+#
+# Besides these core functions
+# other two ones,
+# also specified on The Roots of Lisp,
+# are also implemented on tnis LISP:
+#
+#   - (cadr list) - and any variation possible (caaar, cadadar...)
+#   - (list 'this 'creates 'a 'new 'list)
+#
+# Those are all the functions necessary
+# to implement an eval function
+# able to interprete LISP by itself.
+#
+# And to be sure that this is the case
+# we have this implementation on {file:campa/core.cmp campa/core.cmp}.
 module Campa
-  CR_REGEX = /\Ac((ad)|(a|d){2,})r$$/ # caar, cddr, cadr, but not car or cdr
+  # caar, cddr, cadr, but not car or cdr
+  CR_REGEX = /\Ac((ad)|(a|d){2,})r$$/
+
+  # symbol to reference the "stdout" in a Campa execution context
   SYMBOL_OUT = Symbol.new("__out__")
+
+  # symbol for the lambda function
   SYMBOL_LAMBDA = Symbol.new("lambda")
+
+  # symbol for the quote function
   SYMBOL_QUOTE = Symbol.new("quote")
 
+  # Returns a Pathname pointint to
+  # the root of the "gem".
+  #
+  # Useful for requiring and/or finding files
+  # that need to be read by the runtime.
   def self.root
     @root ||= Pathname.new File.expand_path(__dir__)
   end

data/lib/campa/cli.rb

@@ -1,13 +1,40 @@
 module Campa
+  # Implements the features available
+  # to the command `campa` shipped with this gem.
   class Cli
-    def initialize(repl: nil, evaler: nil, context: nil, reader: nil)
+    # @param repl [#run] the repl to be run if no option is given to `campa`
+    # @param evaler [#eval] lisp/campa evaler to be used
+    #   by the repl or file evaluation
+    # @param context [#push, #[], #[]=] the context provider
+    #   for the current run.
+    #   This is where the __out__ binding pointing to $stdout will be created.
+    # @param reader [#new] lisp/campa reader for when
+    #   an existent file is passed to `campa`.
+    def initialize(repl: nil, evaler: nil, context: nil, reader: Campa::Reader)
       @evaler = evaler || default_evaler
       @context = context || default_context
-      @reader = reader || default_reader
+      @reader = reader
 
       @repl = repl || default_repl
     end
 
+    # Execute some campa stuff
+    # depending on the options given in the command line.
+    #
+    # If no argument is given
+    # it will start a {Campa::Repl} session.
+    #
+    # When first argument is an existent file
+    # then it will evaluated using {Campa::Reader} and {Campa::Evaler}.
+    #
+    # If the CLI argument is anything else,
+    # this method tries to match it with {OPTIONS}
+    # and find the method to be executed.
+    # Current options for the CLI are:
+    #
+    # <b><i>campa test FILE1, FILE2</i></b>
+    # Uses {Campa::Core::Test} and {Campa::Core::TestReport} to evaluate
+    # the files given as options as *Campa* test code.
     def execute(argv = nil, input: $stdin, out: $stdout)
       return repl.run(input, out) if argv.nil? || argv.empty?
       return evaluate(argv[0], input, out) if File.file?(argv[0])
@@ -58,9 +85,5 @@ module Campa
     def default_context
       @default_context ||= Campa::Language.new
     end
-
-    def default_reader
-      @default_reader ||= Campa::Reader
-    end
   end
 end

data/lib/campa/context.rb

@@ -1,36 +1,84 @@
 module Campa
+  # Represents a storage for all bindings
+  # in any <i>Campa</i> execution.
+  #
+  # All functions run inside their own context
+  # so when they are finished
+  # any binding created by it will be gone.
+  #
+  # The {Repl} also uses it's own {Context} for execution.
   class Context
+    # @!visibility private
     attr_accessor :fallback
 
+    # @param env [#[], #[]=] a Hash like or another {Context} object
+    #   to be used as the underlying storage for this {Context}.
     def initialize(env = {})
       @env = env
     end
 
+    # Creates a new binding between a given {Symbol} and an Object.
+    #
+    # @param symbol [Symbol]
+    #   (actually, nothing guarantees it will be a symbol right now)
+    #   to be bound to a value in this {Context}.
+    # @param value [Object] associated to a given {Symbol}
     def []=(symbol, value)
       env[symbol] = value
     end
 
+    # Returns the value bound to a {Symbol}
+    #
+    # @param symbol [Symbol] for which we want to fetch the value
+    #   in this {Context}
+    # @return Object
     def [](symbol)
       return env[symbol] if env.include?(symbol)
 
       fallback[symbol] if !fallback.nil?
     end
 
+    # Check if there is any binding for a {Symbol}
+    #
+    # @param symbol [Symbol] "label" for a (possibly) bound value
     def include?(symbol)
       env.include?(symbol) ||
         (!fallback.nil? && fallback.include?(symbol))
     end
 
+    # Creates a new {Context} assigning self as a #fallback to it.
+    #
+    # This means that if a {Symbol}
+    # is not present on the returned {Context},
+    # it will be searched on this one.
+    # Which allows for building some sort of stack of {Context}s.
+    #
+    # WARNING: The name <i>push</i> on this API is very questionable,
+    # I would like to change this to a visually more telling API.
+    #
+    # @param new_env [#[], #[]=] a Hash like or a {Context}
+    #   that will serve as a fallback.
+    # @return {Context}
     def push(new_env = {})
-      # Context is explicit here
-      # (instead of self.class.new)
-      # because we can inherit a context,
-      # like the Lisp::Core does
-      # and then we want a normal context when pushing to it
+      # Context is explicit here instead of self.class.new
+      # because we can inherit a context
+      # like the Lisp::Core does.
+      # In this case we want a normal context when pushing to it
       # (and not a Lisp::Core).
       Context.new(new_env).tap { |c| c.fallback = self }
     end
 
+    # Return the current bindings in an Array.
+    #
+    # @example A simple {Context} with two bound {Symbol}
+    #   ctx = Context.new(
+    #     Symbol.new("lol") => "what time is it?",
+    #     Symbol.new("bbq") => 420,
+    #   )
+    #   ctx.bindings #=> [
+    #     [Symbol.new("lol"), "what time is it?"],
+    #     [Symbol.new("bbq"), 420]
+    #   ]
     def bindings
       @bindings ||= env.is_a?(Context) ? env.bindings : env.to_a
     end

data/lib/campa/core.rb

@@ -0,0 +1,6 @@
+module Campa
+  # Serves as a house to all functions
+  # that are essential for <i>Campa</i> to work
+  # but not necessary for <i>Lisp</i> itself.
+  module Core; end
+end

data/lib/campa/core/load.rb

@@ -1,10 +1,19 @@
 module Campa
   module Core
+    # Implements a <i>Campa</i> function
+    # that reads ({Reader}) and evaluates ({Evaler})
+    # files with valid <i>Campa</i> code in the given {Context}.
     class Load
       def initialize
         @evaler = Evaler.new
       end
 
+      # @param paths [Array<String>] Strings representing paths to files
+      #   to be evaled in a given context
+      # @param env [Context] where the files pointed by <i>paths</i>
+      #   will be evaled
+      # @return [Object] value of the last form evaled from the last file
+      #   given by <i>paths</i>
       def call(*paths, env:)
         verify_presence(paths)
         paths.reduce(nil) do |_, file|

data/lib/campa/core/print.rb

@@ -1,6 +1,18 @@
 module Campa
   module Core
+    # <i>Campa</i> function that print "anything" to the $stdout.
     class Print
+      # It uses {Printer} to transform an Object
+      # into a human readable form
+      # and sends it to $stdout.
+      #
+      # It is possible to override the preference for using $stdout
+      # by binding {SYMBOL_OUT} to a desired Object
+      # in the env given as a parameter to this method.
+      #
+      # @param stuff [Object] anything resulting from evaling a <i>Campa</i> expression
+      # @param env [Context] where {SYMBOL_OUT} will be searched
+      #   to find an alternative to $stdout
       def call(*stuff, env:)
         string =
           stuff

data/lib/campa/core/print_ln.rb

@@ -1,6 +1,22 @@
 module Campa
   module Core
+    # <i>Campa</i> function that print "anything" to the $stdout.
     class PrintLn
+      # It uses {Printer} to transform an Object
+      # into a human readable form
+      # and sends it to $stdout.
+      #
+      # Uses <i>#puts</i> method in the output to add a new line
+      # after sending each String representation
+      # created via {Printer} be sent to the output.
+      #
+      # It is possible to override the preference for using $stdout
+      # by binding {SYMBOL_OUT} to a desired Object
+      # in the env given as a parameter to this method.
+      #
+      # @param stuff [Object] anything resulting from evaling a <i>Campa</i> expression
+      # @param env [Context] where {SYMBOL_OUT} will be searched
+      #   to find an alternative to $stdout
       def call(*stuff, env:)
         out = env[SYMBOL_OUT] || $stdout
         stuff.each { |s| out.puts(s.is_a?(String) ? s : printer.call(s)) }

data/lib/campa/core/test.rb

@@ -1,12 +1,40 @@
 module Campa
   module Core
+    # Searches functions with prefix test_ or test- (case insenstive)
+    # in a given context, invoke those and
+    # store their results in a Data Structure with the given form:
+    #
+    #   (
+    #     (success, (test-one, test-two)),
+    #     (failures, (test-three, test-four))
+    #   )
+    #
+    # In this example we are considering that
+    # functions <i>test-one</i> and <i>test-two</i> returned <b>true</b> and
+    # functions <i>test-three</i> and <i>test-four</i> returned <b>false</b>.
     class Test
-      TEST_REGEXP = /\Atest(_|-)(.+)$/i
-
       def initialize
         @evaler = Campa::Evaler.new
       end
 
+      # Execute functions named test-* or test_* (case insentive)
+      # and collect the results.
+      #
+      # The param <i>tests</i> can be used to filter
+      # specific tests to be executed.
+      # For a context where functions
+      # test-great-one, test-great-two and test-awful exists,
+      # if we want to execute only the <i>great</i> ones, we could do:
+      #
+      # @example
+      #   test = Test.new
+      #   test.call("great", env: ctx)
+      #
+      # @param tests [Array<String>] if given will be used to "filter"
+      #   functions by name
+      # @param env [Context] will be used to search functions
+      #   named test-* or test_* (case insentive) and also
+      #   to execute those functions
       def call(*tests, env:)
         summary = execute_all(tests, env)
         List.new(
@@ -17,6 +45,8 @@ module Campa
 
       private
 
+      TEST_REGEXP = /\Atest(_|-)(.+)$/i
+
       attr_reader :evaler
 
       def execute_all(tests, env)

data/lib/campa/core/test_report.rb

@@ -1,6 +1,16 @@
 module Campa
   module Core
+    # Uses the result of a {Test#call} execution
+    # to show a human readable summary of a test execution.
     class TestReport
+      # Receives the result of {Test#call}
+      # and shows a (hopefully) useful test summary.
+      #
+      # @param result [List] result of calling {Test#call}
+      # @param env [Context] where object bound to {SYMBOL_OUT} will be searched
+      #   as an alternative to $stdout
+      # @return [Boolean] <b>true</b> if all tests were successful
+      #   (<b>false</b> otherwhise).
       def call(result, env:)
         success, failures = %i[success failures].map { |t| filter(t, result) }
         out = env[SYMBOL_OUT] || $stdout

data/lib/campa/evaler.rb

@@ -1,9 +1,24 @@
 module Campa
+  # All the actual logic on how to evaluate
+  # the differente known forms
+  # in implemented in here.
   class Evaler
     def initialize
       @printer = Printer.new
     end
 
+    # Returns the result of a given form evaluation.
+    #
+    # The parameter expression is evaluated
+    # based on it's type.
+    # Primitives (like booleans, nil, strings...) are returned as is.
+    # {Symbol}s and {List}s are handled like this:
+    # - {Symbol}'s are searched in the given {Context} (env parameter).
+    # - {List}'s are considered function invocations.
+    #
+    # @param expression Can be any known form.
+    # @param env [#[], #[]=] Hash or {Context} containing the bindings
+    #   for the current <i>Campa</i> execution.
     def call(expression, env = {})
       context = self.context(env)
 
@@ -17,6 +32,15 @@ module Campa
       end
     end
 
+    # Receives a {Reader} object
+    # and evaluate all forms returned
+    # by each <i>#next</i> call.
+    # Uses {#call} to do the actual evaluation.
+    #
+    # @param reader [Reader] representing the source code to be evaluated
+    # @param env [Context] to evaluate the code
+    # @return [Object] the result of evaluating the last form
+    #   available in the given {Reader}
     def eval(reader, env = {})
       context = self.context(env)
 

data/lib/campa/execution_error.rb

@@ -1,3 +1,6 @@
 module Campa
+  # This exception serves as a base error.
+  #
+  # In a way it is the "StandardError" on Campa's runtime.
   class ExecutionError < StandardError; end
 end

data/lib/campa/lambda.rb

@@ -1,7 +1,49 @@
 module Campa
+  # Represents an anonymous function
+  # that will be executed in a given {Context}.
+  #
+  # @example
+  #   # given the representation of
+  #   # ((lambda (something) (print something)) "hello world")
+  #   lbd = Lambda.new(
+  #     [Symbol.new("something")],
+  #     [List.new(Symbol.new("print"), Symbol.new("something"))]
+  #   )
+  #
+  #   # sends "hello world" to the $stdout and returns
+  #   lbd.call("hello world") #=> nil
+  #
+  # @example working with closures:
+  #
+  #   # given the representation of
+  #   # (label meaning 42)
+  #   # ((lambda (time) (print "time: " time " meaning of life: " meaning)) 420)
+  #   ctx = Context.new(Symbol.new("meaning") => 42)
+  #
+  #   lbd = Lambda.new(
+  #     [Symbol.new("time")],
+  #     [
+  #       List.new(
+  #         Symbol.new("print"),
+  #         "time: ", Symbol.new("time"),
+  #         ", meaning of life: ", Symbol.new("meaning")
+  #       )
+  #     ],
+  #     ctx
+  #   )
+  #
+  #   # sends "time: 420, meaning of life: 42" to $stdout and returns
+  #   lbd.call(420) #=> nil
   class Lambda
     attr_reader :params, :body, :closure
 
+    # @param params [Array<Symbol>] {Symbol}s naming the parameters
+    #   that a lambda can receive when being invoked
+    # @param body [Array<Object>] expressions composing the body,
+    #   they are executed one by one in order
+    #   in the given {Context}
+    # @param closure [Context] used as a fallback for the {Context}
+    #   given when the {Lambda} is executed
     def initialize(params, body, closure = Context.new)
       @params = params
       @body = Array(body)
@@ -9,6 +51,21 @@ module Campa
       @evaler = Evaler.new
     end
 
+    # Executes the expressions contained in the {#body}
+    # one by one using as {Context} the parameter <i>env:</i>
+    # on this method.
+    #
+    # The <i>env:</i> param will be used here
+    # as a fallback to a brand new {Context}
+    # created in the moment of the invocation.
+    # This isolates the {Context} passed as a parameter
+    # of any mutations that would be created
+    # by the {Lambda} if there is any binding during the execution.
+    #
+    # @param args [Array<Object>] the values that will be bound
+    #   to each of the {#params} given to the constructor
+    # @param env [Context] for the execution of a lambda
+    # @return [Object] result of evaluating the last expression on {#body}
     def call(*args, env:)
       raise arity_error(args) if params.to_a.length != args.length
 
@@ -20,6 +77,12 @@ module Campa
       end
     end
 
+    # Stablishes equality between {Lambda} objects
+    # by comparing {#params} and {#body}
+    #
+    # @param other [Lambda] another {Lambda}
+    # @return [Boolean] <b>true</b> if {#params} names and {#body} expressions
+    #   are <i>#==</i> in both {Lambda}.
     def ==(other)
       return false if !other.is_a?(Campa::Lambda)
 

data/lib/campa/language.rb

@@ -1,4 +1,12 @@
 module Campa
+  # {Context} wrapping the core bindings
+  # that form the core for <b>Campa</b> (language).
+  #
+  # It extends {Lisp::Core} to add
+  #   - (test-run ...)
+  #   - (tests-report)
+  #   - (print ...)
+  #   - (println ...)
   class Language < Lisp::Core
     def initialize
       super

data/lib/campa/lisp/core.rb

@@ -1,6 +1,24 @@
 module Campa
   module Lisp
+    # {Context} representing the base for the minimal Lisp
+    # stablished by <i>Paul Graham's: <b>The Roots of Lisp</b></i>.
+    #
+    # Since this is a {Context}
+    # it can be instantiated and use as a parameter
+    # to any function invocation that
+    # want's to use <i>Lisp</i> functions on it's body.
+    # And also, it can be used as a fallback
+    # so if we want to "extend" <i>Lisp</i>
+    # we could Inherit it or {#push} a new {Context} on it.
     class Core < Context
+      def initialize
+        super Hash[
+          CORE_FUNCS_MAP.map { |label, handler| [sym(label), handler.new] }
+        ]
+      end
+
+      private
+
       CORE_FUNCS_MAP = {
         "quote" => Quote,
         "atom" => Atom,
@@ -19,14 +37,6 @@ module Campa
         "load" => Campa::Core::Load,
       }.freeze
 
-      def initialize
-        super Hash[
-          CORE_FUNCS_MAP.map { |label, handler| [sym(label), handler.new] }
-        ]
-      end
-
-      private
-
       def sym(label)
         Campa::Symbol.new(label)
       end

data/lib/campa/list.rb

@@ -1,9 +1,21 @@
 module Campa
+  # A minimalist implementation of a Linked List.
+  #
+  # An instance of it represents a function ivocation
+  # in the context of a {Evaler#call} or a {Evaler#eval} call.
+  #
+  # The importance of adding the adjective <i>"minimalist"</i>
+  # in this description
+  # is to give already the idea that this implementation
+  # does not come with some algorithms (deleting, for example)
+  # since for this also minimal Lisp implementation
+  # this won't be necessary.
   class List
     include Enumerable
 
     EMPTY = new
 
+    # @param elements [Array<Object>] elements linked on the current {List}
     def initialize(*elements)
       @first = nil
       @head = nil
@@ -12,24 +24,45 @@ module Campa
       with elements
     end
 
+    # Creates a new {List} with the parameter passed
+    # in front of it.
+    #
+    # @example
+    #   List.new(2, 3).push(1) #=> List.new(1, 2, 3)
+    #
+    # @param element [Object] any thing to be pushed into the {List}
+    # @return [List] new {List} with new element in front of it
     def push(element)
       self.class.new.tap do |l|
         l.first = Node.new(value: element, next_node: first)
       end
     end
 
+    # First element of the current {List}.
+    #
+    # Return <i>nil</i> if the current list is {EMPTY}.
+    #
+    # @return [Object, nil]
     def head
       return nil if self == EMPTY
 
       first.value
     end
 
+    # Creates a new list
+    # with all elements of the current one BUT the head.
+    #
+    # @example
+    #   List.new(1, 2, 3).tail #=> List.new(2, 3)
+    #
+    # @return [List] with the "rest" of the elements on this {List}
     def tail
       return EMPTY if first.nil? || first.next_node.nil?
 
       self.class.new.tap { |l| l.first = @first.next_node }
     end
 
+    # Yields each element starting from head.
     def each(&block)
       return if self == EMPTY
 
@@ -37,6 +70,11 @@ module Campa
       tail.each(&block) if tail != EMPTY
     end
 
+    # Stablishes equality by comparing each element in the {List}.
+    #
+    #
+    # @param other [List] to be compared
+    # @return [Boolean] <b>true</b> if of both {List} have equal (<i>#==</i>) elements
     def ==(other)
       return false if !other.is_a?(List)
 
@@ -56,6 +94,11 @@ module Campa
       end
     end
 
+    # Uses {Printer} to represent the current {List}
+    # in a human readable form.
+    #
+    # @example
+    #   List.new(1, 2, 3).inspect #=> "(1 2 3)"
     def inspect
       @printer ||= Printer.new
       @printer.call(self)

data/lib/campa/node.rb

@@ -1,13 +1,19 @@
 module Campa
+  # A node containing a value to form a linked {List}.
   class Node
     attr_accessor :next_node
     attr_reader :value
 
+    # @param value [Object] actual value in the {List} node
+    # @param next_node [Node] next node linked in the {List} chain,
+    #   this {Node} is the last if <i>next_node:</i> is <i>nil</i>
     def initialize(value:, next_node: nil)
       @value = value
       @next_node = next_node
     end
 
+    # @param other [Node] to be compared
+    # @return [Boolean] <b>true</b> if {#value} is <i>#==</i> on both {Node}
     def ==(other)
       return false if !other.is_a?(Node)
 

data/lib/campa/printer.rb

@@ -1,5 +1,32 @@
 module Campa
+  # Represents a <i>Campa</i> expression
+  # in a human readable form.
+  #
+  # In general it tries to create a representation
+  # that is valid <i>Campa</i> code
+  # to make it easy(ier) to copy and paste stuff
+  # from the REPL to a file.
+  #
+  # @example some results produced by {Printer}
+  #   printer = Printer.new
+  #
+  #   printer.call("lol") #=> "lol"
+  #   printer.call("lol") #=> 123
+  #   printer.call(List.new("bbq", 420, List.new("yes"))) #=> ("bbq" 420 ("yes"))
   class Printer
+    # @param expr [Object] <i>Campa</i> expression to be respresented in
+    #   human readable form
+    # @return [String] human readable form (almost always valid code)
+    #   of an Expression
+    def call(expr)
+      format = FORMATS.fetch(expr.class) do
+        expr.is_a?(Context) ? :context : :default
+      end
+      send(format, expr)
+    end
+
+    private
+
     FORMATS = {
       String => :string,
       Symbol => :symbol,
@@ -11,15 +38,6 @@ module Campa
       NilClass => :null,
     }.freeze
 
-    def call(expr)
-      format = FORMATS.fetch(expr.class) do
-        expr.is_a?(Context) ? :context : :default
-      end
-      send(format, expr)
-    end
-
-    private
-
     def string(expr)
       "\"#{expr}\""
     end

data/lib/campa/reader.rb

@@ -1,14 +1,28 @@
 require "stringio"
 
 module Campa
+  # Reads strings or files into <i>Campa</i> expressions.
   # rubocop: disable Metrics/ClassLength
   class Reader
     # rubocop: enable Metrics/ClassLength
+
+    # Given a String, a file pointer or any <i>#getc</i>, <i>#eof?</i>
+    # it allows fetch every valid <i>Campa</i> form from it.
+    #
+    # If the String is a valid file path
+    # it will be converted into a file pointer.
+    # Anything else will be converted into a StringIO
+    #
+    # @param input [String, (#getc, #eof?)]
     def initialize(input)
       @input = to_io_like(input)
       next_char
     end
 
+    # Return the next <i>Campa</i> form available
+    # in the underlying io like object.
+    #
+    # @return [Object] next available <i>Campa</i> form
     def next
       eat_separators
       return read if !@input.eof?

data/lib/campa/repl.rb

@@ -1,5 +1,12 @@
 module Campa
   class Repl
+    # It creates a new {Context} that uses one
+    # given as a parameter to this contructor to evaluate
+    # expressions typed in the <b>REPL</b>.
+    #
+    # @param evaler [Evaler] used to extract value from expressions
+    # @param context [Context] against which expressions will be evaled
+    # @param reader [Reader] to return expressions to be evaled
     def initialize(evaler, context, reader: Reader)
       @reader = reader
       @evaler = evaler
@@ -8,6 +15,17 @@ module Campa
       @printer = Printer.new
     end
 
+    # Uses the <i>#getc</i> method from the parameter <i>input</i>
+    # to create a (probably blocking) loop to evaluate code "live"
+    # creating a <b>REPL</b> session.
+    #
+    # Captures the Interrupt exception to break the loop
+    # and finish the current <b>REPL</b> session.
+    #
+    # @param input [IO] an IO like object from where tokens will be extracted
+    # @param output [IO] IO like object to receive the output
+    #   from evaluating the forms
+    #
     # rubocop: disable Metrics/MethodLength
     def run(input, output)
       output.print "=> "

data/lib/campa/symbol.rb

@@ -1,21 +1,32 @@
 module Campa
+  # Represents the name to which a value is bound in a specific {Context}.
+  #
+  # Implements the necessary interface to be used with success
+  # as key in Hash objects.
   class Symbol
     attr_reader :label
 
+    # @param label [String] name to be bound to a value in a given {Context}
     def initialize(label)
       @label = label
     end
 
+    # @param other [Symbol] another {Symbol} to be compared
+    # @return [Boolean] <b>true</b> if both {#label} are <i>#==</i>
     def ==(other)
       return false if !other.is_a?(self.class)
 
       label == other.label
     end
 
+    # @param other [Symbol] another {Symbol} to be compared
+    # @return [Boolean] <b>true</b> if both {Symbol} are <i>#==</i>
+    #   and both {#hash} are <i>#==</i>
     def eql?(other)
       self == other && hash == other.hash
     end
 
+    # @return [String] String based on <i>label#hash</i>.
     def hash
       @hash ||= "Campa::Symbol_#{label}".hash
     end

data/lib/campa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Campa
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: campa
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Ricardo Valeriano
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-29 00:00:00.000000000 Z
+date: 2021-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -32,6 +32,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitattributes"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -52,6 +53,7 @@ files:
 - lib/campa.rb
 - lib/campa/cli.rb
 - lib/campa/context.rb
+- lib/campa/core.rb
 - lib/campa/core/load.rb
 - lib/campa/core/print.rb
 - lib/campa/core/print_ln.rb