Lib.rs

#+TITLE: sdml-cli 包 #+AUTHOR: Simon Johnston #+EMAIL: [email protected] #+LANGUAGE: en #+STARTUP: overview hidestars inlineimages entitiespretty #+OPTIONS: author:nil created:nil creator:nil date:nil email:nil num:3 toc:nil

Rust CLI for the Simple Domain Modeling Language (SDML).

[https://crates.io/crates/sdml_cli]

此包是 Rust SDML 项目的一部分，并具体实现了 =sdml= 命令行界面（CLI）。项目的目的是提供一个符合习惯的内存模型、解析器、生成器和 CLI 工具的实现。

以下图示展示了该包在更广泛的项目背景中的位置。

#+CAPTION: 包组织 #+BEGIN_EXAMPLE ╭───────╮ │ CLI │ ╔══ │ crate │ ══╗ ║ ╰───────╯ ║ ┌╌╌╌╌╌╌╌╌┐ V V ┆ ┆ ╭───────╮ ╭──────────╮ Formatted Source ┆ file ┆ ══> │ parse │ ══> │ generate │ ══> RDF Representation ┆ ┆ │ ╰───────╯ ╰──────────╯ │ Diagrams └╌╌╌╌╌╌╌╌┘ │ core/errors crate │ ╰──────────────────────────────────╯ ┌───────┐ ⋀ │ other │ ║ │ tools │ ════════════════╝ └───────┘ #+END_EXAMPLE

• 安装

通过 =cargo= 命令安装命令行界面。Cargo 通常与 Rust 工具链一起使用 [[https://rustup.rs/[rustup]]] 安装。

以下命令应下载并构建工具，并也可以用于安装任何更新。

#+BEGIN_EXAMPLE bash ❯ cargo install sdml-cli #+END_EXAMPLE

Cargo 有时会报告您已安装最新版本，为了确保您可以使用 =--force= 选项强制安装。

#+BEGIN_EXAMPLE bash ❯ cargo install sdml-cli --force #+END_EXAMPLE

您可以使用以下检查来确认您已安装该工具并已将其添加到路径中。

#+BEGIN_EXAMPLE bash ❯ sdml versions
SDML CLI: 0.2.7 SDML 语法: 0.2.16 Tree-Sitter ABI: 14 #+END_EXAMPLE

• 全局选项

某些命令行选项作用于所有命令，这些必须出现在命令之前。SDML 工具有一个日志过滤器和无颜色全局选项。

组成 =rust-sdml= 的所有软件包都具有广泛的日志记录功能，可以在运行工具时启用。全局参数 =--log-filter= 接受一个日志级别，并显示任何严重性大于或等于过滤器的日志事件。

#+BEGIN_EXAMPLE bash ❯ sdml --log-filter tracing versions 2024-02-20T19:06:53.141741Z INFO sdml: 日志级别设置为 LevelFilter::Tracing 2024-02-20T19:06:53.141877Z TRACE sdml: Commands::execute self: Versions SDML CLI: 0.2.7 SDML 语法: 0.2.16 Tree-Sitter ABI: 14 #+END_EXAMPLE

一些命令默认会使用彩色输出，如果在保存文件以便将来处理时，控制字符可能会与 diff 工具等产生冲突，这可能会成为一个问题。

#+BEGIN_EXAMPLE bash ❯ sdml --no-color versions ❯ NO_COLOR=1 sdml versions ❯ CLI_COLOR=0 sdml versions #+END_EXAMPLE

• 命令

输入文件

** 获取帮助

#+BEGIN_EXAMPLE bash ❯ sdml --help Rust 简单领域建模语言 (SDML) CLI

用法: sdml [选项]

命令: convert 将模块转换为其他表示形式 draw 从模块中绘制图表 deps 显示模块依赖关系 doc 文档化模块 highlight 对模块源代码进行语法高亮 tags 从模块中提取标签 validate 验证模块 versions 显示工具和库版本 view 查看格式化的模块源代码帮助 打印此消息或给定子命令的帮助信息

选项: --log-filter <LOG_FILTER> 启用的日志级别

      [default: none]

      Possible values:
      - none:        Turn off all logging
      - errors:      Enable error logging only
      - warnings:    Enable warnings and above
      - information: Enable information and above
      - debugging:   Enable debugging and above
      - tracing:     Enable tracing (ALL) and above

  --no-color
      Turn off color for code emitters
      
      [env: NO_COLOR=]

-h, --help 打印帮助（使用 '-h' 查看摘要）

-V, --version 打印版本 #+END_EXAMPLE

** 表示形式转换

此命令（convert）允许将模块从 SDML 表面语法转换为多种其他表示形式之一。

*** RDF

这使用 SDML 语言参考中定义的表面到 RDF 映射。该映射是规范性的且是稳定的。

*** JSON

这是 Rust 包 =sdml_core= 中内存模型的直接表示，以 JSON 格式。此映射是非规范性的，可能根据任何模型结构更改而更改。

*** S-Expression

这是一个调试表示形式，支持底层 tree-sitter 库使用 s-表达式作为解析树的可视化。

** 依赖关系可视化

此命令（dep）生成给定模块的传递闭包依赖关系的表示形式，并将其转换为多种其他表示形式之一。

*** 树

以文本树的形式显示依赖关系，原始依赖关系作为根。

#+BEGIN_EXAMPLE bash ❯ sdml deps sdml sdml ├── owl │ ├── rdf │ │ └── rdfs │ │ └── rdf │ ├── rdfs │ └── xsd │ ├── rdf │ └── rdfs ├── rdf ├── rdfs ├── skos │ ├── rdf │ └── rdfs └── xsd #+END_EXAMPLE

在某些情况下，不需要显示整个依赖关系集，可以添加 =--depth= 参数以仅显示从根开始的一定级别的导入。深度参数指示命令在距离原始模块这么多依赖关系后停止。将深度设置为 1 将仅显示原始的直接依赖关系。

#+BEGIN_EXAMPLE bash ❯ sdml deps --depth 1 sdml sdml ├── owl ├── rdf ├── rdfs ├── skos └── xsd #+END_EXAMPLE

*** 图

使用 GraphViz 创建依赖关系图的 SVG 表示形式。

#+BEGIN_EXAMPLE bash ❯ sdml deps --output-format graph sdml > sdml-deps.svg ❯ open -a Safari sdml-deps.svg #+END_EXAMPLE

[https://raw.githubusercontent.com/sdm-lang/rust-sdml/main/sdml-generate/doc/example_deps_graph.svg]

*** RDF

创建一组表示单个 OWL 导入关系的 RDF 语句，作为 N-Triples。

#+BEGIN_EXAMPLE bash ❯ sdml deps --depth 1 --output-format rdf sdml http://sdml.io/sdml-owl.ttl# http://www.w3.org/2002/07/owl#imports http://www.w3.org/2002/07/owl# . http://sdml.io/sdml-owl.ttl# http://www.w3.org/2002/07/owl#imports http://www.w3.org/1999/02/22-rdf-syntax-ns# . http://sdml.io/sdml-owl.ttl# http://www.w3.org/2002/07/owl#imports http://www.w3.org/2000/01/rdf-schema# . http://sdml.io/sdml-owl.ttl# http://www.w3.org/2002/07/owl#imports http://www.w3.org/2004/02/skos/core# . http://sdml.io/sdml-owl.ttl# http://www.w3.org/2002/07/owl#imports http://www.w3.org/2001/XMLSchema# . #+END_EXAMPLE

** 图表生成

此命令（draw）生成具有不同视角的模块图表。

*** 概念

#+BEGIN_EXAMPLE bash ❯ sdml draw --diagram concepts --o example-concepts.svg -i example/example.sdm ❯ open -a Safari example-concepts.svg #+END_EXAMPLE

[https://raw.githubusercontent.com/sdm-lang/rust-sdml/main/sdml-generate/doc/example-concepts.svg]

*** 实体关系

#+BEGIN_EXAMPLE bash ❯ sdml draw --diagram entity-relationship --o example-erd.svg -i example/example.sdm ❯ open -a Safari example-erd.svg #+END_EXAMPLE

[https://raw.githubusercontent.com/sdm-lang/rust-sdml/main/sdml-generate/doc/example-erd.svg]

*** UML 类

#+BEGIN_EXAMPLE bash ❯ sdml draw --diagram uml-class --o example-uml.svg -i example/example.sdm ❯ open -a Safari example-uml.svg #+END_EXAMPLE

[https://raw.githubusercontent.com/sdm-lang/rust-sdml/main/sdml-generate/doc/example-uml.svg]

** 文档（项目）生成

此命令（doc-book）为模块集合创建结构化文档，包括注释、约束和所有定义类型。生成的文档还包含图表和依赖关系图。

*** Org-mode

创建一个 Emacs org-mode 格式的文件。此格式允许所有内容写入单个文件，并提供导出到 HTML、LaTeX、Word、PDF 等选项。

** 文档（模块）生成

此命令（doc）为模块创建结构化文档，包括注释、约束和所有定义类型。生成的文档还包含图表和依赖关系图。

*** Org-mode

创建一个 Emacs org-mode 格式的文件。此格式允许所有内容写入单个文件，并提供导出到 HTML、LaTeX、Word、PDF 等选项。

*** Markdown

创建一个 markdown 格式的文件，此文件使用 GitHub-flavored markdown，以提供比 CommonMark 更好的内容格式化。

** 模块高亮

待定

** XRef 标签生成

待定

** 验证

此命令（validate）提供对模块内容的深度验证，包括错误、警告和类似 linter 的建议。不仅对初始模块进行检查，还检查其传递加载的依赖项。

#+BEGIN_EXAMPLE bash ❯ sdml validate --level all -i examples/errors/i0506.sdm note[I0506]: identifier not using preferred casing ┌─ examples/errors/i0506.sdm:1:8 │ 1 │ module Example https://example.com/api is │ ^^^^^^^ 此标识符 │ = 期望蛇形大小写（snake_case） = 帮助：有关更多详细信息，请参阅 https://sdml.io/errors/#I0506

note[I0506]: 标识符未使用首选大小写 ┌─ examples/errors/i0506.sdm:3:13 │ 3 │ 结构访问_record is │ ^^^^^^^^^^^^^^ 这个标识符 │ = 期望大驼峰式 (UpperCamelCase) = 帮助：更多详细信息，请参阅 https://sdml.io/errors/#I0506 #+END_EXAMPLE

此外，一个 简短形式 选项将使用 CSV 格式生成诊断信息，这种格式对工具解析更容易。此格式的字段包括：严重性、文件名、起始行、起始列、结束行、结束列、错误代码和消息。

#+BEGIN_EXAMPLE bash ❯ sdml validate --level all --short-form -i examples/errors/i0506.sdm note,examples/errors/i0506.sdm,1,8,1,15,I0506,identifier not using preferred casing note,examples/errors/i0506.sdm,3,13,3,26,I0506,identifier not using preferred casing #+END_EXAMPLE

** 版本信息

此命令（版本）显示的信息比简单的 =--version= 全局参数更多，并且对调试很有用。

#+BEGIN_EXAMPLE bash ❯ sdml versions
SDML CLI: 0.2.7 SDML 语法: 0.2.16 Tree-Sitter ABI: 14 #+END_EXAMPLE

** 模块查看器

此命令（查看）将从模块文件生成源代码，这最初看起来是多余的。然而，此视图提供了不同级别的细节，可以概述模块定义。可以使用 =--level= 参数省略内容并获取模块的概览。

*** 只显示定义

仅显示模块中的定义，任何定义体将被省略，以概述模块内容。省略的定义后跟 =";; ..."=。

#+BEGIN_EXAMPLE bash ❯ sdml view --level definitions -i examples/example.sdm module example https://example.com/api 是

导入 [ dc xsd ]

数据类型 Uuid <- sdml:string ;; ...

实体 Example ;; ...

end #+END_EXAMPLE

*** 成员

显示模块中的定义，并显示产品类型和求和类型变体的成员，但如果不提供则不显示其主体。

#+BEGIN_EXAMPLE bash ❯ sdml view --level members -i examples/example.sdm module example https://example.com/api 是

导入 [ dc xsd ]

数据类型 Uuid <- sdml:string ;; ...

实体 Example 是版本 -> Uuid 名称 -> sdml:string ;; ... end

end #+END_EXAMPLE

*** 完整

显示模块的所有内容。

#+BEGIN_EXAMPLE bash ❯ sdml view --level full -i examples/example.sdm module example https://example.com/api 是

导入 [ dc xsd ]

数据类型 Uuid <- sdml:string 是 @xsd:pattern = "[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}" end

实体 Example 是版本 -> Uuid 名称 -> sdml:string 是 @dc:description = "这个事物的名称"@en end end

end #+END_EXAMPLE

• 更改

版本 0.2.10

• 功能：添加了新的 =doc-book= 命令，为模块集合创建更复杂的文档输出。
• 构建：提升 =sdml-errors=, =sdml-core=, 和 =sdml-generate= 的版本。

版本 0.2.9

• 构建：将依赖项从 =sdml_error= 更新到 =sdml-errors=。
• 构建：提升 =sdml-core=, =sdml-parse=, 和 =sdml-generate= 的版本。

版本 0.2.8

• 构建：升级到 =sdml_core= 版本 =0.2.14= 和新的 =ModelStore= 特性。

版本 0.2.7

• 功能：与 =sdml-errors= 中的验证和诊断一起改进错误处理。

版本 0.2.6

• 构建：更新依赖项。

版本 0.2.5

• 功能：向 CLI 添加了新的 =--no-color= 标志，它还使用 =NO_COLOR= 环境变量。
• 功能：从 =Cargo.toml= 中移除了间接依赖。
• 更新：新的彩色 RDF 生成器功能。

版本 0.2.4

• 功能：添加了新的 =source= 命令以调用新的源生成器。
• 修复：更改 =deps= 命令中 =depth= 参数的描述，=0= 是默认值，表示输出包括所有深度。
• 更新：使用需要模块缓存参数的新生成器特性。

版本 0.2.3

• 功能：添加了具有标准布局的新的 =stdlib= 模块。
• 功能：对缓存和加载器进行轻微重构。

版本 0.2.2

• 特性：更新到最新的语法，用于版本 URI 和 RDF 定义。
  • 在模块中添加对基本 URI 的支持。
  • 在模块中添加对版本信息和 URI 的支持。
  • 在模块导入时添加对版本 URI 的支持。
  • 解析类和属性的 RDF 定义。

版本 0.2.1

• 特性：移除成员组。

版本 0.2.0

• 特性：更新到最新的语法。
  • 移除 =ValueVariant= 的数值。
  • 更新正式约束。
  • 添加类型类。

版本 0.1.6

• 更新依赖项。

版本 0.1.5

初始独立 crate。

版本 0.1.4

之前是单个 crate 的一部分 [[https://crates.io/crates/sdml][sdml]]。