From d0547cdbfd1e73a9e15ce5162fffb90f48d80336 Mon Sep 17 00:00:00 2001 From: Marcono1234 Date: Mon, 7 Feb 2022 20:53:40 +0100 Subject: [PATCH 1/2] Fix and improve Extractor options documentation formatting --- docs/codeql/codeql-cli/extractor-options.rst | 86 +++++++++++--------- 1 file changed, 47 insertions(+), 39 deletions(-) diff --git a/docs/codeql/codeql-cli/extractor-options.rst b/docs/codeql/codeql-cli/extractor-options.rst index 4a95f5d0d92..b9e823f94f6 100644 --- a/docs/codeql/codeql-cli/extractor-options.rst +++ b/docs/codeql/codeql-cli/extractor-options.rst @@ -12,30 +12,32 @@ About extractor options Each extractor defines its own set of configuration options. To find out which options are available for a particular extractor, you can run ``codeql resolve languages`` or ``codeql resolve extractor`` with the ``--format=betterjson`` option. The ``betterjson`` output format provides the root paths of extractors and additional information. The output of ``codeql resolve extractor --format=betterjson`` will often be formatted like the following example:: +.. code-block:: json + { - "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_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]*" + } } - } - } - } - } + } + } + } The extractor option names and descriptions are listed under ``extractor_options``. Each option may contain the following fields: @@ -95,25 +97,29 @@ Each option file contains a tree structure of nested maps. At the root is an ext In JSON:: +.. code-block:: json + { "extractor" : { - “java”: { - "option1" : “abc”, - "group1" : { - "option2" : [ 102 ] - } - } - } - } + "java": { + "option1" : "abc", + "group1" : { + "option2" : [ 102 ] + } + } + } + } In YAML:: +.. code-block:: yaml + extractor: - java: - option1: “abc” - group1: - option2: [ 102 ] + java: + option1: "abc" + group1: + option2: [ 102 ] The value for a ``string`` extractor option must be a string or a number (which will be converted to a string before further processing). @@ -125,12 +131,14 @@ Each extractor option value must match the regular expression pattern of the ext Assigning an extractor option that does not exist is an error. You can make the CodeQL CLI ignore unknown extractor options by using a special ``__allow_unknown_properties`` Boolean field. For example, the following option file asks the CodeQL CLI to ignore all unknown extractor options and option groups under ``group1``:: +.. code-block:: yaml + extractor: - java: - option1: “abc” - group1: - __allow_unknown_properties: true - option2: [ 102 ] + java: + option1: "abc" + group1: + __allow_unknown_properties: true + option2: [ 102 ] You can specify ``--extractor-options-file`` multiple times. The extractor option assignments are processed in the following order: From 5ec1fc11f9045a5bcfb6520d923488ac3cc84ff1 Mon Sep 17 00:00:00 2001 From: Felicity Chapman Date: Thu, 10 Feb 2022 12:41:37 +0000 Subject: [PATCH 2/2] Apply suggestions from code review --- docs/codeql/codeql-cli/extractor-options.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/codeql/codeql-cli/extractor-options.rst b/docs/codeql/codeql-cli/extractor-options.rst index b9e823f94f6..f688025a4d7 100644 --- a/docs/codeql/codeql-cli/extractor-options.rst +++ b/docs/codeql/codeql-cli/extractor-options.rst @@ -10,7 +10,7 @@ setting extractor configuration options through the CodeQL CLI. About extractor options ----------------------- -Each extractor defines its own set of configuration options. To find out which options are available for a particular extractor, you can run ``codeql resolve languages`` or ``codeql resolve extractor`` with the ``--format=betterjson`` option. The ``betterjson`` output format provides the root paths of extractors and additional information. The output of ``codeql resolve extractor --format=betterjson`` will often be formatted like the following example:: +Each extractor defines its own set of configuration options. To find out which options are available for a particular extractor, you can run ``codeql resolve languages`` or ``codeql resolve extractor`` with the ``--format=betterjson`` option. The ``betterjson`` output format provides the root paths of extractors and additional information. The output of ``codeql resolve extractor --format=betterjson`` will often be formatted like the following example: .. code-block:: json @@ -95,7 +95,7 @@ You can also set extractor options through a file. The CodeQL CLI subcommands th Each option file contains a tree structure of nested maps. At the root is an extractor map key, and beneath it are map keys that correspond to extractor names. Starting at the third level, there are extractor options and option groups. -In JSON:: +In JSON: .. code-block:: json @@ -111,7 +111,7 @@ In JSON:: } -In YAML:: +In YAML: .. code-block:: yaml @@ -129,7 +129,7 @@ The value for an option group (of type ``object``) must be a map, which may cont Each extractor option value must match the regular expression pattern of the extractor option (if it exists), and it must not contain newline characters. -Assigning an extractor option that does not exist is an error. You can make the CodeQL CLI ignore unknown extractor options by using a special ``__allow_unknown_properties`` Boolean field. For example, the following option file asks the CodeQL CLI to ignore all unknown extractor options and option groups under ``group1``:: +Assigning an extractor option that does not exist is an error. You can make the CodeQL CLI ignore unknown extractor options by using a special ``__allow_unknown_properties`` Boolean field. For example, the following option file asks the CodeQL CLI to ignore all unknown extractor options and option groups under ``group1``: .. code-block:: yaml