param

Documentation

Index

• func LengthBetween(min, max int) *checker
• func New[T paramTypes](key string) *param[T]
• func NewChecker() *checker
• func TextConsistsOf(chars Charset) *checker
• func TextHasPrefix(pfx string, caseFold bool) *checker
• func TextHasSuffix(sfx string, caseFold bool) *checker
• func TextIsOneOf(vs ...string) *checker
• func TextMatches(expr string) *checker
• func ValueBetween[T numbers](min, max T) *checker
• func ValueGreaterThan[T numbers](min T) *checker
• func ValueIsOneOf[T paramTypes](vs ...T) *checker
• func ValueLessThan[T numbers](max T) *checker
• type Charset
• type Param

Functions

func LengthBetween

func LengthBetween(min, max int) *checker

func New

func New[T paramTypes](key string) *param[T]

Create a parameter.

func NewChecker

func NewChecker() *checker

Creates a checker. Checkers are used by the Param object via param.WithCheckers method. A checker must have a handler function with the following signature:

func(T) (*any, string, []any)

The input parameter of this function is the value to be checked, which can be one of the supported types: bool, float64, int64, uint64, and string. In its output, the first value is a pointer to the checked value, the second value is the error message, and the third value is the variables in the error message (i.e., how fmt.Sprintf is used). The framework determines parameter compliance based on whether the second parameter is empty after calling the checking function. If the check is successful, it checks if the first parameter is nil; if it is not nil, the value pointed to by that pointer is used to replace the parameter's value. For example,

param.New[uint32]("uid").WithCheckers(
	param.NewChecker().WithHandler(func(id uint64) (*any, string, []any) {
	    row := db.QueryRow(`SELECT * FROM users WHERE id=?`, id)
		u, err := rowToUser(row)
		if err != nil {
			return nil, err.Error(), nil
		}
		v := any(u)
		return &v, "", nil
	}).WithHelp("User ID must exist in the database")

In this example, there are a few points to note:

• The parameter `uid` is defined as `uint32`, but the checker function's parameter type is `uint64`. This is because the HAP framework reduces parameter types, converting all signed integers to `int64`, unsigned integers to `uint64`, and floating-point numbers to `float64`. However, all types can still be used during definition. In this example, if `uid` exceeds the maximum value of `uint32` or is a negative number, it will be rejected before calling any checker function.

• Although `uid` is defined as an integer type, the final output parameter value is a `user` object. In other words, by using a checker, HTTP parameters can be converted to any required type. In the Action function, if a parameter has not been type-converted, it is used as follows:

  uid := arg.Get[uint64](a, "uid")

  If it is converted to a `User` object in the above example, it would be:

  user := a.Value("uid").(*User)

• Generally, a checker function only checks the format and range of a parameter. Performing database queries in a checker function is not always a good practice due to its lack of generality. This logic is better handled in the Action function compared to the checker. If it is necessary to perform in-depth preprocessing of parameters in the checker, consider using some caching mechanisms to improve performance.

This package provides several ready-to-use checkers, as demonstrated in the following example:

handler.New("GET").WithParams(
    param.New[string]("ident").WithCheckers(
	    param.LengthBetween(1, 16),
	    param.TextConsistsOf(param.AlphaNumeric),
	).WithHelp("resource identity"),
	param.New[uint16]("amount").WithCheckers(
	    param.ValueLessThan(1000),
	),
	param.New[string]("payment").WithCheckers(
	    param.ValueIsOneOf("master", "visa").
		    WithHelp("only 'master' or 'visa' are supported"),
	)
).WithAction(apiGet)

This example illustrates:

• How to define parameters for a handler.
• That a parameter can have multiple checkers.
• That each checker can include a custom help message. If a custom message is not provided, a default help message is used, with support for localization.

For a complete list of predefined checkers, refer to this document page. All these checkers are designed to be self-explanatory and intuitive.

func TextConsistsOf

func TextConsistsOf(chars Charset) *checker

func TextHasPrefix

func TextHasPrefix(pfx string, caseFold bool) *checker

func TextHasSuffix

func TextHasSuffix(sfx string, caseFold bool) *checker

func TextIsOneOf

func TextIsOneOf(vs ...string) *checker

Similar to ValueIsOneOf, but the comparison is case-insensitive for the `vs` values.

func TextMatches

func TextMatches(expr string) *checker

func ValueBetween

func ValueBetween[T numbers](min, max T) *checker

func ValueGreaterThan

func ValueGreaterThan[T numbers](min T) *checker

func ValueIsOneOf

func ValueIsOneOf[T paramTypes](vs ...T) *checker

func ValueLessThan

func ValueLessThan[T numbers](max T) *checker

Types

type Charset

type Charset string

Represents a set of characters used for validation purposes in a Checker.

const (
	UpperCase    Charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
	LowerCase    Charset = "abcdefghijklmnopqrstuvwxyz"
	Alphabetic   Charset = UpperCase + LowerCase
	Numeric      Charset = "0123456789"
	AlphaNumeric Charset = Alphabetic + Numeric
	Decimal      Charset = Numeric
	Hexadecimal  Charset = Decimal + "abcdefABCDEF"
)

type Param

type Param interface {
	Default() *string                        //Returns the default value of the parameter, if any.
	Help(*message.Printer) []string          //Provides localizable help text for the parameter.
	Name() string                            //Returns the name of the parameter.
	Parse(url.Values) ([]any, string, []any) //Parses URL values into arguments according to parameter spec.
	Required() bool                          //Indicates whether the parameter is required.
	Rules(*message.Printer) [][]string       //Defines the validation rules for the parameter.
	Type() string                            //Returns the type of the parameter.
}

Represents the specification of an HTTP parameter