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.