Documentation
¶
Index ¶
- func LengthBetween[T paramTypes](min, max int) *checker[T]
- func New[T paramTypes](key string) *param[T]
- func NewChecker[T paramTypes]() *checker[T]
- func TextConsistsOf[T string](chars Charset) *checker[T]
- func TextHasPrefix[T string](pfx string, caseFold bool) *checker[T]
- func TextHasSuffix[T string](sfx string, caseFold bool) *checker[T]
- func TextIsOneOf[T string](vs ...string) *checker[T]
- func TextMatches[T string](expr string) *checker[T]
- func ValueBetween[T numbers](min, max T) *checker[T]
- func ValueGreaterThan[T numbers](min T) *checker[T]
- func ValueIsOneOf[T paramTypes](vs ...T) *checker[T]
- func ValueLessThan[T numbers](max T) *checker[T]
- type Charset
- type Param
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewChecker ¶
func NewChecker[T paramTypes]() *checker[T]
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 TextIsOneOf ¶
Similar to ValueIsOneOf, but the comparison is case-insensitive for the `vs` values.
func ValueBetween ¶
func ValueBetween[T numbers](min, max T) *checker[T]
func ValueGreaterThan ¶
func ValueGreaterThan[T numbers](min T) *checker[T]
func ValueIsOneOf ¶
func ValueIsOneOf[T paramTypes](vs ...T) *checker[T]
func ValueLessThan ¶
func ValueLessThan[T numbers](max T) *checker[T]
Types ¶
type Charset ¶
type Charset string
Represents a set of characters used for validation purposes in a Checker.
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
Source Files