Lispy Syntax

docs/src/SUMMARY.md

@@ -12,6 +12,7 @@
 - [Functions](introduction/functions.md)
 - [Loops](introduction/loops.md)
 - [Scopes](introduction/scopes.md)
+- [Lispy Syntax](introduction/lispy-syntax.md)
 
 # Reference
 

docs/src/introduction/functions.md

@@ -3,20 +3,20 @@
 Though lists are a nice way of bundling code, they aren't perfect. For example, when creating your own named function, you will have to call it manually.
 
 ```clojure
-'(1 +) 'add-one def
+'[1 +] 'add-one def
 
 1 add-one
 ;; Pushes the list to the stack, but doesn't call it
-;; [1] -> [1 (1 +)]
+;; [1] -> [1 [1 +]]
 
 call
 ;; Calls the list
-;; [1 (1 +)] -> [2]
+;; [1 [1 +]] -> [2]
 ```
 
 ## The `fn` Expression
 
-For this reason, Stack provides the `fn` expression to mark lists as functions. Internally, what you see as a "function" is actually just a list with the `fn` expression at the beginning.
+For this reason, Stack provides parenthetical syntax to create functions. They function similar to lists, except they start with a `fn` or `fn!` identifier and use parenthesis instead of square brackets.
 
 ```clojure
 '(fn 1 +) 'add-one def
@@ -32,11 +32,10 @@ Notice how we didn't need to call the list manually? That's because the `fn` exp
 
 ## Functions are Lists
 
-Because functions are just marked lists, you can still use them as lists. This means that you can build and modify functions at runtime.
+Though functions are different from lists, you can still use most of the list methods on them (more info [here](../reference/builtins.md)). This means that you can build and modify functions at runtime.
 
 ```clojure
-'()
-'fn push
+'(fn)
 1 push
 '+ push
 ;; [] -> [(fn 1 +)]

docs/src/introduction/lispy-syntax.md

@@ -0,0 +1,202 @@
+# Lispy Syntax
+
+As you have seen, Stack uses postfix notation, meaning the data comes first, then the operations are applied to it. For example:
+
+```clj
+10 2 -
+;; 8
+```
+
+## S-Expressions
+
+Stack supports lisp-like (s-expressions) syntax out-of-the-box. For the example above, you could change it to:
+
+```clj
+(- 10 2)
+;; 8
+```
+
+## Eager Evaluation
+
+You can also add *most* operations within the s-expressions, which will be evaluated eagerly:
+
+```clj
+(- 10 (+ 1 1))
+;; 8
+
+(- 10 (fn (def 'a 2) a))
+;; 8
+```
+
+**Important:** Functions and lists need to be lazy when used as the body of an `if` or `let`:
+
+**`if`:**
+
+```clj
+;; As the argument: Shouldn't be lazy
+(if (fn true) '("hey" print))
+;; Prints "hey"
+
+;; As the body: Should be lazy
+(if true '(fn "hey" print))
+;; Prints "hey"
+
+;; Example with list as the body
+(if true '["hey" print])
+;; Prints "hey"
+
+;; Example with a lazy-lazy list as the body (returns the list if true)
+(if true ''["hey" print])
+;; Pushes `["hey" print]` to the stack
+
+;; Example with s-expression as the body
+(if true '(print "hey"))
+```
+
+**`let`:**
+
+```clj
+;; BOTH arguments should be lazy (the symbol list and the body)
+
+;; Lists
+10 2 (let '[a b] '[a b -])
+;; 8
+
+;; Functions
+10 2 (let '[a b] '(fn a b -))
+;; 8
+
+;; S-Expressions
+10 2 (let '[a b] '(- a b))
+;; 8
+```
+
+This is due to the eager evaluation, where both functions, lists, and s-expressions, if unlazied, will be called during eager evaluation. This can be useful for lambdas within the arguments of an s-expression
+
+## The Underscore
+
+To include items from the stack within an s-expression, you can use `_`. The underscore will pop the last item from the stack and use it as the argument in its place.
+
+```clj
+10 2
+;; b a
+(- _ _)
+;; (- a b) -> (- 2 10) -> -8
+```
+
+In this example, you can see that the underscores don't order the arguments as they are visually. Instead, as the evaluator goes from left to right, they pop an item from the stack. The **first** underscore will pop the **last** item from the stack and the **second** underscore will pop the **second-to-last** item from the stack.
+
+## Parity with Stack-based syntax
+
+Stack's lispy syntax is one-to-one with the visual ordering of all intrinsics, except for a select few, which we will talk about in a bit.
+
+For example, these expressions are all equivalent:
+
+```clj
+10 2 -
+;; 8
+
+(- 10 2)
+;; 8
+
+10 (- _ 2)
+;; 8
+
+2 (- 10 _)
+;; 8
+```
+
+### Exceptions
+
+For ergonomics, Stack modifies the syntax for list and record intrinsics.
+
+**List of Exceptions:**
+- `push`
+- `insert`
+- `let`
+- `def`
+- `set`
+
+In this case, these `push` operations are equal:
+
+```clj
+0 '[] push
+;; [0]
+
+(push '[] 0)
+;; [0]
+```
+
+```clj
+"value" "key" {} insert
+;; {key: "value"}
+
+(insert {} "key" "value")
+;; {key: "value"}
+```
+
+In these cases, the arguments for the s-expressions are reversed in comparison with the stack-based syntax. This is to aid in readability and intuition. The non-lisp syntax doesn't do this for aid in more efficient insertions or pushes:
+
+```clj
+3 2 1 '[] push push push
+;; [1 2 3]
+
+"bar" "foo" "value" "key" {} insert insert
+;; {key: "value", foo: "bar"}
+```
+
+That said, pulling items from the stack works the same as with the other intrinsics:
+
+```clj
+{}
+(insert _ "key" "value")
+;; {key: "value"}
+
+"key" {}
+(insert _ _ "value")
+;; {key: "value"}
+
+"value" {}
+(insert _ "key" _)
+;; {key: "value"}
+
+"value"
+(insert {} "key" _)
+;; {key: "value"}
+```
+
+Here are examples for the last few exceptions:
+
+**Let:**
+
+```clj
+10 2 '[(- a b)] '[a b] let
+;; 8
+
+10 2 (let '[a b] '(- a b))
+;; 8
+```
+
+**Def:**
+
+```clj
+0 'a def
+
+(def 'a 0)
+
+0 'a (def _ _)
+```
+
+**Set:**
+
+```clj
+;; define so we can set
+0 'a def
+;; end of boilerplate
+
+1 'a set
+
+(set 'a 1)
+
+1 'a (set _ _)
+```

docs/src/introduction/lists.md

@@ -4,33 +4,33 @@ Lists are similar to arrays or vectors in other programming languages. A list ca
 
 ## Defining a List
 
-Lists are defined using the `'()` syntax. The items inside of a list are separated by spaces.
+Lists are defined using the `'[]` syntax. The items inside of a list are separated by spaces.
 
 ```clojure
-'(1 2 3 4 5)
+'[1 2 3 4 5]
 ```
 
 ## Eager Evaluation
 
 When lists are pushed to the stack, the items inside of the list are evaluated in-order (due to the [purification](../introduction/stack#purification) step).
 
 ```clojure
-(1 2 3)
+[1 2 3]
 
 ;; Results in `1 2 3`
-;; [] -> [(1 2 3)] -> [1 2 3]
+;; [] -> [[1 2 3]] -> [1 2 3]
 
-(2 2 +)
+[2 2 +]
 
 ;; Results in `4`
-;; [] -> [(2 2 +)] -> [4]
+;; [] -> [[2 2 +]] -> [4]
 
 2 'var def
 
-(var)
+[var]
 
 ;; Results in `2`
-;; [] -> [(var)] -> [2]
+;; [] -> [[var]] -> [2]
 ```
 
 ### Laziness
@@ -40,32 +40,32 @@ Symbols (variables) inside of lazy lists will not be evaluated.
 ```clojure
 2 'var def
 
-'(var)
+'[var]
 
-;; Results in `(var)`
-;; [] -> [(var)]
+;; Results in `[var]`
+;; [] -> [[var]]
 ```
 
 Instead, to add variables into a list, it will need to be created manually.
 
 ```clojure
 2 'var def
 
-var '() push
+var '[] push
 
-;; Results in `(2)`
-;; [] -> [(2)]
+;; Results in `[2]`
+;; [] -> [[2]]
 ```
 
 You can make specific items inside of a list lazy by prefixing `'` to the beginning of the item.
 
 ```clojure
-(2 2 '+)
+[2 2 '+]
 
 ;; Results in the items being pushed to the stack, but the `+` will not be not called
 ;; [] -> [2 2 +]
 
-(2 2 + 5 '*)
+[2 2 + 5 '*]
 
 ;; Results in the items being pushed to the stack, and only the `*` will not be called
 ;; [] -> [4 5 *]
@@ -78,7 +78,7 @@ Lazy lists can be called which will run each expression in the list in-order (le
 Calling a list exhibits the same behavior as the [purification](../introduction/stack.md#purification) step.
 
 ```clojure
-'(2 2 +) call
+'[2 2 +] call
 
 ;; Results in `4` being pushed to the stack
 ;; [] -> [2 2 +] -> [4]
@@ -87,7 +87,7 @@ Calling a list exhibits the same behavior as the [purification](../introduction/
 If a list contains callable items such as other lists, those will also be run.
 
 ```clojure
-'((2 2 +)) call
+'[[2 2 +]] call
 
 ;; Results in `4` being pushed to the stack
 ;; [] -> [2 2 +] -> [4]
@@ -96,16 +96,16 @@ If a list contains callable items such as other lists, those will also be run.
 To change this behavior, any callable items should be made lazy when adding them to the list to ensure that they won't be called.
 
 ```clojure
-'(2 2 +)
+'[2 2 +]
 ;; (2 2 +)
 lazy
 ;; '(2 2 +)
-'() push
+'[] push
 ;; ('(2 2 +))
 call
 
-;; Results in `(2 2 +)` being pushed to the stack
-;; [] -> [(2 2 +)] -> [(2 2 +)]
+;; Results in `[2 2 +]` being pushed to the stack
+;; [] -> [[2 2 +]] -> [[2 2 +]]
 ```
 
 <!-- **Note: Running `call` on a list doesn't provide the same behavior as the [purification](../introduction/stack#purification) step. It evaluates the items in the list, and doesn't keep the items inside the bounds of the list. To keep the items inside the bounds of the list, you can use the `call-list` operator.** -->

docs/src/introduction/loops.md

@@ -9,7 +9,7 @@ Similar to functional programming languages such as Clojure, Stack utilizes recu
 ;; Function isn't lazy so it runs right away
 (fn
   ;; Our if block
-  '(
+  '[
     ;; Push i to the stack
     i
 
@@ -18,7 +18,7 @@ Similar to functional programming languages such as Clojure, Stack utilizes recu
 
     ;; Recur
     recur
-  )
+  ]
 
   ;; Check if i is less than 5
   i 5 <