Highlight Dokumentation

• Handbuch
• Plug-Ins
• Unterstützte Sprachen
• Installation
• Integration
• Syntax-Tests
• Reguläre Ausdrücke
• LSP client
• Service-Modus

  ---

• Syntax-Beispiele
• Theme-Beispiele
• Screenshots
• Screencast

  ---

• ChangeLog
• Mitwirkende
• Git/SVN

  ---

• Wiki (Gitlab)

  ---

• English manual

Plug-Ins

Die Plug-In Schnittstelle erlaubt Anpassungen der Syntax-Erkennung und der Farbgebung. Die Ausgabedatei kann im Kopf- und Fußteil erweitert werden, und Syntaxelemente können um weitere Informationen ergänzt werden.
Ein einfaches Plug-In könnte neue Schlüsselworter mit eigener Formatierung definieren oder bestehende Listen erweitern. Komplexere Skripte lesen beispielsweise Informationen aus ctags-Dateien ein und geben diese als Tooltips aus, oder geben HTML mit Javascript Code-Folding aus.
Das Highlight-Paket enthält mehrere Plug-Ins als Vorlage.

Skriptaufbau

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

Description="Boilerplate plugin"

-- optional parameter: syntax description
function syntaxUpdate(desc)
end

-- optional parameter: theme description
function themeUpdate(desc)
end

-- optional parameter: syntax description
function formatUpdate(desc)
end

Plugins={
  { Type="theme", Chunk=themeUpdate },
  { Type="lang", Chunk=syntaxUpdate },
  { Type="format", Chunk=formatUpdate },
}

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).
The formatUpdate is not executed in a syntax or theme Lua state. It just returns strings to override or enhance the document header and footer.
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 Änderungen 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.

Elemente der Sprachdefinitionen

Diese Liste enthält alle Elemente mit Einfluß auf das Syntax-Highlighting:

Syntax definition items:

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

Document modification items:

HeaderInjection: string
FooterInjection: string

Read only (internal highlighting states):

HL_STANDARD: number
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_STRING: number
HL_STRING_END: number
HL_UNKNOWN: number
HL_REJECT: number

Read only (other):

HL_PLUGIN_PARAM: string (set with --plug-in-param)
HL_LANG_DIR: string (path of language definition directory)


Read only (output document format):

HL_OUTPUT: number (selected format)
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
HL_FORMAT_PANGO: number
HL_FORMAT_ODT: number

Functions:

AddKeyword: function
OnStateChange: function
Decorate: function
DecorateLineBegin: function
DecorateLineEnd: function

WICHTIG: Die Funktionen werden nur dann ausgewertet, wenn sie als lokale Funktion innerhalb der im Plugins-Array angegebenen 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 OR HL_REJECT

Return HL_REJECT if the recognized token and state should be discarded; only the
first character of token will be outputted using the state defined as oldState.

Beispiele:

function OnStateChange(oldState, newState, token, kwgroup)
   if newState==HL_KEYWORD and kwgroup==5 then
      AddKeyword(token, 5)
   end
   return newState
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.

function OnStateChange(oldState, newState, token)
   if token=="]]" and oldState==HL_STRING and newState==HL_BLOCK_COMMENT_END then
      return HL_STRING_END
   end
   return newState
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

AddPersistentState-Funktionen

This function enables storage of keywords and keyword ranges in a plug-in file. If the syntax contains elements which depend on a context, you can highlight them although this context is lost in other input files or code sections.

The invocation of AddPersistentState will cause highlight to save a plugin as temporary file and parse input files using this plug-in again if necessary.

AddPersistentState(keyword, kwGroupID)

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

AddPersistentState(lineno, kwGroupID, column, length)

Parameters: lineno:    line number
            kwGroupID: the keyword group ID
            column:    column
            length:    length of the keyword
Returns:    true if successfull

Decorate-Funktionen

Die Decorate-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).

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

Diee Funktionen DecorateLineBegin und DecorateLineEnd werden aufgerufen wenn eine Zeile beginnt oder endet. So können einzelne Zeilen besonders formatiert werden.

DecorateLineBegin(lineNumber)

  Hook Event: output of a new line
  Parameters: lineNumber: the current line number
  Returns:    A string to be prepended to a new line (or nothing)

DecorateLineEnd(lineNumber)

  Hook Event: output of a line ending
  Parameters: lineNumber: the current line number
  Returns:    A string to be appended to a line (or nothing)

Achtung: Der Rückgabewert von Decorate-Funktionen wird innerhalb von Formatierungstags des Ausgabeformats ausgegeben. Der Rückgabewert wird von highlight nicht geprüft oder verändert.

function Decorate(token, state)
  if (state == HL_KEYWORD) then
    return  string.upper(token)
  end
end

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

Elemente der Theme-Beschreibungen

Diese Liste enthält alle Elemente mit Einfluß auf die Farbausgabe:

Output formatting items:

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

Custom theme items:

Injections: table

Read only (output document format):

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_TRUECOLOR: number
HL_FORMAT_SVG: number
HL_FORMAT_BBCODE:
HL_FORMAT_ODT: number
HL_FORMAT_PANGO: number

Elemente der Formatbeschreibungen

Read only (output document format):

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_TRUECOLOR: number
HL_FORMAT_SVG: number
HL_FORMAT_BBCODE: number
HL_FORMAT_PANGO: number
HL_FORMAT_ODT: number

Funktionen:

DocumentHeader: function
DocumentFooter: function

Funktion DocumentHeader

Diese Funktion wird beim Erzeugen einer neuen Ausgabedatei aufgerufen. Sie kann den Kopfteil des Dokuments ersetzen oder ergänzen.

DocumentHeader(numFiles, currFile, options)

  Hook Event: output of a new file's header
  Parameters: numFiles: number of files to be generated
              currFile: current file counter
              options: Map of the following options
              options.title: document title
              options.encoding: document encoding
              options.fragment: true if header/footer should not be outputted
              options.font: font name
              options.fontsize: font size

  Returns:    [string, boolean?] (or nothing)
              The string contains the new document header
              The boolean value indicates if the string should replace the default
              header (false=default) or if it should be appended to it (true).

Funktion DocumentFooter

Diese Funktion wird beim Erzeugen einer neuen Ausgabedatei aufgerufen. Sie kann den Fußteil des Dokuments ersetzen oder ergänzen.

DocumentFooter(numFiles, currFile, options)

  Hook Event: output of a new file's footer
  Parameters: see DocumentHeader

  Returns:    [string, boolean?] (or nothing)
              The string contains the new document footer
              The boolean value indicates if the string should replace the default
              footer (false=default) or if it should precede it (true).

Komplettes Beispiel:

-- Beginne mit der Beschreibung des Plug-ins
Description="Add qtproject.org reference links to HTML, LaTeX or RTF output"

-- Die syntaxUpdate-Funktion enthält Code, der die Syntaxerkennung beeinflusst
function syntaxUpdate(desc)

  -- Wenn die aktuelle Datei kein C++ enthält, brechen wir ab
  if desc~="C and C++" then
     return
  end

  -- Diese Funktion gibt einen qt-project Referenzlink des Tokens zurück
  function getURL(token)
     -- erzeuge den URL
     url='http://qt-project.org/doc/qt-4.8/'..string.lower(token).. '.html'

     -- Füge die Addresse in einen Link passend zum Ausgabeformat ein
     -- erst HTML, dann LaTeX und RTF
     if (HL_OUTPUT== HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then
        return '<a class="hl" target="new" href="'
               .. url .. '">'.. token .. '</a>'
     elseif (HL_OUTPUT == HL_FORMAT_LATEX) then
        return '\\href{'..url..'}{'..token..'}'
     elseif (HL_OUTPUT == HL_FORMAT_RTF) then
        return '{{\\field{\\*\\fldinst HYPERLINK "'
               ..url..'" }{\\fldrslt\\ul\\ulc0 '..token..'}}}'
     end
   end

  -- Die Decorate Funktion wird für jedes erkannte Token aufgerufen
  function Decorate(token, state)

    -- Wir interessieren uns nur für Schlüsselwörter, Präprozessor- und Standardelemente
    if (state ~= HL_STANDARD and state ~= HL_KEYWORD and
        state ~=HL_PREPROC) then
      return
    end

    -- Qt-Schlüsselwörter beginnen mit Q, gefolgt von einem Groß- und einem Kleinbuchstaben
    -- Wenn dieses Muster zum Token passt, geben wir den URL zurück
    -- Wenn wir nichts zurückgeben, bleibt das Token unverändert
    if string.find(token, "Q%u%l")==1 then
      return getURL(token)
    end

  end
end

-- Die themeUpdate-Funktion beeinflußt Themes
function themeUpdate(desc)
  -- Mit der Injections-Tabelle kann das Theme um weitere Formatangaben erweitert werden

  -- HTML: wir fügen CSS hinzu, um die Links zu verschönern
  -- Sie sollten dasselbe Format wie die umschließenden Tags haben
  if (HL_OUTPUT == HL_FORMAT_HTML or HL_OUTPUT == HL_FORMAT_XHTML) then
    Injections[#Injections+1]=
      "a.hl, a.hl:visited {color:inherit;font-weight:inherit;}"

  -- LaTeX: Links benötigen das hyperref-Paket, also fügen wir es hinzu
  -- Die Optionen colorlinks und pdfborderstyle entfernen unschöne Boxen in der Ausgabe
  elseif (HL_OUTPUT==HL_FORMAT_LATEX) then
    Injections[#Injections+1]=
      "\\usepackage[colorlinks=false, pdfborderstyle={/S/U/W 1}]{hyperref}"
  end
end

-- Chunks zuweisen
Plugins={
  { Type="lang", Chunk=syntaxUpdate },
  { Type="theme", Chunk=themeUpdate },
}

Auswahl von mitgelieferten Plug-Ins

bash_functions.lua

Beschreibung: Fügt Funktionsnamen zu Keyword-Liste hinzu

Funktionen: Bestimmt Funktionsnamen mit Muster, definiert OnStateChange, nutzt AddKeyword

theme_invert.lua

Beschreibung: Invertiert Farben des Themes

Funktionen: Ändert alle Farbattribute des Themes, nutzt Lua Pattern-Matching.

ctags_html_tooltips.lua

Beschreibung: Fügt Tooltips basierend auf einer ctags-Datei hinzu (Default-Eingabedatei: tags)

Funktionen: Liest eine Datei (angegeben mit --plug-in-param) und parst die Tags-Daten vor dem Aufruf von Decorate.

outhtml_curly_brackets_matcher.lua

Beschreibung: Zeigt die geschweiften Klammernpaare an.

Funktionen: Nutzt Decorate um die Klammern mit span-Tags und IDs zu versehen. Fügt Javascript mit der HeaderInjection-Variablen hinzu. Fügt zusätzliche CSS-Styles mit der Injections-Variablen hinzu.

outhtml_keyword_matcher.lua

Beschreibung: Zeigt mehrfach vorkommende Keywords an.

Funktionen: Nutzt Decorate um Keywords mit span-Tags und IDs zu versehen. Definiert OnStateChange um jedem Keyword eine ID zuzuweisen. Fügt Javascript mit der HeaderInjection-Variablen hinzu. Fügt zusätzliche CSS-Styles mit der Injections-Variablen hinzu.

outhtml_codefold.lua

Beschreibung: Ermöglicht Codefolding für C-artige Sprachen, Pascal, Lua und Ruby

Funktionen: Nutzt DecorateLineBegin und DecorateLineEnd um jede Zeile mit einer ID zu versehen. Definiert Decorate um jedem Block-Begrenzer einen onClick-Handler zuzuweisen. Fügt Javascript mit HeaderInjection- und FooterInjection-Variablen hinzu. Fügt zusätzliche CSS-Styles mit der Injections-Variablen hinzu.