Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Update ActionController::Parameters documentation [ci skip]
The changes in this commit are twofold:

 1. The examples showing `#require` accepting two arguments were wrong - you
    have to wrap the arguments (two, or more) in an array.
 2. `ActionController::Parameters` has an `#inspect` method now (since
    #23732), and the documentation should
    reflect that.

Fixes #27658
  • Loading branch information
bquorning authored and rafaelfranca committed Jan 18, 2017
1 parent 3b95e97 commit 5c5b4fa
Showing 1 changed file with 17 additions and 18 deletions.
35 changes: 17 additions & 18 deletions actionpack/lib/action_controller/metal/strong_parameters.rb
Expand Up @@ -60,8 +60,7 @@ def initialize(params) # :nodoc:
# })
#
# permitted = params.require(:person).permit(:name, :age)
# permitted # => {"name"=>"Francesco", "age"=>22}
# permitted.class # => ActionController::Parameters
# permitted # => <ActionController::Parameters {"name"=>"Francesco", "age"=>22} permitted: true>
# permitted.permitted? # => true
#
# Person.first.update!(permitted)
Expand Down Expand Up @@ -89,7 +88,7 @@ def initialize(params) # :nodoc:
#
# params = ActionController::Parameters.new(a: "123", b: "456")
# params.permit(:c)
# # => {}
# # => <ActionController::Parameters {} permitted: true>
#
# ActionController::Parameters.action_on_unpermitted_parameters = :raise
#
Expand Down Expand Up @@ -257,7 +256,7 @@ def permit!
# either present or the singleton +false+, returns said value:
#
# ActionController::Parameters.new(person: { name: 'Francesco' }).require(:person)
# # => {"name"=>"Francesco"}
# # => <ActionController::Parameters {"name"=>"Francesco"} permitted: false>
#
# Otherwise raises <tt>ActionController::ParameterMissing</tt>:
#
Expand All @@ -278,12 +277,12 @@ def permit!
# returned:
#
# params = ActionController::Parameters.new(user: { ... }, profile: { ... })
# user_params, profile_params = params.require(:user, :profile)
# user_params, profile_params = params.require([:user, :profile])
#
# Otherwise, the method re-raises the first exception found:
#
# params = ActionController::Parameters.new(user: {}, profile: {})
# user_params, profile_params = params.require(:user, :profile)
# user_params, profile_params = params.require([:user, :profile])
# # ActionController::ParameterMissing: param is missing or the value is empty: user
#
# Technically this method can be used to fetch terminal values:
Expand Down Expand Up @@ -376,13 +375,13 @@ def require(key)
# })
#
# params.require(:person).permit(:contact)
# # => {}
# # => <ActionController::Parameters {} permitted: true>
#
# params.require(:person).permit(contact: :phone)
# # => {"contact"=>{"phone"=>"555-1234"}}
# # => <ActionController::Parameters {"contact"=><ActionController::Parameters {"phone"=>"555-1234"} permitted: true>} permitted: true>
#
# params.require(:person).permit(contact: [ :email, :phone ])
# # => {"contact"=>{"email"=>"none@test.com", "phone"=>"555-1234"}}
# # => <ActionController::Parameters {"contact"=><ActionController::Parameters {"email"=>"none@test.com", "phone"=>"555-1234"} permitted: true>} permitted: true>
def permit(*filters)
params = self.class.new

Expand All @@ -404,7 +403,7 @@ def permit(*filters)
# returns +nil+.
#
# params = ActionController::Parameters.new(person: { name: 'Francesco' })
# params[:person] # => {"name"=>"Francesco"}
# params[:person] # => <ActionController::Parameters {"name"=>"Francesco"} permitted: false>
# params[:none] # => nil
def [](key)
convert_hashes_to_parameters(key, @parameters[key])
Expand All @@ -423,7 +422,7 @@ def []=(key, value)
# is given, then that will be run and its result returned.
#
# params = ActionController::Parameters.new(person: { name: 'Francesco' })
# params.fetch(:person) # => {"name"=>"Francesco"}
# params.fetch(:person) # => <ActionController::Parameters {"name"=>"Francesco"} permitted: false>
# params.fetch(:none) # => ActionController::ParameterMissing: param is missing or the value is empty: none
# params.fetch(:none, 'Francesco') # => "Francesco"
# params.fetch(:none) { 'Francesco' } # => "Francesco"
Expand Down Expand Up @@ -459,8 +458,8 @@ def dig(*keys)
# don't exist, returns an empty hash.
#
# params = ActionController::Parameters.new(a: 1, b: 2, c: 3)
# params.slice(:a, :b) # => {"a"=>1, "b"=>2}
# params.slice(:d) # => {}
# params.slice(:a, :b) # => <ActionController::Parameters {"a"=>1, "b"=>2} permitted: false>
# params.slice(:d) # => <ActionController::Parameters {} permitted: false>
def slice(*keys)
new_instance_with_inherited_permitted_status(@parameters.slice(*keys))
end
Expand All @@ -476,17 +475,17 @@ def slice!(*keys)
# filters out the given +keys+.
#
# params = ActionController::Parameters.new(a: 1, b: 2, c: 3)
# params.except(:a, :b) # => {"c"=>3}
# params.except(:d) # => {"a"=>1,"b"=>2,"c"=>3}
# params.except(:a, :b) # => <ActionController::Parameters {"c"=>3} permitted: false>
# params.except(:d) # => <ActionController::Parameters {"a"=>1, "b"=>2, "c"=>3} permitted: false>
def except(*keys)
new_instance_with_inherited_permitted_status(@parameters.except(*keys))
end

# Removes and returns the key/value pairs matching the given keys.
#
# params = ActionController::Parameters.new(a: 1, b: 2, c: 3)
# params.extract!(:a, :b) # => {"a"=>1, "b"=>2}
# params # => {"c"=>3}
# params.extract!(:a, :b) # => <ActionController::Parameters {"a"=>1, "b"=>2} permitted: false>
# params # => <ActionController::Parameters {"c"=>3} permitted: false>
def extract!(*keys)
new_instance_with_inherited_permitted_status(@parameters.extract!(*keys))
end
Expand All @@ -496,7 +495,7 @@ def extract!(*keys)
#
# params = ActionController::Parameters.new(a: 1, b: 2, c: 3)
# params.transform_values { |x| x * 2 }
# # => {"a"=>2, "b"=>4, "c"=>6}
# # => <ActionController::Parameters {"a"=>2, "b"=>4, "c"=>6} permitted: false>
def transform_values(&block)
if block
new_instance_with_inherited_permitted_status(
Expand Down

0 comments on commit 5c5b4fa

Please sign in to comment.