ctags(1)

NAMN

ctags – skapa taggfiler för källkod

SYNOPSIS

ctags [optioner] [fil(er)]
etags [optioner] [fil(er)]

BESKRIVNING

Programmen ctags och etags kallas i denna manualsida gemensamt för ctags, utom där de behöver skiljas åt.

ctags skapar en indexfil, en så kallad taggfil, för olika typer av språkobjekt som hittas i angivna källfiler. Taggfilen gör att dessa objekt snabbt och enkelt kan hittas av en textredigerare eller ett annat verktyg.

En tagg betecknar ett språkobjekt som har en indexpost, eller själva indexposten som skapats för objektet.

Alternativt kan ctags skapa en korsreferensfil som i läsbar form listar information om olika källkodsobjekt som hittas i en uppsättning språkfiler.

Taggindexfiler stöds av många redigerare. De gör att användaren kan hitta objektet som hör till ett namn som förekommer i en källfil och hoppa till den fil och rad där namnet definieras.

Redigerare som var kända vid tidpunkten för denna version är bland annat:

• vi(1) och dess efterföljare, till exempel Elvis, Vim, Vile och Lemmy
• CRiSP
• Emacs
• FTE, Folding Text Editor
• JED
• jEdit
• Mined
• NEdit, Nirvana Edit
• TSE, The SemWare Editor
• UltraEdit
• WorkSpace
• X2
• Zeus

ctags kan skapa olika slags taggar för många olika programmeringsspråk. En fullständig lista över språk som stöds, vilka namn de känns igen under och vilka taggtyper som skapas för varje språk visas med optionerna --list-languages och --list-kinds.

KÄLLFILER

Om optionen --language-force inte anges väljs språket för varje källfil automatiskt utifrån en mappning mellan filnamn och språk.

Aktiva mappningar för varje språk kan visas med:

--list-maps

De kan ändras med:

--langmap

På plattformar som stöder det kontrolleras första raden i en körbar fil, om filnamnet inte redan är mappat till ett språk. Om första raden anger ett #!-skript för ett känt språk används detta språk.

Som standard ignoreras alla andra filnamn. Detta gör att man kan köra exempelvis:

ctags *
ctags -R

eftersom endast filer vars namn är mappade till språk kommer att skannas.

Anledningen till att filändelsen .h mappas till C++ i stället för C är att .h ofta används i C++ och att det normalt inte gör någon skada att behandla sådana filer som C++.

OPTIONER

Trots det stora antalet optioner är standardvärdena valda så att ctags oftast kan köras utan optioner.

Exempel:

ctags *
ctags -R

Dessa kommandon skapar en taggfil i aktuell katalog för alla igenkända källfiler.

Optionerna nedan finns främst för att kunna anpassa körningen efter särskilda behov.

Blanksteg mellan en kort option och dess argument är valfritt.

Booleska argument till långa optioner som börjar med -- och tar ett argument av formen:

[=yes|no]

kan utelämnas. Då antas =yes.

Exempel:

--sort

är detsamma som:

--sort=yes

Värdena =1 och =on räknas som synonymer till =yes. Värdena =0 och =off räknas som synonymer till =no.

Vissa optioner ignoreras, eller är endast användbara, när programmet körs i etags-läge. Sådana optioner anges särskilt.

De flesta optioner kan anges var som helst på kommandoraden och påverkar då endast de filer som följer efter optionen. Några optioner måste däremot anges före det första filnamnet; detta anges i respektive beskrivning.

Optioner som tar språknamn accepterar dessa namn oavsett versaler eller gemener. En fullständig lista över inbyggda språknamn visas med:

--list-languages

-a

Motsvarar:

--append

-B

Använd bakåtriktade sökmönster, till exempel:

?mönster?

Ignoreras i etags-läge.

-e

Aktivera etags-läge. Då skapas en taggfil som är avsedd för Emacs.

Om ctags körs under ett namn som innehåller strängen etags, till exempel genom att körbar fil har bytt namn eller via en länk, aktiveras etags-läge automatiskt.

Denna option måste anges före första filnamnet.

-f taggfil

Använd namnet taggfil för taggfilen.

Standard är:

tags

eller, i etags-läge:

TAGS

Om taggfil anges som:

-

skrivs taggfilen till standardutmatningen.

ctags vägrar skriva till en befintlig fil om filens första rad inte innehåller en giltig taggrad. Detta skyddar mot misstag som:

ctags -f *.c

som annars hade skrivit över den första C-filen med taggar skapade från resten av filerna.

Programmet vägrar också acceptera ett fler­teckens filnamn som börjar med bindestreck, eftersom det oftast betyder att användaren glömt ange taggfilens namn och att optionen råkade ta nästa option som filnamn.

Om man verkligen vill kalla taggfilen:

-ugly

ska den anges som:

./-ugly

Denna option måste anges före första filnamnet. Om den anges flera gånger gäller endast den sista.

-F

Använd framåtriktade sökmönster, till exempel:

/mönster/

Detta är standard.

Ignoreras i etags-läge.

-h lista

Anger en lista med filändelser, separerade med punkter, som ska tolkas som include- eller headerfiler.

För att ange filer utan filändelse används en punkt som inte följs av ett annat icke-punkttecken, till exempel:

.
..x
.x.

Optionen påverkar endast hur räckvidden för vissa taggtyper tolkas, alltså om de betraktas som globalt synliga eller endast synliga inom den fil där de definieras. Den mappar inte filändelsen till något särskilt språk.

En tagg som finns i en fil som inte är en include-fil, och som inte kan ses från någon annan fil, betraktas som filbegränsad, exempelvis som static i C.

Ingen taggtyp som förekommer i en include-fil betraktas som filbegränsad.

Om första tecknet i listan är plustecken läggs ändelserna i listan till i den aktuella listan. Annars ersätter listan den aktuella listan.

Se även:

--file-scope

Standardlistan är:

.h.H.hh.hpp.hxx.h++.inc.def

För att återställa standardlistan:

-h default

Om en filändelse som anges här inte redan är mappad till ett språk måste också --langmap eller --language-force användas.

-I identifierarlista

Anger en lista över identifierare som ska hanteras särskilt när C- och C++-källfiler tolkas.

Denna option finns särskilt för specialfall som uppstår vid användning av preprocessormakron.

Om identifierarna i listan är enkla identifierare ignoreras de under parsning. Om en identifierare avslutas med tecknet + ignorerar ctags även en omedelbart efterföljande parentesomsluten argumentlista.

Om två identifierare skiljs åt med tecknet = ersätts den första identifieraren med den andra under parsning.

Listan kan anges direkt på kommandoraden eller läsas från en separat fil.

Om första tecknet i identifierarlista är:

• @
• .
• en sökvägsavgränsare, till exempel / eller \
• eller om de två första tecknen anger en enhetsbokstav, till exempel C:

tolkas argumentet som ett filnamn. Filen ska då innehålla en identifierare per rad.

I annat fall tolkas argumentet som en lista över identifierare eller identifierarpar. Dessa avgränsas med kommatecken eller blanktecken. Om blanktecken används måste listan citeras så att den förblir ett enda kommandoradsargument.

Flera -I-optioner kan anges.

För att rensa listan över ignorerade identifierare anges ett enda bindestreck:

-I -

Denna funktion är användbar när preprocessormakron används på sätt som stör syntaxen.

Exempel:

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

Här skulle makrot ARGDECL4 felaktigt kunna tolkas som funktionsnamn i stället för det korrekta namnet foo. Detta undviks med:

-I ARGDECL4

Exempel:

/* creates an RCS version string in module */
MODULE_VERSION("$Revision: 690 $")

Makroanropet ovan kan likna en funktionsdefinition eftersom det inte följs av semikolon. Det kan till och med följas av en global variabeldefinition som ser ut som en K&R-liknande parameterdeklaration. Detta kan få ctags att försöka läsa resten av filen som en funktionsdefinition.

Det kan undvikas med:

-I MODULE_VERSION+

Exempel:

CLASS Example {
// your content here
};

Här används CLASS som ett preprocessormakro som expanderar olika på olika plattformar. På Win32 kan det exempelvis expandera till:

class __declspec(dllexport)

och på UNIX till:

class

Eftersom nyckelordet class saknas i källtexten kan filen annars tolkas felaktigt. Detta kan korrigeras med:

-I CLASS=class

-L fil

Läs från fil en lista över filnamn som taggar ska skapas för.

Om fil anges som:

-

läses filnamnen från standardinmatningen.

Filnamn som läses med denna option behandlas efter filnamn som anges på kommandoraden. Även optioner accepteras i indata.

Om optionen anges mer än en gång gäller endast den sista.

Filen läses radvis. Nyrad är den enda avgränsaren, och blanktecken som inte finns i slutet av raden betraktas som betydelsefulla. Därmed kan filnamn som innehåller blanksteg anges. Slutblanktecken tas däremot bort från raderna.

Detta kan påverka hur optioner tolkas om de anges i indata.

-n

Motsvarar:

--excmd=number

-N

Motsvarar:

--excmd=pattern

-o taggfil

Motsvarar:

-f taggfil

-R

Motsvarar:

--recurse

-u

Motsvarar:

--sort=no

Alltså osorterad utmatning.

-V

Motsvarar:

--verbose

-w

Denna option ignoreras tyst av bakåtkompatibilitetsskäl med ctags från SVR4 Unix.

-x

Skriv en tabellformad, läsbar korsreferensfil till standardutmatningen i stället för att skapa en taggfil.

Informationen i utmatningen innehåller:

• taggnamn
• taggtyp
• radnummer
• filnamn
• källrad, med extra blanktecken sammanpressade

Ingen taggfil skrivs och alla optioner som påverkar taggfilsutmatning ignoreras.

Exempel på användning:

Lista alla funktioner i en källfil:

ctags -x --c-kinds=f fil

Lista alla externt synliga globala variabler i en källfil:

ctags -x --c-kinds=v --file-scope=no fil

Denna option måste anges före första filnamnet.

--append[=yes|no]

Anger om taggar som skapas från angivna filer ska läggas till i en befintlig taggfil eller ersätta den.

Optionen är avstängd som standard.

Den måste anges före första filnamnet.

--etags-include=fil

Inkludera en referens till fil i taggfilen.

Optionen kan anges hur många gånger som helst.

Detta stöder Emacs-funktionen att använda en taggfil som inkluderar andra taggfiler.

Endast tillgänglig i etags-läge.

--exclude=[mönster]

Lägg till mönster i listan över filer och kataloger som ska uteslutas.

Optionen kan anges flera gånger.

För varje filnamn som ctags överväger jämförs varje uteslutningsmönster mot både:

• hela sökvägen, exempelvis some/path/base.ext
• basnamnet, exempelvis base.ext

Detta gör det möjligt att ange mönster som matchar ett filnamn oberoende av sökväg eller endast en viss sökväg.

Om C-kompilatorns körbibliotek ger stöd för det kan mönster innehålla vanliga skaljokertecken från UNIX. De är inte reguljära uttryck. Kom ihåg att citera optionen så att skalet inte expanderar jokertecknen innan de skickas till ctags.

Jokertecken kan även matcha snedstrecket /.

Man kan se om jokertecken stöds genom att granska utmatningen från:

--version

Om +wildcards finns i listan över kompilerade funktioner stöds jokertecken. Annars jämförs mönster mot filnamn med enkel textjämförelse.

Om mönster börjar med @ tolkas resten av strängen som ett filnamn. Från den filen läses uteslutningsmönster, ett per rad.

Om mönster är tomt rensas listan över uteslutningsmönster.

Vid programstart innehåller standardlistan:

EIFGEN
SCCS
RCS
CVS

Detta är katalognamn som det normalt inte är önskvärt att gå ned i när --recurse används.

--excmd=typ

Bestämmer vilken typ av EX-kommando som används för att hitta taggar i källfilen.

Ignoreras i etags-läge.

Giltiga värden är:

number

Använd endast radnummer i taggfilen för att hitta taggar.

Detta har flera fördelar:

1. Taggfilen blir betydligt mindre.
2. Man undviker att taggar inte hittas därför att raden som definierar taggen ändrats så att sökmönstret inte längre matchar.
3. Man undviker att en identisk men felaktig källrad hittas.
4. Separata poster bevaras för rader som har identiskt innehåll.

Nackdelen är att ändringar i källfilerna kan göra att radnumren i taggfilen inte längre motsvarar rätt rader i källfilen. Hopp till vissa taggar kan då hamna en eller flera rader fel.

Denna typ lämpar sig därför bäst för källkod som inte ändras.

När denna typ väljs ignoreras optionerna:

-B
-F

pattern

Använd endast sökmönster för alla taggar, i stället för radnummer.

Fördelen är att man inte hänvisar till föråldrade radnummer när rader har lagts till eller tagits bort efter att taggfilen skapades.

mixed

Använd i allmänhet mönster, men med vissa undantag.

För C används radnummer för makrodefinitionstaggar. Detta var standardformatet i den ursprungliga ctags och behålls därför som standard för denna option.

För Fortran används radnummer för common-block eftersom deras källrader ofta är identiska, vilket gör mönstersökningar oanvändbara för att hitta alla träffar.

--extra=[+|-]flaggor

Anger om extra taggposter ska inkluderas för vissa typer av information.

Argumentet flaggor är en uppsättning enbokstavsflaggor där varje flagga representerar en extra taggpost som ska inkluderas.

Om flaggor föregås av + eller - läggs respektive tas varje flagga till eller bort från de flaggor som redan är aktiverade. Annars ersätter flaggorna aktuella inställningar.

Giltiga flaggor:

f

Inkludera en post för basfilnamnet för varje källfil, exempelvis example.c. Denna post pekar på första raden i filen.

q

Inkludera en extra klasskvalificerad taggpost för varje tagg som är medlem i en klass, för språk där denna information extraheras. Detta gäller för närvarande C++, Eiffel och Java.

Den faktiska formen beror på språket:

• C++: klass::medlem
• Eiffel och Java: klass.medlem

Detta kan göra det lättare att hitta rätt tagg när samma taggnamn förekommer flera gånger. Det kan dock mer än fördubbla taggfilens storlek.

--fields=[+|-]flaggor

Anger vilka utökade fält som ska ingå i taggfilsposterna.

Argumentet flaggor är en uppsättning enbokstavsflaggor.

Följande flaggor stöds:

a

Åtkomst, eller export, för klassmedlemmar.

f

Filbegränsad räckvidd. Aktiverad som standard.

i

Arvsinformation.

k

Taggtyp som en enda bokstav. Aktiverad som standard.

K

Taggtyp som fullständigt namn.

l

Språk för källfilen som innehåller taggen.

m

Implementationsinformation.

n

Radnummer för taggdefinitionen.

s

Räckvidd för taggdefinitionen. Aktiverad som standard.

S

Signatur för rutin, till exempel prototyp eller parameterlista.

z

Inkludera nyckeln kind: i fältet för taggtyp.

t

Typ och namn för en variabel eller typedef som fältet typeref:. Aktiverad som standard.

Varje bokstav eller grupp av bokstäver kan föregås av + för att läggas till i standardmängden eller - för att tas bort.

Om inget + eller - anges inkluderas endast de fält som uttryckligen anges.

Optionen ignoreras om:

--format=1

har angetts.

Standardvärdet är:

fkst

--file-scope[=yes|no]

Anger om taggar som endast har räckvidd inom en enskild fil ska inkluderas i utmatningen.

Detta gäller exempelvis taggar som inte kan ses utanför filen där de definieras, som static-taggar i C.

Se även:

-h

Optionen är aktiverad som standard.

--filter[=yes|no]

Får ctags att bete sig som ett filter.

Källfilnamn läses från standardinmatningen och taggar skrivs till standardutmatningen fil för fil.

Om --sorted är aktiverat sorteras taggar endast inom den källfil där de definieras.

Filnamn läses radvis från standardinmatningen och först efter filnamn som anges på kommandoraden eller via -L.

När denna option är aktiverad ignoreras:

-f
-o
--totals

Optionen är ovanlig och avstängd som standard.

Den måste anges före första filnamnet.

--filter-terminator=sträng

Anger en sträng som skrivs till standardutmatningen efter taggarna för varje fil när --filter är aktiverad.

Detta kan göra det möjligt för ett program som läser ctags-utmatningen att avgöra när utmatningen för varje fil är färdig.

Om filnamnet som läses är en katalog och --recurse är aktiverad skrivs strängen endast en gång, efter alla taggar som hittats genom att gå ned i katalogen.

Strängen skiljs alltid från sista taggraden för filen med en avslutande nyrad.

Optionen är ovanlig och är tom som standard.

Den måste anges före första filnamnet.

--format=nivå

Ändra formatet för den taggfil som skapas.

Giltiga värden är för närvarande:

1
2

Nivå 1 anger det ursprungliga taggfilformatet.

Nivå 2 anger ett nyare utökat format med utökade fält, men på ett sätt som behåller bakåtkompatibilitet med ursprungliga vi(1)-implementationer.

Standardnivån är 2.

Denna option måste anges före första filnamnet.

Ignoreras i etags-läge.

--help

Skriv en detaljerad användningsbeskrivning till standardutmatningen och avsluta.

--if0[=yes|no]

Anger om kod inuti en #if 0-gren i en preprocessorvillkorssats ska undersökas för andra taggar än makron. Makrotaggar inkluderas alltid.

Eftersom syftet med #if 0 normalt är att inaktivera kod är standardvärdet:

no

Observera att detta endast anger en preferens. Det garanterar inte att kod inuti en #if 0-gren hoppas över, eftersom reservalgoritmen som används när preprocessorvillkor är för komplexa följer alla grenar.

Optionen är avstängd som standard.

--<LANG>-kinds=[+|-]typer

Anger en lista över språkspecifika taggtyper som ska inkluderas i utmatningen för ett visst språk.

I optionsnamnet ersätts <LANG> med ett språknamn. Det är inte skiftlägeskänsligt och måste vara ett av de inbyggda språknamnen.

Argumentet typer är en grupp enbokstavsflaggor som anger taggtyper för språket.

De särskilda flaggorna, deras betydelser och standardvärden visas med:

--list-kinds

Varje bokstav eller grupp av bokstäver kan föregås av + för att läggas till eller - för att tas bort från standardmängden.

Om inget + eller - anges inkluderas endast de uttryckligen angivna typerna.

Exempel för C:

Lägg till prototyper och externa variabeldeklarationer till standardmängden, men uteslut makron:

--c-kinds=+px-d

Inkludera endast funktionstaggar:

--c-kinds=f

--langdef=namn

Definierar ett nytt användardefinierat språk, namn, som ska tolkas med reguljära uttryck.

När språket har definierats kan namn användas i andra optioner som tar språknamn.

Typisk användning är:

1. definiera språket med --langdef
2. mappa filnamn till språket med --langmap
3. ange reguljära uttryck med --regex-<LANG> för att definiera hur taggar hittas

--langmap=mappning[,mappning[...]]

Styr hur filnamn mappas till språk.

Varje kommaseparerad mappning består av:

• språknamn
• kolon
• lista över filändelser och/eller filnamnsmönster

En filändelse anges med punkt framför, exempel:

.c

Ett filnamnsmönster anges inom parentes, exempel:

([Mm]akefile)

Om jokertecken stöds av körbiblioteket kan filnamnsmönster innehålla vanliga skaljokertecken. Citera optionen så att skalet inte expanderar dem innan de skickas till ctags.

Stöd för jokertecken visas i --version som:

+wildcards

När en filändelse mappas tas den först bort från eventuella andra språk.

Om första tecknet i en mappning är plustecken läggs filändelser och filnamnsmönster till i aktuell mappning för språket. Annars ersätter mappningen den aktuella mappningen.

Exempel: behandla endast filer med ändelserna .c och .x som C:

--langmap=c:.c.x

Lägg dessutom till filer med ändelsen .j som Java:

--langmap=c:.c.x,java:+.j

Mappa makefiler till språket make:

--langmap=make:([Mm]akefile).mak

För att mappa filer utan filändelse anges en punkt som inte följs av ett icke-punkttecken:

.
..x
.x.

För att rensa mappningen för ett språk anges en tom filändelselista:

--langmap=fortran:

För att återställa standardmappningen för ett visst språk används nyckelordet:

default

För att återställa alla standardmappningar:

--langmap=default

Filändelser testas före filnamnsmönster när språket för en fil ska bestämmas.

--language-force=språk

Tvinga alla angivna filer att tolkas som det angivna språket i stället för att automatiskt välja språk baserat på filändelse.

Språknamnet är inte skiftlägeskänsligt och kan vara inbyggt eller användardefinierat.

Det särskilda värdet:

auto

anger att språket ska väljas automatiskt, vilket i praktiken inaktiverar denna option.

--languages=[+|-]lista

Anger vilka språk som taggar ska skapas för.

lista innehåller en kommaseparerad lista över språknamn. Språknamnen är inte skiftlägeskänsliga.

Om första språket i listan inte föregås av + eller - rensas den aktuella listan innan språken läggs till eller tas bort.

Tills ett - påträffas läggs språken i listan till. Efter - tas språken bort. Ett + gör att efterföljande språk läggs till igen.

De faktiska filer som taggar skapas för beror på den aktiva mappningen mellan filändelser och språk.

Alla språk, även användardefinierade språk, är aktiverade om de inte uttryckligen inaktiveras.

Standardvärdet är:

all

--license

Skriv en sammanfattning av programvarulicensen till standardutmatningen och avsluta.

--line-directives[=yes|no]

Anger om #line-direktiv ska kännas igen.

Sådana direktiv finns i utdata från preprocessorer och innehåller radnummer, och ibland filnamn, för den ursprungliga källfil som preprocessorns utdata skapades från.

När optionen är aktiverad skapar ctags taggposter märkta med de ursprungliga filnamnen och radnumren, i stället för deras faktiska plats i preprocessorns utdatafil.

De faktiska filnamnen i taggfilen får samma inledande sökvägskomponenter som preprocessorns utdatafil, eftersom det antas att originalfilerna finns relativt preprocessorns utdatafil, om inte #line-direktivet anger en absolut sökväg.

Optionen är avstängd som standard.

Den är normalt endast användbar tillsammans med:

--excmd=number
-n

Man kan också behöva använda --langmap eller --language-force om filändelsen på preprocessorns utdatafil inte är känd för ctags.

--links[=yes|no]

Anger om symboliska länkar ska följas, om plattformen stöder dem.

När optionen är avstängd ignoreras symboliska länkar.

Optionen är aktiverad som standard.

--list-kinds[=språk|all]

Lista de taggtyper som känns igen för det angivna språket eller för alla språk och avsluta.

Varje taggtyp i taggfilen representeras av en enbokstavsflagga. Samma flagga används för att filtrera vilka taggar som placeras i utmatningen med --<LANG>-kinds.

Vissa språk eller taggtyper kan vara implementerade med reguljära uttryck och kan saknas om stöd för reguljära uttryck inte kompilerats in.

Varje typ som visas är aktiverad om den inte följs av:

[off]

--list-maps[=språk|all]

Lista filändelser och filnamnsmönster som kopplar filnamn till språk, för ett visst språk eller alla språk, och avsluta.

Se även:

--langmap

--list-languages

Lista namnen på de språk som ctags förstår och avsluta.

Språknamnen är inte skiftlägeskänsliga och kan användas med optioner som:

--language-force
--languages
--<LANG>-kinds
--regex-<LANG>

--options=fil

Läs ytterligare optioner från fil.

Filen ska innehålla en option per rad.

Som specialfall inaktiverar:

--options=NONE

automatisk läsning av konfigurationsoptioner från fil eller miljö, om det anges som första option på kommandoraden.

Se även avsnittet FILER.

--recurse[=yes|no]

Gå rekursivt ned i kataloger som förekommer i listan över angivna filer.

Om listan över angivna filer är tom och ingen fillista anges med -L antas aktuell katalog:

.

Symboliska länkar följs.

Om detta inte önskas bör filer anges uttryckligen eller utmatningen från find(1) skickas till:

ctags -L-

Optionen stöds inte på alla plattformar. Om den stöds visas den i utmatningen från:

--help

Se även --exclude för att begränsa rekursion.

--regex-<LANG>=/regexp/ersättning/[typspec/][flaggor]

Definierar ett reguljärt uttryck och ett ersättningsmönster som används för att skapa taggar från källfiler som är mappade till språket <LANG>.

Språknamnet är inte skiftlägeskänsligt och kan vara inbyggt eller användardefinierat.

Parametern liknar en sed-substitution.

regexp är ett utökat reguljärt uttryck som används för att hitta en källrad som innehåller en tagg. Tabulatortecken kan anges som:

\t

När en matchande rad hittas skapas en tagg med namn som definieras av ersättning. Ersättningen kan använda specialreferenserna:

\1
\2
...
\9

Dessa hänvisar till matchande deluttryck i regexp.

Avgränsaren / kan ersättas med valfritt tecken. Om samma tecken ska användas inuti parametern måste det föregås av omvänt snedstreck.

Det reguljära uttrycket läggs till i den aktuella listan för språket, om parametern anges. Om parametern utelämnas rensas listan.

Om inget annat anges av flaggorna tolkas regexp som ett POSIX-utökat reguljärt uttryck.

ersättning bör expandera till en icke-tom sträng för alla matchande rader. Annars rapporteras en varning.

En valfri typspecifikation kan följa efter ersättningen. Den bestämmer vilken typ av tagg som rapporteras i fältet kind.

Den fullständiga formen är:

bokstav,namn,beskrivning

Om typspecifikationen utelämnas används standardvärdet:

r,regex

Flaggor:

b

Mönstret tolkas som ett POSIX-grundläggande reguljärt uttryck.

e

Mönstret tolkas som ett POSIX-utökat reguljärt uttryck. Detta är standard.

i

Det reguljära uttrycket tillämpas utan hänsyn till versaler och gemener.

Optionen är endast tillgänglig om ctags kompilerats med stöd för reguljära uttryck. Detta visas i --version som:

+regex

--sort[=yes|no|foldcase]

Anger om taggfilen ska sorteras efter taggnamn.

Standard är:

yes

Den ursprungliga vi(1) krävde sorterade taggar.

Värdet foldcase anger skiftlägesokänslig sortering. Snabba binära sökningar i taggfiler sorterade på detta sätt kräver särskilt stöd i de verktyg som läser taggfilen, till exempel:

• ctags-biblioteket readtags
• Vim 6.2 eller senare med set ignorecase

Denna option måste anges före första filnamnet.

Ignoreras i etags-läge.

--tag-relative[=yes|no]

Anger att filsökvägar som skrivs i taggfilen ska vara relativa till katalogen som innehåller taggfilen, i stället för relativa till aktuell katalog.

Detta gäller inte filer som anges med absoluta sökvägar på kommandoraden.

Optionen måste anges före första filnamnet.

Standard är:

• yes i etags-läge
• no annars

--totals[=yes|no]

Skriv statistik över lästa källfiler och skriven taggfil för den aktuella körningen.

Optionen är avstängd som standard.

Den måste anges före första filnamnet.

--verbose[=yes|no]

Aktivera utförligt läge.

Detta skriver information om optionsbehandling och korta meddelanden om vad som görs för varje fil som ctags överväger.

Normalt läser ctags inte kommandoradsargument förrän efter att optioner har lästs från konfigurationsfiler och från miljövariabeln CTAGS.

Om denna option är första argument på kommandoraden träder den i kraft innan optioner läses från dessa källor.

Standard är:

no

--version

Skriv en versionsidentifierare till standardutmatningen och avsluta.

Utmatningen innehåller alltid strängen:

Exuberant Ctags

FUNKTIONSSÄTT

När ctags behandlar varje filnamn försöker programmet bestämma filens språk genom tre tester i följande ordning:

1. Om filändelsen har mappats till ett språk.
2. Om filnamnet matchar ett skalmönster som mappats till ett språk.
3. Om filen är körbar och första raden anger en tolk med UNIX-formen #!, om detta stöds på plattformen.

När ett språk har identifierats öppnas filen och rätt språkparser anropas. Parsern läser igenom filen och lägger till en post i taggfilen för varje språkobjekt som den hanterar.

Denna implementation av ctags ställer inga formateringskrav på C-kod, till skillnad från äldre implementationer. Äldre versioner av ctags byggde ofta på vissa formateringsantaganden för att hantera problem orsakade av preprocessorvillkor.

I allmänhet försöker ctags hantera villkorliga preprocessordirektiv på ett smart sätt.

Om ett preprocessorvillkor hittas inne i en sats som definierar en tagg följer ctags normalt endast den första grenen i villkoret. Specialfallet #if 0 gör att endast den sista grenen följs.

Skälet är att båda grenarna annars kan ge tvetydig syntax.

Exempel:

#ifdef TWO_ALTERNATIVES
struct {
#else
union {
#endif

short a;
long b;

}

Båda grenarna kan inte följas samtidigt, eftersom klamrarna då hamnar i obalans och ctags inte längre kan tolka syntaxen.

Om denna heuristik misslyckas försöker ctags läsa om filen med en annan heuristik. Då följs inte preprocessorgrenar selektivt. I stället används en avslutande klammerparentes i kolumn 1 som tecken på slutet av ett block, efter att obalans uppstått genom att en #if-gren har följts.

ctags försöker också särskilt hantera argumentlistor inom dubbla parenteser, till exempel:

extern void foo __ARGS((int one, char two));

Ett namn omedelbart före (( ignoreras automatiskt och föregående namn används.

C++-operatordefinitioner hanteras särskilt. För konsekvens mellan överlagrade operatorer och konverteringsoperatorer föregås operatornamnet i taggfilen alltid av strängen:

operator 

Det gäller även om definitionen i källan skrevs som exempelvis:

operator<<

Efter att taggfilen skapats eller utökats sorteras den efter taggnamn, och identiska taggrader tas bort.

TAGGFILFORMAT

När programmet inte körs i etags-läge består varje post i taggfilen av en separat rad.

Den allmänna formen är:

taggnamn<TAB>filnamn<TAB>ex_kommando;"<TAB>utökade_fält

Fälten är:

1. taggnamn
2. ett tabulatortecken
3. namnet på filen där objektet som hör till taggen finns
4. ett tabulatortecken
5. EX-kommando som används för att hitta taggen i filen
6. eventuella utökade fält

EX-kommandot är normalt ett sökmönster, till exempel:

/mönster/
?mönster?

eller ett radnummer.

Taggfilformat nivå 2, se --format, utökar EX-kommandot genom att under vissa omständigheter lägga till utökade fält som en EX-kommentar. Detta behåller bakåtkompatibilitet med ursprungliga vi(1)-implementationer.

Några särskilda taggar skrivs till taggfilen för interna ändamål. De konstrueras så att de alltid sorteras överst i filen. Därför används de första två tecknen i sådana taggar som ett magiskt nummer för att upptäcka en taggfil och undvika att en källfil skrivs över av misstag.

Namnet på varje källfil skrivs i taggfilen exakt som det angavs på kommandoraden. Om sökvägen var relativ till aktuell katalog kommer den alltså att skrivas på samma sätt i taggfilen.

Se optionen --tag-relative för hur detta kan ändras.

Utökade fält

Utökade fält är tabseparerade nyckel-värde-par som läggs till i slutet av EX-kommandot som en kommentar.

Allmän form:

nyckel:värde

Vilka fält som finns styrs av:

--fields

Möjliga nycklar:

access

Anger synlighet för en klassmedlem. Värdet är språkberoende.

file

Anger att taggen har filbegränsad synlighet. Denna nyckel har inget tillhörande värde.

kind

Anger taggens typ. Värdet är antingen en enbokstavsflagga eller ett fullständigt namn.

implementation

Anger, när det finns, begränsad implementation för en rutin eller klass. Detta kan till exempel vara virtual eller pure virtual i C++ eller abstract i Java.

inherits

Anger, när det finns, en kommaseparerad lista över klasser som klassen ärver från.

signature

Anger, när det finns, en språkberoende representation av en rutins signatur.

För C-baserade språk innehåller signaturen för närvarande argumentlistan men inte returtypen.

Dessutom kan information om räckvidden för en taggdefinition finnas. Nyckeln är då en språkberoende konstruktion och värdet namnet på konstruktionen.

Exempel för en C-strukturmedlem:

struct:myStruct

ANVÄNDNING MED VI

vi förväntar sig som standard en taggfil med namnet:

tags

i aktuell katalog.

När taggfilen har skapats kan följande kommandon användas.

Starta vi och placera markören vid den fil och rad där taggen definieras:

vi -t tagg

Hitta en tagg inifrån vi:

:ta tagg

Hitta taggen under markören:

Ctrl-]

Återgå till föregående plats före tagghoppet, om redigeraren stöder detta:

Ctrl-T

ANVÄNDNING MED GNU EMACS

Emacs förväntar sig som standard en taggfil med namnet:

TAGS

i aktuell katalog.

När taggfilen har skapats kan följande kommandon användas.

Välj taggfil:

M-x visit-tags-table <RET> FIL <RET>

Hitta första definitionen av en tagg:

M-. [TAGG] <RET>

Standardtaggen är identifieraren under markören.

Gå tillbaka till platsen där M-. kördes:

M-*

Hitta nästa definition för den senaste taggen:

C-u M-.

Fler kommandon finns under ämnet Tags i Emacs info-dokumentation.

ANVÄNDNING MED NEDIT

NEdit version 5.1 och senare kan hantera det nya utökade taggfilformatet, se --format.

För att använda taggfilen i NEdit väljer man:

File -> Load Tags File

För att hoppa till definitionen för en tagg markerar man ordet och trycker:

Ctrl-D

NEdit 5.1 kan läsa flera taggfiler från olika kataloger.

Genom att sätta X-resursen:

nedit.tagFile

till namnet på en taggfil kan NEdit automatiskt läsa in taggfilen vid start.

VARNINGAR OCH BEGRÄNSNINGAR

Eftersom ctags varken är en preprocessor eller en kompilator kan preprocessormakron lura programmet så att taggar missas eller felaktiga taggar skapas.

Även om ctags är konstruerat för att hantera vissa vanliga fall är detta den största källan till rapporterade problem.

Särskilt kan preprocessorkonstruktioner som ändrar den textuella C-syntaxen lura ctags.

Många sådana problem kan kringgås med optionen:

-I

Eftersom ctags skapar sökmönster för att hitta taggar är det möjligt att redigeraren hittar fel rad om en annan källrad är identisk med raden som innehåller taggen.

Exempel:

int variable;

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

Beroende på redigerare och aktuell position i koden kan sökmönstret hitta den lokala parameterdeklarationen i foo() före den verkliga globala variabeldefinitionen, eftersom raderna är identiska.

Det kan undvikas med:

--excmd=n

FEL

ctags har fler optioner än ls(1).

När en C++-medlemsfunktionsdefinition parsas, exempelvis:

className::function

kan ctags inte avgöra om räckviddsspecifikationen är ett klassnamn eller ett namnrymdsnamn. Den listas därför alltid som ett klassnamn i räckviddsdelen av de utökade fälten.

Om en C++-funktion definieras utanför klassdeklarationen, vilket är det vanliga fallet, är åtkomstspecifikationen, exempelvis public, protected eller private, och implementationsinformationen, exempelvis virtual eller pure virtual, inte kända när taggen för funktionsdefinitionen skapas.

Informationen finns däremot tillgänglig för prototyper, exempelvis med:

--c++-kinds=+p

Inga kvalificerade taggar skapas för språkobjekt som ärvs in i en klass.

MILJÖVARIABLER

CTAGS

Om denna miljövariabel finns förväntas den innehålla en uppsättning standardoptioner som läses när ctags startar.

De läses efter konfigurationsfilerna som listas i avsnittet FILER, men före kommandoradsoptionerna.

Optioner på kommandoraden åsidosätter optioner i denna variabel.

Endast optioner läses från variabeln.

Allt blankutrymme i variabeln räknas som avgränsare, vilket gör det omöjligt att skicka ett optionsargument som innehåller ett inbäddat blanksteg. Om detta behövs bör en konfigurationsfil användas i stället.

ETAGS

Liknar CTAGS, men läses när etags startar. Om ETAGS inte finns försöker etags använda CTAGS i stället.

TMPDIR

På UNIX-liknande system där mkstemp() finns anger denna variabel katalogen där temporära filer ska placeras.

Detta kan vara användbart om en temporär fil blir för stor för partitionen som innehåller standardkatalogen för temporära filer.

ctags skapar temporära filer endast om ett av följande gäller:

• en Emacs-liknande taggfil skapas
• taggfilen skrivs till standardutmatningen
• programmet kompilerades för att använda en intern sorteringsalgoritm i stället för operativsystemets sort-verktyg

Om operativsystemets sort används följer även det normalt denna variabel.

Om ctags körs setuid ignoreras TMPDIR.

FILER

Följande konfigurationsfiler kan användas:

/ctags.cnf                 endast MSDOS/MSWindows
/etc/ctags.conf
/usr/local/etc/ctags.conf
$HOME/.ctags
$HOME/ctags.cnf            endast MSDOS/MSWindows
.ctags
ctags.cnf                  endast MSDOS/MSWindows

Om någon av dessa filer finns förväntas den innehålla standardoptioner.

Filerna läses i angiven ordning när ctags startar, men före miljövariabeln CTAGS och före kommandoradsoptioner.

Detta gör det möjligt att ha standardinställningar på:

• systemnivå
• användarnivå
• projektnivå

Det är möjligt att kompilera ctags så att ytterligare en konfigurationsfil läses före de som listas ovan. Detta visas i --version som funktionen:

custom-conf

Optioner i CTAGS eller på kommandoraden åsidosätter optioner i dessa filer.

Endast optioner läses från dessa filer.

Optionsfiler läses radvis och blanktecken är betydelsefulla, eftersom skalcitering inte är möjlig. Varje rad läses som ett kommandoradsargument, som om den hade citerats med enkla citationstecken.

Använd därför nya rader för att ange separata kommandoradsargument.

tags

Standardtaggfil som skapas av ctags.

TAGS

Standardtaggfil som skapas av etags.

SE ÄVEN

Officiell webbplats för Exuberant Ctags:

http://ctags.sourceforge.net/

Relaterade sidor:

• ex(1)
• vi(1)
• Elvis
• Vim

Vim-webbplatsen:

http://www.vim.org/

FÖRFATTARE

Darren Hiebert

dhiebert at users.sourceforge.net

Webbplats:

http://DarrenHiebert.com/

MOTIVATION

Citat ur Bahá'í-skrifterna återges i originalmanualen som motivation för arbetet:

Think ye at all times of rendering some service to every member of the human race.

och:

All effort and exertion put forth by man from the fullness of his heart is worship,
if it is prompted by the highest motives and the will to do service to humanity.

TACK

Denna version av ctags härstammar ursprungligen från och inspirerades av ctags-programmet av Steve Kirkendall, som ingick i Elvis, en vi-klon. Praktiskt taget ingen av den ursprungliga koden finns dock kvar.

Tack riktas också till Bram Moolenaar, författaren till vim, som lagt mycket tid och energi både på att utveckla redigeraren som en tjänst för andra och på att hjälpa föräldralösa barn i Uganda.

Avsnittet om användning med GNU Emacs i originalmanualen är hämtat från infosidan för GNU etags.

SIDOR SOM HÄNVISAR TILL DENNA SIDA

• jove(1)
• nedit(1)
• nedit-client(1)
• nvi(1)
• xvile(1)

KORT SAMMANFATTNING

ctags skapar en taggfil som gör att redigerare som vi, vim och emacs snabbt kan hoppa till definitioner i källkod.

Skapa taggar i aktuell katalog:

ctags *

Skapa taggar rekursivt:

ctags -R

Använd taggar i vi:

vi -t funktionsnamn

eller inne i vi:

:ta funktionsnamn
Ctrl-]
Ctrl-T

Skapa Emacs-taggfil:

ctags -e

Visa stödda språk:

ctags --list-languages

Visa stödda taggtyper:

ctags --list-kinds

Sidslut

Orginalhemsidan på Engelska https://linux.die.net/man/1/ctags Det här är en maskinöversättning av Linux man sidor till svenska. Om du hittar fel är vi tacksamma om du rapporterar dem via formuläret som finns på https://www.linux.se/kontaka-linux-se/

Tack till Datorhjälp hemma som har sponsrat Linux.se med webbhotell.