{"id":17723765,"url":"https://github.com/ncw/gotemplate","last_synced_at":"2025-04-07T11:08:47.869Z","repository":{"id":21476732,"uuid":"24795364","full_name":"ncw/gotemplate","owner":"ncw","description":"Package based templating system for Go","archived":false,"fork":false,"pushed_at":"2022-05-04T09:22:59.000Z","size":110,"stargazers_count":258,"open_issues_count":9,"forks_count":28,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-07-05T14:30:48.979Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ncw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-04T16:59:18.000Z","updated_at":"2024-06-14T06:33:05.000Z","dependencies_parsed_at":"2022-08-21T14:40:36.999Z","dependency_job_id":null,"html_url":"https://github.com/ncw/gotemplate","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncw%2Fgotemplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncw%2Fgotemplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncw%2Fgotemplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncw%2Fgotemplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ncw","download_url":"https://codeload.github.com/ncw/gotemplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640465,"owners_count":20971557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-25T15:43:59.648Z","updated_at":"2025-04-07T11:08:47.846Z","avatar_url":"https://github.com/ncw.png","language":"Go","readme":"Go templates\n============\n\n**Note:** with the advent of [generics](https://go.dev/doc/tutorial/generics)\nin go 1.18 this package is now obsolete. Please use go 1.18 and its\ngeneric facilities instead. I will keep this package here for existing\nusers, but I won't be updating it any more - @ncw\n\n----\n\nThis tool manages package based templates for the Go language using\n\"go generate\" which requires go 1.4.\n\n[![Build Status](https://travis-ci.org/ncw/gotemplate.png)](https://travis-ci.org/ncw/gotemplate)\n\nInstall\n-------\n\nInstall using go get\n\n    go get github.com/ncw/gotemplate/...\n\nand this will build the `gotemplate` binary in `$GOPATH/bin`.\n\nIt will also pull in a set of templates you can start using straight away\n\n  * [set](http://godoc.org/github.com/ncw/gotemplate/set)\n  * [list](http://godoc.org/github.com/ncw/gotemplate/list)\n  * [sort](http://godoc.org/github.com/ncw/gotemplate/sort)\n  * [heap](http://godoc.org/github.com/ncw/gotemplate/heap)\n  * [treemap](http://godoc.org/github.com/ncw/gotemplate/treemap)\n\nUsing templates\n---------------\n\nTo use a template, first you must tell `gotemplate` that you want to\nuse it using a special comment in your code.  For example\n\n    //go:generate gotemplate \"github.com/ncw/gotemplate/set\" mySet(string)\n\nThis tells `go generate` to run `gotemplate` and that you want to use\nthe set template with the `string` type parameter and with the local\nname `mySet`.\n\nNow run `go generate` in your code directory with no arguments.  This\nwill instantiate the template into a file called `gotemplate_mySet.go`\nwhich will provide a `mySet` type and `newMySet` and `newSizedMySet`\nfunctions to make them. Note that the first letter of your custom name \nis still capitalized when it is not at the beginning of the new name.\n\n    $ go generate\n    substituting \"github.com/ncw/gotemplate/set\" with mySet(string) into package main\n    Written 'gotemplate_mySet.go'\n\nIf you wish to change what the output file names look like then you\ncan use the `-outfmt format` flag.  The format must contain a single\ninstance of the `%v` verb which will be replaced with the template\ninstance name (default \"gotemplate_%v\")\n\nInstantiating the templates into your project gives them the ability\nto use internal types from your project.\n\nIf you use an initial capital when you name your template\ninstantiation then any external functions will be public.  Eg\n\n    //go:generate gotemplate \"github.com/ncw/gotemplate/set\" MySet(string)\n\nWould give you `MySet`, `NewMySet` and `NewSizedMySet` instead.\n\nYou can use multiple templates and you can use the same template with\ndifferent parameters.  In that case you must give it a different name,\neg\n\n    //go:generate gotemplate \"github.com/ncw/gotemplate/set\" StringSet(string)\n    //go:generate gotemplate \"github.com/ncw/gotemplate/set\" FloatSet(float64)\n\nIf the parameters have spaces in then they need to be in quotes, eg\n\n    //go:generate gotemplate \"github.com/ncw/gotemplate/sort\" \"SortGt(string, func(a, b string) bool { return a \u003e b })\"\n\nRenaming rules\n--------------\n\nAll top level identifiers will be substituted when the template is\ninstantiated.  This is to ensure that they are unique if the template\nis instantiated more than once.\n\nAny identifiers with the template name in (eg `Set`) will have the\ntemplate name (eg `Set`) part substituted. If the template name does\nnot begin the identifier, Go's casing style is respected and the \nfirst letter of your new identifier is capitalized. (eg 'newMySet'\ninstead of 'newmySet').\n\nAny identifiers without the template name in will just be post-fixed\nwith the template name.\n\nSo if this was run\n\n    //go:generate gotemplate \"github.com/ncw/gotemplate/set\" MySet(string)\n\nThis would substitute these top level identifiers\n\n  * `Set` to `MySet`\n  * `NewSet` to `NewMySet`\n  * `NewSizedSet` to `NewSizedMySet`\n  * `utilityFunc` to `utilityFuncMySet`\n\nDepending on whether the template name is public (initial capital) or\nnot, all the public external identifiers will have their initial\ncapitals turned into lower case.  So if this was run\n\n    //go:generate gotemplate \"github.com/ncw/gotemplate/set\" mySet(string)\n\nThis would substitute\n\n  * `Set` to `mySet`\n  * `NewSet` to `newMySet`\n  * `NewSizedSet` to `newSizedMySet`\n  * `utilityFunc` to `utilityFuncMySet`\n\nInstalling templates\n--------------------\n\nTemplates can be installed using `go get` because they are normal Go\npackages.  Eg\n\n    go get github.com/someones/template\n\nWill install a template package you can use in your code with\n\n    //go:generate gotemplate \"github.com/someones/template\" T(Potato)\n\nThen instantiate with\n\n    go generate\n\nSource control for templates\n----------------------------\n\nIt is expected that the generated files will be checked into version\ncontrol, and users of your code will just run `go get` to fetch it.\n`go generate` will only be run by developers of the package.\n\nWriting templates\n-----------------\n\nTemplates are valid go packages.  They should compile and have tests\nand be usable as-is.  Because they are packages, if you aren't writing\na public template you should put them in a subdirectory of your\nproject most likely.\n\nTo make a Go package a template it should have one or more\ndeclarations and a special comment signaling to `gotemplate` what the\ntemplate is called and what its parameters are. Supported\nparameterized declarations are type, const, var and func.\n\nHere is an example from the set package.\n\n    // template type Set(A)\n    type A int\n\nThis indicates that the base name for the template is `Set` and it has\none type parameter `A`.  When you are writing the template package\nmake sure you use `A` instead of `int` where you want it to be\nsubstituted with a new type when the template is instantiated.\n\nSimilarly, you could write a package with a const parameter.\n\n    // template type Vector(A, N)\n    type A int\n    const N = 2\n\n    type Vector[N]A\n\nThis indicates that the base name for the template is `Vector` and it\nhas one type parameter `A` and one constant parameter `N`. Again, all\nuses of `N` in the template code will be replaced by a literal value\nwhen the template is instantiated.\n\nAll the definitions of the template parameters will be removed from\nthe instantiated template.\n\nAll test files are ignored.\n\nBugs\n----\n\nThere may be constraints on the types which aren't understood by\n`gotemplate`.  For instance the set requires that the types are\ncomparable.  If you try this you'll get a compile error for example.\n\n    //go:generate gotemplate \"github.com/ncw/gotemplate/set\" BytesSet([]byte)\n\nOnly one .go file is used when reading template definitions at the\nmoment (programmer laziness - will fix at some point!)\n\nChangelog\n---------\n\n  * v0.06 - 2017-05-05\n    * Add -outfmt string (thanks Paul Jolly)\n  * v0.05 - 2016-02-26\n    * Fix docs and examples\n    * More set methods - thanks Adam Willis\n    * Fix missing error check in code generation\n  * v0.04 - 2014-12-23\n    * Fixed multi-line type declarations\n  * v0.03 - 2014-12-22\n    * Allow const and var to be substituted as template parameters\n  * v0.02 - 2014-12-15\n    * Fixed multi-line const/var declarations\n  * v0.01 - 2014-12-10\n    * Change renaming rules to make better Go names.  This only affects private exports, eg for `mySet` in the example above,\n      * `NewSet` becomes `newMySet` (was `newmySet`)\n      * `NewSizedSet` becomes `newSizedMySet` (was `newSizedmySet`)\n      * `utilityFunc` becomes `utilityFuncMySet` (`utilityFuncmySet`)\n    * This is a backwards incompatible change\n  * v0.00 - 2014-10-05\n    * First public release\n\nIdeas for the future\n--------------------\n\nMake a set type for non comparable things?  Pass in a compare routine?\n\nMake sure that types implement an interface?\n\nOptional parameters?\n\nPhilosophy\n----------\n\nAll code (templates, use of templates and template instantiations)\nshould be normal Go code - no special types / extensions.\n\nAll configuration done with specially formatted comments\n\nShould provide lots practical templates people can use right now.\n\nLicense\n-------\n\nThis is free software under the terms of MIT the license (check the\nCOPYING file included in this package).\n\nPortions of the code have been copied from the Go source.  These are\nidentified by comments at the head of each file and these are\nCopyright (c) The Go Authors.  See the GO-LICENSE file for full details.\n\nContact and support\n-------------------\n\nThe project website is at:\n\n  * https://github.com/ncw/gotemplate\n\nThere you can file bug reports, ask for help or contribute patches.\n\nAuthors\n-------\n\n  * Nick Craig-Wood \u003cnick@craig-wood.com\u003e\n\nContributors\n------------\n\n  * Patrick Oyarzun \u003cpatrickoyarzun@gmail.com\u003e\n  * Adam Willis \u003cakwillis@inbox.com\u003e\n  * Paul Jolly \u003cpaul@myitcv.org.uk\u003e\n  * Igor Mikushkin \u003cigor.mikushkin@gmail.com\u003e\n","funding_links":[],"categories":["[](https://github.com/golang/go/wiki/CodeTools#code-generation-templating-and-generics)Code generation, Templating and Generics"],"sub_categories":["[](https://github.com/golang/go/wiki/CodeTools#tools)Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncw%2Fgotemplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fncw%2Fgotemplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncw%2Fgotemplate/lists"}