Snails

Module: ActionController::Params

Defined in:
runtime/action_controller/params.rb,
runtime/action_controller/params.rbs

Overview

Narrowing accessors over the request-params tree.

The request's params are a plain Hash here, so the counterpart of ActionController::Parameters (require, permit) is a set of module functions over that Hash — require cannot be a method on it: the call would reach Kernel's private require instead.

The narrowing is is_a? in narrowing position (the branch answers the narrowed value), the shape the compiler already handles.

Class Method Summary collapse

Class Method Details

.permit(source, filters) ⇒ Hash{Symbol => untyped}

the strong-parameters filter over the plain request-params Hash: only the named keys survive, each value shaped by its filter.

A Symbol names a scalar key and keeps its value when truthy; {} keeps a nested Hash as-is (JSON leaves are already permitted); an Array keeps only the listed keys of a Hash, or maps each Hash element of an Array through the same list and passes non-Hash elements through. Unknown top-level keys and unshaped values are dropped.

The result's top-level keys are Symbols (call sites read them that way); nested keys keep the objects the request carried.

Examples:

ActionController::Params.permit(
  { "uuid" => "u", "network_info" => [{ "name" => "en0", "extra" => 1 }] },
  [ :uuid, { network_info: [ :name ] } ]
)
# => { uuid: "u", network_info: [{ "name" => "en0" }] }

Parameters:

  • source (Hash) —

    the request params (String or Symbol keys)

  • filters (Array<Symbol, Hash>) —

    the allowed keys and their shapes

Returns:

  • (Hash{Symbol => untyped}) —

    the permitted set

Raises:

  • (ArgumentError) —

    source is not a Hash, filters is not an Array, or a filter has a shape other than a Symbol, {}, or an Array of Symbols



136
 
# File 'runtime/action_controller/params.rb', line 136

def self.permit: (Hash[untyped, untyped], untyped) -> Hash[Symbol, untyped]

.permitted(acc, params, key, name) ⇒ Hash

one key of a permitted set: the scalar the request carried for key is added to acc under name, and left out otherwise, so a model write leaves that attribute alone.

Examples:

ActionController::Params.permitted({}, params, "password", :password)

Parameters:

  • acc (Hash) —

    the accumulating permitted set

  • params (Hash) —

    the request's params

  • key (String) —

    the parameter key

  • name (Symbol) —

    the attribute name the model reads the field under

Returns:

  • (Hash) —

    the accumulating set



81
 
# File 'runtime/action_controller/params.rb', line 81

def self.permitted: (Hash[Symbol, String], Hash[String, untyped], String, Symbol) -> Hash[Symbol, String]

.provided(sub, key) ⇒ Boolean

did the request carry a usable value for key? A blank string counts as provided (permit keeps a blank, compact drops only an explicit nil); an absent key, a JSON null, and a non-scalar do not.

Named without a ? on purpose — this is generated code, so portability beats the Ruby idiom.

Examples:

ActionController::Params.provided(params, "title")   # => true

Parameters:

  • sub (Hash) —

    the params, or a resource hash under one

  • key (String) —

    the key to test

Returns:

  • (Boolean) —

    true when a scalar was carried for the key



100
 
# File 'runtime/action_controller/params.rb', line 100

def self.provided: (Hash[String, untyped], String) -> bool

.require_key(params, key) ⇒ Object

the value the request carried for key, turning a missing or blank parameter into a 400 instead of a nil that fails somewhere later. sub is the forgiving counterpart (absent yields {}).

Examples:

ActionController::Params.require_key(params, "url")   # raises when absent

Parameters:

  • params (Hash) —

    the request's params

  • key (String) —

    the required key

Returns:

  • (Object) —

    the value the request carried

Raises:



59
 
# File 'runtime/action_controller/params.rb', line 59

def self.require_key: (Hash[String, untyped], String) -> untyped

.str(sub, key, fallback) ⇒ String

the scalar under key, or fallback when the key is absent or holds a nested hash or array.

Examples:

ActionController::Params.str(params, "title", "")   # => "Hello"

Parameters:

  • sub (Hash) —

    the params, or a resource hash under one

  • key (String) —

    the field key

  • fallback (String) —

    what to answer when there is no scalar

Returns:

  • (String) —

    the scalar, or the fallback



39
 
# File 'runtime/action_controller/params.rb', line 39

def self.str: (Hash[String, untyped], String, String) -> String

.sub(params, key) ⇒ Hash

the nested resource hash the params carry under key ({"article" => {"title" => …}}).

Examples:

ActionController::Params.sub(params, "article")   # => { "title" => "…" }

Parameters:

  • params (Hash) —

    the request's params

  • key (String) —

    the resource key

Returns:

  • (Hash) —

    the nested hash; empty when the key is absent or holds something other than a hash



21
 
# File 'runtime/action_controller/params.rb', line 21

def self.sub: (Hash[String, untyped], String) -> Hash[String, untyped]