Highlight Dokumentation

Plug-Ins

Skriptaufbau

Das folgende Skript enthält ein minimales Plug-In ohne Auswirkung auf die Ausgabe, da die Funktionen mit leerem Rumpf definiert sind:

01 Description="NOOP plugin"
02 
03 -- optional parameter: syntax description
04 function syntaxUpdate(desc)
05 end
06 
07 -- optional parameter: theme description
08 function themeUpdate(desc)
09 end
10 
11 Plugins={
12   { Type="theme", Chunk=themeUpdate },
13   { Type="lang", Chunk=syntaxUpdate },
14 }

Die erste Zeile enthält eine Beschreibung des Plug-Ins.

Die nächsten Zeilen enthalten Funktionsdefinitionen: Die syntaxUpdate Funktion wird auf Sprachdefinitionen angewandt (*.lang), während die themeUpdate Funktion auf Farbschemata angewandt wird (*.theme). Die Namen der Funktionen können frei gewählt werden.
Der desc-Parameter enthält die Beschreibung der Sprachdefiniton oder des Farbschemas. Er kann benutzt werden, um Änderugen nur auf bestimmte Eingabedaten anzuwenden (z.B. sollen syslog-Schlüsselwörter nur bei C Code ergänzt werden).

Das Plugins Array verbindet die Funktionen mit den Lua-States, die beim Laden der lang- oder theme-Skripte erzeugt werden. In diesem Beispiel ist themeUpdate mit dem theme-State verbunden, und syntaxUpdate mit dem lang-State. Es ist nicht nötig, beide Verbindungen anzugeben, wenn nur ein Typ der Konfigurationsskripte angepasst werden soll.

Elemente der Sprachdefinitionen

Diese Liste enthält alle Elemente, die überschrieben oder erweitert werden können, um das Syntax-Highlighting anzupassen:

Comments: table
Description: string
Digits: string
EnableIndentation: boolean
Identifiers: string
IgnoreCase: boolean
Keywords: table
NestedSections: table
Operators: string
PreProcessor: table
Strings: table

Read only constants:

HL_LANG_DIR: string
HL_BLOCK_COMMENT: number
HL_BLOCK_COMMENT_END: number
HL_EMBEDDED_CODE_BEGIN: number
HL_EMBEDDED_CODE_END: number
HL_ESC_SEQ: number
HL_ESC_SEQ_END: number
HL_IDENTIFIER_BEGIN: number
HL_IDENTIFIER_END: number
HL_KEYWORD: number
HL_KEYWORD_END: number
HL_LINENUMBER: number
HL_LINE_COMMENT: number
HL_LINE_COMMENT_END: number
HL_NUMBER: number
HL_OPERATOR: number
HL_OPERATOR_END: number
HL_PREPROC: number
HL_PREPROC_END: number
HL_PREPROC_STRING: number
HL_STANDARD: number
HL_STRING: number
HL_STRING_END: number
HL_UNKNOWN: number

HL_OUTPUT: number
HL_FORMAT_HTML: number
HL_FORMAT_XHTML: number
HL_FORMAT_TEX: number
HL_FORMAT_LATEX: number
HL_FORMAT_RTF: number
HL_FORMAT_ANSI: number
HL_FORMAT_XTERM256: number
HL_FORMAT_SVG: number
HL_FORMAT_BBCODE: number

Functions:

AddKeyword: function
OnStateChange: function
Decorate: function

WICHTIG: Die Funktionen werden nur dann ausgewertet, wenn sie als lokale Funktion innerhalb der im Plugins-Array angegebenen lang-Funktion definiert werden. An anderen Stellen im Skript werden sie ignoriert.

Funktion OnStateChange

Diese Hook-Funktion wird immer dann ausgeführt, wenn sich der Zustand des Parsers ändert (z.B. von HL_STANDARD zu HL_KEYWORD wenn ein Schlüsselwort erkannt wird). Mit OnStateChange kann der neue Zustand angepasst werden oder es können Syntaxelemente manipuliert werden.

OnStateChange(oldState, newState, token, kwGroupID)

  Hook Event: Highlighting parser state change
  Parameters: oldState:  old state
              newState:  intended new state
              token:     the current token which triggered
	                 the new state
              kwGroupID: if newState is HL_KEYWORD, the parameter
                         contains the keyword group ID
  Returns:    Correct state to continue

Beispiele:

01 function OnStateChange(oldState, newState, token, kwgroup)
02    if newState==HL_KEYWORD and kwgroup==5 then
03       AddKeyword(token, 5)
04    end
05    return newState
06 end

Dise Funktion fügt das aktuelle Token zu der internen Schlüsselwort-Liste hinzu, wenn es zur Schlüsselwortgruppe 5 gehört. Wird Gruppe 5 durch einen regulären Ausdruck bestimmt, so wird das Token später als Schlüsselwort erkannt, auch wenn der Ausdruck dann nicht zutreffen sollte.

01 function OnStateChange(oldState, newState, token)
02    if token=="]]" and oldState==HL_STRING and newState==HL_BLOCK_COMMENT_END then
03       return HL_STRING_END
04    end
05    return newState
06 end

Dise Funktion behebt ein Problem mit dem Lua Begrenzer "]]", der Kommentare und Strings abschliessen kann.

Funktion AddKeyword

Diese Funktion fügt ein Schlüsselwort zu einer der internen Listen hinzu. Sie tut nichts wenn das Schlüsselwort bereits Element einer Liste ist. Die mit AddKeyword angegebenen Schlüsselwörter bleiben für alle Dateien derselben Syntax bestehen, wenn Highlight im Batch-Modus ausgeführt wird.

AddKeyword(keyword, kwGroupID)

  Parameters: keyword:   string which should be added to a keyword list
              kwGroupID: keyword group ID of the keyword
  Returns:    true if successfull

Funktion Decorate

Diese Hook-Funktion wird ausgeführt, wenn ein Token erkannt wurde. Mit ihrer Hilfe kann das Token verändert oder zusätzlicher Text im Ausgabeformat hinzugefügt werden (z.B Hyperlinks). Achtung: Der Rückgabewert von Decorate wird innerhalb von umschließenden Formatierungstags ausgegeben. Der Rückgabewert wird von highlight nicht geprüft oder verändert.

Decorate(token, state, kwGroupID)

  Hook Event: Token identification
  Parameters: token:     the current token
	      state:     the current state
              kwGroupID: if state is HL_KEYWORD, the parameter
                         contains the keyword group ID
  Returns:    Altered token string or nothing if original token should be
              outputted

Beispiele:

01 function Decorate(token, state)
02   if (state == HL_KEYWORD) then
03     return  string.upper(token)
04   end
05 end

Diese Funktion konvertiert alle Schlüsselwörter in Großbuchstaben.

01 knowntags={}
02 file = assert(io.open(HL_INPUT_FILE, "r"))
03 -- read file and fill knowntags
04 
05 function Decorate(token, state, kwclass)
06   for k,v in pairs(knowntags) do
07     if k==token  then
08       return '<span title="'..v..'">'..token .. '</span>'
09     end
10   end
11 end

Diese Funktion versieht Token mit Tooltips, wenn sie in der angegebenen tags Datei enthalten sind.

Elemente der Farbbeschreibungen

Diese Liste enthält alle Elemente, die überschrieben oder erweitert werden können, um die Farbausgabe anzupassen:

Default: table
Canvas: table
Number: table
Escape: table
String: table
StringPreProc: table
BlockComment: table
PreProcessor: table
LineNum: table
Operator: table
LineComment: table
Keywords: table
Injections: table

Read only:

HL_OUTPUT: number
HL_FORMAT_HTML: number
HL_FORMAT_XHTML: number
HL_FORMAT_TEX: number
HL_FORMAT_LATEX: number
HL_FORMAT_RTF: number
HL_FORMAT_ANSI: number
HL_FORMAT_XTERM256: number
HL_FORMAT_SVG: number
HL_FORMAT_BBCODE: number

Beispiel:

01 -- Beginne mit der Beschreibung des Plug-ins
02 Description="Add qtproject.org reference links to HTML, LaTeX or RTF output"
03 
04 -- Die syntaxUpdate-Funktion enthält Code, der die Syntaxerkennung beeinflusst
05 function syntaxUpdate(desc)
06 
07   -- Wenn die aktuelle Datei kein C++ enthält, brechen wir ab
08   if desc~="C and C++" then
09      return
10   end
11       
12   -- Diese Funktion gibt einen qt-project Referenzlink des Tokens zurück
13   function getURL(token)
14      -- erzeuge den URL
15      url='http://qt-project.org/doc/qt-4.8/'..string.lower(token).. '.html'
16      
17      -- Füge die Addresse in einen Link passend zum Ausgabeformat ein
18      -- erst HTML, dann LaTeX und RTF
19      if (HL_OUTPUT== HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then
20         return '<a class="hl" target="new" href="' 
21                .. url .. '">'.. token .. '</a>'
22      elseif (HL_OUTPUT == HL_FORMAT_LATEX) then
23         return '\\href{'..url..'}{'..token..'}'
24      elseif (HL_OUTPUT == HL_FORMAT_RTF) then
25         return '{{\\field{\\*\\fldinst HYPERLINK "'
26                ..url..'" }{\\fldrslt\\ul\\ulc0 '..token..'}}}'
27      end
28    end
29 
30   -- Die Decorate Funktion wird für jedes erkannte Token aufgerufen
31   function Decorate(token, state)
32 
33     -- Wir interessieren uns nur für Schlüsselwörter, Präprozessor- und Standardelemente
34     if (state ~= HL_STANDARD and state ~= HL_KEYWORD and 
35         state ~=HL_PREPROC) then
36       return
37     end
38 
39     -- Qt-Schlüsselwörter beginnen mit Q, gefolgt von einem Groß- und einem Kleinbuchstaben
40     -- Wenn dieses Muster zum Token passt, geben wir den URL zurück
41     -- Wenn wir nichts zurückgeben, bleibt das Token unverändert
42     if string.find(token, "Q%u%l")==1 then
43       return getURL(token)
44     end
45 
46   end
47 end
48 
49 -- Die themeUpdate-Funktion beeinflußt Themes
50 function themeUpdate(desc)
51   -- Mit der Injections-Tabelle kann das Theme um weitere Formatangaben erweitert werden
52   
53   -- HTML: wir fügen CSS hinzu, um die Links zu verschönern
54   -- Sie sollten dasselbe Format wie die umschließenden Tags haben
55   if (HL_OUTPUT == HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then
56     Injections[#Injections+1]=
57       "a.hl, a.hl:visited {color:inherit;font-weight:inherit;}"
58       
59   -- LaTeX: Links benötigen das hyperref-Paket, also fügen wir es hinzu
60   -- Die Optionen colorlinks und pdfborderstyle entfernen unschöne Boxen in der Ausgabe
61   elseif (HL_OUTPUT==HL_FORMAT_LATEX) then
62     Injections[#Injections+1]=
63       "\\usepackage[colorlinks=false, pdfborderstyle={/S/U/W 1}]{hyperref}"
64   end
65 end
66 
67 -- Lasse highlight den richtigen Code laden
68 Plugins={
69   { Type="lang", Chunk=syntaxUpdate },
70   { Type="theme", Chunk=themeUpdate },
71 }