forge

README

forge

//todo: update description

forge is a tool for automating the creation of methods that satisfy some built-in interfaces or those defined in the templates.

Table of content

1. Usage

   1. Scaffolder
   2. Enum
   3. Model
   4. Bindata
   5. Project

Usage

forge can be run from console in directory with target type or with help go generate:

$ forge enum --type MyType

Or

package main

//go:generate forge enum --type MyType
type MyType int 

const (
	MyTypeA MyType   = iota
	MyTypeB
	MyTypeC
)

$  ./forge 
NAME:
   forge - cli tool and generator from lancer-kit

USAGE:
   forge [global options] command [command options] [arguments...]

VERSION:
   2.5

COMMANDS:
     new      generate new project structure from template
     enum     generate var and methods for the iota-enums
     model    generate code for structure by template
     bindata  forge bindata <options>
     help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h     show help
   --version, -v  print the version

Scaffolder

CLI tool for scaffolding the Golang project

Templates

The Scaffold project uses Go Modules. The whole scaffold project uses these modules structure:

• github.com/go-chi/chi
• github.com/go-chi/cors
• github.com/go-ozzo/ozzo-validation
• github.com/lancer-kit/armory
• github.com/lancer-kit/uwe/v2
• github.com/rubenv/sql-migrate
• github.com/sirupsen/logrus
• github.com/urfave/cli
• gopkg.in/yaml.v2

Templates are use lancer-kit armory package for DB and log management and uwe/v2 package to provider worker pool functionality in the project.

The scaffolder may generate the go mods with project name and tidy them on --gomods flag.

Example

go get github.com/lancer-kit/forge

CLI Usage

forge new [arguments...]

new cmd - generates the scaffold project contains following options that described in the table:

Option	Required	Description
--gomods project name, -m project name	no	project name of project with Go Modules (ex. forge) [$GOMOD_PROJECT_NAME]
--outdir dir path, -o dir path	no	project name of project with Go Modules (ex. forge) [$GOMOD_PROJECT_NAME]
--gopath project domain name, -g project domain name	yes	project domain name (ex. github.com/gitnetwork.com/team/project) [$GOPATH_PROJECT_DOMAIN]
--gitorigin git origin, -r git origin	no	git origin to init git repository add all changes to remote origin [$GIT_ORIGIN]

Usage of CLI and its options described in /example

Enum

Command: forge enum

Implements predefined interfaces for a user-defined integer type with iota-constants.

Interface list:

1. fmt.Stringer - String() string;
2. json.Marshaler - MarshalJSON() ([]byte, error);
3. json.Unmarshaler - UnmarshalJSON([]byte) error;
4. driver.Valuer - Value() (Value, error);
5. sql.Scanner - Scan(src interface{}) error;
6. Validator - Validate() error.

Predefined variables :

• var def<Type>ValueToName map[<Type>]string - matching a constant and its string representation;
• var def<Type>NameToValue map[string]<Type> - matching a string representation and constant;
• var Err<Type>Invalid error - error.

All methods and maps can be pre-determined before generation, and at run they will be omitted.

List of arguments:

Flag	Type	Description
type	string	The name of the target type or types for code generation
transform	snake, kebab, space, none	A rule describing the strategy for converting constant names to a string. Default: none
tprefix	true, false	add type name prefix into string values or not. Default: false
prefix	string	A prefix to be added to the output file
suffix	string	A suffix to be added to the output. Default: "_enums"
merge	bool	Merge all output into one file, if set prefix and suffix will be ignored. Default: false

Example

forge enum --type ShirtSize,WeekDay --merge true

Model

Command: forge model

Find the structure definition, analyze it and fill in the transposed template.

Available fields for template:

Flag	Type	Description
Package	string	Name of package with type
TypeName	string	Type name
TypeString	string	camelCased type name
Fields	[]Field	List of structure field definitions
Field.Name	string	Name of filed
Field.FType	string	Type of field
Field.Tags	map[string]string	Field tags

List of arguments:

Flag	Type	Description
tmpl	string	path to the templates; required
type	string	list of type names; required
prefix	string	prefix to be added to the output file
suffix	string	suffix to be added to the output file

Bindata

Build-in fork of go-bindata

USAGE:
   forge bindata [command options] [arguments...]


OPTIONS:
   --debug           Do not embed the assets, but provide the embedding API. Contents will still be loaded from disk.
   --dev             Similar to debug, but does not emit absolute paths. Expects a rootDir variable to already exist in the generated code's package.
   --nomemcopy       Use a .rodata hack to get rid of unnecessary memcopies. Refer to the documentation to see what implications this carries.
   --nocompress      Assets will *not* be GZIP compressed when this flag is specified.
   --nometadata      Assets will not preserve size, mode, and modtime info.
   --tags value      Optional set of build tags to include.
   --prefix value    Optional path prefix to strip off asset names.
   --pkg value       Package name to use in the generated code.
   -o value          Optional name of the output file to be generated.
   --mode value      Optional file mode override for all files. (default: 0)
   --modetime value  Optional modification unix timestamp override for all files. (default: 0)
   --ignore value    Regex pattern to ignore
   -i value          List of input directories/files

Project

ToDo

• Improve documentation, add tests
• Add string types support
• Add bitmap types support
• Add custom template support

License

This tool contains code from next repos:

• https://github.com/campoy/jsonenums.
• https://github.com/jteeuwen/go-bindata.

Documentation

Overview

JSONenums is a tool to automate the creation of methods that satisfy the fmt.Stringer, json.Marshaler and json.Unmarshaler interfaces. Given the name of a (signed or unsigned) integer type T that has constants defined, forge will create a new self-contained Go source file implementing

func (t T) String() string
func (t T) MarshalJSON() ([]byte, error)
func (t *T) UnmarshalJSON([]byte) error

The file is created in the same package and directory as the package that defines T. It has helpful defaults designed for use with go generate.

JSONenums is a simple implementation of a concept and the code might not be the most performant or beautiful to read.

For example, given this snippet,

package painkiller

type Pill int

const (
	Placebo Pill = iota
	Aspirin
	Ibuprofen
	Paracetamol
	Acetaminophen = Paracetamol
)

running this command

forge -type=Pill

in the same directory will create the file pill_jsonenums.go, in package painkiller, containing a definition of

func (r Pill) String() string
func (r Pill) MarshalJSON() ([]byte, error)
func (r *Pill) UnmarshalJSON([]byte) error

That method will translate the value of a Pill constant to the string representation of the respective constant name, so that the call fmt.Print(painkiller.Aspirin) will print the string "Aspirin".

Typically this process would be run using go generate, like this:

//go:generate forge -type=Pill

If multiple constants have the same value, the lexically first matching name will be used (in the example, Acetaminophen will print as "Paracetamol").

With no arguments, it processes the package in the current directory. Otherwise, the arguments must name a single directory holding a Go package or a set of Go source files that represent a single Go package.

The -type flag accepts a comma-separated list of types so a single run can generate methods for multiple types. The default output file is t_jsonenums.go, where t is the lower-cased name of the first type listed. The suffix can be overridden with the -suffix flag and a prefix may be added with the -prefix flag.