Add a README

README.md

@@ -0,0 +1,153 @@
+# JSON as Functional Progamming Syntax
+
+A parser, interpretter, and compiler for a functional programming language with the same grammar as JSON.
+
+This project started as something of a joke:  Could I use JavaScript Object
+Notation as a way of describing not just standard arrays and objects, but also
+functions and other data types?  Bascially, could I turn JSON into a
+programming language which compiles to JavaScript?
+
+The answer, it turns out, is yes!
+
+## Setup
+
+This project has no dependencies, just Python3!  That means all you have to do to run is install Python3 and clone the repository.  Once you have the code, you can either run:
+
+```bash
+python3 main.py # Open a REPL with only the built-ins
+```
+
+OR
+
+```bash
+python3 main.py example.json # Evaluate some code and either print the results or open a REPL
+```
+
+
+## Syntax Rundown
+
+### Functions / Lambdas
+
+A function is defined using a standard JavaScript object with string keys.  The simplest function you can write is the identity function:
+
+```json
+{"x": "x"}
+```
+
+(equivalent JavaScript code:)
+
+```js
+x => x
+```
+
+This function takes in one argument (called "x") and returns it unmodified.  The "x" on the left defines the argument, and the "x" on the right is the return value.  You'll notice we're also introducing the syntax for variables:  Strings!  While there are some times that strings don't function as variables (such as that first "x" on the left, which is an argument), most of the strings you'll see are variables.  They refer to some previous value, and resolve to that.  Here, the "x" on the right refers to the "x" on the left.
+
+If you type this code into the repl, however, you'll see this output:
+
+```json
+{"x": "x"}
+```
+
+Unchanged!  In order to do something with this function, we'll need...
+
+### Function Application
+
+Function application!  (Meaning calling functions or passing them arguments).  For this, we borrow JSON's array syntax.  The first element of the array is the function being applied, and all things to the left are the arguments, which are passed in order from left to right.
+
+Let's try applying our identity function to a number (new syntax!  numbers are just JSON numbers!):
+
+```json
+[{"x": "x"}, 4]
+```
+
+(equivalent JavaScript code:)
+
+```js
+(x => x)(4)
+```
+
+Let's try putting this new expression into the REPL!
+
+```json
+4
+```
+
+Now we get just 4!  Our code worked!  The four was returned unmodified.
+
+This is a little bit boring though.  We can start to make things more interesting by applying some of the built-in functions.  One simple example is the "S" (or successor) function.  Let's write a function which applies the S function twice:
+
+```json
+{"x": ["S", ["S", "x"]]}
+```
+
+and now apply it:
+
+```json
+[{"x": ["S", ["S", "x"]]}, 4]
+```
+
+(output:)
+
+```json
+6
+```
+
+Nice!
+
+### Pattern Matching
+
+Much like in other functional languages, all functions can perform case matching.  By adding additional key/value pairs to the function (object), we can pattern match on different terms.  All keys still need to be strings, but the contents of the string represent the pattern sub-language.  For example, this function subtracts one from a number, unless that number is zero:
+
+```json
+{"0": 0, "S x": "x"}
+```
+
+Note:  The documentation for this section and the following sections are currently incomplete.  While I aim to finish eventually, for now this is all there is.  I encourage you to play around with the examples in `example.json` as well as on your own.  If you're comfortable with Python, you can also poke around in the source code to find out how things work!
+
+### Let Bindings
+
+```json
+["x", 3, "y", ["+", "x", 5], ["+", "x", "y"]]
+```
+
+Equivalent JavaScript:
+
+```js
+{
+	const x = 3;
+	const y = x + 5;
+	return x + y
+}
+```
+
+### Bind values in REPL
+
+aka a let binding without an "in" clause
+
+```json
+["addTwo", {"x": ["S", ["S", "x"]]}]
+```
+
+### Execute REPL within context
+
+(this is still a bit buggy, and may create an invalid REPL)
+
+```json
+[{"x": []}, 12]
+```
+
+### Multi-argument functions
+
+```json
+{"x": {"y": ["+", "x", "y"]}}
+```
+
+Equivalent JavaScript:
+
+```js
+x => y => x + y
+```
+
+(note:  produces curried JS)
+
+### More language features remain undocumented :(