arg

Documentation

Overview

Provides utilities for managing and processing arguments in a structured way. It is designed to facilitate handling HTTP request parameters, context data, and finalizers in a clean and organized manner, featuring:

• Parameter Handling: efficient extraction and manipulation of parameters from various sources within HTTP requests. Parameters are parsed and stored in a way that enables easy access and processing.
• Context Management: managing and utilizing context data throughout the request processing pipeline. This context can store important information such as user details or other request-specific data, which can be accessed by subsequent processing steps.
• Finalizers: functions that are executed after the main processing of a request. Finalizers are useful for tasks like logging and metrics collection, ensuring that essential post-processing operations are handled effectively.
• Internationalization: using client language preferences to apply appropriate translations to output strings, enhancing user experience across different languages.

Index

• func Get[T argTypes](as *Args, name string) T
• func GetCSV[T argTypes](as *Args, name string) ([]T, error)
• func GetContext[T any](as *Args, name string) T
• func Gets[T argTypes](as *Args, name string) []T
• type Args
  • func (as *Args) Add(key string, val any)
  • func (as *Args) AddFinalizer(f func(*Args))
  • func (as Args) Context(key string) any
  • func (as *Args) Del(key string)
  • func (as Args) Finalizers() []func(*Args)
  • func (as Args) Has(key string) bool
  • func (as Args) HasContext(key string) bool
  • func (as *Args) Init()
  • func (as Args) Keys() []string
  • func (as Args) Localizer() *message.Printer
  • func (as *Args) Set(key string, val ...any)
  • func (as Args) Value(key string) any
  • func (as Args) Values(key string) []any
  • func (as *Args) WithContext(key string, val any) *Args
  • func (as *Args) WithLocalizer(mp *message.Printer) *Args

Functions

func Get

func Get[T argTypes](as *Args, name string) T

Get the first argument value of `name`. If no value exists, returns the zero value of type T. See Gets for supported types.

func GetCSV

func GetCSV[T argTypes](as *Args, name string) ([]T, error)

Parse a CSV string argument to a slice of type T.

func GetContext

func GetContext[T any](as *Args, name string) T

Get context value of `name` as type T.

func Gets

func Gets[T argTypes](as *Args, name string) []T

Get the argument values corresponding to `name` as type T. Supported types are:

• bool
• float64: float32 values are converted to float64
• int64: all signed int values are converted to int64
• string
• uint64: all unsigned int values are converted to uint64

Note: if a wrong type is specified, zero value will be returned.

Types

type Args

type Args struct {
	// contains filtered or unexported fields
}

The Args struct is used to store parameters parsed from HTTP requests. It serves as a central repository for managing these parameters throughout the request handling process.

This struct is created and used automatically by the framework. Its primary usage is within go.xrfang.cn/hap/v2.Action functions:

func greet(a *arg.Args, w http.ResponsWriter, r *http.Request) any {
	name := arg.Get[string](a, "name")
	fmt.Fprintf(w, "Hello %s!", name)
	return nil
}

Do not declare a variable of type Args in your code.

func (*Args) Add

func (as *Args) Add(key string, val any)

Add an argument (key-value pair). Note that a `key` can have multiple `val`, just like [url.Values].

func (*Args) AddFinalizer

func (as *Args) AddFinalizer(f func(*Args))

Add a finalizer function.

func (Args) Context

func (as Args) Context(key string) any

Get the context value of `key`.

func (*Args) Del

func (as *Args) Del(key string)

Delete an argument along with all its values.

func (Args) Finalizers

func (as Args) Finalizers() []func(*Args)

Get a list of all finalizers. This function is used internally by the framework.

func (Args) Has

func (as Args) Has(key string) bool

Check if argument `key` exists or not.

func (Args) HasContext

func (as Args) HasContext(key string) bool

Check if context `key` exists or not.

func (*Args) Init

func (as *Args) Init()

Initialize the Args struct. This function is used internally by the framework.

func (Args) Keys

func (as Args) Keys() []string

Get a list of all argument names.

func (Args) Localizer

func (as Args) Localizer() *message.Printer

Returns a localized output formatter, which is created by the framework before processing requests. This function is primarily used by the framework itself. However, it may be necessary at times to use the localizer to localize text in API response data.

func (*Args) Set

func (as *Args) Set(key string, val ...any)

Set the values of an argument. This will replace all values of an existing `key` with `val` (a slice of any).

func (Args) Value

func (as Args) Value(key string) any

Get the first element of the argument values corresponding to `key`. If `key` does not exist in argument, returns nil.

func (Args) Values

func (as Args) Values(key string) []any

Get all values corresponding to `key`.

func (*Args) WithContext

func (as *Args) WithContext(key string, val any) *Args

Adds a context entry that is passed to the next action in the chain or to finalizers. This function is typically used in "login" actions to add user information or to create a "session" after successful authentication.

The `key` parameter is the context entry key, and `val` is the corresponding value. The function returns the current Args instance to support method chaining.

func (*Args) WithLocalizer

func (as *Args) WithLocalizer(mp *message.Printer) *Args

Sets a *message.Printer which is used to localize output information. This function is used internally by the framework.

See here for more information on i18n/l10n capabilities of the HAP framework.