README

osteele · Jul 2, 2017 · d29e4b2 · d29e4b2
1 parent f6c4299
commit d29e4b2
Showing 1 changed file with 52 additions and 22 deletions.
diff --git a/README.md b/README.md
@@ -1,11 +1,33 @@
 # Go Liquid Template Parser
+[![Build Status](https://travis-ci.org/osteele/liquid.svg?branch=master)](https://travis-ci.org/osteele/liquid)
+[![Go Report Card](https://goreportcard.com/badge/github.com/osteele/liquid)](https://goreportcard.com/report/github.com/osteele/liquid)
 [![GoDoc](https://godoc.org/github.com/osteele/liquid?status.svg)](http://godoc.org/github.com/osteele/liquid)
 
-`goliquid` is a pure Go implementation of [Shopify Liquid templates](https://shopify.github.io/liquid), for use in [gojekyll](https://github.com/osteele/gojekyll).
+`liquid` is a pure Go implementation of [Shopify Liquid templates](https://shopify.github.io/liquid), for use in [gojekyll](https://github.com/osteele/gojekyll).
+
+It supports a functional API for defining tags and filters. On the one hand, this isn't idiomatic Go. On the other hand, this made it possibly to quickly implement a boatload of Liquid and Jekyll filters that would otherwise have been onerous. The jury is still out…
+
+<!-- TOC -->
+
+- [Go Liquid Template Parser](#go-liquid-template-parser)
+    - [Status](#status)
+    - [Install](#install)
+    - [Contribute](#contribute)
+        - [Setup](#setup)
+        - [Workflow](#workflow)
+        - [Working on the Parser and Lexer](#working-on-the-parser-and-lexer)
+    - [References](#references)
+    - [Attribution](#attribution)
+    - [Other Implementations](#other-implementations)
+        - [Go](#go)
+        - [Other Languages](#other-languages)
+    - [License](#license)
+
+<!-- /TOC -->
 
 ## Status
-[![Build Status](https://travis-ci.org/osteele/liquid.svg?branch=master)](https://travis-ci.org/osteele/liquid)
-[![Go Report Card](https://goreportcard.com/badge/github.com/osteele/liquid)](https://goreportcard.com/report/github.com/osteele/liquid)
+
+This library is in its early days. IMO it's not sufficiently mature to be worth snapping off a [versioned URL](http://labix.org/gopkg.in). In particular, the tag and filter extension API is likely to change.
 
 - [ ] Basics
   - [x] Literals
@@ -19,7 +41,7 @@
   - [ ] Control Flow
     - [x] `if`/`else`/`elsif`
     - [x] `unless`
-    - [ ] `case`
+    - [x] `case`
       - [x] `when`
       - [ ] `else`
   - [ ] Iteration
@@ -49,12 +71,9 @@
 make setup
 ```
 
-Install Ragel. On macOS: `brew install ragel`.
-
 ### Workflow
 
 ```bash
-go generate ./...
 go test ./...
 ```
 
@@ -72,37 +91,48 @@ godoc -http=:6060&
 open http://localhost:6060/pkg/github.com/osteele/liquid/
 ```
 
-## References
+### Working on the Parser and Lexer
+
+To work on the lexer, install Ragel. On macOS: `brew install ragel`.
+
+Do this after editing `scanner.rl` or `expressions.y`:
 
-<https://shopify.github.io/liquid>
+```bash
+go generate ./...
+```
 
-<https://help.shopify.com/themes/liquid>
+## References
 
-<https://github.com/Shopify/liquid/wiki/Liquid-for-Designers>
+* [Shopify.github.io/liquid](https://shopify.github.io/liquid) is the definitive reference.
+* [Help.shopify.com](https://help.shopify.com/themes/liquid) goes into more detail, but includes features that aren't present in core Liquid as used by Jekyll.
+* Shopify's [Liquid for Designers](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) is another take.
 
 
 ## Attribution
 
-| Package | Author | Description |
-| --- | --- | --- |
-| [gopkg.in/yaml.v2](https://github.com/go-yaml) | Canonical | YAML support |
-| [Ragel](http://www.colm.net/open-source/ragel/) | Adrian Thurston | scanning expressions |
+| Package                                               | Author          | Description                                  | License            |
+|-------------------------------------------------------|-----------------|----------------------------------------------|--------------------|
+| [gopkg.in/yaml.v2](https://github.com/go-yaml/yaml)   | Canonical       | YAML support (for printing parse trees)      | Apache License 2.0 |
+| [jeffjen/datefmt](https://github.com/jeffjen/datefmt) | Jeffrey Jen     | Go bindings to GNU `strftime` and `strptime` | MIT                |
+| [Ragel](http://www.colm.net/open-source/ragel/)       | Adrian Thurston | scanning expressions                         | MIT                |
 
 Michael Hamrah's [Lexing with Ragel and Parsing with Yacc using Go](https://medium.com/@mhamrah/lexing-with-ragel-and-parsing-with-yacc-using-go-81e50475f88f) was essential to understanding `go yacc`.
 
 The [original Liquid engine](https://shopify.github.io/liquid), of course, for the design and documentation of the Liquid template language. Many of the tag and filter test cases are taken directly from the Liquid documentation.
 
-(That said, this is a clean-room implementation to make sure it just implements the documented design.)
-
 ## Other Implementations
 
-Go:
+### Go
+
+* [karlseguin/liquid](https://github.com/karlseguin/liquid) is a dormant implementation that inspired a lot of forks.
+* [acstech/liquid](https://github.com/acstech/liquid) is a more active fork of Karl Seguin's implementation. I submitted a couple of pull requests there.
+* [hownowstephen/go-liquid](https://github.com/hownowstephen/go-liquid) is a more recent entry.
+
+After trying each of these, and looking at how to extend them, I concluded that I wasn't going to get very far without a parser generator. I also wanted an easy API for writing filters.
 
-* <https://godoc.org/github.com/karlseguin/liquid> is a partial implementation.
-* <https://godoc.org/github.com/acstech/liquid> is a more active fork of Karl Seguin's implementation.
-* <https://godoc.org/github.com/hownowstephen/go-liquid> is a more recent entry.
+### Other Languages
 
-<https://github.com/Shopify/liquid/wiki/Ports-of-Liquid-to-other-environments> lists ports to other languages.
+ See Shopify's [ports of Liquid to other environments](https://github.com/Shopify/liquid/wiki/Ports-of-Liquid-to-other-environments).
 
 ## License