gopkg.in/easygen.v4@v4.1.0/README.md (about) 1 # easygen 2 3 [](LICENSE) 4 [](http://godoc.org/github.com/go-easygen/easygen) 5 [](https://goreportcard.com/report/github.com/go-easygen/easygen) 6 [](https://travis-ci.org/go-easygen/easygen) 7 [ ](https://codeship.com/projects/135255) 8 9 ## TOC 10 - [easygen - Easy to use universal code/text generator](#easygen---easy-to-use-universal-codetext-generator) 11 - [Usage](#usage) 12 - [$ easygen](#-easygen) 13 - [Install](#install) 14 - [Install as Debian/Unbuntu package](#install-as-debianunbuntu-package) 15 - [Install from source](#install-from-source) 16 - [Test](#test) 17 - [Details](#details) 18 - [Command line flag handling code auto-generation](#command-line-flag-handling-code-auto-generation) 19 - [`easygen` itself](#`easygen`-itself) 20 - [`cli` based](#`cli`-based) 21 - [The `easygen` usage](#the-`easygen`-usage) 22 - [Command line](#command-line) 23 - [The library ](#the-library-) 24 - [> cmd/easygen/main.go](#-cmdeasygenmaingo) 25 - [Different Versions](#different-versions) 26 - [Author(s) & Contributor(s)](#author(s)-&-contributor(s)) 27 28 # easygen - Easy to use universal code/text generator 29 30 Command `easygen` is an easy to use universal code/text generator. 31 32 It can be used as a text or html generator for _arbitrary_ purposes with _arbitrary_ data and templates. It is a good [GSL](https://github.com/imatix/gsl) replacement, as it 33 34 - is more easy to define driving data, in form of YML instead of XML 35 - has more powerful template engine that based on Go template. 36 You can also write your own function in Go to customize your template. 37 38 You can even use easygen as a generic Go template testing tool using the `-ts` commandline option, and much more. 39 40 Note this document is for `easygen` versions 4.0+. For historic versions check out the [Different Versions](#different-versions) section. 41 42 43 ## Usage 44 45 ### $ easygen 46 ```sh 47 easygen version 4.0.0 48 49 Usage: 50 easygen [flags] template_name [data_filename [data_filename...]] 51 52 Flags: 53 54 -debug level 55 debugging level 56 -ej extension 57 extension of json file (default ".json") 58 -et extension 59 extension of template file (default ".tmpl") 60 -ey extension 61 extension of yaml file (default ".yaml") 62 -ts string 63 template string (in text) 64 65 data_filename(s): The name for the .yaml or .json data. 66 - If omitted derive from the template_name. 67 - Can have the extension or without it. If withot extension, 68 will try .yaml first then .json 69 - Can include the path as well. 70 71 template_name: The name for the template file. 72 - Can have the extension or without it. 73 - Can include the path as well. 74 - Can be a comma-separated list giving many template files, in which case 75 at least one data_filename must be given. 76 77 Flag defaults can be overridden by corresponding environment variable, e.g.: 78 EASYGEN_EY=.yml EASYGEN_ET=.tpl easygen ... 79 ``` 80 81 ## Install 82 83 ### Install as Debian/Unbuntu package 84 85 86 apt install easygen 87 88 89 ### Install from source 90 91 go get github.com/go-easygen/easygen/... 92 ls -l $GOPATH/bin 93 94 You should find an `easygen` executable newly created in there. 95 96 ## Test 97 98 export PATH=$PATH:$GOPATH/bin 99 100 $ easygen $GOPATH/src/github.com/go-easygen/easygen/test/list0 101 The colors are: red, blue, white, . 102 103 cd $GOPATH/src/github.com/go-easygen/easygen 104 105 $ easygen test/list1 106 The quoted colors are: "red", "blue", "white", . 107 108 $ easygen test/listfunc1 test/list0 109 red, blue, white. 110 111 112 And also check out the provided [more examples](https://godoc.org/github.com/go-easygen/easygen#pkg-examples) in the [](https://godoc.org/github.com/go-easygen/easygen) document. 113 114 115 ## Details 116 117 It can be used as a code generator, for example, command line parameter handling code generator, or anything that is structurally repetitive, like the following: 118 119 120 - [Introduction to easygen and its philosophy ](https://suntong.github.io/blogs/2016/01/01/easygen---easy-to-use-universal-code/text-generator) 121 - [Easygen is now coding itself ](https://sfxpt.wordpress.com/2015/07/04/easygen-is-now-coding-itself/) 122 - [Showcasing the power of easygen with ffcvt ](https://sfxpt.wordpress.com/2015/08/02/showcasing-the-power-of-easygen-with-ffcvt/) 123 - [Easygen for HTML mock-up ](https://sfxpt.wordpress.com/2015/07/10/easygen-for-mock-up/) 124 - [Moving beyond code-gen and mock-up, using easygen in real life creating GPT partitions](https://suntong.github.io/blogs/2015/12/26/creating-gpt-partitions-easily-on-the-command-line) 125 126 Ready to get started? Then check out [Getting Started](https://github.com/go-easygen/easygen/wiki/Getting-Started) to start building your way to turn your data into any form, any way you want. 127 128 <a name="clfhcag" /> 129 130 ## Command line flag handling code auto-generation 131 132 [ ](https://suntong.github.io/blogs/) 133 134 As explained above, one practical use of `easygen` is to auto-generating Go code for command line parameter handling, for both [`viper` and `cobra`](https://github.com/suntong/blog/blob/master/GoOptP7-easygen.md), and Go's [built-in `flag` package](https://sfxpt.wordpress.com/2015/07/04/easygen-is-now-coding-itself/). 135 136 137 ### `easygen` itself 138 139 Currently, `easygen`'s command line parameter handling is built on top of Go's built-in `flag` package, and the handling code is entirely generated by `easygen` itself. Thus, showing how `easygen` is handling the command line parameters itself also means showing what functionality the auto-generated command line parameter handling code can do for you. 140 141 Currently, there are three tiers program parameters can be given: 142 143 1. Default values defined within the program, so that program parameters can have meaningful defaults to start with 144 1. Values defined in environment variables 145 1. Values passed from command line 146 147 The latter will have higher priority and will override values defined formerly. I.e., the values from command line will override that in environment variables, which in turn override program defaults. 148 149 We will use the `-ts`, template string, as an example to illustrate. The program defaults is empty, which means using the `.tmpl` template file the same as the `.yaml` data file. We will override that first by environment variable, then from command line, illustrated in next section. 150 151 ### `cli` based 152 153 See, 154 155 [A cookbook on how to jump-start a `cli` based command line handling program](cli-project.md#cookbook) 156 157 ## The `easygen` usage 158 159 ### Command line 160 161 [Check here for more on using `easygen` the command line tool](using_easygen.md). 162 163 ### The library 164 165 The `easygen` is a library as well as a command line tools. Not only it is super easy to use, it is super easy to extend as well. 166 167 The [restructured `easygen`](https://github.com/go-easygen/easygen/issues/10) can now be a building block that people can easily extend, any extra functionalities, or extra feature that it depends on, or any external dependencies are now moved out to sub modules. Thus the library users can now pick and choose exactly what they want from the library. 168 169 - The [egVar package example](http://godoc.org/github.com/go-easygen/easygen/egVar#example-package) shows how to add the variable name manipulation on top of the default library. 170 - The [egCal package example](http://godoc.org/github.com/go-easygen/easygen/egCal#example-package) shows how to add the variable name manipulation and generic calculation functionalities, together with the default functions, all at the same time. 171 172 To put them all together, check out the `easygen`'s `main.go`: 173 174 #### > cmd/easygen/main.go 175 176 ```go 177 package main 178 179 import ( 180 "flag" 181 "os" 182 183 "github.com/go-easygen/easygen" 184 "github.com/go-easygen/easygen/egCal" 185 "github.com/go-easygen/easygen/egVar" 186 ) 187 188 //go:generate sh -v easygen.gen.sh 189 190 //////////////////////////////////////////////////////////////////////////// 191 // Main 192 193 func main() { 194 flag.Usage = Usage 195 flag.Parse() 196 197 // One mandatory non-flag arguments 198 if flag.NArg() < 1 { 199 Usage() 200 } 201 202 tmpl0 := easygen.NewTemplate().Customize() 203 tmpl := tmpl0.Funcs(easygen.FuncDefs()). 204 Funcs(egVar.FuncDefs()).Funcs(egCal.FuncDefs()) 205 206 args := flag.Args() 207 if len(easygen.Opts.TemplateStr) > 0 { 208 easygen.Process0(tmpl, os.Stdout, easygen.Opts.TemplateStr, args...) 209 } else { 210 easygen.Process(tmpl, os.Stdout, args...) 211 } 212 } 213 ``` 214 215 It has been as simple as this up until version 3. I.e., it's quite simple to make use of `easygen` as a package. 216 217 218 ### Different Versions 219 220 The `easygen` has gone through four different versions whose API are a bit different between them. 221 222 To always stay at the latest version, `import` 223 224 "github.com/go-easygen/easygen" 225 226 in your Go code. However, to stay within a certain version, `import` the following package respectively to what you need: 227 228 - V4: "[gopkg.in/easygen.v4](https://gopkg.in/easygen.v4)" 229 - V3: "[gopkg.in/easygen.v3](https://gopkg.in/easygen.v3)" 230 - V2: "[gopkg.in/easygen.v2](https://gopkg.in/easygen.v2)" 231 - V1: "[gopkg.in/easygen.v1](https://gopkg.in/easygen.v1)" 232 233 To see the differences between them, check out 234 235 - [V4 vs V3](https://github.com/go-easygen/easygen/wiki/V4-vs-V3) 236 - [V3 vs V2](https://github.com/go-easygen/easygen/wiki/V3-vs-V2) 237 - [V2 vs V1](https://github.com/go-easygen/easygen/wiki/V2-vs-V1) 238 239 ## Author(s) & Contributor(s) 240 241 Tong SUN 242  243 244 Gerrit Renker 245 https://github.com/grrtrr 246 247 All patches welcome.