parse_yaml 项目技术文档

parse_yaml 项目技术文档

1. 安装指南

1.1 环境要求

• 操作系统：Linux 或 macOS
• 依赖：Bash 环境

1.2 安装步骤

1. 克隆项目仓库到本地：

   git clone https://github.com/yourusername/parse_yaml.git
   

2. 进入项目目录：

   cd parse_yaml
   

3. 将 parse_yaml.sh 脚本添加到你的 Bash 环境中。你可以选择将其复制到 /usr/local/bin 目录下，或者直接在需要使用的脚本中 source 该脚本。

2. 项目使用说明

2.1 基本使用

首先，你需要在 Bash 脚本中 source parse_yaml.sh 脚本：

source parse_yaml.sh

然后，你可以使用 parse_yaml 函数来解析 YAML 文件，并将解析结果赋值给 Shell 变量：

eval $(parse_yaml sample.yml)

2.2 进阶使用

你还可以通过管道将解析结果传递给其他 Shell 脚本或工具进行进一步处理：

parse_yaml sample.yml | some_script

此外，你可以从一个默认的 YAML 文件中加载默认值，然后用特定文件中的值覆盖这些默认值：

eval $(parse_yaml defaults.yml)
eval $(parse_yaml sample.yml)

2.3 自定义分隔符

你可以通过提供第二个参数来指定变量名的前缀，并通过第三个参数来更改分隔符（默认为下划线 _）：

eval $(parse_yaml sample.yml "" "-")

3. 项目 API 使用文档

3.1 parse_yaml 函数

• 功能：解析 YAML 文件并生成 Shell 变量定义的代码。
• 参数：
  • yaml_file：要解析的 YAML 文件路径。
  • prefix（可选）：变量名的前缀。
  • separator（可选）：变量名中各层级之间的分隔符。
• 返回值：生成 Shell 变量定义的代码，可以通过 eval 执行。

3.2 示例

假设你有一个 YAML 文件 sample.yml，内容如下：

---
global:
  input:
    - "main.c"
    - "main.h"
  flags: [ "-O3", "-fpic" ]
  sample_input:
    -  { property1: value1, property2: value2 }
    -  { property1: "value 3", property2: 'value 4' }
  licence: |
    this is published under
    open source license
    in the hope that it would 
    be useful
...

使用 parse_yaml 函数解析该文件：

eval $(parse_yaml sample.yml)

解析结果将生成如下 Shell 变量：

global_input_1="main.c"
global_input_2="main.h"
global_flags_1="-O3"
global_flags_2="-fpic"
global_sample_input_1_property1="value1"
global_sample_input_1_property2="value2"
global_sample_input_2_property1="value 3"
global_sample_input_2_property2="value 4"
global_licence="this is published under\nopen source license\nin the hope that it would \nbe useful\n"

4. 项目安装方式

4.1 直接使用

你可以直接在需要解析 YAML 文件的 Bash 脚本中 source parse_yaml.sh 脚本，然后调用 parse_yaml 函数。

4.2 全局安装

如果你希望在多个项目中使用该工具，可以将 parse_yaml.sh 脚本复制到 /usr/local/bin 目录下，并在需要使用的脚本中直接调用：

cp parse_yaml.sh /usr/local/bin/parse_yaml

然后在脚本中直接调用：

eval $(parse_yaml sample.yml)

通过以上步骤，你可以轻松地在 Bash 环境中使用 parse_yaml 工具来解析 YAML 文件，并将其内容转换为 Shell 变量。