Opções do extrator

Opções de extrator disponíveis

Cada extrator define seu próprio conjunto de opções de configuração para criar um banco de dados consultável CodeQL a partir do código-fonte. Para descobrir quais opções estão disponíveis para um determinado extrator, você pode executar um dos seguintes comandos:

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

O formato de saída betterjson fornece os caminhos raiz dos extratores e informações adicionais. A saída de codeql resolve extractor --language=LANGUAGE --format=betterjson geralmente será formatada como o seguinte exemplo:

{
    "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]*"
                }
            }
        }
    }
}

Os nomes e as descrições das opções do extrator estão listados em extractor_options. Cada opção pode conter os seguintes campos:

•         `title` (obrigatório): o título da opção
  

•         `description` (obrigatório): a descrição da opção
  

•         `type` (obrigatório): o tipo da opção, que pode ser
  

  * string: indicando que a opção pode ter um só valor de cadeia de caracteres * array: indicando que a opção pode ter uma sequência de valores de cadeia de caracteres * object: indicando que não é uma opção em si, mas um agrupamento que pode conter outras opções e grupos de opções

•         `pattern` (opcional): os padrões de expressão regular aos quais todos os valores da opção devem corresponder. Observe que o extrator pode impor restrições adicionais aos valores de opção que não são ou não podem ser expressos nesse padrão de expressão regular. Essas restrições, se existirem, serão explicadas no campo de descrição.
  

•         `properties` (opcional): um mapa dos nomes de opção do extrator no grupo de opções para as descrições da opção do extrator correspondentes. Esse campo só pode estar presente para grupos de opções. Por exemplo, opções do tipo `object`.
  

No exemplo acima, o extrator declara duas opções:

•         `option1` é uma opção `string` com valor correspondente a `[a-z]+`
  

•         `group1.option2` é uma opção `array` com valores correspondentes a `[1-9][0-9]\*`
  

Comandos para definir opções do extrator

A CodeQL CLI dá suporte à configuração de opções do extrator em subcomandos que invocam extratores direta ou indiretamente. Estes comandos são:

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

Ao executar esses subcomandos, você pode definir as opções do extrator com a opção da CLI --extractor-option. Por exemplo:

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

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

          `--extractor-option` requer exatamente um argumento do formulário `extractor_option_name=extractor_option_value`:
  

•         `extractor_option_name` é o nome do extrator (neste exemplo, `java`) seguido por um ponto e depois o nome da opção extrator (neste exemplo, `option1` ou `group1.option2`).
  

•         `extractor_option_value` é o valor que está sendo atribuído à opção do extrator. O valor precisa corresponder ao padrão de expressão regular da opção do extrator (se existir) e não pode conter caracteres de nova linha.
  

O uso de --extractor-option para atribuir uma opção do extrator que não existe é um erro.

A CodeQL CLI aceita várias opções --extractor-option na mesma invocação. Se você definir uma opção stringdo extrator várias vezes, o último valor da opção substituirá todos os anteriores. Se você definir uma opção do extrator de matriz várias vezes, todos os valores da opção serão concatenados na ordem.

Você também pode especificar nomes de opção do extrator sem o nome do extrator. Por exemplo:

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

Se você não especificar um nome de extrator, as configurações de opção do extrator serão aplicadas a todos os extratores que declaram uma opção com o nome fornecido. No exemplo acima, o primeiro comando define a opção option1 do extrator como abc para o extrator java e para cada extrator que tem uma opção option1, por exemplo, o extrator cpp, caso a opção option1 do extrator exista para esse extrator.

Formato de arquivo para opções do extrator

Você também pode definir opções do extrator por meio de um arquivo. Os subcomandos da CodeQL CLI que aceitam --extractor-option também aceitam --extractor-options-file, que tem um argumento necessário do caminho para um arquivo YAML (com a extensão .yaml ou .yml) ou um arquivo JSON (com a extensão .json). Por exemplo:

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

Cada arquivo de opções contém uma estrutura em árvore de mapas aninhados. Na raiz, há uma chave de mapa do extrator e, abaixo dela, estão as chaves de mapa que correspondem aos nomes dos extratores. A partir do terceiro nível, há opções e grupos de opções do extrator.

Em JSON:

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

No YAML:

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

O valor de uma opção string do extrator precisa ser uma cadeia de caracteres ou um número (que será convertido em uma cadeia de caracteres antes que o processamento continue).

O valor de uma opção array do extrator precisa ser uma matriz de cadeias de caracteres ou números.

O valor de um grupo de opções (do tipo object) deve ser um mapa, que pode conter opções de extrator aninhadas e grupos de opções.

Cada valor de opção do extrator precisa corresponder ao padrão de expressão regular da opção do extrator (caso exista) e não pode conter caracteres de nova linha.

A atribuição de uma opção do extrator que não existe é um erro. Você pode fazer com que a CodeQL CLI ignore as opções do extrator desconhecidas usando o campo booliano especial __allow_unknown_properties. Por exemplo, o seguinte arquivo de opção solicita que a CodeQL CLI ignore todas as opções e os grupos de opções do extrator desconhecidos em group1:

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

Você pode especificar --extractor-options-file várias vezes. As atribuições de opção do extrator são processadas na seguinte ordem:

1. Todos os arquivos de opção do extrator especificados por --extractor-options-file são processados na ordem em que aparecem na linha de comando, depois
2. Todas as atribuições de opção do extrator especificadas por --extractor-option são processadas na ordem em que aparecem na linha de comando

As mesmas regras regem o que acontece quando a mesma opção do extrator é definida várias vezes, sejam as atribuições feitas usando --extractor-option, --extractor-options-fileou alguma combinação das duas opções. Se você definir uma opção string do extrator várias vezes, o último valor da opção substituirá todos os valores anteriores. Se você definir uma opção array do extrator várias vezes, todos os valores da opção serão concatenados na ordem estabelecida.