← Home · Ruby skill tree

An interactive Ruby lesson

Keyword arguments

Keyword arguments name the values passed to a method. Start with Methods and Hashes.

p displays a value. Predict the output, press Run, then open the expected output. Change one input and run again. Reset restores that example; Stop ends a running example.

The first Run downloads Ruby into your browser. JavaScript and a network connection are needed to run examples. Each run starts fresh, so keep the method definition and its calls together in the editor you run. The code and answers remain readable without JavaScript.

1. Require a named keyword

quantity: in a method definition requires a keyword named quantity. In the call, quantity: 2 supplies its value. The method body uses quantity as a local variable. Predict the total.

Show expected output
6

Try it: Change quantity: 2 to quantity: 5. Predict the total.

Calling total() without quantity: raises ArgumentError, which stops the program unless handled. A keyword this method does not accept, such as discount:, also raises ArgumentError.

2. Match keywords by name

quantity: and price: are both required. Ruby matches keyword arguments by name, so their order in a call can change. Predict both totals.

Show expected output
6
6

Try it: Change price: 3 to price: 5 in both calls. Explain why the totals still match.

3. Give a keyword a default

price: 3 in the definition makes price optional. Ruby uses 3 when the call omits it. A supplied value replaces the default for that call. quantity: remains required. Predict both totals.

Show expected output
6
10

Try it: Change the explicit price: 5 to price: 0. Predict which total changes. Zero is a supplied value, so it does not use the default.

4. Mix positional and keyword arguments

quantity has no colon in this definition, so it is positional: the first value in the call supplies it. price: is a required keyword supplied by name. Put positional arguments before keywords. Predict the total.

Show expected output
6

Try it: Change the positional 2 to 4, then change price: 3 to price: 5. Predict each total.

5. Expand an options hash

{ quantity: 2, price: 3 } is a hash with symbol keys :quantity and :price. In a call, **options expands its entries into keyword arguments. Predict the total.

Show expected output
6

Try it: Change the hash to { quantity: 4, price: 5 }. Predict the total. Explain how each key matches a keyword in the definition.

In Ruby 4.0, total(options) passes one positional hash. It does not supply the required keywords for this method and raises ArgumentError. Use total(**options) to expand the hash into keywords.

6. Collect and forward keywords

In def order_total(**options), **options collects keyword arguments into a hash named options. Inside the method, total(**options) expands that hash to pass the keywords to total. Predict the result of this delegation.

Show expected output
10

Try it: Remove , price: 5 from the call to order_total. Predict how the default in total affects the result. Then change quantity: 2 to quantity: 4.

Forwarding a missing quantity: or an unexpected keyword raises ArgumentError there.

Practice on your own

Replace the code in the last editor with a program for these tasks. Predict the output, then run it.

  1. Define ticket_total(quantity:, price: 4) to return the quantity multiplied by the price.
  2. Create an options hash with quantity: 3. Call ticket_total using **options and display the result.
  3. Set options[:price] = 5. Call the method with **options again and display the result.
Show a solution and its output
def ticket_total(quantity:, price: 4)
  quantity * price
end

options = { quantity: 3 }
p(ticket_total(**options))
options[:price] = 5
p(ticket_total(**options))

Output:

12
15

Ruby 4.0 reference: Defining keyword arguments and Unpacking keyword arguments.

Return to keyword arguments in the skill tree →