Note to anyone who may care: I haven't used or substantially updated this project in a long time and do not plan on putting any further effort into it. The npm package has been deprecated to reflect this. If you want this to work for you, feel free to fork it.
Oppo is a sweet little lisp for javascript. This is experimental, and therefore any suggestions are welcome.
To install, run the following in your terminal. Make sure you have node.js and npm installed first.
npm install -g [email protected] # The repl doesn't work properly in 0.1.3
Now you have access to the oppo
command. To enter the repl:
oppo
or
oppo -r
To compile a file:
oppo -c /path/to/file.oppo
You can also specify an output file:
oppo -o /path/to/file.js -c /path/to/file.oppo
In the previous command, if you have uglify-js2
installed globally,
it will prettify the resulting javascript. You could pass the -C
switch to
have it compress your code instead.
To run a file:
oppo /path/to/file.oppo
Since oppo is a lisp, it takes on the basic semantics of a lisp. Oppo isn't dissimilar to scheme or clojure, so if you want to get a feel for the basic semantics of lisp, there's plenty of code out there to look at.
Here are some specifics about the way oppo is parsed:
- Integer:
2
,-5
- Float:
-2.5
,.34
- Scientific notation:
10e-2.5
- Explicit base:
2#001101
,8#1427
,16#fff
"whatever"
. If you need to escape a double-quote, you can use \"
.
Oppo accepts most characters as valid symbols. Symbols can't start
with a number or any of the following sequences: #
, "
, '
, \``,
,,
,@,
.`. Symbols can't contain any kind of whitespace. Anything
else on the US keyboard is fair game.
Lists are code. Oppo code is primarily a tree of lists. All lists are executable. The basic way to make a list is to put space-separated items in parenthesis:
(puts "I" "am" "a" "list")
Since lists are executable, this will call the puts
macro, which
will log the rest of the items in the list to the console. If you
don't want your list to be executed you can quote it or use a literal
array:
'(1 2 3) ;; Won't try to call this as a function
#[1 2 3] ;; Same result
Oppo only thinks of objects as data and never tries to execute an object. Objects are made like this:
#{'a 1 'b 2}
You can do some interesting things with oppo objects that you can't do in javascript (at least not as easily). For example, keys can be variables in the same way their values can:
(def key 'asdf)
(def value 5)
#{key value} ;; -> #{asdf 5}
Oppo uses the lambda
macro to generate functions. There is also a
reader macro #(...)
which acts as a shorthand for the lambda
macro. You can also define a function with the def
macro:
(lambda (a b) (+ a b))
#(+ #1 #2) ;; #1 and #2 access the 0th and 1st arguments respectively
(def (add-a-b a b)
(+ a b))
Following is a list of macros, functions and variables available to
the oppo programmer. Entries take the format of
<module>::<item-name>
. The core
module is automatically available,
so you don't have to use the module prefix in that case. As an
example, you can call core::str
by simply invoking str
(unless you
have replaced str
in your current module or in an active local
scope).
-
macro
core::defmacro
:(defmacro optional-metadata (macro-name ...args) ...body)
Defines a macro.Example:
(defmacro (log ...x) `(.log console ,@x))
-
macro
core::def
:(def optional-metadata name value)
|(def optional-metadata (fn-name ...args) ...body)
Defines a variable on the current module.Example:
;; Define module variable (def one 1) ;; Define function (def (identity x) x)
-
macro
core::set!
:(set! name value)
Resets the value of a variable.Example:
(def n 1) (set! n (+ n 1))
-
macro
core::lambda
:(lambda (...args) ...body)
Creates a function. You can also use the#(...)
reader macro for this. Arguments that aren't named can still be accessed from thearguments
object. A reader macro is provided for this as well,#1
where the1
can be any number greater than 0.#1
will access the 0th argument,#2
the first argument and so on.Example:
(map (lambda (a) (+ a 1)) #[1 2 3 4 5]) ;; -> #[2 3 4 5 6] (map #(+ #1 1) #[1 2 3 4 5]) ;; -> #[2 3 4 5 6]
-
macro
core::call
:(call callable-item ...args)
This is used internally for all function/macro calling. This is not generally the way you will need to call things.Example:
(call puts 1 2 3) ;; The normal way to call things is without `call`. ;; Running it this way will do the same thing as the line above. (puts 1 2 3)
-
macro
core::object-get-value
:(object-get-value prop base)
Gets the value with the correspondingprop
in a collection. You shouldn't often need to invoke this directly. See example below.Example:
(object-get-value 'alert window) ;; Here's a better way to do this: ('alert window) ;; or ("alert" window)
-
macro
core::.
:(. fname base ...args)
Gets a callable value frombase
and immediately calls it withargs
. Because of a handy reader macro, there doesn't need to be a space separating the.
from thefname
.Example:
(.alert window 5) (."static" express)
-
macro
core::quote
:(quote x)
Quotesx
. Instead of using the explicit call, most of the time you will want to use the reader macro'
.Example:
(quote x) ;; -> x 'x ;; -> x
-
macro
core::quasiquote
:(quasiquote x)
Quasiquotesx
. You can also use the reader macro ```.Example:
(def a 5) `(1 2 3 4 a ,a) ;; -> '(1 2 3 4 a 5)
-
macro
core::unquote
:(unquote x)
Unquotesx
. You can also use the reader macro,
.Example:
(def a 5) `(1 2 3 4 a ,a) ;; -> '(1 2 3 4 a 5)
-
macro
core::unquote-splicing
:(unquote-splicing x)
Unquotes each item inx
in sequence into another structure. You can also use the reader macro,@
.Example:
(def a #[1 2 3 4 5]) `(0 ,@a 6) ;; -> #[0 1 2 3 4 5 6]
-
macro
core::let
:(let (...bindings) ...body)
Introduces a local scope.bindings
are the local variables. It will run each item in body in this new local scope and return the result of the last item.Example:
(let [a 1 b 2 c 3] (+ a b c)) ;; -> 6
-
macro
core::if
:(if condition run-if-true optional-run-if-false)
if
expression.Example:
(if (nil? x) (do-something) (do-something-else))
-
macro
core::for
:(for [defs ls] ...body)
Thefor
expression is very similar to map, but can be much faster.Example:
;; `n` represents an item in the array. (for [n #[1 2 3 4 5]] (* n 2)) ;; -> #[2 4 6 8 10] ;; `n` represents an item in the array and `i` represents the index. (for [(n i) #[1 2 3 4 5]] (+ n i)) ;; -> #[1 3 5 7 9]
-
macro
core::do
:(do ...body)
do
will run each item inbody
and give you the result of the last statement.Example:
(if (< n 5) (do (puts n) (set! n (+ n 1))))
-
macro
core::include
:(include ...module-names)
This will find and compile each module. If the module has already been compiled, then it is already available and will not attempt to compile it again.Modules are simple directory paths that are resolved in the same base directory as the main file. Generally, you should only send one single file to the oppo compiler, and this file will include all the modules it needs, and those modules will include the modules they need, and so forth. In this way, the compiler will get all the source files used and compile them all into a single javascript file.
Example:
(include routes/main routes/users) (.get app "/" routes/main::home) (.get app "/user/:id" routes/users::show)
-
macro
core::apply
:(apply fn args)
This is the same as using the javascript .apply function, except you can't specify scope. -
macro
core::require
:(require module-name)
|(require varname module)
Makes using the node.js require function (or any implementation similar enough) simpler to use.Example:
(require express) ;; var express = require('express'); (require routes "./routes") ;; var routes = require('./routes');
-
macro
core::new
:(new Class ...args)
Allows you to instantiate a class. -
macro
core::puts
:(puts ...args)
Logs output to the console. -
macro
core::puts-warning
:(puts-warning ...args)
Logs warning message to the console. -
macro
core::puts-error
:(puts-error ..args)
Logs error message to the console. -
macro
core::cond
:(cond cond1 body1 cond2 body2 cond-n body-n)
Evaluates each condition until it finds one that is true. When it finds a true condition, it executes the corresponding body.Example:
(def n 3) (cond (eq n 1) (puts "one") (eq n 2) (puts "two") (eq n 3) (puts "three") 'else (puts "idk")) ;; will print "three" to the console.
-
macro
core::use-from
:(use-from module ...items)
Extracts items frommodule
and defines a copy locally.Example:
(use-from js eval typeof) ;; Now the macros eval and typeof are available in the current scope.
-
macro
core::use
:(use module1 defs1 module2 defs2 module-n defs-n)
With each module and defs pair, it callsuse-from
.Example:
(use module-a [a b c] module-b [d e f])
-
macro/function
core::symbol
:(make-symbol x)
Generates a symbol from x.Example:
(symbol 'asdf) (symbol "asdf")
-
Basic operations These are all of type macro/function, and are all in the module
core
. They all correspond with the same operator in javascript unless otherwise noted.Math
+
-
*
/
Logical
not
(javascript!
)or
(javascript||
)and
(javascript&&
)
Comparison
<
>
<=
>=
eq
(javascript===
)not-eq
(javascript!==
)eq~
(javascript==
)not-eq~
(javascript!=
)
-
Type checking All the following are of type function/macro and check to see that their argument is equal to the type the name describes. (For example,
(number? x)
returns true whenx
is a number). All are in thecore
module.number?
string?
array?
arguments?
(returns true when its argument is a function's arguments object.)nil?
(returns true when its argument is either null or undefined.)function?
regex?
date?
-
function
core::typeof
:(typeof x)
This is thetoType
function by Angus Croll found here. -
function
core::eval
:(eval to-eval)
This invokes oppo's compiler onto-eval
,eval
s the compiled code using the javascripteval
function and returns the computed result.Example:
(eval '(+ 1 1)) ;; -> 2
-
function
core::empty?
:(empty? coll)
Checks to see if a collection is empty. Accepts argument of any type. Empty arrays, objects and strings will return true. Additionally,#nil
and0
will also return true. Anything else will return false. -
function
core::contains?
:(contains? coll value optional-deep-eq)
Checks to see if the collection contains the value.optional-deep-eq
is#true
by default. If it is set to#false
, it will use the===
operator for comparison rather than the oppo=
function. -
function
core::contains-key?
:(contains-key? coll, key)
Checks to see if the collection contains the given key. Works for arrays, the arguments object, strings and objects. If you pass something else forcoll
, the result will be#false
. -
function
core::list
:(list ...args)
Makes a list out of the arguments. You can call this function directly, or you can use the#[...]
reader macro.Example:
(= (list 1 2 3) #[1 2 3]) ;; -> #true
-
function
core::->list
:(->list object)
Turns any object with a length property into a list. -
function
core::map
:(map fn list)
Invokesfn
with each item inlist
and gathers the results of those calls into an array, which is returned. Similar tofor
.Example:
(def ls #[1 2 3 4 5]) (map #(* #1 2) ls) ;; -> #[2 4 6 8 10]
-
function
core::reduce
:(reduce fn list)
Invokesfn
with the first two items inlist
, gets the result, and then continues through the rest of the list callingfn
with the previous result and the next item in the list until the list is exhausted. Returns the final result.Example:
(def ls #[1 2 3 4 5]) (reduce * ls) ;; -> 120
-
function
core::reduce-right
:(reduce-right fn list)
Same ascore::reduce
, but operates on the list in reverse. -
function
core::filter
:(filter fn list)
Invokesfn
on each item in the list and returns a new list of all the items for whichfn
returned a truthy value.Example:
(def (is-odd? n) (> (mod n 2) 0)) (def ls #[0 1 2 3 4 5 6]) (filter is-odd? ls) ;; -> #[1 3 5]
-
function
core::concat
:(concat ls1 ls2 ls-n)
This works on lists and strings, but if you are working on lists then eachls
must be a list and if you are working on strings then eachls
must be a string. It uses the nativeconcat
method for lists and strings respectively. -
function
core::first
:(first ls)
Returns the first item in an ordered collection. -
function
core::second
:(second ls)
Returns the second item in an ordered collection. -
function
core::third
:(third ls)
Returns the third item in an ordered collection. -
function
core::last
:(last ls)
Returns the last item in an ordered collection. -
function
core::slice
:(slice ls start optional-end)
Returns a list of all the items betweenstart
and eitheroptional-end
or the end of the list. -
function
core::head
:(head ls)
Returns a new list of all the items inls
except the last one. -
function
core::tail
:(tail ls)
Returns a new list of all the items inls
except the first one. -
function
core::nth
:(nth ls n)
Returns then
th item ofls
. Operates onls
as if it were 1-indexed.Example:
(def ls #[1 2 3]) (nth ls 1) ;; -> 1
-
function
core::object
:(object key1 value1 key2 value2 key-n value-n)
Creates an object. You can also use the reader macro#{...}
Example:
(object 'a 1 'b 2 'c 3 'd 4 'e 5) ;; -> #{a 1 b 2 c 3 d 4 e 5}
-
function
core::->object
:(->object x)
Convertsx
into an Object. -
function
core::merge
:(merge ...objects)
Creates a new object with the combined properties of each object passed in. If there are conflicts, objects passed in later will have priority.Example:
(def o1 #{'a 1 'b 2 'c 3}) (def o2 #{'a #nil 'd 4}) (merge o1 o2) ;; -> #{a #nil b 2 c 3 d 4}
-
function
core::keys
:(keys obj)
Returns all direct keys of any object. This will not return keys on the prototype of the object. -
function
core::str
:(str ...strings)
Concatenates allstrings
into a single string. Arguments do not have to explicitly be a string. If they are not a string, they will be converted into a string for the final result. -
function
core::->string
:(->string x)
Convertsx
into a string. -
function
core::->number
:(->number x)
Convertsx
into a number. -
function
core::->boolean
:(->boolean x)
Convertsx
into a boolean. -
function
core::=
:(= ...items)
Checks to see if all items are equal to each other. In the case of objects,=
will check to see if the objects are similar enough to be considered equal. -
function
core::not=
:(not= ...items)
The inverse ofcore::=
. -
function
core::list?
:(list? x)
Checks if x is a list (it is either an array or an arguments object). -
function
core::object?
:(object? x)
Checks if x is any kind of object. -
function
core::isNaN?
:(isNaN? x)
Checks if x is theisNaN
primitive. -
object
core::global
This refers toglobal
when it is available andwindow
otherwise.
-
macro
js::eval
:(js::eval to-eval)
If you pass in a string,js::eval
will dump that string as-is into the compiler output. If you pass in anything else, it will be compiled normally and then passed to the javascripteval
function.Example:
(def obj #{'a 1 'b 2}) (if (js::eval "'a' in obj") (do-something obj))
-
macro
js::typeof
:(js::typeof x)
This is the same as the javascript operatortypeof
.Example:
(typeof 5) ;; -> "number"" (typeof #nil) ;; -> "object"