Hooks 项目技术文档

1. 安装指南

1.1 使用 Gemfile 安装

在项目的 Gemfile 中添加以下内容：

gem "hooks"

然后运行以下命令安装：

bundle install

1.2 手动安装

你也可以直接通过 RubyGems 安装：

gem install hooks

2. 项目使用说明

2.1 基本概念

Hooks 是一个用于 Ruby 的通用钩子库，允许你在类中声明性地定义钩子。你可以为钩子添加回调，当钩子被触发时，回调将会被执行。

2.2 示例

以下是一个简单的示例，展示了如何在类中定义钩子并添加回调：

require 'hooks'

class Cat
  include Hooks

  define_hooks :before_dinner, :after_dinner

  before_dinner :wash_paws

  after_dinner do
    puts "Ice cream for #{self}!"
  end

  after_dinner :have_a_dessert

  def have_a_dessert
    puts "Hell, yeah!"
  end

  def wash_paws
    puts "Washing paws..."
  end
end

cat = Cat.new
cat.run_hook :before_dinner
cat.run_hook :after_dinner

输出结果：

Washing paws...
Ice cream for #<Cat:0x00007f8b1c0aeb80>!
Hell, yeah!

2.3 继承钩子

钩子可以被继承。子类可以定义自己的钩子回调，并且会继承父类的钩子回调。

class Garfield < Cat
  after_dinner :want_some_more

  def want_some_more
    puts "Is that all?"
  end
end

garfield = Garfield.new
garfield.run_hook :after_dinner

输出结果：

Ice cream for #<Cat:0x00007f8b1c0aeb80>!
Hell, yeah!
Is that all?

2.4 传递参数

你可以向 run_hook 方法传递参数，这些参数将会传递给回调函数。

cat.run_hook :before_dinner, cat, Time.now

回调函数需要准备好接收这些参数：

before_dinner do |who, when|
  puts "Washing #{who}'s paws at #{when}"
end

2.5 停止钩子执行

你可以使用 :halts_on_falsey 选项来在回调返回 nil 或 false 时停止钩子的执行。

class Garfield
  include Hooks
  define_hook :after_dark, halts_on_falsey: true

  after_dark { "Chase mice" }
  after_dark { nil }
  after_dark { "Enjoy supper" }
end

result = Garfield.new.run_hook :after_dark
puts result.halted? #=> true

3. 项目API使用文档

3.1 define_hooks

用于定义钩子。可以定义多个钩子，钩子名称作为参数传递。

define_hooks :before_dinner, :after_dinner

3.2 run_hook

用于触发钩子，执行所有注册的回调。

cat.run_hook :after_dinner

3.3 before_dinner 和 after_dinner

用于为钩子添加回调。可以是一个方法名或一个块。

before_dinner :wash_paws
after_dinner do
  puts "Ice cream for #{self}!"
end

3.4 :halts_on_falsey 选项

用于在回调返回 nil 或 false 时停止钩子的执行。

define_hook :after_dark, halts_on_falsey: true

3.5 :scope 选项

用于指定回调的执行上下文。

define_hook :before_lunch, scope: lambda { |callback, scope| Logger }

4. 项目安装方式

4.1 使用 Gemfile

在 Gemfile 中添加：

gem "hooks"

然后运行：

bundle install

4.2 手动安装

通过 RubyGems 安装：

gem install hooks

通过以上步骤，你可以成功安装并使用 Hooks 项目。