campa 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65c3985813d98dec3df69c8f956d3fc06fc2c8c4b48875d8ff1f273a324b83d4
-  data.tar.gz: a1563601fdb1e7cb7e9727a80670d51c11704c91595e6cc22184b25a79b89975
+  metadata.gz: 0150f5fd77bacb8efd9e190bdae9ba219db3fbd4aea1cda44677dd97c5c33881
+  data.tar.gz: 7a68bda264a3ccb37c74c618c1c38e472d0786efc90a335065f66c640c00892c
 SHA512:
-  metadata.gz: 39d8e5da9a5bda8b42cb6e2ec03fed4d2f49eceaaf1f17b8deab6dd903885b79b212c42ba05910ebe253694e63aa42488c74740be6807422792caaf7a420aa26
-  data.tar.gz: f944df966fbdd2cbba599c876bc7536f3181aef0d016db96436987737dff9e8f83a95490cdfcc55ac344b6120aed20a741b9e4168dafba7fdda28074095fa715
+  metadata.gz: d73fd6d7e091d1c2820ead91af26e5d7ce94cf8971c08829bf4a8323c150b589bd0505f3cfde2df34d263259c168284413b4e9399213ca85b164ddfbc416aa6e
+  data.tar.gz: 93c832a4259a5ce546bfea743b6a0b1f0f02667dec51b9dbffab796b8ec13fa0b0a56e44bfecf7c392a596a0ae39c2a669a28a04a0016a881629081f9d731f74

data/.travis.yml

@@ -6,3 +6,9 @@ rvm:
 install:
   - gem install bundler -v 2.2.20
   - bundle install --jobs=3 --retry=3
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    campa (0.1.0)
+    campa (0.1.1)
       zeitwerk (~> 2.4)
 
 GEM

data/README.md

@@ -1,28 +1,244 @@
 # Campa
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/campa`. To experiment with that code, run `bin/console` for an interactive prompt.
+![travis build (shildes.io) badge](https://img.shields.io/travis/com/mistersourcerer/campa?style=plastic "Build Status")
+![coverage (shildes.io) badge](https://img.shields.io/codeclimate/coverage/mistersourcerer/campa?style=plastic "Coverage Status")
+![gem version (shildes.io) badge](https://img.shields.io/gem/v/campa?include_prereleases&style=plastic "Version")
 
-TODO: Delete this and the text above, and describe your gem
+This is a [LISP](https://www.britannica.com/technology/LISP-computer-language) implementation written in Ruby.
 
-## Installation
+[![XKCD lisp cycles comic strip](https://imgs.xkcd.com/comics/lisp_cycles.png)](https://xkcd.com/297/)
 
-Add this line to your application's Gemfile:
+It comes equiped with a [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)
+and a (very rudimentary) test framework.
 
-```ruby
-gem 'campa'
-```
+You can install this gem normaly with:
+
+    $ gem install campa
 
-And then execute:
+And after that the REPL can be run:
 
-    $ bundle install
+    $ campa
 
-Or install it yourself as:
+This will give you a prompt
+where you can check if campa is working
+by making an offer to the gods of programming:
 
-    $ gem install campa
+    => (defun hello-world () (print "hello world"))
+    (lambda () (print "hello world"))
+    => (hello-world)
+    "hello world"NIL
+
+## What is this about?
+
+Before going any further
+you should probably know that,
+as a LISP implementation,
+this one is for sure on the EXTREMELY simple
+side of the measuring device - whatever such a thing may be.
+
+<img src="https://i.chzbgr.com/full/6819818496/h1DC5249B/measurement-fail" width="300" />
+
+It's main purpose is to create room
+for the author to learn about LISP
+and language implementation.
+So you should curb your enthusiasm while using/reading it.
+
+
+### Paul Graham's The Roots of Lisp
+
+There is this article by [Paul Graham](http://www.paulgraham.com/)
+called [The Roots of Lisp](http://www.paulgraham.com/rootsoflisp.html).
+As far as I can tell this is a seminal work
+[that helped many people to understand LISP better](https://hn.algolia.com/?dateRange=all&page=0&prefix=false&query=%22roots%20of%20lisp%22&sort=byPopularity&type=story)
+and maybe even made [the original McCarthy's ideas](https://crypto.stanford.edu/~blynn/lambda/lisp.html)
+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)
+and see how it is done already).
 
 ## Usage
 
-TODO: Write usage instructions here
+### Executing .cmp files
+
+Let's say you have a *Campa* file `hello.cmp`
+with the following code:
+
+```lisp
+(defun hello (stuff) (print "hello" stuff))
+(label thing "Marvin")
+
+(hello thing)
+```
+
+You can run this code
+by using the *campa* executable like this:
+
+    $ campa hello.cmp
+    hello Marvin
+
+Note that the functions *print* and *println*
+are given "for free" to the user
+in the sense that they are not specified in the *Roots of Lisp*.
+But more on that later.
+
+### Playing around in the REPL
+
+Now if you want to play around with some ideas
+before commit those to a file
+(or version control, for that matter)
+you can fire up the repl by typing _campa_:
+
+    $ campa
+    =>
+
+The **=>** is the *REPL* prompt
+and a sign that you can enter code now.
+
+I will use this opportunity to show you
+yet another function that comes with this implementation
+but is not part of the *Roots of Lisp*.
+Let's *load* the same file that was used on the previous example
+in the current *REPL* session.
+
+    => (load "./hello.cmp")
+    hello  MarvinNIL
+
+The **NIL** shown after the printed message
+(hello Marvin) is the return of the *print* function itself.
+
+Notice also that the function *hello*,
+declared in the *hello.cmp* file,
+is now available in the current *REPL* session.
+
+    => (hello "World")
+    hello  WorldNIL
+
+## The Roots
+
+The following functions are available
+and considered the **core** of this LISP implementation.
+They all have the expected behavior specified
+in the aforementioned article [*The Roots of Lisp*](http://www.paulgraham.com/rootsoflisp.html).
+
+```lisp
+(atom thing)
+(car list)
+(cdr list)
+(cond ((condition) some-value) ((other-condition) other-value))
+(cons 'new-head '(list with stuffz))
+(defun func-name (params, more-params) (do-something))
+(eq 'meaning-of-life 42)
+(label a-symbol 4,20)
+(lambda (params, more-params) (do-something))
+(list 'this 'creates 'a 'list 'with 'all 'given 'params)
+(quote '(a b c))
+```
+
+Besides the actual functions
+the notation that uses single quotation mark (')
+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).
+
+## Beyond the Roots
+
+Some mentions were made in this very own Readme
+about things that are available on *Campa*
+but were not specified on *Roots of Lisp*.
+
+Those are mainly functions and they come in two flavors:
+the ones implemented on *Campa* itself
+and the ones implemented on the runtime (in Ruby).
+
+### Extras in Campa
+
+  - [(assert x y)](../blob/4fc244d41dd6d9/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)
+    Read and evaluate the files given as arguments
+  - [(print "some" "stuff" 4 '("even" "lists"))](../blob/4fc244d41dd6d9/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)
+    Same as print but add a line break (`\n`) after each parameter.
+
+#### Tests
+
+There is a very simplistic test framework
+implemented in the runtime.
+It is available via the *campa* command line
+with the option **test**.
+It receives as argument files containing well...
+tests.
+
+The definition of a test in this context is any function
+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).
+
+    $ campa test test/core_test.cmp
+
+    10 tests ran
+    Success: none of those returned false
+
+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)
+
+The *tests-run* function will find
+any function whose name starts with *test-* or *test_* (case insensitive)
+in the current context and run it.
+A function that returns false
+is considered a failing test.
+
+We can simulate this clearly in the REPL:
+
+    $ campa
+    => (defun test-one () "do nothing" false)
+    (lambda () "do nothing" false)
+    => (defun test-two () "great success" true)
+    (lambda () "great success" true)
+    => (tests-run)
+    ((success (test-two)) (failures (test-one)))
+
+This structure returned by *tests-run*
+is well known by a second function...
+
+##### (tests-report)
+
+... we can use the *tests-report* function
+to show a nice summary of tests ran:
+
+    => (tests-report (tests-run))
+    2 tests ran
+    FAIL!
+      1 tests failed
+      they are:
+        - test-one
+    false
+
+Notice that *tests-report* return *false* if there is a failure
+or *true* if all tests pass.
+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).
+
 
 ## Development
 

data/campa.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/mistersourcerer/campa."
+  spec.metadata["source_code_uri"] = "https://github.com/mistersourcerer/campa"
   spec.metadata["changelog_uri"] = "https://github.com/mistersourcerer/campa/blob/main/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
@@ -28,7 +28,4 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "zeitwerk", "~> 2.4"
-
-  # For more information and examples about making a new gem, checkout our
-  # guide at: https://bundler.io/guides/creating_gem.html
 end

data/lib/campa/core/load.rb

@@ -8,7 +8,8 @@ module Campa
       def call(*paths, env:)
         verify_presence(paths)
         paths.reduce(nil) do |_, file|
-          evaler.eval(Reader.new(file), env)
+          reader = Reader.new(File.expand_path(file))
+          evaler.eval(reader, env)
         end
       end
 
@@ -17,7 +18,7 @@ module Campa
       attr_reader :evaler
 
       def verify_presence(paths)
-        not_here = paths.find { |f| !File.exist?(f) }
+        not_here = paths.find { |f| !File.file?(File.expand_path(f)) }
         raise Error::NotFound, not_here if !not_here.nil?
       end
     end

data/lib/campa/core/print.rb

@@ -4,7 +4,7 @@ module Campa
       def call(*stuff, env:)
         string =
           stuff
-          .map { |s| printer.call(s) }
+          .map { |s| s.is_a?(String) ? s : printer.call(s) }
           .join(" ")
         (env[SYMBOL_OUT] || $stdout).print(string)
         nil

data/lib/campa/core/print_ln.rb

@@ -3,7 +3,7 @@ module Campa
     class PrintLn
       def call(*stuff, env:)
         out = env[SYMBOL_OUT] || $stdout
-        stuff.each { |s| out.puts printer.call(s) }
+        stuff.each { |s| out.puts(s.is_a?(String) ? s : printer.call(s)) }
         nil
       end
 

data/lib/campa/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: campa
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Ricardo Valeriano
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-27 00:00:00.000000000 Z
+date: 2021-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -95,7 +95,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/mistersourcerer/campa
-  source_code_uri: https://github.com/mistersourcerer/campa.
+  source_code_uri: https://github.com/mistersourcerer/campa
   changelog_uri: https://github.com/mistersourcerer/campa/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []