README

Hoa 是一套 模块化、可扩展 和 结构化 的 PHP 库。
此外，Hoa 旨在成为工业界和研究界之间的桥梁。

Hoa\Option

此库是实现著名的 Option 多态类型（也称为 Maybe）。Option 表示一个可选值，要么有 Some 值，要么有 None，它是 null 的等价物。这是一种方便且安全地处理可选值的方法。

了解更多.

安装

使用 Composer，要将此库包含到依赖项中，您需要要求 hoa/option

$ composer require hoa/option '~1.0'

有关更多安装说明，请参阅 源代码页面。

测试

在运行测试套件之前，必须安装开发依赖项

$ composer install

然后，要运行所有测试套件

$ vendor/bin/hoa test:run

有关更多信息，请参阅 贡献者指南。

快速使用

以下示例说明了如何使用 Hoa\Option\Option 类。

构建一个可选值

有两个静态方法用于分配一个可选值

• Hoa\Option\Option::some($value) 用于一些值，
• Hoa\Option\Option::none() 用于无值。

存在两个函数别名，分别是

• Hoa\Option\Some($value)，和
• Hoa\Option\None().

在接下来的示例中，假设已经声明了 use function Hoa\Option\{Some, None}，因此我们可以直接使用 Some 和 None。

基本操作

isSome 和 isNone 方法分别返回 true，如果选项包含一些值或无值

$x = Some(42);
$y = None();

assert($x->isSome());
assert($y->isNone());

unwrap 方法如果存在一些值，则返回包含的值，如果不存在，则抛出 RuntimeException

assert(Some(42)->unwrap() === 42);
assert(None()->unwrap()); // will throw a `RuntimeException`.

通常，由于意外的异常，不鼓励使用。最好使用：例如，expect、unwrapOr、isSome 或 isNone。

一个常见的错误是认为需要从选项中提取/展开值。实际上，Hoa\Option\Option API 设计为始终操作一个选项，而无需提取其包含的值。可以构建或映射新的选项，请参阅下一节。

unwrap 方法可以抛出一个具有默认消息的 RuntimeException。要使用自定义消息，请使用 expect 方法

$x = None();

assert($x->expect('Damn…') === 42);

unwrapOr 方法在包含值存在时返回该值，不存在时返回默认值。

$x = Some(42);
$y = None();

assert($x->unwrapOr(153) === 42);
assert($y->unwrapOr(153) === 153);

unwrapOrElse 方法在包含值存在时返回该值，不存在时从给定的可调用对象中计算默认值。

$x = Some(42);
$y = None();

$else = function (): int { return 153; };

assert($x->unwrapOrElse($else) === 42);
assert($y->unwrapOrElse($else) === 153);

映射器

映射器通过将可调用对象应用于包含的值（如果有的话）将选项转换为另一个选项。

$x = Some('Hello, World!');
$y = None();

assert($x->map('strlen') == Some(13));
assert($x->map('strlen') == None());

mapOr 映射器将选项转换为另一个选项，但没有包含值时使用默认值。

$x = None();

assert($x->mapOr('strlen', 0) == Some(0));

mapOr 的结果始终是一个包含值的选项。

mapOrElse 映射器类似于 mapOr，但它从可调用对象中计算默认值。

$x    = None();
$else = function (): int { return 0; };

assert($x->mapOrElse('strlen', $else) == Some(0));

布尔运算

可以对选项应用布尔运算。如果当前选项没有值，则 and 方法返回一个空选项，否则返回右侧的选项。

assert(Some(42)->and(Some(153)) == Some(153));
assert(Some(42)->and(None())    == None());
assert(None()->and(Some(153))   == None());

andThen 方法如果当前选项没有值，则返回一个空选项，否则返回由可调用对象计算的新选项。某些语言将此操作称为 flatmap。

$square = function (int $x): Option {
    return Some($x * $x);
};
$nop = function (): Option {
    return None();
};

assert(Some(2)->andThen($square)->andThen($square) == Some(16));
assert(Some(2)->andThen($nop)->andThen($square)    == None());

or 方法如果当前选项有值，则返回当前选项，否则返回右侧的选项。

assert(Some(42)->or(Some(153)) == Some(42));
assert(None()->or(Some(153))   == Some(153));

最后，orElse 选项如果当前选项有值，则返回该选项，否则返回由可调用对象计算的新选项。

$somebody = function (): Option {
    return Some('somebody');
};

assert(None()->orElse($somebody) == Some('somebody'));

文档

在 hack book of Hoa\Option 中包含有关如何使用此库及其工作原理的详细信息。

要本地生成文档，请执行以下命令：

$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open

更多文档可以在项目的网站上找到： hoa-project.net。

获取帮助

主要有两种方式获取帮助：

• 在 #hoaproject IRC 频道中，
• 在 users.hoa-project.net 的论坛上。

贡献

你想贡献力量吗？谢谢！详细的 贡献指南 解释了你需要知道的一切。

许可

Hoa 采用新 BSD 许可证（BSD-3-Clause）。请参阅 LICENSE 了解详细信息。