README

Dipper 是一个快速的 YAML 解析器，它解析 YAML 1.0 和 1.2 官方规范中更常用的一部分。它根据 BSD 3 条款许可证免费提供给个人或商业项目使用。

理念

当坐下来创建 YAML 解析器时，人们必须质疑自己，因为已经有很多很好的解决方案。有 SPYC，它能够很好地解析 YAML 1.0，Symfony 也有一款解析 YAML 1.2 规范的 YAML 解析器。这两个项目都没有声称完全支持它们分别解析的规范的所有方面（规范很大且很深入），但它们都支持定义功能的大多数子集。

但我们的想法是，我们很少使用这些功能的大部分。也许我们不是 YAML 高级用户，但我们自己主要使用的是与这些库将 PHP 直接转换为 YAML 时使用的相同 YAML 子集。主要是：正常的键/值对（字符串、标量、数字 & 布尔值）、列表和映射。

YAML 设计的一部分是定义一种相对复杂的解析语法，以换取简单（但强大）的格式，以便于人类阅读。我们发现，很多解析复杂性都来自于支持我们实际上使用的简单 YAML 子集之外的功能。

因此，Dipper 应运而生。它是为速度而构建的，微优化以解析我们实际使用的 YAML 部分，而不做更多。

结果

我们进行了一些基准测试，以确保 Dipper 确实很快，因此值得发布，以下是我们的发现。请注意，我们不是科学家，但我们是作为比较的例子。

  Parser    |  YAML->PHP  |  PHP->YAML
------------+-------------+-------------
  SPYC      |    ~22ms    |    ~17ms
  Symfony   |    ~24ms    |    ~12ms
  Dipper    |    ~10ms    |    ~ 3ms

我们将相同的 500 行 YAML 文件通过本文件中描述的每个解析器各 250 次进行测试。然后，我们取每个解析器解析文档的平均时间，以获得 YAML->PHP 时间。接下来，我们将 500 行 YAML 文件解析成 PHP，然后每个解析器将其转换回 YAML 250 次进行测试。转换回 YAML 的平均时间是 PHP->YAML 时间。

正如您从这些时间中看到的，Dipper 在解析 YAML 和将其重建方面都取得了领先。

使用方法

Dipper 执行两个任务：将格式良好的 YAML 转换为 PHP，以及将 PHP 转换为格式良好的 YAML。

// include Dipper and ready it for use
require('Dipper.php');
use secondparty\Dipper\Dipper as Dipper;

// now you can convert YAML into PHP
$php = Dipper::parse($yaml);

// or you can convert PHP into YAML
$yaml = Dipper::make($php);

就是这样。

它可以解析什么

以下是 Dipper 将解析的 YAML 子集的完整列表。

字符串

string: this is a string
single_quoted_string: 'this is a single-quoted string'
double_quoted_string: "this is a double-quoted string"
string_with_single_quote: this's a string with a single quote
string_with_colon: 'this is a string: containing a colon'
string_with_comma: F j, Y
quoted_number: "120"
quoted_true: "true"
quoted_false: "false"
url: http://something.com

标量

literal_scalar: |
  This is a scalar
  that will preserve
  its line breaks.

folding_scalar: >
  This is a scalar
  that will fold up
  line breaks.

数字

integer: 42            # becomes an integer 
float: -12.12          # becomes a float
octal: 0755            # YAML 1.0-style, becomes an integer, converted from octal
also_octal: 0o755      # YAML 1.2-style, becomes an integer, converted from octal
hex: 0xff              # becomes an integer, converted from hexadecimal
infinite: (inf)        # YAML 1.0-style, becomes INF, PHP constant for infinity
minus_inf: (-inf)      # YAML 1.0-style, becomes -INF, PHP constant for negative infinity
not_a_number: (NaN)    # YAML 1.0-style, becomes NAN, PHP constant for not-a-number
also_infinity: .inf    # YAML 1.2-style, becomes INF, PHP constant for infinity
also_minus_inf: -.inf  # YAML 1.2-style, becomes -INF, PHP constant for negative infinity
also_nan: .NaN         # YAML 1.2-style, becomes NAN, PHP constant for not-a-number

布尔值 & 空值

bool_true: true        # becomes true (as a boolean)
bool_false: false      # becomes false (as a boolean)
null_value: null       # becomes a PHP null value
shorthand_null: ~      # becomes a PHP null value
empty_value:           # becomes a PHP null value

列表

regular_list:
  - first item
  - second item
  - third item

shorthand_list: [ first item, second item, third item ]

映射

regular_map:
  one: first
  two: second
  
shorthand_map: { one: first, two: second }

这些组合

除了这些元素中的每一个单独的元素之外，您还可以按预期将它们组合和嵌套，以创建更复杂的结构。列表和映射的简写版本不应嵌套其他列表或映射。

它将创建什么

以下是 Dipper 将从传递给它的 YAML 创建的 PHP 的完整列表。

字符串
整数
浮点数（包括任何浮点常量）
布尔值
空值
空字符串
顺序数组（转换为列表）
关联数组（转换为映射）
对象（如果它们实现了 __toString）

注意事项

与SPYC和Symfony的代码类似，Dipper也支持PHP的syck YAML解析扩展，如果您的服务器已安装并启用，则可以这样做。这会将YAML解析下沉到系统级别，从而实现比直接PHP代码本身快得多得多的解析速度。
除了YAML之外，我们还非常喜欢Markdown。为了更好地支持Markdown，字面量标量不会对每行进行右修剪以删除额外的空白，允许您通过在行尾添加两个空格来定义Markdown样式的换行。

感谢

特别感谢Thomas Weinert，他为将dipper引入composer、travis和phpunit领域做了大量工作。

secondparty / dipper

维护者

详细信息