Comando ctags do Linux

Em sistemas operacionais do tipo Unix, o comando ctags cria arquivos de tags para o código- fonte .

Descrição

Os programas ctags e etags (daqui em diante referidos coletivamente como ctags , exceto onde distinguidos) geram um arquivo de índice (ou “tag”) para uma variedade de objetos de idioma encontrados no (s) arquivo (s) especificado (s). Esse arquivo de tag permite que esses itens sejam localizados rápida e facilmente por um editor de texto ou outro utilitário . Uma “marca” significa um objeto de idioma para o qual uma entrada de índice está disponível (ou a entrada de índice criada para esse objeto).

Como alternativa, ctags pode gerar um arquivo de referência cruzada que lista, de forma legível por humanos, informações sobre os vários objetos de origem encontrados em um conjunto de arquivos de idioma.

Os arquivos de índice de tags são suportados por vários editores, que permitem ao usuário localizar o objeto associado a um nome que aparece em um arquivo de origem e pular para o arquivo e a linha que define o nome. Esses incluem:

• vi e seus derivados (por exemplo, Elvis , Vim , Vile , Lemmy )
• CRiSP
• Emacs
• FTE (editor de texto dobrável)
• JED
• jEdit
• Minado
• NEdit (Edição do Nirvana)
• TSE (o editor do SemWare)
• UltraEdit
• Área de trabalho
• X2
• Zeus

O ctags é capaz de gerar diferentes tipos de tags para cada um dos muitos idiomas diferentes. Para obter uma lista completa dos idiomas suportados, os nomes pelos quais são reconhecidos e os tipos de tags gerados para cada um, consulte as opções –list-languages e –list-types .

Arquivos Fonte

A menos que a opção –language-force seja especificada, o idioma de cada arquivo de origem é selecionado automaticamente com base no mapeamento dos nomes dos arquivos para os idiomas. Os mapeamentos em vigor para cada idioma podem ser exibidos usando a opção –list-maps e podem ser alterados usando a opção –langmap . Nas plataformas que o suportam, se o nome de um arquivo não estiver mapeado para um idioma e o arquivo for executável , a primeira linha do arquivo será verificada para verificar se o arquivo é um script ” #! ” Para um idioma reconhecido.

Por padrão, todos os outros nomes de arquivos são ignorados. Isso permite executar ctags em todos os arquivos em um único diretório (por exemplo, ” ctags * “) ou em todos os arquivos em uma árvore inteira de diretórios de origem (por exemplo, ” ctags -R “), uma vez que somente os arquivos cujos nomes são mapeados para idiomas serão verificados.

O motivo pelo qual extensões .h são mapeadas para arquivos C ++ em vez de arquivos C é porque é comum usar extensões .h no C ++, e nenhum dano resulta em tratá-las como arquivos C ++.

Sintaxe

   ctags [options] [file(s)]

   etags [options] [file(s)]

Opções

Apesar da variedade de opções disponíveis, os padrões são definidos para que ctags seja executado normalmente sem nenhuma opção (por exemplo, ” ctags * ” ou ” ctags -R “), que criará um arquivo de tag no diretório atual para todas as fontes reconhecidas arquivos. As opções descritas abaixo são fornecidas apenas para permitir a personalização personalizada para atender a necessidades especiais.

Observe que os espaços que separam as opções de letra única de seus parâmetros são opcionais.

Observe também que os parâmetros booleanos para as opções de formato longo (aqueles que começam com ” – ” e que usam o parâmetro ” [= yes | no] “) podem ser omitidos; nesse caso, ” = yes ” está implícito. (por exemplo, –sort é equivalente a –sort = yes ). Observe também que ” = 1 ” e ” = on ” são considerados sinônimos para ” = yes ” e que ” = 0 ” e ” = off ” são considerados sinônimos para ” = no “.

Algumas opções são ignoradas ou úteis apenas quando usadas durante a execução no modo etags (consulte a opção -e ). Tais opções serão anotadas.

A maioria das opções pode aparecer em qualquer lugar da linha de comando , afetando apenas os arquivos que seguem a opção. Algumas opções, no entanto, devem aparecer antes do primeiro nome do arquivo e serão anotadas como tal.

As opções que adotam nomes de idiomas aceitarão esses nomes em maiúsculas ou minúsculas. Veja a opção –list-languages para obter uma lista completa dos nomes dos idiomas embutidos.

As opções são:

  int foo ARGDECL4 (void *, ptr, long int, nbytes)

  / * cria uma cadeia de versão RCS no módulo * / 
 MODULE_VERSION ("$ Revisão: 690 $")

  Exemplo CLASS {// seu conteúdo aqui};

Detalhes operacionais

Como ctags considera o nome de cada arquivo, tenta determinar o idioma do arquivo aplicando os três testes a seguir em ordem: se a extensão do arquivo foi mapeada para um idioma, se o nome do arquivo corresponder a um padrão de shell mapeado para um idioma e, finalmente, se o arquivo for executável e sua primeira linha especificar um intérprete usando a especificação “#!” no estilo Unix (se houver suporte na plataforma). Se um idioma foi identificado, o arquivo é aberto e o analisador de idioma apropriado é chamado para operar no arquivo aberto no momento. O analisador analisa o arquivo e adiciona uma entrada ao arquivo de tags para cada objeto de idioma para o qual ele foi gravado. Consulte Tag File Format, abaixo, para obter detalhes sobre essas entradas.

As implementações mais recentes de ctags não impõem requisitos de formatação no código C, assim como as implementações herdadas. As implementações mais antigas de ctags tendiam a depender de certas suposições de formatação para ajudá-lo a resolver dilemas de codificação causados ​​por condicionais do pré-processador.

Em geral, o ctags tenta ser inteligente quanto às diretivas condicionais do pré-processador. Se um condicional do pré-processador for encontrado em uma instrução que define uma tag, ctags segue apenas o primeiro ramo dessa condicional (exceto no caso especial de “#if 0”, caso em que segue apenas o último ramo). A razão para isso é que não buscar apenas uma ramificação pode resultar em sintaxe ambígua, como no exemplo a seguir:

#ifdef TWO_ALTERNATIVES struct {#else union {#endif short a; b longo; }

Os dois ramos não podem ser seguidos, ou as chaves se tornam desequilibradas e as ctags seriam incapazes de entender a sintaxe. Se a aplicação dessa heurística falhar na análise adequada de um arquivo, geralmente devido ao emparelhamento complicado e inconsistente nos condicionais, ctags tentará novamente o arquivo usando uma heurística diferente que não segue seletivamente ramificações condicionais de pré-processador, mas volta a confiar em um chave de fechamento (“}”) na coluna 1 como indicando o fim de um bloco, uma vez que qualquer desequilíbrio de chave resulta de seguir um #if ramo condicional.

O ctags também tentará lidar especialmente com listas de argumentos entre conjuntos de parênteses duplos para aceitar a seguinte construção condicional:

extern void foo __ARGS ((int um, caractere dois));

Qualquer nome imediatamente anterior a “((” será automaticamente ignorado e o nome anterior será usado. As definições de operador do C ++ são tratadas especialmente. Para consistência com todos os tipos de operadores (sobrecarregados e de conversão)), o nome do operador no arquivo de tags sempre será ser precedido pela string “operator” (ou seja, mesmo que a definição real do operador tenha sido gravada como “operator <<“).

Após criar ou anexar ao arquivo de tags, ele é classificado pelo nome da tag, removendo linhas de tags idênticas.

Formato de arquivo de tag

Quando não está sendo executado no modo etags, cada entrada no arquivo de tags consiste em uma linha separada, cada uma parecida com esta no caso mais geral:

tag_name <TAB> nome_do_arquivo <TAB> ex_cmd; “<TAB> campos_de extensão

Os campos e separadores dessas linhas são especificados da seguinte maneira:

nome da tag;
caractere de tabulação única;
nome do arquivo no qual o objeto associado à tag está localizado;
caractere de tabulação única;
Comando EX usado para localizar a tag dentro do arquivo; geralmente um padrão de pesquisa (/ pattern / ou? pattern?) ou número de linha (consulte –excmd). O formato de arquivo de tag 2 (consulte –format) estende esse comando EX sob certas circunstâncias para incluir um conjunto de campos de extensão (descritos abaixo) incorporados em um comentário EX imediatamente anexado ao comando EX, o que o torna compatível com versões anteriores das implementações originais do vi .

Algumas tags especiais são gravadas no arquivo de tags para fins internos. Essas tags são compostas de forma que sempre sejam classificadas na parte superior do arquivo. Portanto, os dois primeiros caracteres dessas tags são usados ​​como um número mágico para detectar um arquivo de tags com o objetivo de determinar se um arquivo de tag válido está sendo substituído e não um arquivo de origem.

Observe que o nome de cada arquivo de origem será gravado no arquivo de tags exatamente como aparece na linha de comando. Portanto, se o caminho que você especificou na linha de comando for relativo ao diretório atual, ele será gravado da mesma maneira no arquivo de tags. Consulte, no entanto, a opção –tag-related para saber como esse comportamento pode ser modificado.

Os campos de extensão são pares de valores-chave separados por tabulação anexados ao final do comando EX como um comentário, conforme descrito acima. Esses pares de valores-chave aparecem na forma geral “chave: valor”. Sua presença nas linhas do arquivo de tags é controlada pela opção –fields. As chaves possíveis e o significado de seus valores são os seguintes:

acesso Indica a visibilidade deste membro da classe, em que o valor é específico para o idioma.
Arquivo Indica que a tag tem visibilidade limitada ao arquivo. Esta chave não tem valor correspondente.
tipo Indica o tipo ou tipo de tag. Seu valor é um dos sinalizadores de uma letra correspondentes descritos nas várias opções <LANG> -kinds acima, ou um nome completo. É permitido (e é, de fato, o padrão) que a parte principal desse campo seja omitida. Os comportamentos opcionais são controlados com a opção –fields.
implementação Quando presente, isso indica uma implementação limitada (abstrata versus concreta) de uma rotina ou classe, em que o valor é específico da linguagem (“virtual” ou “virtual pura” para C ++; “abstrata” para Java).
herda Quando presente, value é uma lista separada por vírgula de classes da qual essa classe é derivada (isto é, herda de).
assinatura Quando presente, valor é uma representação dependente do idioma da assinatura de uma rotina. Uma assinatura de rotina em sua forma completa especifica o tipo de retorno de uma rotina e sua lista formal de argumentos. Atualmente, este campo de extensão é suportado apenas para idiomas baseados em C e não inclui o tipo de retorno.

Além disso, informações sobre o escopo da definição de marca podem estar disponíveis, com a parte da chave igual a algum nome de construção dependente do idioma e seu valor o nome declarado para essa construção no programa. Esta entrada de escopo indica o escopo em que a tag foi encontrada. Por exemplo, uma tag gerada para um membro da estrutura C teria um escopo parecido com “struct: myStruct”.

Como usar com o Vi

O Vi, por padrão, espera um arquivo de tags com o nome “tags” no diretório atual. Depois que o arquivo de tags é criado, os seguintes comandos exercitam o recurso de indexação de tags:

tag vi -t

Inicie vi e posicione o cursor no arquivo e na linha em que “tag” está definido.

: ta tag

Encontre uma etiqueta.

Ctrl-]

Encontre a tag abaixo do cursor.

Ctrl-T

Retorne ao local anterior antes de pular para a tag (não amplamente implementada).

Como usar com o Gnu Emacs

O Emacs, por padrão, espera um arquivo de tag com o nome “TAGS” no diretório atual. Depois que o arquivo de tags é criado, os seguintes comandos exercitam o recurso de indexação de tags:

Mx visit-tags-table <RET> ARQUIVO <RET>

Selecione o arquivo de tag “FILE” para usar.

M-. [TAG] <RET>

Encontre a primeira definição de TAG. A tag padrão é o identificador abaixo do cursor.

M- *

Volte para onde você invocou anteriormente “M-“.

Porra-.

Encontre a próxima definição para a última tag.

Como usar com o Nedit

O NEdit versão 5.1 e posterior pode lidar com o novo formato de arquivo de tag estendido (consulte –format). Para fazer o NEdit usar o arquivo de tags, selecione “Arquivo-> Carregar arquivo de tags”. Para pular para a definição de uma tag, realce a palavra e pressione Ctrl-D. O NEdit 5.1 pode ler vários arquivos de tags de diferentes diretórios. Definir o recurso X nedit.tagFile como o nome de um arquivo de tag instrui o NEdit a carregar automaticamente esse arquivo de tag no momento da inicialização.

Ressalvas

Because ctags is neither a preprocessor nor a compiler, use of preprocessor macros can fool ctags into either missing tags or improperly generating inappropriate tags. Although ctags has been designed to handle certain common cases, this is the single biggest cause of reported problems. In particular, the use of preprocessor constructs which alter the textual syntax of C can fool ctags . You can work around many such problems by using the -I option.

Note that since ctags generates patterns for locating tags (see the –excmd option), it is entirely possible that the wrong line may be found by your editor if there exists another source line that is identical to the line containing the tag. The following example demonstrates this condition:

 int variable;
/* ... */
void foo(variable)
int variable;
 {
    /* ... */
 }

Depending upon what editor you use and where in the code you happen to be, it is possible that the search pattern may locate the local parameter declaration in foo() before it finds the actual global variable definition, since the lines (and therefore their search patterns are identical). This can be avoided by use of the –excmd=n option.

Bugs conhecidos

When parsing a C++ member function definition (eg, ” className::function “), ctags cannot determine whether the scope specifier is a class name or a namespace specifier and always lists it as a class name in the scope portion of the extension fields. Also, if a C++ function is defined outside of the class declaration (the usual case), the access specification (ie public , protected , or private ) and implementation information (eg, virtual , pure virtual ) contained in the function declaration are not known when the tag is generated for the function definition. It will, however be available for prototypes (eg –c++-kinds=+p ).

No qualified tags are generated for language objects inherited into a class.

variáveis ​​ambientais

arquivos

• /ctags.cnf (apenas no MS-DOS e Microsoft Windows )
• /etc/ctags.conf
• /usr/local/etc/ctags.conf
• $ HOME / .ctags
• $ HOME / ctags.cnf (apenas no MS-DOS, Microsoft Windows)
• .ctags
• ctags.cnf (apenas no MS-DOS, Microsoft Windows)

Se algum desses arquivos de configuração existir, espera-se que cada um deles contenha um conjunto de opções padrão lidas na ordem listada quando as ctags forem iniciadas, mas antes que a variável de ambiente CTAGS seja lida ou que qualquer opção de linha de comando seja lida. Isso possibilita a configuração de padrões em todo o site, pessoal ou em nível de projeto. É possível compilar ctags para ler um arquivo de configuração adicional antes de qualquer um dos mostrados acima, o que será indicado se a saída produzida pela opção –version listar o recurso ” custom-conf “. Opções que aparecem no CTAGSvariável de ambiente ou na linha de comando substituirá as opções especificadas nesses arquivos. Somente opções serão lidas nesses arquivos. Observe que os arquivos de opções são lidos no modo orientado a linhas, no qual os espaços são significativos (uma vez que a citação do shell não é possível). Cada linha do arquivo é lida como um parâmetro de linha de comando (como se estivesse entre aspas simples). Portanto, use novas linhas para indicar argumentos de linha de comando separados.

• tags (o arquivo de tags padrão criado por ctags .)
• TAGS (o arquivo de tag padrão criado por etags .)

Exemplos

 ctags -R *

Crie um arquivo de tags para cada arquivo de origem no diretório atual e em todos os subdiretórios.

Comandos relacionados

ex – modo editor de linha do editor detexto vi .
lex – Gere programas para executar tarefas lexicais.
vgrind – “Grind”listagens de programas legais .
vi – Editor de texto baseado no modo visual de ex .
yacc – “Mais um compilador-compilador.”