1 files changed, 39 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..aff8d50
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# Jester
+
+A simple programming language, typed using algebraic subtyping.
+
+## Usage
+
+Jester syntax is Clojure data structures. Compiling Jester code consists of passing a data structure representing the program to `jester.compiler/compile-form` and calling the resulting function with a single argument.
+
+```clojure
+(require '[jester.compiler :refer [compile-form]])
+(def f (compile-form '(string= "a" "b")))
+(f nil) ;;=> false
+```
+
+Jester expressions can carry implicit dependencies on the argument structure. Any free names within a Jester script are looked up by keyword in the function argument:
+
+```clojure
+(def name-is-john (compile-form '(string= name "John")))
+(name-is-john {:name "John"}) ;;=> true
+(name-is-john {:name "Steve"}) ;;=> false
+```
+
+Keywords can be looked up in values with a dotted syntax reminiscent of many modern languages.
+
+```clojure
+(def person-name-is-john (compile-form '(string= person.name "John")))
+(person-name-is-john {:person {:name "John"}}) ;;=> true
+(person-name-is-john {:person {:name "Steve"}}) ;;=> false
+```
+
+If the input structure doesn't match the required rule structure, an exception will be thrown.
+
+```clojure
+(person-name-is-john {:name "John"}) ;; => throws exception
+```
+
+## Quirks
+
+String comparisons are case insensitive. This is usually what humans want out of language.