README

phuph 是一个简单的 PHP 命令行工具，它读取 Markdown 文件并解释 phuph 中的 PHP 代码，允许你编写作为构建部分进行评估的文档。

它是 Rob Norris 的 sbt-tut for Scala 的直接（尽可能直接）移植。

它只是 PHP，通过评估文档中的 PHP 生成 PHP 文档。而单子是内射函子范畴中的幺半群。

安装和使用

composer g require beezee/phuph

确保 ~/.composer/vendor/bin 在你的 PATH 中。

这允许你使用 phuph 命令针对特别格式化的 Markdown 文件进行文档生成。如果你的 Markdown 在文件 README.phuph 中，你会运行

phuph README.phuph > README.MD

来生成一个评估版本，其中代码块的输出与它们的定义交织在一起。

示例

给定以下文件 README.phuph

##### This is an example

Here is some regular markdown content

```phuph

function example($i) {
  return ['foo' => (1 * $i), 'bar' => (2 * $i)];
}

repl{ example(7); }

repl{ example(9); }
phuph```

And here's the end

phuph README.phuph 会输出以下内容

#### This is an example

Here is some regular markdown content

```php

function example($i) {
  return ['foo' => (1 * $i), 'bar' => (2 * $i)];
}

php>  example(7); 
/* Array
(
    [foo] => 7
    [bar] => 14
)
 */

php>  example(9); 
/* Array
(
    [foo] => 9
    [bar] => 18
)
 */
```

And here's the end

如下所示。

这是一个示例

这里是些常规 Markdown 内容

function example($i) {
  return ['foo' => (1 * $i), 'bar' => (2 * $i)];
}

php>  example(7); 
/* Array
(
    [foo] => 7
    [bar] => 14
)
 */

php>  example(9); 
/* Array
(
    [foo] => 9
    [bar] => 18
)
 */

这里是结束

基本用法

phuph 块

phuph 块内的代码将被静默评估，代码将以 PHP 语法高亮的形式打印出来。例如

```phuph
function print_and_return($i) {
  echo $i;
  return $i;
}

print_and_return(3);
phuph```

上面的代码将不会输出 3，但代码将以 PHP 语法高亮的形式打印出来，并且函数 print_and_return 将可以在后面的 repl 表达式中使用，如下所示。

来自不同 phuph 块的上下文是共享的，因此定义在早期块中的函数和类可以在后面的块中使用。

repl 表达式

在一个 phuph 块内，可以使用 repl 表达式立即包含评估表达式的结果。例如，给定上面定义的函数 print_and_return，以下

```phuph
repl{ print_and_return(3); }
phuph```

将输出如下

php>  print_and_return(3); 
/* 3 */

repl 表达式 必须 是单个表达式，并且 必须 有可返回的值。这是由于 PHP 的 eval 函数的行为。repl 表达式内的内容必须用于形成返回语句，然后再进行评估，以便捕获结果值并将其包含在输出中。

修饰符

除了基本的 phuph 块外，还有两种变体。

• plaincode - 用于在内容区域中转义所有 phuph 操作符
• phuphsilent - 用于评估 PHP 供后续 phuph 块使用，而不显示评估的代码

除了 repl 表达式外，还有一个变体。

• escape - 用于在 phuph 块内替代 repl 以包含应显示但未评估的代码。

以上所有内容的示例可以在 用于生成此 README 的文件 中找到

贡献

如果你从 phuph 中获得了价值，那太棒了。我知道 Scala 版本对我来说一直是主食，虽然功能一致性并不是我特别关注的事情，但这里有很多功能允许我使用 phuph 生成自己的文档。这比我预期的要复杂一些。

编码风格高度功能化，没有太多仪式。这意味着修复和功能添加通常只需要少量代码更改即可实现，但找到正确的代码进行更改需要仔细思考。这是故意为之。

话虽如此，欢迎 pull requests 和 issues。