github.com/sridharv/stencil@v0.0.0-20170626103218-a81b4a7626a1/README.md (about) 1 # Stencil - Simple code templating for Go 2 3 Stencil generates specialized versions of Go packages by replacing types. 4 This is a prototype of [this proposal](https://www.laddoo.net/p/stencil). It will have bugs and only supports 5 a subset of the features in the proposal. 6 7 Given a package with an interface `A`, stencil can generate a new package with all uses of `A` replaced by `int` (or any other type). 8 The generated package is stored in the closest vendor directory of the repo. If no such directory exists, one is created. 9 10 ## Installation 11 12 Download stencil using 13 14 ``` 15 go get -u github.com/sridharv/stencil 16 ``` 17 18 Install with 19 20 ``` 21 go install github.com/sridharv/stencil/cmd/stencil 22 ``` 23 24 ## Usage 25 26 Detailed documentation is at [![GoDoc](https://godoc.org/github.com/sridharv/stencil/cmd/stencil?status.svg)](https://godoc.org/github.com/sridharv/stencil/cmd/stencil) 27 28 ### Example Walkthrough 29 30 Install stencil as shown above. Then create a package to act as a stencil. Let's create a generic Sum method. 31 32 Create `$GOPATH/src/example/stencil/math/math.go` (or a package of your choice) containing 33 34 ``` 35 package math 36 37 func Sum(n...float64) float64 { 38 var r float64 39 for _, v := range n { 40 r += v 41 } 42 return r 43 } 44 ``` 45 46 Now use it to compute the sum of `int`s by using `stencil` to replace `float64` with `int`. 47 48 Create `$GOPATH/src/example/usestencil/main.go` (or another package of your choice) containing 49 50 ``` 51 package main 52 53 //go:generate stencil 54 import ( 55 "fmt" 56 int_math "example/stencil/math/float64/int" 57 ) 58 59 // PrintIntSum prints the sum of all elements of v to stdout. 60 func main() { 61 ints := []int{1, 2, 3, 4, 5} 62 fmt.Println("Sum of", v, "=", int_math.Sum(ints...)) 63 } 64 ``` 65 66 Now run 67 68 ``` 69 # Or the path to the main package you created 70 cd $GOPATH/src/example/usestencil/ 71 ``` 72 and then 73 ``` 74 go generate 75 ``` 76 77 Take a look at `$GOPATH/src/example/usestencil/`. It will have a vendor directory with a specialised version of 78 `example/stencil/math`. You can now build and run the example with 79 80 ``` 81 go run main.go 82 ``` 83 84 ## Libraries 85 86 A few useful packages that lend themselves to being used with `stencil`. 87 88 * `github.com/sridharv/stencil/std/num` - Max, Min and Sum for numbers. [![GoDoc](https://godoc.org/github.com/sridharv/stencil/std/num?status.svg)](https://godoc.org/github.com/sridharv/stencil/std/num) 89 * `github.com/sridharv/stencil/std/slice` - Slice utilities. [![GoDoc](https://godoc.org/github.com/sridharv/stencil/std/slice?status.svg)](https://godoc.org/github.com/sridharv/stencil/std/slice) 90 91 ## License 92 93 Stencil is available under the Apache License. See the LICENSE file for details. 94 95 ### Contributing 96 97 Pull requests are always welcome! Please ensure any changes you send have an accompanying test case.