README

2024-11-27 01:34:41 +01:00 · 2017-07-01 20:24:27 -04:00 · 2017-07-01 20:24:27 -04:00 · d29e4b207b
commit d29e4b207b
parent f6c4299739
1 changed files with 55 additions and 25 deletions
--- a/README.md
+++ b/README.md
@ -1,11 +1,33 @@
 # Go Liquid Template Parser
-[![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).
-
-## 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)
+[![GoDoc](https://godoc.org/github.com/osteele/liquid?status.svg)](http://godoc.org/github.com/osteele/liquid)
+
+`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
+
+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/
 ```

+### 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`:
+
+```bash
+go generate ./...
+```
+
 ## References

-<https://shopify.github.io/liquid>
-
-<https://help.shopify.com/themes/liquid>
-
-<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

-* <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.
+* [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.

-<https://github.com/Shopify/liquid/wiki/Ports-of-Liquid-to-other-environments> lists ports to other languages.
+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.
+
+### Other Languages
+
+ See Shopify's [ports of Liquid to other environments](https://github.com/Shopify/liquid/wiki/Ports-of-Liquid-to-other-environments).

 ## License