Exuberant Ctags#
Program ctags#
--langmap#
Argument --langmap
dla bieżącego wywołania programu ctags kontroluje stanem mapowań plików dla poszczególnych języków spośród wszystkich obsługiwanych języków (zarówno tych pochodzących z wbudowanych parserów, jak i tych z własnych wyrażeń regularnych), które będą brane pod uwagę przy generowaniu tagów dla analizowanych plików.
Opis działania#
Prawidłowe użycie argumentu najlepiej objaśnić na zapisie składniowym:
ctags --langmap[=value] [--argument | -argument] [path]
gdzie poszczególne człony oznaczają:
- ctags - ścieżka względna lub bezwzględna do pliku binarnego programu ctags (
ctags.exe
). Wszystko zależy od sposobu uruchamiania programu ctags, np. z systemowej konsoli, ze skrótu do programu czy z innego programu/skryptu. value - jedna z dwóch wartości tekstowych wpływająca na stan mapowań plików w poszczególnych językach (wielkość znaków nie ma znaczenia tylko w przypadku identyfikatorów języków):
"list"
- lista mapowań plików dla poszczególnych języków spośród wszystkich obsługiwanych języków w bieżącym wywołaniu programu ctags, które będą brane pod uwagę przy generowaniu tagów dla analizowanych plików. Separatorem między mapowaniami na liście jest znak przecinka (bez otaczania go dodatkowymi spacjami), np."lang1:patterns,lang2:patterns"
.Każde mapowanie plików # można wyrazić zapisem
"lang:patterns"
, gdzie najpierw podaje się identyfikator konkretnego języka, a za dwukropkiem umieszcza się listę ze wzorcami dla rozszerzeń plików i/lub wzorcami dla całych plików (tj. nazwy z ich ewentualnym rozszerzeniem), które będą kojarzone z tym językiem. Przy tworzeniu mapowań plików należy pamiętać o kilku regułach:- Poszczególnych wzorców na liście ze wzorcami nie rozdziela się żadnym dodatkowym separatorem, np.
"(plik1)(plik2)(plik3).a.b.c"
. - Wzorzec z rozszerzeniem pliku jest wskazywany poprzez rozpoczęcie go od znaku kropki, co można wyrazić zapisem
".pattern"
, np.".c"
. - Wzorzec z całym plikiem jest wskazywany poprzez umieszczenie go w nawiasach okrągłych, co można wyrazić zapisem
"(pattern)"
, np."(plik)"
czy"(plik.js)"
. - Dla każdego kolejnego wzorca z rozszerzeniem pliku program ctags najpierw usunie go z mapowań we wszystkich obsługiwanych językach, jeśli któryś z obsługiwanych języków używał tego samego wzorca, a dopiero potem doda go do listy mapowań w konkretnym języku. Z tego też powodu każdy wzorzec z rozszerzeniami plików jest unikatowy i nigdy nie zostanie powtórzony na liście mapowań plików we wszystkich obsługiwanych językach, co w przypadku wzorców z całymi plikami jest dopuszczalne.
- Przy analizowaniu plików wzorce dla rozszerzeń plików są porównywane przed wzorcami dla całych plików. Z tego też powodu wzorce z rozszerzeniami plików zawsze wyświetlane są przed wzorcami całych plików w liście zwracanej przez argument
−-list-maps
. - W przypadku ostatniej oficjalnej wersji programu ctags dla systemu Windows między wzorcami a analizowanymi plikami użyte zostaje proste porównanie tekstowe, gdzie umieszczone we wzorcach znaki wieloznaczności
*
i?
lub znaki grupujące w postaci nawiasów kwadratowych nie są obsługiwane. Zadecydował o tym brak funkcji+wildcards
ustawianej w czasie kompilacji, co można sprawdzić np. argumentem--version
. Mimo że znaki te są akceptowane przy definiowaniu wzorców i będą widoczne w liście zwracanej przez argument−-list-maps
to nie oznacza wcale, że zostaną obsłużone zgodnie z ich pierwotnym przeznaczeniem. - Pozostawienie pustej listy mapowań plików dla konkretnego języka oznacza anulowanie wszystkich zdefiniowanych do tej pory mapowań plików dla tego języka, np.
"lang:"
. - Zamiast listy ze wzorcami można podać specjalną wartość
"default"
, która przywraca domyślne mapowania plików dla konkretnego języka, np."lang:default"
. Dla języków zdefiniowanych za pomocą argumentu--langdef=lang
oznacza to brak jakichkolwiek mapowań plików, co jest równoważne z jawnym użyciem argumentu--langmap=lang:
dla konkretnego języka. - Jeśli lista ze wzorcami rozpoczyna się od dodatkowego prefiksu w postaci znaku
"+"
to wszystkie wzorce z tej listy zostaną dołączone do już istniejących wzorców dla danego języka. W przeciwnym razie nowe wzorce wymienione w liście zawsze zastąpią wszystkie już istniejące wzorce dla danego języka. Przykładowo zapis"c:.c.x,java:+.j"
oznacza, że tylko pliki z rozszerzeniami.c
i.x
zostaną skojarzone z językiem C, a pliki z rozszerzeniem.j
zostaną dodatkowo skojarzone z językiem Java. - Użycie we wzorcu znaku kroki, po którym nie wystąpi inny znak niż kropka oznacza wszystkie pliki bez rozszerzenia, co w programie ctags jest uznawane za wzorzec z rozszerzeniem pliku (z uwagi na użycie we wzorcu znaku kropki). W liście zwracanej przez argument
−-list-maps
wzorzec taki będzie wyświetlany jako"*."
. Warto zaznaczyć, że wzorzec całego pliku w postaci"(*.)"
również będzie wyświetlany na liście zwracanej przez argument−-list-maps
jako"*."
, ale jego rzeczywista obsługa jest zależna od danej kompilacji programu ctags.
- Poszczególnych wzorców na liście ze wzorcami nie rozdziela się żadnym dodatkowym separatorem, np.
"default"
- specjalna wartość przywracająca domyślne mapowania plików we wszystkich obsługiwanych językach dla bieżącego wywołania programu ctags. Dla języków zdefiniowanych za pomocą argumentu--langdef=lang
oznacza to brak mapowań, co jest równoważne z jawnym użyciem argumentu--langmap=lang:
dla każdego takiego języka z osobna.
- argument - jeden lub więcej dodatkowych argumentów dostrajających działanie programu ctags.
- path - jedna lub więcej dodatkowych ścieżek do plików/folderów, które będą analizowane przy generowaniu tagów (szczegóły).
Kilka uwag odnośnie stosowania argumentu --langmap
:
- Argument
--langmap
można podawać wielokrotnie (separatorem jest spacja), i każdy kolejny będzie miał wpływ tylko na te argumenty, które występują bezpośrednio po nim. - Przekazanie argumentu
--langmap
bez podania jakiejkolwiek wartości lub z pustą wartością""
zostanie całkowicie zignorowane (bez zgłaszania dodatkowego błędu czy ostrzeżenia). - Jeśli w mapowaniach plików kontrolowanych przez argument
--langmap
pojawi się identyfikator nieobsługiwanego języka to zwrócony zostanie komunikatctags: Warning: Unknown language "xxx" in "langmap" option
. - Mapowania plików we wszystkich obsługiwanych językach są istotne tylko i wyłącznie w trakcie automatycznego doboru właściwego języka dla analizowanych plików. Jeśli któryś z obsługiwanych języków został wyłączony za pomocą argumentu
--languages
to jego mapowania plików są pomijane przy analizowaniu plików. Stan wyłączenia dla wszystkich obsługiwanych języków można zweryfikować za pomocą argumentu--list-languages
, który za identyfikatorem pomijanego języka wyświetli dopisek"[disabled]"
. - Zadeklarowanie w argumencie
--langmap
pustej listy mapowań plików dla konkretnego języka spowoduje jego pominięcie w trakcie automatycznego doboru właściwego języka dla analizowanych plików, co jest równoznaczne z jawnym wyłączeniem tego języka za pomocą argumentu--languages
. - Listę mapowań plików dla języków obsługiwanych tylko przez wbudowane parsery można pobrać z informacji o wewnętrznym stanie programu zwracanych przez argumenty
--verbose
lub-v
(użytych jako inicjujący argument). Listę mapowań plików dla wszystkich obsługiwanych języków (z wbudowanych parserów oraz własnych wyrażeń regularnych) można pobrać za pomocą argumentu−-list-maps
.
Prosty przykład:
ctags --langmap="" --list-maps :: zignorowanie pustego argumentu '--langmap'
ctags --langmap= --list-maps :: zignorowanie pustego argumentu '--langmap'
ctags --langmap --list-maps :: zignorowanie pustego argumentu '--langmap'
ctags --langmap=c: --list-maps :: wyczyszczenie mapowań dla języka C
ctags --langmap=c:,php: --list-maps :: wyczyszczenie mapowań dla języka C i PHP
ctags --langmap=c:,php: --langmap=default --list-maps :: przywrócenie domyślnych mapowań dla wszystkich języków
ctags --langmap=c:,php: --langmap=c:default --list-maps :: przywrócenie domyślnych mapowań dla języka C
ctags --langmap=c:,php: --langmap=c:default,php:default --list-maps :: przywrócenie domyślnych mapowań dla języka C i PHP
ctags --list-maps=c :: lista mapowań dla języka C ma postać: *.c
ctags --langmap=c:.a.b --list-maps :: lista mapowań dla języka C ma postać: *.a *.b
ctags --langmap=c:+.a.b --list-maps :: lista mapowań dla języka C ma postać: *.c *.a *.b
ctags --langmap=c:.a+.b --list-maps :: lista mapowań dla języka C ma postać: *.a+ *.b
ctags --langmap=c:(a)(b) --list-maps :: lista mapowań dla języka C ma postać: a b
ctags --langmap=c:+(a)(b) --list-maps :: lista mapowań dla języka C ma postać: *.c a b
ctags --langmap=c:+(+a)(+b) --list-maps :: lista mapowań dla języka C ma postać: *.c +a +b
ctags --langmap=c:.java.htm.html --list-maps :: ustawienie rozszerzeń .java, .htm i .html dla języka C
ctags --langmap=c:+.java.htm.html --list-maps :: dodanie rozszerzeń .java, .htm i .html do języka C
ctags --langdef=new --list-maps :: lista mapowań dla języka new jest pusta
ctags --langdef=new --langmap=new:. --list-maps :: lista mapowań dla języka new ma postać: *.
ctags --langdef=new --langmap=new:.. --list-maps :: lista mapowań dla języka new ma postać: *.
ctags --langdef=new --langmap=new:..a.b. --list-maps :: lista mapowań dla języka new ma postać: *.a *.b *.
ctags --langdef=new --langmap=new:.a.b.c --list-maps :: lista mapowań dla języka new ma postać: *.a *.b *.c
ctags --langdef=new --langmap=new:.a.b.b.a --list-maps :: lista mapowań dla języka new ma postać: *.b *.a
ctags --langdef=new --langmap=new:.a[bc].[def] --list-maps :: lista mapowań dla języka new ma postać: *.a[bc] *.[def]
ctags --langdef=new --langmap=new:(*.) --list-maps :: lista mapowań dla języka new ma postać: *.
ctags --langdef=new --langmap=new:(abc) --list-maps :: lista mapowań dla języka new ma postać: abc
ctags --langdef=new --langmap=new:(a)(b)(c) --list-maps :: lista mapowań dla języka new ma postać: a b c
ctags --langdef=new --langmap=new:(a[bc])([def]) --list-maps :: lista mapowań dla języka new ma postać: a[bc] [def]
ctags --langdef=new --langmap=new:(a)(a)(b)(b) --list-maps :: lista mapowań dla języka new ma postać: a a b b
ctags --langdef=new --langmap=new:.a.b(c)(d) --list-maps :: lista mapowań dla języka new ma postać: *.a *.b c d
ctags --langdef=new --langmap=new:(c)(d).a.b --list-maps :: lista mapowań dla języka new ma postać: *.a *.b c d
ctags --langdef=new --langmap=new:.a(c).b(d) --list-maps :: lista mapowań dla języka new ma postać: *.a *.b c d
ctags --langdef=new --langmap=new:.a(b) --langmap=default --list-maps :: lista mapowań dla języka new jest pusta
ctags --langdef=new --langmap=new:.a(b) --langmap=new:default --list-maps :: lista mapowań dla języka new jest pusta
:: Błędne przypadki
ctags --langmap=DEFAULT
ctags --langmap=html
ctags --langmap=cos
ctags --langmap=cos:
ctags --langmap=c:a, b