Getting Started - blancas/eisen GitHub Wiki

In this page we'll cover the basics of the API and how to evaluate Eisen code at the Clojure REPL. Once the project dependency is added to the Leiningen project.clj or Maven pom.xml, we can load the core namespace:

(use 'blancas.eisen.core)

Next we initialize the library:

(init-eisen)
;; #<Namespace user>

This will install predefined commands to the language and make available to Eisen code a set of Clojure core functions with similar but idiomatic names. For example, readLine instead of read-line. Since Eisen uses infix arithmetic notation, dashes are not allowed in regular names. In order to use a Clojure name with dashes it has to be put in backquotes: `read-line`. So these predefined names make common Clojure function easier to type.

eisen runs the supplied Eisen code. It takes an optional string with the origin of the text, like "repl" or a file name for use in error messages. This function is meant to be used programmatically and not interactively.

(eisen "3 + 4")
;; {:ok true, :decls ((+ 3 4)), :value 7}
(eisen "3 / 0")
;; {:ok false, :error [(/ 3 0) "java.lang.ArithmeticException: Divide by zero"]}

The return value is a map with the following fields:

:ok a boolean that is true on success and false on failure.
:decls the translated Clojure code if :ok is true.
:value the value of the Eisen code.
:error the translated Clojure code plus any error message if :ok is false.

eisen= runs the supplied Eisen code; for use at the REPL. It returns the :value field or prints any error messages if the code fails to evaluate.

(eisen= "3 + 4")
;; 7
(eisen= "3 / 0")
;; [(/ 3 0) java.lang.ArithmeticException: Divide by zero]

eisen* parses the supplied Eisen code; for use at the REPL. It returns the abstract syntax tree (AST) that results from the parsing phase. The code is not translated nor evaluated.

(eisen* "3 + 4")
;; [{:token :BINOP,
;;   :op {:token :sym, :value \\+, :pos {:src "", :line 1, :col 3}},
;;   :left {:token :dec-lit, :value 3, :pos {:src "", :line 1, :col 1}},
;;   :right {:token :dec-lit, :value 4, :pos {:src "", :line 1, :col 5}}}]

eisenf runs the code in the file specified by the supplied path. It takes an optional string argument with the encoding to use for reading the file. The return value is the same as the eisen function.

$ cat avg.esn
(1.0 + 2.0 + 3.0) / 3

(eisenf "avg.esn")
;; {:ok true, :decls ((/ (+ (+ 1.0 2.0) 3.0) 3)), :value 2.0}

eisenf= runs the code in the file specified by the supplied path. It takes an optional string argument with the encoding to use for reading the file. Like the eisen= function, it will return the :value field of the resulting map or print any error messages.

(eisenf= "avg.esn")
;; 2.0

eisen-repl starts a REPL for evaluating Eisen code. The REPL reads text until an empty line is entered, showing a continuation prompt (by default >) when it asks for more input. To end this loop and go back to the Clojure REPL type "//" and Enter.

(eisen-repl)
user: 3 + 4
> 
7
user: (1.0 + 2.0 + 3.0) / 3
> 
2.0
user: //
user=>