taqc

README

taqc 🚕

Tag based url Query parameters Constructor.
(This is pronounced as same as "taxi")

Synopsis

type Query struct {
	Foo             string    `taqc:"foo"`
	Bar             *string   `taqc:"bar"`
	Buz             int64     `taqc:"buz"`
	Qux             []float64 `taqc:"qux"`
	FooBar          bool      `taqc:"foobar"`
	Falsy           bool      `taqc:"falsy"`
	ShouldBeIgnored string
}

queryParams, err := taqc.ConvertToQueryParams(&Query{
	Foo:             "string_value",
	Bar:             nil, // <= should be ignored
	Buz:             123,
	Qux:             []float64{123.456, 234.567},
	FooBar:          true,  // <= be "foobar=1"
	Falsy:           false, // <= should be ignored
	ShouldBeIgnored: "should be ignored",
})
if err != nil {
	panic(err)
}

fmt.Printf("%s\n", queryParams.Encode())

// Output:
// buz=123&foo=string_value&foobar=1&qux=123.456000&qux=234.567000

Requirements

• Go 1.17 or later

Description

This library constructs the query parameters (i.e. url.Value{}) according to the struct, and the taqc tag which is in each field.

Currently, it supports the following field types: string, int64, float64, bool, *string, *int64, *float64, *bool, []string, []int64, []float64, time.Time, *time.Time, and []time.Time.

If the bool field is true, the query parameter becomes param_name=1. Else, it omits the parameter.

And, when the pointer value is nil, it omits the parameter.

time.Time field

This library supports the time.Time fields. By default, it encodes that timestamp by Time#Unix().

If you want to encode it by another unix time format, you can use unixTimeUnit custom tag value. For example:

type Query struct {
	Foo time.Time `taqc:"foo, unixTimeUnit=millisec"`
}

in the case of the above example, it encodes the timestamp by Time#UnixMilli().

Currently unixTmeUnit supports the following values:

• sec
• millisec
• microsec
• nanosec

It also supports encoding with arbitrary time layout by timeLayout custom tag value. e.g.

type Query struct {
	Foo time.Time `taqc:"foo, timeLayout=2006-01-02T15:04:05Z07:00"` // RFC3339 layout
}

then, it encodes the timestamp by Time#Format() with given layout.

NOTE: timeLayout takes priority over unixTimeUnit. This means it uses timeLayout option even if you put them together.

Command-line Tool

This library also provides a command-line tool to generate code.

taqc.ConvertToQueryParams() converts the given struct value to query parameters by using reflection dynamically, but this way has a little disadvantage from the performance perspective.

This CLI tool generates the code statically, and this can convert that structure to the query parameters more efficiently.

Installation

go install github.com/moznion/taqc/cmd/taqc@latest

And you can grab a pre-built binary here: https://github.com/moznion/taqc/releases

Usage

Usage of taqc:
  -type string
        [mandatory] a type name
  -output string
        [optional] output file name (default "srcdir/<type>_gen.go")
  -version
        show the version information

Example

When it has the following code:

//go:generate taqc --type=QueryParam
type QueryParam struct {
	Foo             string  `taqc:"foo"`
	Bar             int64   `taqc:"bar"`
	Buz             float64 `taqc:"buz"`
	Qux             bool    `taqc:"qux"`
}

then you run go generate ./..., it generates code on query_param_gen.go that is in the same directory of the original struct file. That generated file has a method (v *QueryParam) ToQueryParameters() url.Values.

Author

moznion (moznion@mail.moznion.net)

Documentation

Index

• Variables
• func ConvertToQueryParams(v interface{}) (url.Values, error)

Examples

• ConvertToQueryParams

Variables

var (
	ErrNilValueGiven             = errors.New("given value is nil")
	ErrQueryParameterNameIsEmpty = errors.New("query parameter name is empty in a tag")
	ErrUnsupportedFieldType      = errors.New("unsupported filed type has come")
	ErrUnsupportedUnixTimeUnit   = errors.New("unsupported unix time unit has given")
)

Functions

func ConvertToQueryParams

func ConvertToQueryParams(v interface{}) (url.Values, error)

ConvertToQueryParams converts given structure to the query parameters according to the custom tags.

When a field of the structure has `taqc` tag, it converts a value of that field to query parameter. Currently, it supports the following field types: `string`, `int64`, `float64`, `bool`, `*string`, `*int64`, `*float64`, `*bool`, `[]string`, `[]int64`, `[]float64`, `time.Time`, `*time.Time`, and `[]time.Time`. If the bool field is `true`, the query parameter becomes `param_name=1`. Else, it omits the parameter. And when the pointer value is `nil`, it omits the parameter.

This library supports the `time.Time` fields. By default, it encodes that timestamp by `Time#Unix()`. If you want to encode it by another unix time format, you can use `unixTimeUnit` custom tag value. For example:

type Query struct {
	Foo time.Time `taqc:"foo, unixTimeUnit=millisec"`
}

in the case of the above example, it encodes the timestamp by `Time#UnixMilli()`.

Currently `unixTmeUnit` supports the following values:

- `sec` - `millisec` - `microsec` - `nanosec`

It also supports encoding with arbitrary time layout by `timeLayout` custom tag value. e.g.

type Query struct {
	Foo time.Time `taqc:"foo, timeLayout=2006-01-02T15:04:05Z07:00"` // RFC3339 layout
}

then, it encodes the timestamp by `Time#Format()` with given layout.

NOTE: `timeLayout` takes priority over `unixTimeUnit`. This means it uses `timeLayout` option even if you put them together.

Example

type Query struct {
	Foo             string    `taqc:"foo"`
	Bar             *string   `taqc:"bar"`
	Buz             int64     `taqc:"buz"`
	Qux             []float64 `taqc:"qux"`
	FooBar          bool      `taqc:"foobar"`
	Falsy           bool      `taqc:"falsy"`
	ShouldBeIgnored string
}

queryParams, err := ConvertToQueryParams(&Query{
	Foo:             "string_value",
	Bar:             nil, // <= should be ignored
	Buz:             123,
	Qux:             []float64{123.456, 234.567},
	FooBar:          true,  // <= be "foobar=1"
	Falsy:           false, // <= should be ignored
	ShouldBeIgnored: "should be ignored",
})
if err != nil {
	panic(err)
}

fmt.Printf("%s\n", queryParams.Encode())

Output:

buz=123&foo=string_value&foobar=1&qux=123.456000&qux=234.567000