Documentation
¶
Overview ¶
Package parameters is a pure-Go, CGO-free port of ActionController::Parameters (Rails "strong parameters"), faithful to MRI/Rails 4.0.5-era semantics of require / permit / permitted? / to_h.
A Parameters value wraps an insertion-ordered string-keyed map whose values are one of: a scalar (string, bool, integer, float, or nil), a []any array, or a nested *Parameters. Construction from a plain Go map converts nested maps and array-of-map elements recursively into *Parameters, and orders keys deterministically (sorted) since Go maps have no intrinsic order.
Index ¶
- Variables
- type ParameterMissing
- type Parameters
- func (p *Parameters) Each(fn func(key string, val any) bool)
- func (p *Parameters) Get(key string) (any, bool)
- func (p *Parameters) Has(key string) bool
- func (p *Parameters) Keys() []string
- func (p *Parameters) Len() int
- func (p *Parameters) Merge(other *Parameters) *Parameters
- func (p *Parameters) Permit(filters ...any) *Parameters
- func (p *Parameters) Permitted() bool
- func (p *Parameters) Require(key string) (any, error)
- func (p *Parameters) RequireAll(keys []string) ([]any, error)
- func (p *Parameters) String() string
- func (p *Parameters) ToH() (map[string]any, error)
- func (p *Parameters) ToUnsafeH() map[string]any
- type UnfilteredParameters
- type UnpermittedParameters
Constants ¶
This section is empty.
Variables ¶
var ActionOnUnpermittedParameters = ""
ActionOnUnpermittedParameters controls what permit does when the source contains keys that were not requested. It mirrors Rails' config.action_controller.action_on_unpermitted_parameters:
- "" / "log": filter silently (the default).
- "raise": panic with *UnpermittedParameters (Rails raises an exception, which the controller layer turns into a rescuable error).
Functions ¶
This section is empty.
Types ¶
type ParameterMissing ¶
type ParameterMissing struct {
// Key is the missing parameter name.
Key string
// Params lists the keys that were present, for diagnostics.
Params []string
}
ParameterMissing is the analogue of ActionController::ParameterMissing, raised by Require when a required key is absent or blank.
func (*ParameterMissing) Error ¶
func (e *ParameterMissing) Error() string
type Parameters ¶
type Parameters struct {
// contains filtered or unexported fields
}
Parameters is the Go analogue of ActionController::Parameters.
func New ¶
func New(src map[string]any) *Parameters
New builds a Parameters from a plain Go map (which may be nil for an empty set). Nested map[string]any values become nested *Parameters, and array elements that are maps are converted as well. The resulting Parameters is not permitted.
func (*Parameters) Each ¶
func (p *Parameters) Each(fn func(key string, val any) bool)
Each iterates key/value pairs in order. Returning false from fn stops.
func (*Parameters) Get ¶
func (p *Parameters) Get(key string) (any, bool)
Get returns the value for key and whether it was present. A nested hash is returned as *Parameters, matching Rails' [] accessor.
func (*Parameters) Has ¶
func (p *Parameters) Has(key string) bool
Has reports whether key is present.
func (*Parameters) Keys ¶
func (p *Parameters) Keys() []string
Keys returns the keys in order. The slice is a copy.
func (*Parameters) Merge ¶
func (p *Parameters) Merge(other *Parameters) *Parameters
Merge returns a new Parameters with p's pairs overlaid by other's (other wins on collision). The result inherits p's permitted flag.
func (*Parameters) Permit ¶
func (p *Parameters) Permit(filters ...any) *Parameters
Permit returns a new, permitted Parameters containing only the values allowed by filters. Each filter is either:
- a string: permit a scalar under that key;
- a map[string]any{key: []any{}}: permit an array of scalars under key;
- a map[string]any{key: []any{"a", "b", ...}}: permit a nested hash (or array of hashes) whose own keys are filtered by the inner filters;
- a map[string]any{key: map[string]any{}}: permit an arbitrary nested hash wholesale (Rails' `key: {}`).
Slice filters are flattened, so Permit("a", "b", []any{"c"}) works. When a source key is present but not requested and ActionOnUnpermittedParameters is "raise", Permit panics with *UnpermittedParameters.
func (*Parameters) Permitted ¶
func (p *Parameters) Permitted() bool
Permitted reports whether the parameters have been marked permitted.
func (*Parameters) Require ¶
func (p *Parameters) Require(key string) (any, error)
Require returns the value for key, raising ParameterMissing (as an error) when the key is absent or its value is "blank" (nil, "", empty array, or empty hash). The literal value false is not blank, matching Rails.
func (*Parameters) RequireAll ¶
func (p *Parameters) RequireAll(keys []string) ([]any, error)
RequireAll requires each key in turn, returning the values in order. The first missing key produces the error, mirroring params.require([:a, :b]).
func (*Parameters) String ¶
func (p *Parameters) String() string
String renders a stable debug form.
func (*Parameters) ToH ¶
func (p *Parameters) ToH() (map[string]any, error)
ToH returns a deep plain-map snapshot of the permitted parameters. It returns *UnfilteredParameters when the parameters have not been permitted, mirroring ActionController::Parameters#to_h.
func (*Parameters) ToUnsafeH ¶
func (p *Parameters) ToUnsafeH() map[string]any
ToUnsafeH returns a deep plain-map snapshot regardless of the permitted flag, mirroring #to_unsafe_h.
type UnfilteredParameters ¶
type UnfilteredParameters struct{}
UnfilteredParameters is the analogue of ActionController::UnfilteredParameters, returned by ToH on parameters that have not been permitted.
func (*UnfilteredParameters) Error ¶
func (e *UnfilteredParameters) Error() string
type UnpermittedParameters ¶
type UnpermittedParameters struct {
// Keys are the parameter names that were present but not permitted.
Keys []string
}
UnpermittedParameters is the analogue of ActionController::UnpermittedParameters, used when ActionOnUnpermittedParameters is "raise".
func (*UnpermittedParameters) Error ¶
func (e *UnpermittedParameters) Error() string
Source Files