方法¶ ↑

方法实现了程序的功能。这是一个简单的定义方法

def one_plus_one
  1 + 1
end

方法定义由def关键字、方法名、方法体、return值和end关键字组成。当调用时，方法将执行方法体。此方法返回2。

从 Ruby 3.0 开始，还有一种方法的简写语法，该语法只包含一个表达式

def one_plus_one = 1 + 1

本节仅涵盖定义方法。另请参阅调用方法的语法文档。

`Method` 名称¶ ↑

Method 名称可以是运算符之一，或者必须以字母或第八位设置为 1 的字符开头。它可以包含字母、数字、_（下划线）或第八位设置为 1 的字符。约定是使用下划线来分隔多词方法名称中的单词。

def method_name
  puts "use underscores to separate words"
end

Ruby 程序必须使用与 US-ASCII 兼容的字符集编写，例如 UTF-8、ISO-8859-1 等。在这些字符集中，如果第八位设置为 1，则表示扩展字符。Ruby 允许方法名称和其他标识符包含此类字符。Ruby 程序不能包含某些字符，例如 ASCII NUL (\x00)。

以下是有效 Ruby 方法的示例

def hello
  "hello"
end

def こんにちは
  puts "means hello in Japanese"
end

通常，方法名称与 US-ASCII 兼容，因为所有键盘上都存在用于输入它们的键。

Method 名称可以以 !（感叹号）、?（问号）或 =（等号）结尾。

带感叹号的方法（方法名称末尾的 !）的调用和执行方式与任何其他方法相同。但是，按照惯例，带有感叹号或 bang 的方法被认为是危险的。在 Ruby 的核心库中，危险方法意味着当方法以 bang（!）结尾时，它表示与非 bang 等效方法不同，它会永久修改其接收者。几乎总是，Ruby 核心库将具有每个 bang 方法（方法名称以 ! 结尾）的非 bang 对应方法（方法名称不以 ! 结尾），该方法不会修改接收者。此约定通常适用于 Ruby 核心库，但可能适用于其他 Ruby 库，也可能不适用于其他 Ruby 库。

按照惯例，以问号结尾的方法返回布尔值，但它们并不总是只返回 true 或 false。通常，它们将返回一个对象来指示真值（或“真值”）。

以等号结尾的方法表示赋值方法。

class C
  def attr
    @attr
  end

  def attr=(val)
    @attr = val
  end
end

c = C.new
c.attr      #=> nil
c.attr = 10 # calls "attr=(10)"
c.attr      #=> 10

不能使用简写语法定义赋值方法。

这些是各种 Ruby 运算符的函数名。每个运算符只接受一个参数。运算符后面是运算符的典型用法或名称。为运算符创建替代含义可能会导致混淆，因为用户期望加号用于加法，减号用于减法等。此外，您不能更改运算符的优先级。

+: 加法
-: 减法
*: 乘法
**: 幂
/: 除法
%: 模除，String#%
&: 与
^: 异或（异或）
>>: 右移
<<: 左移，追加
==: 等于
!=: 不等于
===: 案例相等。见 Object#===
=~: 模式匹配。（不仅仅用于正则表达式）
!~: 不匹配
<=>: 比较，也称为宇宙飞船运算符。见 Comparable
<: 小于
<=: 小于或等于
>: 大于
>=: 大于或等于

要定义一元减号和加号方法，请在运算符后面加上一个 @，例如 +@

class C
  def -@
    puts "you inverted this object"
  end
end

obj = C.new

-obj # prints "you inverted this object"

需要 @ 来区分一元减号和加号运算符与二元减号和加号运算符。

您也可以在波浪号和非（!）一元方法后面加上 @，但这不是必需的，因为没有二元波浪号和非运算符。

一元方法不接受任何参数。

此外，可以定义元素引用和赋值方法：分别为 [] 和 []=。两者都可以接受一个或多个参数，元素引用可以不接受任何参数。

class C
  def [](a, b)
    puts a + b
  end

  def []=(a, b, c)
    puts a * b + c
  end
end

obj = C.new

obj[2, 3]     # prints "5"
obj[2, 3] = 4 # prints "10"

返回值¶ ↑

默认情况下，方法返回在方法主体中评估的最后一个表达式。在上面的示例中，评估的最后一个（也是唯一一个）表达式是简单的求和 1 + 1。return 关键字可用于明确地使方法返回一个值。

def one_plus_one
  return 1 + 1
end

它还可以用于使方法在评估最后一个表达式之前返回。

def two_plus_two
  return 2 + 2
  1 + 1  # this expression is never evaluated
end

请注意，对于赋值方法，当使用赋值语法时，返回值将被忽略。相反，将返回参数

def a=(value)
  return 1 + value
end

p(self.a = 5) # prints 5

直接调用方法时，将返回实际的返回值

p send(:a=, 5) # prints 6

范围¶ ↑

定义方法的标准语法

def my_method
  # ...
end

将方法添加到类中。您可以使用 class 关键字在特定类上定义实例方法

class C
  def my_method
    # ...
  end
end

方法可以定义在另一个对象上。您可以定义一个“类方法”（在类上定义的方法，而不是类的实例）如下

class C
  def self.my_method
    # ...
  end
end

但是，这仅仅是 Ruby 更大语法能力的一个特例，即向任何对象添加方法的能力。类是对象，因此添加类方法只是向 Class 对象添加方法。

向对象添加方法的语法如下

greeting = "Hello"

def greeting.broaden
  self + ", world!"
end

greeting.broaden # returns "Hello, world!"

self 是一个关键字，它指的是编译器正在考虑的当前对象，这可能使上述在定义类方法时使用 self 更清晰。事实上，向类 String 添加 hello 方法的示例可以改写为

def String.hello
  "Hello, world!"
end

这样定义的方法称为“单例方法”。broaden 仅存在于字符串实例 greeting 上。其他字符串将没有 broaden。

覆盖¶ ↑

当 Ruby 遇到 def 关键字时，如果方法已经存在，它不会将其视为错误：它只是重新定义它。这称为覆盖。就像扩展核心类一样，这是一种潜在的危险能力，应该谨慎使用，因为它会导致意外的结果。例如，考虑以下 irb 会话

>> "43".to_i
=> 43
>> class String
>>   def to_i
>>     42
>>   end
>> end
=> nil
>> "43".to_i
=> 42

这将有效地破坏任何使用 String#to_i 方法从字符串解析数字的代码。

参数¶ ↑

方法可以接受参数。参数列表位于方法名称之后

def add_one(value)
  value + 1
end

调用时，add_one 方法的用户必须提供一个参数。该参数是方法体中的局部变量。然后，该方法将对该参数加一并返回该值。如果给定 1，该方法将返回 2。

参数周围的括号是可选的

def add_one value
  value + 1
end

在简写方法定义中，括号是必需的

# OK
def add_one(value) = value + 1
# SyntaxError
def add_one value = value + 1

多个参数用逗号分隔

def add_values(a, b)
  a + b
end

调用时，必须按确切的顺序提供参数。换句话说，参数是位置性的。

默认值¶ ↑

参数可以有默认值

def add_values(a, b = 1)
  a + b
end

默认值不需要出现在第一个位置，但带有默认值的实参必须分组在一起。这是可以的

def add_values(a = 1, b = 2, c)
  a + b + c
end

这将引发 SyntaxError

def add_values(a = 1, b, c = 1)
  a + b + c
end

默认实参值可以引用已经作为局部变量求值的实参，并且实参值始终从左到右求值。所以这是允许的

def add_values(a = 1, b = a)
  a + b
end
add_values
# => 2

但这将引发 NameError（除非定义了名为 b 的方法）

def add_values(a = b, b = 1)
  a + b
end
add_values
# NameError (undefined local variable or method `b' for main:Object)

`Array` 分解¶ ↑

您可以使用实参中的额外括号来分解（解包或提取值）Array

def my_method((a, b))
  p a: a, b: b
end

my_method([1, 2])

这将打印

{:a=>1, :b=>2}

如果实参在 Array 中有额外的元素，它们将被忽略

def my_method((a, b))
  p a: a, b: b
end

my_method([1, 2, 3])

这与上面的输出相同。

您可以使用 * 来收集剩余的实参。这将把 Array 分割成第一个元素和其余部分

def my_method((a, *b))
  p a: a, b: b
end

my_method([1, 2, 3])

这将打印

{:a=>1, :b=>[2, 3]}

如果实参响应 to_ary，它将被分解。您应该只在可以使用您的对象代替 Array 时定义 to_ary。

内部括号的使用只使用发送的实参之一。如果实参不是 Array，它将被分配给分解中的第一个实参，而分解中的剩余实参将为 nil

def my_method(a, (b, c), d)
  p a: a, b: b, c: c, d: d
end

my_method(1, 2, 3)

这将打印

{:a=>1, :b=>2, :c=>nil, :d=>3}

您可以任意嵌套分解

def my_method(((a, b), c))
  # ...
end

Array/Hash 实参¶ ↑

在实参前加上 * 会将所有剩余的实参转换为 Array

def gather_arguments(*arguments)
  p arguments
end

gather_arguments 1, 2, 3 # prints [1, 2, 3]

数组实参必须出现在任何关键字实参之前。

可以在开头或中间收集实参

def gather_arguments(first_arg, *middle_arguments, last_arg)
  p middle_arguments
end

gather_arguments 1, 2, 3, 4 # prints [2, 3]

如果调用者在所有位置实参之后提供了关键字，数组实参将捕获 Hash 作为最后一个条目。

def gather_arguments(*arguments)
  p arguments
end

gather_arguments 1, a: 2 # prints [1, {:a=>2}]

但是，只有在方法没有声明任何关键字实参的情况下才会发生这种情况。

def gather_arguments_keyword(*positional, keyword: nil)
 p positional: positional, keyword: keyword
end

gather_arguments_keyword 1, 2, three: 3
#=> raises: unknown keyword: three (ArgumentError)

此外，请注意，可以使用裸 * 来忽略实参

def ignore_arguments(*)
end

您也可以在调用方法时使用裸 * 将实参直接传递给另一个方法

def delegate_arguments(*)
  other_method(*)
end

关键字实参¶ ↑

关键字实参类似于带有默认值的位置实参

def add_values(first: 1, second: 2)
  first + second
end

使用 ** 将接受任意关键字实参

def gather_arguments(first: nil, **rest)
  p first, rest
end

gather_arguments first: 1, second: 2, third: 3
# prints 1 then {:second=>2, :third=>3}

在使用关键字实参调用方法时，实参可以以任何顺序出现。如果调用者发送了未知的关键字实参，并且方法不接受任意关键字实参，则会引发 ArgumentError。

要要求特定的关键字实参，请不要为关键字实参包含默认值

def add_values(first:, second:)
  first + second
end
add_values
# ArgumentError (missing keywords: first, second)
add_values(first: 1, second: 2)
# => 3

在混合关键字实参和位置实参时，所有位置实参必须出现在任何关键字实参之前。

此外，请注意，可以使用 ** 来忽略关键字实参

def ignore_keywords(**)
end

您也可以在调用方法时使用 ** 将关键字实参委托给另一个方法

def delegate_keywords(**)
  other_method(**)
end

要将方法标记为接受关键字，但实际上不接受关键字，可以使用 `**nil`

def no_keywords(**nil)
end

使用关键字或非空关键字 splat 调用此类方法会导致 ArgumentError。支持此语法，以便以后可以将关键字添加到方法中，而不会影响向后兼容性。

如果方法定义不接受任何关键字，并且未使用 `**nil` 语法，则在调用方法时提供的任何关键字将被转换为 Hash 位置参数

def meth(arg)
  arg
end
meth(a: 1)
# => {:a=>1}

块参数¶ ↑

块参数由 `&` 表示，必须放在最后

def my_method(&my_block)
  my_block.call(self)
end

最常见的是，块参数用于将块传递给另一个方法

def each_item(&block)
  @items.each(&block)
end

如果您只是将块传递给另一个方法，则不需要为块命名

def each_item(&)
  @items.each(&)
end

如果您只打算调用块，并且不会以其他方式操作它或将其发送到另一个方法，则建议使用 `yield` 而不使用显式块参数。此方法等效于本节中的第一种方法

def my_method
  yield self
end

参数转发¶ ↑

从 Ruby 2.7 开始，可以使用全参数转发语法

def concrete_method(*positional_args, **keyword_args, &block)
  [positional_args, keyword_args, block]
end

def forwarding_method(...)
  concrete_method(...)
end

forwarding_method(1, b: 2) { puts 3 }
#=>  [[1], {:b=>2}, #<Proc:...skip...>]

仅在使用 `...` 定义的方法中可以使用转发 `...` 调用。

def regular_method(arg, **kwarg)
  concrete_method(...) # Syntax error
end

从 Ruby 3.0 开始，在定义和调用中，`...` 之前可以有前导参数（但在定义中，它们只能是位置参数，没有默认值）。

def request(method, path, **headers)
  puts "#{method.upcase} #{path} #{headers}"
end

def get(...)
  request(:GET, ...) # leading argument in invoking
end

get('https://www.ruby-lang.org.cn', 'Accept' => 'text/html')
# Prints: GET https://www.ruby-lang.org.cn {"Accept"=>"text/html"}

def logged_get(msg, ...) # leading argument in definition
  puts "Invoking #get: #{msg}"
  get(...)
end

logged_get('Ruby site', 'https://www.ruby-lang.org.cn')
# Prints:
#   Invoking #get: Ruby site
#   GET https://www.ruby-lang.org.cn {}

请注意，在转发调用中省略括号可能会导致意外结果

def log(...)
  puts ...  # This would be treated as `puts()...',
            # i.e. endless range from puts result
end

log("test")
# Prints: warning: ... at EOL, should be parenthesized?
# ...and then empty line

`Exception` 处理¶ ↑

方法有一个隐含的异常处理块，因此您不需要使用 `begin` 或 `end` 来处理异常。这

def my_method
  begin
    # code that may raise an exception
  rescue
    # handle exception
  end
end

可以写成

def my_method
  # code that may raise an exception
rescue
  # handle exception
end

类似地，如果您希望即使抛出异常也始终运行代码，可以使用 `ensure` 而不使用 `begin` 和 `end`

def my_method
  # code that may raise an exception
ensure
  # code that runs even if previous code raised an exception
end

您还可以将 `rescue` 与 `ensure` 和/或 `else` 结合使用，而无需 `begin` 和 `end`

def my_method
  # code that may raise an exception
rescue
  # handle exception
else
  # only run if no exception raised above
ensure
  # code that runs even if previous code raised an exception
end

如果您希望仅针对方法的一部分进行异常救援，请使用 `begin` 和 `end`。有关更多详细信息，请参阅有关异常处理的页面。

方法¶ ↑

Method 名称¶ ↑

返回值¶ ↑

范围¶ ↑

覆盖¶ ↑

参数¶ ↑

默认值¶ ↑

Array 分解¶ ↑

Array/Hash 实参¶ ↑

关键字实参¶ ↑

块参数¶ ↑

参数转发¶ ↑

Exception 处理¶ ↑

`Method` 名称¶ ↑

`Array` 分解¶ ↑

`Exception` 处理¶ ↑