抽取器选项

可用的提取程序选项

每个提取器都定义了自己的一组配置选项，用于从源代码构建可查询的 CodeQL 数据库。若要了解哪些选项可用于特定提取程序，可以运行以下命令之一：

codeql resolve languages --format=betterjson

codeql resolve extractor --language=LANGUAGE --format=betterjson

        `betterjson` 输出格式提供提取程序的根路径和其他信息。 
        `codeql resolve extractor --language=LANGUAGE --format=betterjson` 的输出通常采用如下例所示的格式：

{
    "extractor_root" : "/home/user/codeql/java",
    "extractor_options" : {
        "option1" : {
            "title" : "Java extractor option 1",
            "description" : "An example string option for the Java extractor.",
            "type" : "string",
            "pattern" : "[a-z]+"
        },
        "group1" : {
            "title" : "Java extractor group 1",
            "description" : "An example option group for the Java extractor.",
            "type" : "object",
            "properties" : {
                "option2" : {
                    "title" : "Java extractor option 2",
                    "description" : "An example array option for the Java extractor",
                    "type" : "array",
                    "pattern" : "[1-9][0-9]*"
                }
            }
        }
    }
}

extractor_options 下列出了提取程序选项名称和说明。每个选项可能包含以下字段：

        `title`（必填）：选项的标题

        `description`（必填）：选项说明

```
        `type`（必填）：选项的类型，可以是
```
* string：指示选项可以具有单个字符串值 * array：指示选项可以具有字符串值序列 * object：指示它不是选项本身，而是可能包含其他选项和选项组的分组

        `pattern`（可选）：选项的所有值都应匹配的正则表达式模式。 请注意，提取程序可能会对未采用或无法采用此正则表达式模式来表示的选项值施加其他约束。 说明字段下会解释此类约束（如果存在）。

          `properties`（可选）：选项组中的提取器选项名称到对应提取器选项描述的映射。 此字段只为选项组提供。 例如，`object` 类型的选项。

在上面的示例中，提取程序声明了两个选项：

        `option1` 是一个 `string` 选项，其值与 `[a-z]+` 匹配

        `group1.option2` 是一个 `array` 选项，其值与 `[1-9][0-9]\*` 匹配

用于设置提取程序选项的命令

CodeQL CLI 支持在直接或间接调用提取程序的子命令中设置提取程序选项。这些命令包括：

codeql database create
codeql database start-tracing
codeql database trace-command
codeql database index-files

运行这些子命令时，可以使用 --extractor-option CLI 选项设置提取程序选项。例如：

codeql database create --extractor-option java.option1=abc ...

codeql database start-tracing --extractor-option java.group1.option2=102 ...

        `--extractor-option` 需要恰好一个格式为 `extractor_option_name=extractor_option_value` 的参数：

        `extractor_option_name` 是提取程序的名称（在此示例中为 `java`）后跟句点，然后是提取程序选项的名称（在此示例中为 `option1` 或 `group1.option2`）。

        `extractor_option_value` 是分配给提取程序选项的值。 该值必须与提取程序选项的正则表达式模式（如果存在）匹配，并且不能包含换行符。

使用 --extractor-option 分配不存在的提取程序选项时会出现错误。

CodeQL CLI 接受在同一调用中使用多个 --extractor-option 选项。如果多次设置 string 提取程序选项，最后一个选项值会覆盖所有之前的值。如果多次设置数组提取器选项，则所有选项值会按顺序连接。

你也可以在不指定提取程序名称的情况下，指定提取程序选项名称。例如：

codeql database create --extractor-option option1=abc ...
codeql database start-tracing --extractor-option group1.option2=102 ...

如果未指定提取程序名称，提取程序选项设置将应用于声明具有给定名称的选项的所有提取程序。在上面的示例中，第一个命令会将 java 提取程序以及所有具有 option1 选项的提取程序（例如cpp 提取程序，如果存在 option1 提取程序选项）中的提取选项 option1 设置为 abc。

提取选项的文件格式

还可以通过文件设置提取程序选项。接受 --extractor-option 的 CodeQL CLI 子命令也接受 --extractor-options-file，该命令具有 YAML 文件（扩展名为 .yaml 或 .yml）路径或 JSON 文件（扩展名为 .json）路径的必需参数。例如：

codeql database create --extractor-options-file options.yml ...
codeql database start-tracing --extractor-options-file options.json ...

每个选项文件都包含嵌套映射的树结构。根位置是提取程序映射键，其下方是对应于提取程序名称的映射键。从第三个级别开始，有提取器选项和选项组。

在 JSON 中：

{
     "extractor" : {
        "java": {
            "option1" : "abc",
            "group1" : {
                "option2" : [ 102 ]
            }
        }
    }
}

在 YAML 中：

extractor:
    java:
        option1: "abc"
        group1:
            option2: [ 102 ]

          `string` 提取程序选项的值必须是字符串或数字（其将在进一步处理之前将转换为字符串）。

          `array` 提取程序选项的值必须是由字符串或数字构成的数组。

选项组（object 类型）的值必须是映射，其中可能包含嵌套提取程序选项和选项组。

每个提取程序选项值必须与提取程序选项的正则表达式模式（如果存在）匹配，并且不能包含换行符。

分配不存在的提取程序选项时会出现错误。可以使用特殊的 __allow_unknown_properties 布尔字段使 CodeQL CLI 忽略未知提取程序选项。例如，以下选项文件要求 CodeQL CLI 忽略 group1 下的所有未知提取程序选项和选项组：

extractor:
    java:
        option1: "abc"
        group1:
            __allow_unknown_properties: true
            option2: [ 102 ]

可以多次指定 --extractor-options-file。提取器选项分配按以下顺序进行处理：

由 --extractor-options-file 指定的所有提取程序选项文件均按它们在命令行上的显示顺序进行处理，然后
由 --extractor-option 指定的所有提取程序选项分配均按它们在命令行上的显示顺序进行处理

相同的规则控制多次设置同一提取程序选项时会发生什么情况，而无论分配是使用 --extractor-option、--extractor-options-file 还是两者的某种组合完成的。如果多次设置 string 提取程序选项，最后一个选项值会覆盖所有以前的值。如果多次设置 array 提取程序选项，则所有选项值会按顺序连接。

谁可以使用此功能？

本文内容

可用的提取程序选项

用于设置提取程序选项的命令

提取选项的文件格式