;; # wisp

; Wisp is homoiconic JS dialect with a clojure syntax, s-expressions and
; macros. Wisp code compiles to a human readable javascript, which is one
; of they key differences from clojurescript.

;; ## wisp data structures

;; 1. nil - is just like js undefined with a differenc that it's
;;    not something can be defined. In fact it's just a shortcut for
;;    void(0) in JS.
nil ;; => void(0)

;; 2. Booleans - Wisp booleans true / false are JS booleans

true ;; => true

;; 3. Numbers - Wisp numbers are JS numbers
1  ;; => 1

;; 4. Strings - Wisp strings are JS Strings
"Hello world"
;;    Wisp strings can be multiline
"Hello,
My name is wisp!"

;; 5. Characters - Characters are sugar for JS single char strings
\a  ;; => "a"

;; 6. Keywords - Keywords are symbolic identifiers that evaluate to
;;               themselves.
:keyword  ;; => "keyword"
;;    Since in JS string constats fulfill this purpose of symbolic
;;    identifiers, keywords compile to equivalent JS strings.
(window.addEventListener :load handler false)
;;    Keywords can be invoked as functions, that desugars to plain
;;    associated value access in JS
(:bar foo) ;; => foo["bar"]


;; 7. Vectors - Wisp vectors are JS arrays.
[ 1 2 3 4 ]
;;    Note: Commas are white space & can be used if desired
[ 1, 2, 3, 4]


;; 8. Maps - Maps are hash maps, plain JS objects. Note that unlike
;;    in clojure keys can not be of arbitary types.
{ "foo" bar :beep-bop "bop" 1 2 }
;;    Commas are optional but can come handy for separating key value
;;    pairs.
{ a 1, b 2 }
;; In a future JSONs syntax may be made compatible with map syntax.


;; 9. Lists - You can't have a lisp without lists! Wisp has lists too.
;;    Wisp is homoiconic and it's code is made up of lists representing
;;    expressions. The first item in the expression is a function, being
;;    invoked with rest items as arguments.
(foo bar baz) ; => foo(bar, baz);

;; # Conventions
;; Wisp puts a lot of effort in making naming conventions transparent,
;; by encouraning lisp conventions and then translating them to equivalent
;; JS conventions:

(dash-delimited)   ;; => dashDelimited
(predicate?)       ;; => isPredicate
(**privates**)     ;; => __privates__
(list->vector)     ;; => listToVector

;; As a side effect some names can be expressed in a few ways, although
;; it's considered to be an advantage.

(parse-int x)
(parseInt x)

(array? x)
(isArray x)


;; # Special forms

;; There are some functions in wisp that are special, in a sence that
;; they compile to JS expressions & can not be passed around as regular
;; functions. JS operators are represteted in wisp as special forms

;; Arithmetic forms - Wisp comes with special form for arithmetic
;; operations.

(+ a b)        ; => a + b
(+ a b c)      ; => a + b + c
(- a b)        ; => a - b
(* a b c)      ; => a * b * c
(/ a b)        ; => a / b
(mod a b)      ; => a % 2

;; Comparison forms - Wisp comes with special forms for comparisons

(identical? a b)     ;; => a === b
(identical? a b c)   ;; => a === b && b === c
(= a b)              ;; => a == b
(= a b c)            ;; => a == b && b == c
(> a b)              ;; => a > b
(>= a b)             ;; => a >= b
(< a b c)            ;; => a < b && b < c
(<= a b c)           ;; => a <= b && b <= c

;; Logical forms - Wisp comes with special forms for logical operations

(and a b)            ;; => a && b
(and a b c)          ;; => a && b && c
(or a b)             ;; => a || b
(and (or a b)
     (and c d))      ;; (a || b) && (c && d)


;; Definitions - Variable definitions also happen through special forms.
(def a)     ; => var a = void(0);
(def b 2)   ; => var b = 2;

;; Assignments - In wisp new values can be set to a variables via `set!`
;; special form. Note that in functional programing binding changes are
;; a bad practice, avoiding those would make your programs only better!
;; Stil if you need it you have it.
(set! a 1)

;; Conditionals - Conditional code branching in wisp is expressed via
;; if special form. First expression following `if` is a condition,
;; if it evaluates to `true` result of the `if` expression is second
;; expression otherwise it's third expression.
(if (< number 10)
  "Digit"
  "Number")
;; Else expression is optional, if missing and conditional evaluates to
;; `true` result will be `nil`.
(if (monday? today) "How was your weekend")



;; Compbining expressions - In wisp is everything is an expression, but
;; sometimes one might want to compbine multiple expressions into one,
;; usually for the purpose of evaluating expressions that have
;; side-effects
(do
  (console.log "Computing sum of a & b")
  (+ a b))

;; Also number of expressions is `do` special form 0 to many. If `0`
;; result of evaluation will be nil.
(do)


;; Bindings - Let special form evaluates containing expressions in a
;; lexical context of in which simbols in the bindings-forms (first item)
;; are bound to their respective expression results.

(let [a 1
      b (+ a c)]
  (+ a b))


;; Functions - Wisp functions are JS functions
(fn [x] (+ x 1))

;; Wisp functions can be named similar to JS
(fn increment [x] (+ x 1))

;; Wisp functions can also contain documentation and some metadata.
;; Note: Docstring and metadata is not presented in compiled JS yet,
;; but in a future it will compile to comments associated with function.
(fn incerement
  "Returns a number one greater than given."
  {:added "1.0"}
  [x] (+ x 1))

;; Wisp makes capturing of rest arguments a lot easier than JS. argument
;; that follows special `&` simbol will capture all the rest args in array.

(fn [x & rest]
  (rest.reduce (fn [sum x] (+ sum x)) x))

;; Overloads - In wisp functions can be overloaded depending on number
;; of arguments they take, without introspection of rest arguments.
(fn sum
  "Return the sum of all arguments"
  {:version "1.0"}
  ([] 0)
  ([x] x)
  ([x y] (+ x y))
  ([x & more] (more.reduce (fn [x y] (+ x y)) x)))

;; If function does not has variadic overload and more arguments is
;; passed to it, it throws exception.
(fn
  ([x] x)
  ([x y] (- x y)))



;; ## Other Special Forms

;; Instantiation - In wisp type instantiation has a consice form, type
;; function just needs to be suffixed with `.` character
(Type. options)

;; More verbose but JS like form is also there
(new Class options)


;; Method calls - In wisp method calls are no different from function
;; calls, it's just method functions are perfixed with `.` character
(.log console "hello wisp")

;; Also more JS like forms are supported too!
(window.addEventListener "load" handler false)


;; Attribute access - In wisp attribute access is also just like function
;; call. Attribute name just needs to be prefixed with `.-`
(.-location window)

;; Compound properties can be access via `get` special form
(get templates (.-id element))

;; Catching exceptions - In wisp exceptions can be handled via `try`
;; special form. As everything else try form is also expression. It
;; results to nil if no handling takes place.
(try (raise exception))

;; Although catch form can be used to handle exceptions
(try
  (raise exception)
  (catch error (.log console error)))

;; Also finally clase can be used when necessary
(try
  (raise exception)
  (catch error (recover error))
  (finally (.log console "That was a close one!")))


;; Throwing exceptions - Throw special form allows throwing exceptions,
;; although doing that is not idiomatic.
(fn raise [message] (throw (Error. message)))


;; ## Macros
;; Wisp has a programmatic macro system which allows the compiler to
;; be extended by user code. Many core constructs of Wisp are in fact
;; normal macros.

;; quote

;; Before diving into macros too much, we need to learn about few more
;; things. In lisp any expression can be marked to prevent it from being
;; evaluated. For instance, if you enter the symbol `foo` you will be
;; evaluating the reference to the value of the corresponding variable.
foo

;; If you wish to refer to the literal symbol, rather than reference you
;; could use
(quote foo)
;; or more usually
'foo

;; Any expression can be quoted, to prevent it's evaluation. Although your
;; resulting programs should not have these forms compiled to JS.
'foo
':bar
'(a b)

;; Wisp doesn’t have `unless` special form or a macro, but it's trivial
;; to implement it via macro. Although let's try implemting it as a
;; function to understand a use case for macro!

;; We want to execute body unless condition is `true`.
(defn unless-fn [condition body]
  (if condition nil body))

;; Although following code will log "should not print" anyway, since
;; function arguments are exectued before function is called.
(unless-fn true (console.log "should not print"))

;; Macros solve this problem, because they do not evaluate their arguments
;; immediately. Instead, you get to choose when (and if!) the arguments
;; to a macro are evaluated. Macros take items of the expression as
;; arguments and return new form that is compiled instead.
(defmacro unless
  [condition form]
  (list 'if condition nil form))

;; The body of unless macro executes at macro expansion time, producing an
;; if form for compilation. Which later is compiled as usual. This way
;; compiled JS is a conditional instead of function call.
(unless true (console.log "should not print"))

;; Simple macros like above could be written via templating, expressed
;; as syntax-quoted forms.

;; `syntax-quote` is almost the same as the plain `quote`, but it allows
;; sub expressions to be unquoted so that form acts a template. Symbols
;; inside form are resolved to help prevent inadvertent symbol capture.
;; Which can be done via `unquote` and `unquote-splicing` forms.

(syntax-quote (foo (unquote bar)))
(syntax-quote (foo (unquote bar) (unquote-splicing bazs)))

;; Also there is a special syntax sugar for both unquoting operators:

;; Syntax quote: Quote form, but allow internal unquoting so that form
;; acts as template. Symbols inside form are resolved to help prevent
;; inadvertent symbol capture.
`(foo bar)

;; Unquote: Use inside a syntax-quote to substitute an unquoted value.
`(foo ~bar)

;; Splicing unquote: Use inside a syntax-quote to splice an unquoted
; list into a template.
`(foo ~bar ~@bazs)


;; For expmale build-in `defn` macro can be defined expressed with
;; simple template macro. That's more or less how build-in `defn`
;; macro is implemented.
(defmacro define-fn
  [name & body]
  `(def ~name (fn ~@body)))


;; Now if we use `define-fn` form above defined macro will be expanded
;; and compile time resulting into diff program output.
(define-fn print
  [message]
  (.log console message))


;; Not all of the macros can be expressed via templating, but all of the
;; language is available at hand to assemble macro expanded form.
;; For instance let's define macro to ease functional chanining popular
;; in JS but usually expressed via method chaining. For example following
;; API is pioneered by jQuery is very common in JS:
;;
;; open(target, "keypress).
;;  filter(isEnterKey).
;;  map(getInputText).
;;  reduce(render)
;;
;; Unfortunately though it usually requires all the functions need to be
;; methods of dsl object, which is very limited. Making third party
;; functions second class. Via macros we can achieve similar chaining
;; without such tradeoffs.
(defmacro ->
  [& operations]
  (reduce
   (fn [form operation]
     (cons (first operation)
           (cons form (rest operation))))
   (first operations)
   (rest operations)))

(->
 (open tagret :keypress)
 (filter enter-key?)
 (map get-input-text)
 (reduce render))