Forem: Samuel Su

【译】用 Rust 实现 csv 解析-part6

Samuel Su — Sun, 24 Jan 2021 09:19:03 +0000

Rust and CSV parsing 译文（用 Rust 实现 csv 解析-part6）

原文链接：https://blog.burntsushi.net/csv/

原文作者：BurntSushi

译文来自：https://github.com/suhanyujie/article-transfer-rs/

译者：suhanyujie

译者博客：suhanyujie

ps：水平有限，翻译不当之处，还请指正。

标签：Rust，csv

写入 tab 分隔符的值

在前面的章节中，我们了解了如何将 CSV 数据输出到标准输出中，如下：

City,State,Population,Latitude,Longitude
Davidsons Landing,AK,,65.2419444,-165.2716667
Kenai,AK,7610,60.5544444,-151.2583333
Oakman,AL,,33.7133333,-87.3886111

你可能会想：如果都是这么简单地数据，那使用 CSV writer 还有什么意义？CSV writer 的好处是，它能处理所有类型的数据，而不会牺牲数据的完整性。也就是说，它知道何时引用包含特殊 CSV 字符的字段（如逗号或者换行），或在数据中出现的转义字面量引号。CSV writer 还可以方便地配置使用不同地分隔符或引用策略。

在这一节中，我们将看看如何调整 CSV writer 上的设置。特别地，我们将使用 TSV（“制表符分割值”）来替代 CSV，并且我们要求 CSV writer 引用所有非数字字段。这里有一个例子：

fn run() -> Result<(), Box<Error>> {
    let mut wtr = csv::WriterBuilder::new()
        .delimiter(b'\t')
        .quote_style(csv::QuoteStyle::NonNumeric)
        .from_writer(io::stdout());

    wtr.write_record(&["City", "State", "Population", "Latitude", "Longitude"])?;
    wtr.write_record(&["Davidsons Landing", "AK", "", "65.2419444", "-165.2716667"])?;
    wtr.write_record(&["Kenai", "AK", "7610", "60.5544444", "-151.2583333"])?;
    wtr.write_record(&["Oakman", "AL", "", "33.7133333", "-87.3886111"])?;

    wtr.flush()?;
    Ok(())
}

编译并运行这个例子：

$ cargo build
$ ./target/debug/csvtutor
"City"  "State" "Population"    "Latitude"      "Longitude"
"Davidsons Landing"     "AK"    ""      65.2419444      -165.2716667
"Kenai" "AK"    7610    60.5544444      -151.2583333
"Oakman"        "AL"    ""      33.7133333      -87.3886111

在本例中，我们使用了一个新类型 QuoteStyle 。QuoteStyle 类型表示你可以使用不同的引用策略。默认情况下，只在必要时才向字段值周围添加引号。这可能适用于大多数例子，但你也可以一直在字段两边添加引号，或不添加引号，或者只在非数字两边加引号。

使用 Serde 写入

正如 CSV reader 支持将数据自动反序列化为 Rust 类型数据一样，CSV writer 也支持那样使用 Serde 将 Rust 类型数据序列化为 CSV 记录数据。在本节中，我们就学习怎么使用它。

与读一样，我们先看看如何序列化一个 Rust 元组。

fn run() -> Result<(), Box<Error>> {
    let mut wtr = csv::Writer::from_writer(io::stdout());

    // 我们仍然需要手动地写入头部
    wtr.write_record(&["City", "State", "Population", "Latitude", "Longitude"])?;

    // 但现在我们可以通过提供的常用的 Rust 值，写入记录。
    //
    // 注意，奇数列的 `None::<u64>` 预发是必须的，因为 `None` 本身没有具体的类型，但 Serde 需要一个具体的类型以便进行序列化。也就是说，`None` 的类型 `Option<T>`，而 `None::<u64>` 的类型是 `Option<u64>`。
    wtr.serialize(("Davidsons Landing", "AK", None::<u64>, 65.2419444, -165.2716667))?;
    wtr.serialize(("Kenai", "AK", Some(7610), 60.5544444, -151.2583333))?;
    wtr.serialize(("Oakman", "AL", None::<u64>, 33.7133333, -87.3886111))?;

    wtr.flush()?;
    Ok(())
}

编译并运行这个程序，期望的输出如下：

$ cargo build
$ ./target/debug/csvtutor
City,State,Population,Latitude,Longitude
Davidsons Landing,AK,,65.2419444,-165.2716667
Kenai,AK,7610,60.5544444,-151.2583333
Oakman,AL,,33.7133333,-87.3886111

在上面的例子中，需要注意的关键点是，使用 serialize 而不是 write_record 进行写入数据。特别地，write_record 在写入仅包含字符串数据的简单记录时使用。另一方面，当数据包含更复杂的值时，如数字、浮点数、可选值时，则使用 serialize。当然，你总是可以将复杂的值转为字符串，然后再使用 write_record 统一写入，但 Serde 可以为你自动的完成上面那些繁琐的工作。

和读一样，我们也可以将自定义结构序列化为 CSV 记录。这样的好处是，结构体中的字段将被识别为头记录。

要将自定义结构写入 CSV 记录，我们需要再次使用 serde_derive crate。正如前面章节的使用 Serde 读取数据所述，我们需要在我们的 Cargo.toml 中的 [dependencies] 区块下加上两个 crate 依赖声明（如果没有就加上）。

serde = "1"
serde_derive = "1"

我们还需要在代码中加上两行外部库的引入代码 extern crate ，如下方所示：

extern crate csv;
extern crate serde;
 #[macro_use]
extern crate serde_derive;

use std::error::Error;
use std::io;
use std::process;

// 记住结构体可以派生两个 trait：Serialize 和 Deserialize！
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "PascalCase")]
struct Record<'a> {
    city: &'a str,
    state: &'a str,
    population: Option<u64>,
    latitude: f64,
    longitude: f64,
}

fn run() -> Result<(), Box<Error>> {
    let mut wtr = csv::Writer::from_writer(io::stdout());

    wtr.serialize(Record {
        city: "Davidsons Landing",
        state: "AK",
        population: None,
        latitude: 65.2419444,
        longitude: -165.2716667,
    })?;
    wtr.serialize(Record {
        city: "Kenai",
        state: "AK",
        population: Some(7610),
        latitude: 60.5544444,
        longitude: -151.2583333,
    })?;
    wtr.serialize(Record {
        city: "Oakman",
        state: "AL",
        population: None,
        latitude: 33.7133333,
        longitude: -87.3886111,
    })?;

    wtr.flush()?;
    Ok(())
}

fn main() {
    if let Err(err) = run() {
        println!("{}", err);
        process::exit(1);
    }
}

编译并运行这个示例，虽然我们没有显式地写入头部，但输出和上次是一样的。

$ cargo build
$ ./target/debug/csvtutor
City,State,Population,Latitude,Longitude
Davidsons Landing,AK,,65.2419444,-165.2716667
Kenai,AK,7610,60.5544444,-151.2583333
Oakman,AL,,33.7133333,-87.3886111

在这个例子中，可以看到，serialize 方法上被标记上了一个结构体字段名。这样做的话，serialize 将自动写入一个头部（只要其他记录尚未写入），该记录的结构体的字段是按照他们定义的顺序组成。请注意，可以通过 WriterBuilder::has_headers 方法将此行为禁用。

同样值得指出的是，在 Record 结构体中使用了一个生命周期参数：

struct Record<'a> {
    city: &'a str,
    state: &'a str,
    population: Option<u64>,
    latitude: f64,
    longitude: f64,
}

'a 声明周期参数对应于 city 和 state 字符串切片的生命周期。这表示 Record 结构体包含了借用的数据。我们本可以在不借用任何数据的情况下编写结构体，这时也就不需要生命周期参数了：

struct Record {
    city: String,
    state: String,
    population: Option<u64>,
    latitude: f64,
    longitude: f64,
}

然而，由于我们使用 String 类型替换 &str 类型，我们现在被迫为我们所写的每条记录中的 city 和 state 分配一个新的 String 值。这样做本身没有问题，但会有点性能浪费。

关于序列化的更多示例和详细信息，可以参考 Writer::serialize 方法。

Pipelining

待续...

【译】从 Rust 到不只是 Rust：PHP 语言领域

Samuel Su — Wed, 21 Aug 2019 04:23:13 +0000

From Rust to beyond: The PHP galaxy 译文

原文地址：https://mnt.io/2018/10/29/from-rust-to-beyond-the-php-galaxy/

原文仓库：https://github.com/Hywan/gutenberg-parser-rs/tree/master/bindings/

原文作者：Ivan Enderlin

译文出自：https://github.com/suhanyujie/article-transfer-rs

本文永久链接：https://github.com/suhanyujie/article-transfer-rs/blob/master/src/2019/From-Rust-to-beyond-The-PHP-galaxy.md

译者：suhanyujie

翻译不当之处，还请指出，谢谢！

tags：用 Rust 为 PHP 开发扩展；用 Rust 为 PHP 助力

这篇博客文章是“如何将 Rust 传播到其他语言领域”系列文章之一。Rust 完成进度：

前言,
WebAssembly 领域,
ASM.js 领域,
C 领域,
PHP 领域 (当前章节)，以及
NodeJS 领域

我们今天探索的领域是 PHP 领域。这个文章解释了什么是 PHP，如何将 Rust 程序编译成 C 再转换成 PHP 原生扩展。

PHP 是什么？为什么是它？

PHP 是:

受欢迎的通用脚本语言，尤其是在 web 开发领域。从个人博客到世界上最流行的网站，PHP 提供了快速、灵活并且实用的功能。

令人遗憾的是，PHP 近年来名声不佳，但是最近的发行版（从 PHP 7.0 开始）引入了许多简洁的语言特性，这些特性令人喜爱。PHP 也是一种快速脚本语言，并且非常灵活。PHP 现在已经具备了类型、性征、可变参数、闭包（带有显式范围）、生成器和强大的向后兼容特性。PHP 的开发由 RFCs 领导，整个过程是开放和民主的。Gutenberg 项目是 WordPress 的新编辑器。WordPress 是用 PHP 编写的。很自然的，我们需要一个 PHP 的本地扩展来解析 Gutenberg 文章格式。PHP 是一种具有规范的语言。其最流行的虚拟机是 Zend Engine，还有一些其他虚拟机，比如 HHVM（但 HHVM 最近已经放弃对 PHP 的支持，转而支持他们团队自己的 PHP 分支，也称为 Hack），Peachpie 或 Tagua VM（正在开发中）。在本文中，我们将为 Zend Engine 创建一个扩展。这个虚拟机是 C 语言编写的。恰好跟之前的一篇文章 C 系列相契合。

Rust 🚀 C 🚀 PHP

要将 Rust 解析器移植到 PHP 中，我们首先需要将它移植到 C。这在上一篇文章中已经实现了。从这一端到 C 有两个文件：libgutenberg_post_parser.a 和 gutenberg_post_parser.h，分别是静态库和头文件。

使用脚手架引导

PHP 源码中自带了一个创建扩展的脚手架/模板，是 ext_skel.php。这个脚本可以从 Zend Engine 虚拟机的源代码z中找到。可以这样使用它：

$ cd php-src/ext/
$ ./ext_skel.php \
      --ext gutenberg_post_parser \
      --author 'Ivan Enderlin' \
      --dir /path/to/extension \
      --onlyunix
$ cd /path/to/extension
$ ls gutenberg_post_parser
tests/
.gitignore
CREDITS
config.m4
gutenberg_post_parser.c
php_gutenberg_post_parser.h

ext_skel.php 脚本建议以如下步骤使用：
- 重新构建 PHP 源码配置（在 php-src 根目录下运行 ./buildconf），
- 重新配置构建系统以启用扩展，如 ./configure --enable-gutenberg_post_parser，
- 使用 make 构建
- 完成

但是我们的扩展很可能位于 php-src 以外的目录。所以我们使用 phpize。phpize 跟 php、php-cgi、phpdbg、php-config 等类似，是一个可执行文件。它让我们根据已编译的 php 二进制文件去编译扩展，这很符合我们的例子。我们像下面这样使用它：

$ cd /path/to/extension/gutenberg_post_parser

$ # Get the bin directory for PHP utilities.
$ PHP_PREFIX_BIN=$(php-config --prefix)/bin

$ # Clean (except if it is the first run).
$ $PHP_PREFIX_BIN/phpize --clean

$ # “phpize” the extension.
$ $PHP_PREFIX_BIN/phpize

$ # Configure the extension for a particular PHP version.
$ ./configure --with-php-config=$PHP_PREFIX_BIN/php-config

$ # Compile.
$ make install

在这篇文章中，我们将不再展示相关的代码修改，而是将重点放在扩展绑定上。所有的相关源码可以在这里找到，简单的说，这是 config.m4 文件的配置:

PHP_ARG_ENABLE(gutenberg_post_parser, whether to enable gutenberg_post_parser support,
[  --with-gutenberg_post_parser          Include gutenberg_post_parser support], no)

if  test "$PHP_GUTENBERG_POST_PARSER" != "no"; then
  PHP_SUBST(GUTENBERG_POST_PARSER_SHARED_LIBADD)

  PHP_ADD_LIBRARY_WITH_PATH(gutenberg_post_parser, ., GUTENBERG_POST_PARSER_SHARED_LIBADD)

  PHP_NEW_EXTENSION(gutenberg_post_parser, gutenberg_post_parser.c, $ext_shared)
fi

它的作用主要有以下这些：
- 在构建系统中注册 --with-gutenberg_post_parser 选项，并且
- 声明要编译的静态库以及扩展源代码。

我么必须在同一级目录（链接符号是可用的）下添加 libgutenberg_post_parser.a 和 gutenberg_post_parser.h 文件，然后可以得到如下的目录结构：

$ ls gutenberg_post_parser
tests/                       # from ext_skel
.gitignore                   # from ext_skel
CREDITS                      # from ext_skel
config.m4                    # from ext_skel (edited)
gutenberg_post_parser.c      # from ext_skel (will be edited)
gutenberg_post_parser.h      # from Rust
libgutenberg_post_parser.a   # from Rust
php_gutenberg_post_parser.h  # from ext_skel

扩展的核心是 gutenberg_post_parser.c 文件。这个文件负责创建模块，并且将 Rust 代码绑定到 PHP。

模块即扩展

如前所述，我们将在 gutenberg_post_parser.c 中实现我们的逻辑。首先，引入所需要的文件：

#include "php.h"
#include "ext/standard/info.h"
#include "php_gutenberg_post_parser.h"
#include "gutenberg_post_parser.h"

最后一行引入的 gutenberg_post_parser.h 文件由 Rust 生成（准确的说是 cbindgen 生成的，如果你不记得，阅读上一篇文章）。接着，我们必须决定好向 PHP 暴露的 API，Rust 解析器生成的 AST 定义如下：

pub enum Node<'a> {
    Block {
        name: (Input<'a>, Input<'a>),
        attributes: Option<Input<'a>>,
        children: Vec<Node<'a>>
    },
    Phrase(Input<'a>)
}

AST 的 C 变体与上方的版本是类似的（具有很多结构，但思路几乎相同）。所以在 PHP 中，选择如下结构：

class Gutenberg_Parser_Block {
    public string $namespace;
    public string $name;
    public string $attributes;
    public array $children;
}

class Gutenberg_Parser_Phrase {
    public string $content;
}

function gutenberg_post_parse(string $gutenberg_post): array;

gutenberg_post_parse 函数输出一个对象数组，对象类型是 gutenberg_post_parse 或 Gutenberg_Parser_Phrase，也就是我们的 AST。我们需要声明这些类。

类的声明

注意：后面的 4 个代码块不是本文的核心，它只是需要编写的代码，如果你不打算编写 PHP 扩展，可以跳过它

zend_class_entry *gutenberg_parser_block_class_entry;
zend_class_entry *gutenberg_parser_phrase_class_entry;
zend_object_handlers gutenberg_parser_node_class_entry_handlers;

typedef struct _gutenberg_parser_node {
    zend_object zobj;
} gutenberg_parser_node;

一个 class entry 代表一个特定的类型。并会有对应的处理程序与 class entry 相关联。逻辑有些复杂。如果你想了解更多内容，我建议你阅读 PHP Internals Book。接着，我们创建一个函数来实例化这些对象：

static zend_object *create_parser_node_object(zend_class_entry *class_entry)
{
    gutenberg_parser_node *gutenberg_parser_node_object;

    gutenberg_parser_node_object = ecalloc(1, sizeof(*gutenberg_parser_node_object) + zend_object_properties_size(class_entry));

    zend_object_std_init(&gutenberg_parser_node_object->zobj, class_entry);
    object_properties_init(&gutenberg_parser_node_object->zobj, class_entry);

    gutenberg_parser_node_object->zobj.handlers = &gutenberg_parser_node_class_entry_handlers;

    return &gutenberg_parser_node_object->zobj;
}

然后，我们创建一个函数来释放这些对象。它的工作有两步：调用对象的析构函数（在用户态）来析构对象，然后将其释放（在虚拟机中）：

static void destroy_parser_node_object(zend_object *gutenberg_parser_node_object)
{
    zend_objects_destroy_object(gutenberg_parser_node_object);
}

static void free_parser_node_object(zend_object *gutenberg_parser_node_object)
{
    zend_object_std_dtor(gutenberg_parser_node_object);
}

然后，我们初始化这个“模块”，也就是扩展。在初始化过程中，我们将在用户空间中创建类，并声明它的属性等。

PHP_MINIT_FUNCTION(gutenberg_post_parser)
{
    zend_class_entry class_entry;

    // 声明 Gutenberg_Parser_Block.
    INIT_CLASS_ENTRY(class_entry, "Gutenberg_Parser_Block", NULL);
    gutenberg_parser_block_class_entry = zend_register_internal_class(&class_entry TSRMLS_CC);

    // 声明 create handler.
    gutenberg_parser_block_class_entry->create_object = create_parser_node_object;

    // 类是 final 的（不能被继承）
    gutenberg_parser_block_class_entry->ce_flags |= ZEND_ACC_FINAL;

    // 使用空字符串作为默认值声明 `namespace` 公共属性,
    zend_declare_property_string(gutenberg_parser_block_class_entry, "namespace", sizeof("namespace") - 1, "", ZEND_ACC_PUBLIC);

    // 使用空字符串作为默认值声明 `name` 公共属性
    zend_declare_property_string(gutenberg_parser_block_class_entry, "name", sizeof("name") - 1, "", ZEND_ACC_PUBLIC);

    // 使用 `NULL` 作为默认值声明 `attributes` 公共属性
    zend_declare_property_null(gutenberg_parser_block_class_entry, "attributes", sizeof("attributes") - 1, ZEND_ACC_PUBLIC);

    // 使用 `NULL` 作为默认值，声明 `children` 公共属性
    zend_declare_property_null(gutenberg_parser_block_class_entry, "children", sizeof("children") - 1, ZEND_ACC_PUBLIC);

    // 声明 Gutenberg_Parser_Block.

    … 略 …

    // 声明 Gutenberg 解析器节点对象 handler

    memcpy(&gutenberg_parser_node_class_entry_handlers, zend_get_std_object_handlers(), sizeof(gutenberg_parser_node_class_entry_handlers));

    gutenberg_parser_node_class_entry_handlers.offset = XtOffsetOf(gutenberg_parser_node, zobj);
    gutenberg_parser_node_class_entry_handlers.dtor_obj = destroy_parser_node_object;
    gutenberg_parser_node_class_entry_handlers.free_obj = free_parser_node_object;

    return SUCCESS;
}

如果你还在阅读，首先我表示感谢，其次，恭喜！接着，代码中有 PHP_RINIT_FUNCTION 和 PHP_MINFO_FUNCTION 函数，它们是由 ext_skel.php 脚本生成的。模块条目信息和模块配置也是这样生成的。

`gutenberg_post_parse` 函数

现在我们将重点介绍 gutenberg_post_parse 函数。该函数接收一个字符串作为参数，如果解析失败，则返回 false，否则返回类型为 Gutenberg_Parser_Block 或 Gutenberg_Parser_Phrase 的对象数组。我们开始编写它！注意它是由 PHP_FUNCTION 宏声明的.

PHP_FUNCTION(gutenberg_post_parse)
{
    char *input;
    size_t input_len;

    // 将 input 作为字符串读入
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &input, &input_len) == FAILURE) {
        return;
    }

在这个步骤中，参数已经作为字符串（"s"）被声明和引入了。字符串值在 input 中，字符串长度存储在 input_len。下一步就是解析 input。（实际上不需要字符串长度）。这就是我们要调用 Rust 代码的地方！我们可以这样做：

    // 解析 input
    Result parser_result = parse(input);

    // 如果解析失败，则返回 false.
    if (parser_result.tag == Err) {
        RETURN_FALSE;
    }

    // 否则将 Rust 的 AST 映射到 PHP 的数组中
    const Vector_Node nodes = parse_result.ok._0;

Result 类型和 parse 函数来自 Rust 中。如果你不记得这些类型，可以阅读前一篇关于 C 领域的文章。Zend Engine 有一个 RETURN_FALSE 宏，用于返回 false！很方便是吗？最后，如果顺利，我们将得到 Vector_Node 类型的节点集合。下一步是将它们映射到 PHP 类型中，如 Gutenberg 类型的数组。我们开始干吧：

    // 注意：return_value 是一个"魔术"变量，它用于存放返回值
    //
    // 分配一个数组空间
    array_init_size(return_value, nodes.length);

    // 映射 Rust AST
    into_php_objects(return_value, &nodes);
}

完事了 😁！噢，等等 …… 还要实现 into_php_objects函数！

`into_php_objects` 函数

这个函数并不复杂：只是它是通过 Zend Engine 的 API 实现。我们会向勤奋的读者阐释如何将 Block 映射为 Gutenberg_Parser_Block 对象，以及让 Phrase 映射为 Gutenberg_Parser_Phrase。我们开始吧：

void into_php_objects(zval *php_array, const Vector_Node *nodes)
{
    const uintptr_t number_of_nodes = nodes->length;

    if (number_of_nodes == 0) {
        return;
    }

    // 遍历所有节点
    for (uintptr_t nth = 0; nth < number_of_nodes; ++nth) {
        const Node node = nodes->buffer[nth];

        if (node.tag == Block) {
            // 将 Block 映射为 Gutenberg_Parser_Block
        } else if (node.tag == Phrase) {
            // 将 Phrase 映射为 Gutenberg_Parser_Phrase
        }
    }
}

现在，我们开始实现映射一个内存区块（以下简称块）。主要过程如下:

为块名称空间和块名称分配 PHP 字符串，
分配对象,
将块名称空间和块名称设定为各自的独享属性
为块属性分配一个 PHP 字符串
把块属性设定为对应的对象属性
如果有子节点，初始化一个数组，并使用子节点和新数组调用 into_php_objects
把子节点设定为对应的对象属性
最后，在返回的数组中添加块对象

const Block_Body block = node.block;
zval php_block, php_block_namespace, php_block_name;

// 1. 准备 PHP 字符串
ZVAL_STRINGL(&php_block_namespace, block.namespace.pointer, block.namespace.length);
ZVAL_STRINGL(&php_block_name, block.name.pointer, block.name.length);

你还记得名称空间、名称和其他类似数据的类型是 Slice_c_char 吗？它就是一个带有指针和长度的结构体。指针指向原始的输入字符串，因此没有副本（这其实是 slice 的定义）。好了，Zend Engine 中有名为 ZVAL_STRINGL 的宏，它的功能是通过“指针”和“长度”创建字符串，很棒！可不幸的是，Zend Engine 在底层做了拷贝…… 没有办法只保留指针和长度，但是它保证拷贝的数量很小。我想应该为了获取数据的全部所有权，这是垃圾回收所必需的。

// 2. 创建 Gutenberg_Parser_Block 对象
object_init_ex(&php_block, gutenberg_parser_block_class_entry);

使用 gutenberg_parser_block_class_entry 所代表的类实例化对象。

// 3. 设定命名空间和名称
add_property_zval(&php_block, "namespace", &php_block_namespace);
add_property_zval(&php_block, "name", &php_block_name);

zval_ptr_dtor(&php_block_namespace);
zval_ptr_dtor(&php_block_name);

zval_ptr_dtor 的作用是给引用计数加 1。便于垃圾回收。

// 4. 处理一些内存块属性
if (block.attributes.tag == Some) {
    Slice_c_char attributes = block.attributes.some._0;
    zval php_block_attributes;

    ZVAL_STRINGL(&php_block_attributes, attributes.pointer, attributes.length);

    // 5. 设置属性
    add_property_zval(&php_block, "attributes", &php_block_attributes);

    zval_ptr_dtor(&php_block_attributes);
}

它类似于 namespace 和 name 所做的。现在我们继续讨论 children。

// 6. 处理子节点
const Vector_Node *children = (const Vector_Node*) (block.children);

if (children->length > 0) {
    zval php_children_array;

    array_init_size(&php_children_array, children->length);

    // 递归
    into_php_objects(&php_children_array, children);

    // 7. 设置 children
    add_property_zval(&php_block, "children", &php_children_array);

    Z_DELREF(php_children_array);
}

free((void*) children);

最后，将块实例增加到返回的数组中：

// 8. 在集合中加入对象
add_next_index_zval(php_array, &php_block);

完整代码点此查看

PHP 扩展 🚀 PHP 用户态

现在扩展写好了，我们必须编译它。可以直接重复前面提到的使用 phpize 等展示的命令集。一旦扩展被编译，就会在本地的扩展存放目录中生成 generated gutenberg_post_parser.so 文件。使用以下命令可以找到该目录：

$ php-config --extension-dir

例如，在我的计算机中，扩展目录是 /usr/local/Cellar/php/7.2.11/pecl/20170718。然后，要使用扩展需要先启用它，你必须这样做：

$ php -d extension=gutenberg_post_parser -m | \
      grep gutenberg_post_parser

或者，针对所有的脚本执行启用扩展，你需要使用命令 php --ini 定位到 php.ini 文件，并编辑，向其中追加以下内容：

extension=gutenberg_post_parser

完成！现在，我们使用一些反射来检查扩展是否被 PHP 正确加载和处理：

$ php --re gutenberg_post_parser
Extension [ <persistent> extension #64 gutenberg_post_parser version 0.1.0 ] {

  - Functions {
    Function [ <internal:gutenberg_post_parser> function gutenberg_post_parse ] {

      - Parameters [1] {
        Parameter #0 [ <required> $gutenberg_post_as_string ]
      }
    }
  }

  - Classes [2] {
    Class [ <internal:gutenberg_post_parser> final class Gutenberg_Parser_Block ] {

      - Constants [0] {
      }

      - Static properties [0] {
      }

      - Static methods [0] {
      }

      - Properties [4] {
        Property [ <default> public $namespace ]
        Property [ <default> public $name ]
        Property [ <default> public $attributes ]
        Property [ <default> public $children ]
      }

      - Methods [0] {
      }
    }

    Class [ <internal:gutenberg_post_parser> final class Gutenberg_Parser_Phrase ] {

      - Constants [0] {
      }

      - Static properties [0] {
      }

      - Static methods [0] {
      }

      - Properties [1] {
        Property [ <default> public $content ]
      }

      - Methods [0] {
      }
    }
  }
}

看起来没什么问题：有一个函数和两个预定义的类。现在，我们来编写本文的 PHP 代码！

<?php

var_dump(
    gutenberg_post_parse(
        '<!-- wp:foo /-->bar<!-- wp:baz -->qux<!-- /wp:baz -->'
    )
);

/**
 * Will output:
 *     array(3) {
 *       [0]=>
 *       object(Gutenberg_Parser_Block)#1 (4) {
 *         ["namespace"]=>
 *         string(4) "core"
 *         ["name"]=>
 *         string(3) "foo"
 *         ["attributes"]=>
 *         NULL
 *         ["children"]=>
 *         NULL
 *       }
 *       [1]=>
 *       object(Gutenberg_Parser_Phrase)#2 (1) {
 *         ["content"]=>
 *         string(3) "bar"
 *       }
 *       [2]=>
 *       object(Gutenberg_Parser_Block)#3 (4) {
 *         ["namespace"]=>
 *         string(4) "core"
 *         ["name"]=>
 *         string(3) "baz"
 *         ["attributes"]=>
 *         NULL
 *         ["children"]=>
 *         array(1) {
 *           [0]=>
 *           object(Gutenberg_Parser_Phrase)#4 (1) {
 *             ["content"]=>
 *             string(3) "qux"
 *           }
 *         }
 *       }
 *     }
 */

它正确执行了！

结语

主要过程：

获取 PHP 字符串
在中 Zend Engine 为 Gutenberg 扩展分配内存，
通过 FFI（静态库 + header）传递到 Rust，
通过 Gutenberg 扩展返回数据到 Zend Engine
生成 PHP 对象，
PHP 读取该对象。

Rust 适用于很多地方！我们已经看到在实际编程中已经有人实现如何用 Rust 实现解析器，如何将其绑定到 C 语言并生成除了 C 头文件之外的静态库，如何创建一个 PHP 扩展并暴露一个函数接口和两个对象，如何把“C 绑定”集成到 PHP，以及如何在 PHP 中使用该扩展。提醒一下，“C 绑定”大概有 150 行代码。PHP 扩展大概有 300 行代码，但是减去自动生成的“代码修饰”（一些声明和管理扩展的模板文件），PHP 扩展将减少到大约 200 行代码。同样，考虑到解析器仍然是用 Rust 编写的，修改解析器不会影响绑定（除非 AST 发生了较大更新），我发现整个实现过程只是一小部分代码。PHP 是一个有垃圾回收的语言。这就解释了为何需要拷贝所有的字符串，这样数据都能被 PHP 拥有。然而，Rust 中不拷贝任何数据的事实表明可以减少内存分配和释放，这些开销恰好在大多数情况下是最大的时间成本。Rust 还提供了安全性。考虑到我们要进行绑定的数量，这个特性可能受到质疑：Rust 到 C 到 PHP，这种安全性还存在吗？从 Rust 的角度看，答案是确定的，但在 C 或 PHP 中发生的所有操作都被认为是不安全的。在 C 绑定中必须特别谨慎处理所有情况。这样还快吗？好吧，让我们进行基准测试。我想提醒你，这个实验的首要目标是解决原始的 PEG.js 解析器性能问题。在 JavaScript 的基础上，WASM 和 ASM.js 方案已经被证明要快的多（参见 WebAssembly 领域和 ASM.js 领域）。对于 PHP，使用 phpegjs：它读取为 PEG.js 编写的语法并将其编译到 PHP。我们来比较一下：

文件名	PEG PHP parser (ms)	Rust parser as a PHP extension (ms)	提升倍数
`demo-post.html`	30.409	0.0012	× 25341
`shortcode-shortcomings.html`	76.39	0.096	× 796
`redesigning-chrome-desktop.html`	225.824	0.399	× 566
`web-at-maximum-fps.html`	173.495	0.275	× 631
`early-adopting-the-future.html`	280.433	0.298	× 941
`pygmalian-raw-html.html`	377.392	0.052	× 7258
`moby-dick-parsed.html`	5,437.630	5.037	× 1080

Rust 解析器的 PHP 扩展比实际的 PEG PHP 实现平均快 5230 倍。提升倍数的中位数是 941。另一个问题是 PEG 解析器由于内存限制无法处理过多的 Gutenberg 文档。当然，增大内存的大小可能解决这个问题，但并不是最佳方案。使用 Rust 解析器作为 PHP 扩展，内存消耗基本保持不变，并且接近解析文档的大小。我认为我们可以通过迭代器而非数组的方式来进一步优化该扩展。这是我想探索的东西以及分析对性能的影响。PHP 内核书籍有个迭代器章节。我们将在本系列的下一节看到 Rust 可以助力于很多领域，而且传播的越多，就越有趣味。感谢你的阅读！

【译】使用 Rust 和 WebAssembly 构建离线画图页面

Samuel Su — Sat, 06 Jul 2019 09:02:27 +0000

【译】使用 Rust 和 WebAssembly 构建离线画图页面

原文地址：https://dev.to/sendilkumarn/create-dev-s-offline-page-with-rust-and-webassembly-21gn

原文仓库：https://github.com/sendilkumarn/draw-page

原文作者：Sendil Kumar N

译文出自：https://github.com/suhanyujie

本文永久链接：（缺省）

译者：suhanyujie

翻译不当之处，还请指出，谢谢！

文中的页面效果可以参考这里：离线画图页

Dev 网站的离线画图页很有趣。我们能用 Rust 和 WebAssembly 来实现吗？

答案是肯定的。让我们现在就来实现它。

首先，我们通过 Webpack 创建了一个基于 Rust 和 WebAssembly 的简单应用。

npm init rust-webpack dev-offline-canvas

Rust 和 WebAssembly 生态提供了 web_sys，它在 Web API 上提供了很多需要的绑定。可以从这里检出。

示例应用已经引入了 web_sys 依赖。web_sys crate 中包含了所有可用的 WebAPI 绑定。

如果引入所有的 WebAPI 绑定将会增加绑定文件的大小。按需引入必要的 API 是比较重要的。

我们移除已经存在的 feature 列表（位于 toml 文件中）

features = [
    'console'
]

并使用下面的替代：

features = [
  'CanvasRenderingContext2d',
  'CssStyleDeclaration',
  'Document',
  'Element',
  'EventTarget',
  'HtmlCanvasElement',
  'HtmlElement',
  'MouseEvent',
  'Node',
  'Window',
]

上面的 features 列表是我们将在本例中需要使用的一些 features。

开始写 Rust 代码

打开文件 src/lib.rs。

使用下面的代码替换掉文件中的 start() 函数：

#[wasm_bindgen(start)]
pub fn start() -> Result<(), JsValue> {

   Ok()
}

一旦实例化了 WebAssembly 模块，#[wasm_bindgen(start)] 就会调用这个函数。可以查看规范中关于 start 函数的详细信息。

我们在 Rust 中将得到 window 对象。

let window = web_sys::window().expect("should have a window in this context");

接着从 window 对象中获取 document。

let document = window.document().expect("window should have a document");

创建一个 Canvas 元素，将其插入到 document 中。

let canvas = document
         .create_element("canvas")?
         .dyn_into::<web_sys::HtmlCanvasElement>()?;

document.body().unwrap().append_child(&canvas)?;

设置 canvas 元素的宽、高和边框。

canvas.set_width(640);
canvas.set_height(480);
canvas.style().set_property("border", "solid")?;

在 Rust 中，一旦离开当前上下文或者函数已经 return，对应的内存就会被释放。但在 JavaScript 中，window, document 在页面的启动和运行时都是活动的（位于生命周期中）。

因此，为内存创建一个引用并使其静态化，直到程序运行结束，这一点很重要。

获取 Canvas 渲染的上下文，并在其外层包装一个 wrapper，以保证它的生命周期。

RC 表示 Reference Counted。

Rc 类型提供在堆中分配类型为 T 的值，并共享其所有权。在 Rc 上调用 clone 会生成指向堆中相同值的新的指针。当指向给定值的最后一个 Rc 指针即将被释放时，它指向的值也将被释放。 —— RC 文档

这个引用被 clone 并用于回调方法。

let context = canvas
        .get_context("2d")?
        .unwrap()
        .dyn_into::<web_sys::CanvasRenderingContext2d>()?;

let context = Rc::new(context);

Since we are going to capture the mouse events. We will create a boolean variable called pressed. The pressed will hold the current value of mouse click.
因为我们要响应 mouse 事件。因此我们将创建一个名为 pressed 的布尔类型的变量。pressed 用于保存 mouse click（鼠标点击）的当前值。

let pressed = Rc::new(Cell::new(false));

现在，我们需要为 mouseDown、mouseUp、mouseMove 创建一个闭包（回调函数）。

{ mouse_down(&context, &pressed, &canvas); }
{ mouse_move(&context, &pressed, &canvas); }
{ mouse_up(&context, &pressed, &canvas); }

我们将把这些事件触发时需要执行的操作定义为独立的函数。这些函数接收 canvas 元素的上下文和鼠标按下状态作为参数。

fn mouse_up(context: &std::rc::Rc<web_sys::CanvasRenderingContext2d>, pressed: &std::rc::Rc<std::cell::Cell<bool>>, canvas: &web_sys::HtmlCanvasElement) {
    let context = context.clone();
    let pressed = pressed.clone();
    let closure = Closure::wrap(Box::new(move |event: web_sys::MouseEvent| {
        pressed.set(false);
        context.line_to(event.offset_x() as f64, event.offset_y() as f64);
        context.stroke();
    }) as Box<dyn FnMut(_)>);
    canvas.add_event_listener_with_callback("mouseup", closure.as_ref().unchecked_ref()).unwrap();
    closure.forget();
}

fn mouse_move(context: &std::rc::Rc<web_sys::CanvasRenderingContext2d>, pressed: &std::rc::Rc<std::cell::Cell<bool>>, canvas: &web_sys::HtmlCanvasElement){
    let context = context.clone();
    let pressed = pressed.clone();
    let closure = Closure::wrap(Box::new(move |event: web_sys::MouseEvent| {
        if pressed.get() {
            context.line_to(event.offset_x() as f64, event.offset_y() as f64);
            context.stroke();
            context.begin_path();
            context.move_to(event.offset_x() as f64, event.offset_y() as f64);
        }
    }) as Box<dyn FnMut(_)>);
    canvas.add_event_listener_with_callback("mousemove", closure.as_ref().unchecked_ref()).unwrap();
    closure.forget();
}

fn mouse_down(context: &std::rc::Rc<web_sys::CanvasRenderingContext2d>, pressed: &std::rc::Rc<std::cell::Cell<bool>>, canvas: &web_sys::HtmlCanvasElement){
    let context = context.clone();
    let pressed = pressed.clone();

    let closure = Closure::wrap(Box::new(move |event: web_sys::MouseEvent| {
        context.begin_path();
        context.set_line_width(5.0);
        context.move_to(event.offset_x() as f64, event.offset_y() as f64);
        pressed.set(true);
    }) as Box<dyn FnMut(_)>);
    canvas.add_event_listener_with_callback("mousedown", closure.as_ref().unchecked_ref()).unwrap();
    closure.forget();
}

他们非常类似于你平时写的 JavaScript 的 API，但它们是用 Rust 编写的。

现在我们都设置好了。我们可以运行应用程序并在画布中画画。 🎉 🎉 🎉

但我们还没有设定颜色。

添加多个颜色

增加颜色样本，创建一个 div 列表，并使用它们作为颜色选择器。

在 start 函数中定义我们需要的颜色列表。

#[wasm_bindgen(start)]
pub fn start() -> Result<(), JsValue> {
    // ....... Some content
    let colors = vec!["#F4908E", "#F2F097", "#88B0DC", "#F7B5D1", "#53C4AF", "#FDE38C"];

    Ok()
}

然后遍历颜色列表，为所有颜色创建一个 div，并将其加入到 document 中。对于每个 div，还需要添加一个 onClick 处理程序来更改画板颜色。

for c in colors {
    let div = document
        .create_element("div")?
        .dyn_into::<web_sys::HtmlElement>()?;
    div.set_class_name("color");
    {
        click(&context, &div, c.clone());  // On Click Closure.
    }

    div.style().set_property("background-color", c);
    let div = div.dyn_into::<web_sys::Node>()?;
    document.body().unwrap().append_child(&div)?;
}

其中 click 函数实现如下所示：

fn click(context: &std::rc::Rc<web_sys::CanvasRenderingContext2d>, div: &web_sys::HtmlElement, c: &str) {
    let context = context.clone();
    let c = JsValue::from(String::from(c));
    let closure = Closure::wrap(Box::new(move || {
        context.set_stroke_style(&c);            
    }) as Box<dyn FnMut()>);

    div.set_onclick(Some(closure.as_ref().unchecked_ref()));
    closure.forget();
}

现在稍微美化一下。打开 static/index.html 文件。在其中添加 div 样式。

<style>
       .color {
            display: inline-block;
            width: 50px;
            height: 50px;
            border-radius: 50%;
            cursor: pointer;
            margin: 10px;
       }
 </style>

这就是我们的画板了，我们已经创建好了这个应用。🎉

可以从这里检出示例应用。

希望这个例子能给你开启美妙的 WebAssembly 旅程带来灵感。如果你有任何的问题、建议、感受，欢迎给我留言评论。

你可以在 Twitter 关注我。

如果你喜欢这个文章，请给这个文章点赞或留言。❤️

还可以阅读我的其他 WebAssembly 文章，点击这儿。

Forem: Samuel Su

【译】用 Rust 实现 csv 解析-part6

写入 tab 分隔符的值

使用 Serde 写入

Pipelining

【译】从 Rust 到不只是 Rust：PHP 语言领域

PHP 是什么？为什么是它？

Rust 🚀 C 🚀 PHP

使用脚手架引导

模块即扩展

类的声明

gutenberg_post_parse 函数

into_php_objects 函数

PHP 扩展 🚀 PHP 用户态

结语

【译】使用 Rust 和 WebAssembly 构建离线画图页面

【译】使用 Rust 和 WebAssembly 构建离线画图页面

开始写 Rust 代码

添加多个颜色

`gutenberg_post_parse` 函数

`into_php_objects` 函数