More drop examples

README.md

@@ -37,12 +37,18 @@ These features of Shopify Liquid aren't implemented:
 - Non-strict filters. An undefined filter is currently an error.
 - Strict variables. An undefined variable is not an error.
 
+Drops have a different design from the Shopify (Ruby) implementation.
+A Ruby drop sets `liquid_attributes` to a list of attributes that are exposed to Liquid.
+A Go drop implements `ToLiquid() interface{}`, that returns a proxy object.
+Conventionally, the proxy is a `map` or `struct` that defines the exposed properties.
+See <http://godoc.org/github.com/osteele/liquid#Drop> for additional information.
+
 ## Stability
 
 This library is at an early stage of development.
 It has been mostly used by its author.
 
-Only the liquid package itself, and the sub-package types that are used in that top-level package, are guaranteed stable. For example, `render.Context` is documented as the parameter type for tag definitions; it therefore won't change incompatibly with minor versions.
+Only the liquid package itself, and the sub-package types that are used in that top-level package, are guaranteed stable. For example, `render.Context` is documented as the parameter type for tag definitions; it therefore won't change incompatibly, if ever, until at least version 2 (at which point `gopkg.in/osteele/liquid.v1` will continue to pin to the v1 implementation).
 
 ## Install
 

drops_test.go

@@ -1,6 +1,8 @@
 package liquid
 
 import (
+	"fmt"
+	"log"
 	"testing"
 
 	"github.com/stretchr/testify/require"
@@ -15,3 +17,76 @@ func TestDrops(t *testing.T) {
 
 	require.Equal(t, "not a drop", FromDrop("not a drop"))
 }
+
+type redConvertible struct{}
+
+func (c redConvertible) ToLiquid() interface{} {
+	return map[string]interface{}{
+		"color": "red",
+	}
+}
+
+func ExampleDrop_map() {
+	// type redConvertible struct{}
+	//
+	// func (c redConvertible) ToLiquid() interface{} {
+	// 	return map[string]interface{}{
+	// 		"color": "red",
+	// 	}
+	// }
+	engine := NewEngine()
+	bindings := map[string]interface{}{
+		"car": redConvertible{},
+	}
+	template := `{{ car.color }}`
+	out, err := engine.ParseAndRenderString(template, bindings)
+	if err != nil {
+		log.Fatalln(err)
+	}
+	fmt.Println(out)
+	// Output: red
+}
+
+type car struct{ color, model string }
+
+func (c car) ToLiquid() interface{} {
+	return carDrop{c.model, c.color}
+}
+
+type carDrop struct {
+	Model string
+	Color string `liquid:"color"`
+}
+
+func (c carDrop) Drive() string {
+	return "AWD"
+}
+
+func ExampleDrop_struct() {
+	// type car struct{ color, model string }
+	//
+	// func (c car) ToLiquid() interface{} {
+	// 	return carDrop{c.model, c.color}
+	// }
+	//
+	// type carDrop struct {
+	// 	Model string
+	// 	Color string `liquid:"color"`
+	// }
+	//
+	// func (c carDrop) Drive() string {
+	// 	return "AWD"
+	// }
+
+	engine := NewEngine()
+	bindings := map[string]interface{}{
+		"car": car{"blue", "S85"},
+	}
+	template := `{{ car.color }} {{ car.Drive }} Model {{ car.Model }}`
+	out, err := engine.ParseAndRenderString(template, bindings)
+	if err != nil {
+		log.Fatalln(err)
+	}
+	fmt.Println(out)
+	// Output: blue AWD Model S85
+}

engine_examples_test.go

@@ -119,28 +119,3 @@ func ExampleEngine_RegisterBlock() {
 	fmt.Println(out)
 	// Output: 3
 }
-
-type redConvertible struct{}
-
-func (c redConvertible) ToLiquid() interface{} {
-	return "red"
-}
-
-func ExampleDrop() {
-	// type redConvertible struct{}
-	//
-	// func (c redConvertible) ToLiquid() interface{} {
-	// 	return "red"
-	// }
-	engine := NewEngine()
-	bindings := map[string]interface{}{
-		"drop": redConvertible{},
-	}
-	template := `{{ drop }}`
-	out, err := engine.ParseAndRenderString(template, bindings)
-	if err != nil {
-		log.Fatalln(err)
-	}
-	fmt.Println(out)
-	// Output: red
-}