mapry 1.0.0.4

文档

本文档仅提供了Mapry的简要概述。完整的文档可以在这里找到。

介绍

在这里，我们将通过展示一个简短的示例来介绍Mapry，以便您对生成器的使用有一个初步印象。要全面了解，请查阅文档。

模式以名称和描述开始，接着是特定语言的设置（指定代码生成的非标准部分），然后是图结构的定义，最后是对象图本身的属性定义。

以下是一个示例模式，以供您了解

{
  "name": "Pipeline",
  "description": "defines an address book.",
  "cpp": {
    "namespace": "book::address",
    "path_as": "boost::filesystem::path",
    "optional_as": "std::experimental::optional",
    "datetime_library": "ctime"
  },
  "go": {
    "package": "address"
  },
  "py": {
    "module_name": "book.address",
    "path_as": "pathlib.Path",
    "timezone_as": "pytz.timezone"
  },
  "classes": [
    {
      "name": "Person",
      "description": "defines a contactable person.",
      "properties": {
        "full_name": {
          "type": "string",
          "description": "gives the full name (including middle names)."
        },
        "birthday": {
          "type": "date",
          "description": "indicates the birthday in UTC."
        },
        "address": {
          "type": "Address",
          "description": "notes where the person lives."
        }
      }
    }
  ],
  "embeds": [
    {
      "name": "Address",
      "description": "defines an address.",
      "properties": {
        "text": {
          "type": "string",
          "description": "gives the full address."
        }
      }
    }
  ],
  "properties": {
    "maintainer": {
      "type": "Person",
      "description": "indicates the maintainer of the address book."
    }
  }
}

一旦您使用Mapry生成了反序列化代码，您就可以使用它从可序列化为JSON的结构中获取对象图。

例如，假设一个可序列化为JSON的结构存储在/path/to/the/file.json

{
  "persons": {
    "alice": {
      "full_name": "Alice Doe",
      "birthday": "1983-10-24",
      "address": {
        "text": "Some street 12, Some City, Some Country"
      }
    },
    "bob": {
      "full_name": "Bob Johnson",
      "birthday": "2016-07-03",
      "address": {
        "text": "Another street 36, Another City, Another Country"
      }
    }
  },
  "maintainer": "alice"
}

您可以使用Python解析对象图

# Obtain a JSONable
pth = '/path/to/the/file.json'
with open(pth, 'rt') as fid:
    value = json.load(fid)

# Parse the JSONable
errors = book.address.parse.Errors(cap=10)

pipeline = book.address.fromjsonable.pipeline_from(
    value=value,
    ref=pth + '#',
    errors=errors)

if not errors.empty():
    for error in errors.values():
        print("{}: {}".format(error.ref, error.message), file=sys.stderr)

    return 1

并将对象图作为pipeline访问

print('Persons are:')
for person in pipeline.persons:
    print('{} (full name: {}, address: {}, birthday: {})'.format(
        person.id,
        person.full_name,
        person.address.text,
        person.birthday.strftime("%d.%m.%Y")))

print('The maintainer is: {}'.format(
    pipeline.maintainer.id))

此模式的生成代码可以下载用于C++、Go和Python。

用法

Mapry通过mapry-to命令提供单一入口点进行所有代码生成。

要生成不同语言的代码，请调用

对于**C++**

mapry-to cpp \
    --schema /path/to/schema.json \
    --outdir /path/to/cpp/code

对于**Go**

mapry-to go \
    --schema /path/to/schema.json \
    --outdir /path/to/go/code

对于**Python**

mapry-to py \
    --schema /path/to/schema.json \
    --outdir /path/to/py/code

如果输出目录不存在，它将被创建。任何现有的文件都将被静默覆盖。

安装

我们提供可预包装的PEX文件，可以轻松下载和执行。请参阅发布部分。

如果您希望将 Mapry 作为库（例如，作为您基于 Python 的构建系统的一部分）来使用，请使用 pip 进行安装

pip3 install mapry

贡献

所有贡献都备受欢迎。请参阅文档中的此页面，了解您如何进行贡献：贡献页面。

版本控制

我们遵循 语义版本控制。我们扩展了标准的语义版本控制，添加了一个额外的格式版本。版本 W.X.Y.Z 表示

• W 是格式版本（数据表示向后不兼容），

• X 是主要版本（库接口向后不兼容），

• Y 是次要版本（库接口扩展，但向后兼容），

• Z 是补丁版本（向后兼容的错误修复）。

相关项目

我们在文档中整理了一份详尽的相关项目列表以及它们与 Mapry 的比较。

在此，我们仅介绍一些最突出的项目以及它们与 Mapry 的主要差异

标准 JSON 库

仅支持对象 树，而不是图。它们通常缺乏模式（例如，Python 的 json 模块）。

基于注解的序列化和反序列化工具

通过自定义逻辑处理对象图（例如，Java 的 Jackson）。由于它们基于源代码中的注解，多语言代码库需要在不同的语言之间进行重复，这可能既繁琐又容易出错，难以保持同步。

标准或广泛使用的序列化库

很好地处理对象图并提供丰富的原语。但是，序列化格式在不同语言之间不同（例如，C++ 的 Boost.Serialization 或 Python 的 Pickle 需要在 Go 中得到支持）。

基于生成代码的流行序列化工具

通常不进行对象图的反序列化和序列化，而仅进行对象树的序列化和反序列化（例如，Protocol Buffers 或 Cap’n Proto）。

Flatbuffers 是一个例外，它原生地处理对象图，但缺乏对复杂的类型（如映射、日期时间、持续时间等）的支持。