# Praca z podświetlaniem składni

## Wprowadzenie

System podświetlania składni służy do wyświetlania określonych fragmentów tekstu w różnych stylach czcionki i kolorach, w zależności od funkcji tego tekstu w strukturze edytowanego pliku. Na przykład jeżeli jest to kod źródłowy jakiegoś programu, to instrukcje kontrolne mogą być pogrubione, zaś typu zmiennych i komentarze mogą być wyróżnione kolorem innym od reszty tekstu. To znacznie podnosi czytelność tekstu, dzięki czemu tworzenie programów jest bardziej efektywne i produktywne.

Fragment programu w języku Perl wyświetlonego z wykorzystaniem podświetlania składni.

Fragment programu w języku Perl wyświetlonego z wykorzystaniem podświetlania składni.

Ten sam fragment pokazany bez podświetlania

Ten sam fragment pokazany bez podświetlania.

Który z dwóch powyższych przykładów jest bardziej czytelny?

Edytor &kate; ma zintegrowany potężny, elastyczny i w pełni konfigurowalny system podświetlania składni, zaś domyślna instalacja programu zawiera wiele definicji dla różnych języków programowania, języków skryptowych, języków opartych na znacznikach oraz innych plików tekstowych. Dodatkowo użytkownik może tworzyć własne definicje podświetlania składni w plikach &XML; o stosunkowo prostej strukturze.

Podczas otwierania pliku tekstowego, &kate; automatycznie wykryje odpowiednią dla tego pliku definicję podświetlania składni na podstawie przypisanego dla niego typu &MIME;. Typ pliku określany jest na podstawie rozszerzenia nazwy pliku, a jeżeli plik nie ma rozszerzenia. to na podstawie jego zawartości. Jeżeli typ pliku został wykryty niepoprawnie, to można ręcznie zmienić definicję podświetlania składni za pomocą menu Narzędzia Typ pliku.

Styl i kolor tekstu dla wszystkich reguł podświetlania może zostać zdefiniowany w karcie Czcionki i kolory Okna konfiguracji natomiast typy &MIME;, dla których powinny być stosowane określone reguły konfigurowane są w karcie Podświetlenie.

Podświetlanie składni ma na celu zwiększenie czytelności treści dokumentu, ale nie należy zbyt polegać na jego możliwościach wskazywania błędów w kodzie programu. Algorytmy rozpoznawania składni mogą być skomplikowane i zależy to od używanego formatu dokumentu. Autorzy reguł podświetlania składni mogą się pochwalić 98% skutecznością stosowanych algorytmów rozpoznawania składni, jednak często jest ona wyższa i tylko naprawdę rzadko stosowane definicje reguł podświetlania powodują 2% błędnych podświetleń.

Ze strony WWW programu &kate; można pobrać nowe i zaktualizowane bieżące definicje reguł podświetlania składni. Można to zrobić naciskając przycisk Pobierz... w karcie Podświetlenie okna dialogowego Konfiguracji.

## System podświetlania składni programu &kate;

Poniższa sekcja zawiera bardziej szczegółowe omówienie mechanizmów podświetlania składni w programie &kate;. Jest ona przeznaczona dla użytkowników chcących dodawać lub modyfikować istniejące reguły podświetlania, lub dla osób chcących się czegoś więcej na ten temat dowiedzieć.

### Jak to działa?

Przy każdej operacji otwierania pliku program &kate; próbuje wykryć odpowiednią dla niego regułę podświetlania składni. Podczas wyświetlania pliku i w trakcie jego edycji system podświetlania składni będzie analizował tekst za pomocą reguł określonych w definicji podświetlania składni oraz zaznaczać miejsca, w których poszczególne konteksty treści i style tekstu rozpoczynają się i kończą.

Podczas edycji dokumentu nowo wprowadzany tekst jest analizowany i oznaczany na bieżąco, jeżeli więc użytkownik usunie znak będący początkiem lub końcem jakiegoś kontekstu to styl otaczającego ten znak tekstu zmieni się zgodnie z wymaganiami bieżącej reguły podświetlania składni.

Definicje reguł podświetlania składni w &kate; to pliki zapisane w standardzie &XML; zawierające:

- Zasady opisujące rolę spełnianą przez określone fragmenty tekstu zorganizowane w odpowienie bloki kontekstowe

- Listy słów kluczowych

- Definicje elementów stylu

Podczas analizy składni reguły są sprawdzane w kolejności ich wystąpienia w pliku. Jeżeli początek bieżącego tekstu zostaje dopasowany do danej reguły to następuje przełączenie na wskazany kontekst. Punkt przetwarzania treści przesuwa się na koniec bieżącego dopasowania reguły, a pętla sprawdzania reguł rozpoczyna się na nowo, ale już w kontekście przetwarzania wskazanym przez poprzednie dopasowanie.

### Reguły

Reguły stanowią serce systemu rozpoznawania składni. Reguła może odnosić się do napisu, pojedynczego znaku lub wyrażenia regularnego. Do reguł dopasowywany jest analizowany tekst dokumentu. Reguły wskazują, jakiego stylu należy użyć do wyświetlenia dopasowanego fragmentu tekstu, mogą też przełączać kontekst roboczy systemu podświetlania składni przez podanie nazwy kontekstu lub nakazując powrót do kontekstu poprzedniego.

Reguły są zgrupowane w bloki kontekstowe. Blok kontekstowy jest związany z głównymi elementami składni analizowanego tekstu np. tekst w cudzysłowach lub bloki komentarzy kodu źródłowego. Dzięki temu system podświetlania składni nie musi analizować wszystkich reguł, jeżeli nie jest to konieczne. Także pewne sekwencje znaków w tekście mogą być różnie traktowane w zależności od wybranego kontekstu przetwarzania.

Kontekst przetwarzania może być generowany dynamicznie, pozwalając na stosowaniu w regułach danych zależnych od wystąpienia określonego tekstu w treści dokumentu.

### Style kontekstu i słowa kluczowe

W niektórych językach programowania kompilator (czyli program zmieniający tzw. kod źródłowy programu na plik wykonywalny) w różny sposób traktuje liczby całkowite i zmiennoprzecinkowe. Dodatkowo wewnątrz otoczonego cudzysłowami napisu mogą być znaki o specjalnym znaczeniu. W takich wypadkach sensowne jest wyróżnienie ich z otaczającego tekstu tak aby były łatwo identyfikowalne. Tak więc nawet jeżeli takie fragmenty tekstu nie stanowią osobnego kontekstu, to są tak traktowane przez system podświetlania składni i dzięki temu mogą być odpowiednio różnicowane przy wyświetlaniu.

Definicja składni może zawierać dowolną liczbę stylów niezbędną do objęcia wszystkich elementów składniowych w danym formacie tekstu.

Dla wielu formatów dokumentów definiuje się listy słów reprezentujących określone pojęcia. Na przykład w językach programowania są to instrukcje kontrolne, typy zmiennych oraz wbudowane funkcje (każda z tych kategorii stanowi osobne pojęcie). System podświetlania składni w &kate; wykorzystuje listy słów kluczowych do zaznaczania w tekście wystąpień poszczególnych kategorii skadniowych danego formatu dokumentu.

### Style domyślne

W przypadku otwarcia pliku z programem w C++ , &Java; lub dokumentu HTML można zauważyć, że mimo iż poszczególne typy dokumentów znacząco się od siebie różnią (inne słowa są podświetlane, itp.) to używane przez &kate; kolory są identyczne. Dzieje się tak dlatego ponieważ w &kate; istnieje zdefiniowana lista stylów domyślnych tekstu wykorzystywanych przez wszystkie definicje reguł podświetlania składni.

Pozwala to na użytkownikowi na rozpoznawanie pojęć o podobnym znaczeniu w różnych formatach dokumentu. Na przykład komentarze, które istnieją w kodzie źródłowym w niemal wszystkich językach programowania, językach skryptowych lub językach znaczników, są wyświetlane z użyciem tego samego stylu co pozwala użytkownikowi łatwo zidentyfikować wyróżniony w tekście fragment jako komentarz, niezależnie w jakim języku programowania ten tekst będzie napisany.

Wszystkie definicje podświetlania składni korzystają z minimum jednego stylu domyślnego. Część z nich wykorzystuje więcej stylów domyślnych. Jeżeli z danego formatu dokumentu użytkownik często korzysta, to warto uruchomić okno konfiguracji i sprawdzić jakie pojęcia są dla niego zdefiniowane w zbiorze reguł podświetlania. Na przykład, dostępny jest tylko jeden styl domyślny dla napisów, jednak ponieważ język Perl działa na dwóch rodzajach napisów, to możliwe jest takie skonfigurowanie systemu podświetlania, aby oba rodzaje były wyświetlane w różny sposób. Wszystkie dostępne style domyślne zostaną omówione poniżej.

## Struktura pliku definicji podświetlania składni w formacie &XML;

### Wprowadzenie

Poniższa sekcja zawiera opis formatu pliku definicji podświetlania składni. Opisane zostaną główne elementy skadni &XML; pliku, ich znaczenie oraz sposoby wykorzystania. Kolejna sekcja zawiera szczegółowy opis poszczególnych reguł interpretacji składni.

Formalna definicja struktury pliku &XML; (czyli tak zwany dokument DTD) zawarta jest w pliku `language.dtd`, który najczęściej zlokalizowany jest w katalogu: `$`KDEDIR`/share/apps/katepart/syntax`.

### Główne sekcje pliku definicji reguł podświetlania składni dla programu &kate;

Plik z definicją reguł podświetlania składni zawiera nagłówek definiujący wersję języka XML oraz rodzaj dokumentu (doctype):

-     <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE language SYSTEM "language.dtd">

Głównym elementem składowym pliku z definicją jest element `language` posiadający następujące atrybuty:

- Atrybuty wymagane:

  `name` określa nazwę języka (format dokumentu), która pojawia się później w menu i w oknach dialogowych.

  `section` określa kategorię danego formatu dokumentu.

  `extensions` określa rozszerzenia nazw plików, np.: "*.cpp;*.h"

  Atrybuty opcjonalne:

  `mimetype` typy &MIME; plików, których dotyczy zbiór definicji.

  `version` określa wersję pliku definicji reguł podświetlania.

  `kateversion` określa minimalną wersję &kate;, wymaganą do prawidłowego działania pliku definicji.

  `casesensitive` określa wrażliwość na wielkość liter w słowach kluczowych.

  `priority` określa priorytet stosowania danego zbioru definicji dla tych samych rozszerzeń nazw plików. Jeżeli do danego rozszerzenia pasuje kilka plików definicji, to zostaje wybrany ten o najwyższym priorytecie.

  `author` zawiera imię i nazwisko autora definicji oraz jego adres e-mail.

  `license` określa na jakiej licencji został udostępniony plik. Z reguły są to licencje: LGPL, Artistic, GPL, ale mogą też być inne.

  `hidden` wyłącza wyświetlanie nazwy zbioru definicji w menu programu &kate;.

  Czyli kolejny wiersz pliku definicji może wyglądać następująco:

      <language name="C++" version="1.00" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" />

Następnym elementem struktury pliku jest znacznik `highlighting` zawierający element opcjonalny `list` oraz elementy wymagane:`contexts` oraz `itemDatas`.

- Elementy typu `list` zawierają listy słów kluczowych. W przedstawionym poniżej przykładzie są to słowa class i const. Możliwe jest dodanie wielu elementów typu `list` w zależności od potrzeb.

  Element `contexts` zawiera wszystkie konteksty występujące w składni definiowanego formatu dokumentu. Pierwszy kontekst jest domyślny i to od niego rozpoczyna się analiza składni. W omawianym przykładzie występują dwie reguły w kontekście o nazwie: Normal Text, dopasowujące listę słów kluczowych o nazwie: somename oraz reguła wykrywająca tekst w cudzysłowie przełączająca kontekst na: string. Więcej o regułach można przeczytać w kolejnym rozdziale.

  Trzecia część to element `itemDatas`. Zawiera on wszystkie kolory i style czcionek wykorzystywane przez konteksty i reguły. W omawianym przykładzie występują następujące elementy typu `itemData`: Normal Text, String i Keyword.

      <highlighting>
          <list name="somename">
            <item> class </item>
            <item> const </item>
          </list>
          <contexts>
            <context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
              <keyword attribute="Keyword" context="#stay" String="somename" />
              <DetectChar attribute="String" context="string" char="&quot;" />
            </context>
            <context attribute="String" lineEndContext="#stay" name="string" >
              <DetectChar attribute="String" context="#pop" char="&quot;" />
            </context>
          </contexts>
          <itemDatas>
            <itemData name="Normal Text" defStyleNum="dsNormal" />
            <itemData name="Keyword" defStyleNum="dsKeyword" />
            <itemData name="String" defStyleNum="dsString" />
          </itemDatas>
        </highlighting>

Ostatnią częścią struktury piku definicji podświetlania jest opcjonalna sekcja `general`, która może zawierać dodatkowe informacje o słowach kluczowych, zasadach zwijaniu kodu, komentarzach i wcięciach.

- W części `comment` definiowany jest napis rozpoczynający komentarz jedno-wierszowy. Możliwe jest także definiowanie komentarzy wielowierszowych za pomocą multiLine z dodatkowym atrybutem end. Ta część definicji jest niezbędna do działania poleceń Komentarz/Odkomentuj dostępnych w programie &kate;.

  W sekcji `keywords` określona jest wrażliwość na wielkość liter przy rozpoznawaniu słów kluczowych. Pozostałe atrybuty opisane są poniżej.

      <general>
          <comments>
            <comment name="singleLine" start="#"/>
          </comments>
          <keywords casesensitive="1"/>
        </general>
      </language>

### Szczegółowy opis poszczególnych sekcji

W tej części omówione zostaną wszystkie dostępne atrybuty dla elementów typu: context, itemData, keywords, a także dla komentarzy, zasad zwijania kodu i wcięć.

Element `context`, należący do grupy `contexts`, definiuje reguły specyficzne dla określonego kontekstu, czyli np. co ma się stać, jeżeli system analizy składni dojdzie do końca wiersza. Dostępne atrybuty to:

- `name` określa nazwę kontekstu wykorzystywaną w operacjach przełączania kontekstu podczas interpretacji reguł analizy składni.

  `lineEndContext` określa na jaki kontekst system analizy powinien się przełączyć po osiągnięciu końca wiersza. Może to być nazwa kontekstu, napis `#stay` oznaczający pozostanie w bieżącym kontekście lub napis `#pop` powodujący przejście do poprzedniego kontekstu. Możliwe jest wielokrotne użycie #pop np.:`#pop#pop#pop` aby przejść do trzeciego kontekstu wstecz.

  `lineBeginContext` określa zmianę kontekstu w przypadku wykrycia początku wiersza. Wartość domyślna: #stay.

  `fallthrough` nakazuje systemowi podświetlania składni do przełączenia się do innego kontekstu (określonego przez "fallthroughContext"), jeżeli żadna reguła nie zostanie dopasowana. Wartość domyślna: false.

  `fallthroughContext` określa kontekst, do którego system powinien się przełączyć, jeżeli żadna reguła nie zostanie dopasowana.

  `dynamic` jeżeli ma wartość true, to powoduje zachowywanie napisów/wskaźników miejsca zapisanych przez reguły dynamiczne. Jest to wymagane np. przez dokumenty typu HERE. Wartość domyślna: false.

Element `itemData` należący do grupy `itemDatas` definiuje style czcionki i kolory. Możliwe jest z jego pomocą samodzielne definiowanie własnych stylów i kolorów, chociaż zalecane jest korzystanie ze stylów domyślnych, tak aby użytkownik widział te same kolory w różnych językach programowania. Czasami jednak niezbędne jest zdefiniowanie własnych kolorów i stylów czcionki. Dla tego elementu wymagane są atrybuty "name" oraz "defStyleNum" zaś pozostałe są opcjonalne. Dostępne atrybuty:

- `name` określa nazwę elementu itemData. Poszczególne reguły i konteksty będą korzystać z tej nazwy, odnosząc się do tego elementu itemData.

  `defStyleNum` określa styl domyślny, który należy wykorzystać do wyświetlania. Dostępne style domyślne są opisane poniżej.

  `color` określa kolor w formacie '#rrggbb' lub '#rgb'.

  `selColor` określa kolor zaznaczenia.

  `italic` jeżeli true to tekst będzie wyświetlony kursywą.

  `bold` jeżeli true to tekst będzie pogrubiony.

  `underline` jeżeli true to tekst będzie podkreślony.

  `strikeout` jeżeli true to tekst będzie przekreślony.

Element `keywords` należący do grupy `general` określa właściwości dla słów kluczowych i posiada następujące atrybuty:

- Atrybut `casesensitive` mogący przyjmować wartości true lub false. Jeżeli będzie to wartość true to operacja dopasowania słów kluczowych będzie wrażliwa na wielkość liter.

  `weakDeliminator` zawiera listę znaków nie pełniących funkcji rozdzielającej słowa. Na przykład kropka `'.'` rozdziela słowa. Jeżeli więc jakieś słowo kluczowe na liście `list` zawiera kropkę, to zostanie dopasowane tylko wtedy, gdy kropka zostanie zdefiniowana tutaj jako znak nie pełniący funkcji rozdzielającej.

  `additionalDeliminator` określa dodatkowe znaki rozdzielające.

  `wordWrapDeliminator` określa znak, po którym może nastąpić przejście do następnego wiersza.

  Domyślnymi znakami rozdzielającymi są znaki: `.():!+,-<=>%&*/;?[]^{|}~\`, spacja (`' '`) oraz tabulator (`'\t'`).

Element `comment` należący do grupy `comments` zawiera informacje niezbędne do działania poleceń menu: Narzędzia Komentarz oraz Narzędzia Odkomentuj. Dostępne atrybuty:

- Atrybut `name` może mieć wartość singleLine lub multiLine. W przypadku użycia argumentu multiLine wymagane stają się atrybuty end oraz region.

  `start` określa napis oznaczający początek komentarza (np. w języku C++ jest to "/*").

  `end` określa napis oznaczający koniec komentarza (np. w języku C++ jest to "*/").

  `region` określa nazwę dla zwijalnego wielowierszowego komentarza. Zakładając, że zdefiniowane są następujące reguły: beginRegion="Comment" ... endRegion="Comment" można jako wartość tego atrybutu ustawić region="Comment". Dzięki temu odkomentowywanie tekstu działa nawet jeżeli nie zostanie zaznaczony cały komentarz wielowierszowy. Wystarczy, że kursor znajduje się w dowolnym miejscu treści tego komentarza.

Element `folding` należący do grupy `general` określa właściwości funkcji zwijania kodu. Dostępne są dla niego następujące atrybuty:

- `indentationsensitive` jeżeli jest true, to znaczniki zwijania będą dodawane z uwzględnieniem wcięć, tak jak w języku skryptowym Python. Z reguły nie jest to jednak wymagane, a wartością domyślną jest: false.

Element `indentation` należący do grupy `general` określa algorytm generowania automatycznych wcięć. Definiowanie tego elementu nie jest wskazane, dlatego iż wcięcia są generowane w zależności od typu pliku lub od trybu edycji wiersza. Jeżeli element zostanie zdefiniowany to spowoduje wymuszenie na użytkowniku stosowania automatycznych wcięć, nawet jeżeli on tego nie potrzebuje. Dla elementu dostępne są atrybuty:

- `mode` określa nazwę trybu generowania wcięć. Możliwe są następujące tryby: normal, cstyle, csands, xml, python oraz varindent.

### Style domyślne

Style domyślne zostały już wcześniej krótko omówione. Są to predefiniowane w programie &kate; style i kolory czcionki.

Poniżej przedstawiono listę dostępnych stylów domyślnych:

- `dsNormal`, dla zwykłego tekstu.

  `dsKeyword`, dla słów kluczowych.

  `dsDataType`, dla definicji typów danych.

  `dsDecVal`, dla liczb dziesiętnych.

  `dsBaseN`, dla liczb zapisanych w systemie innym niż dziesiętny.

  `dsFloat`, dla liczb zmiennoprzecinkowych.

  `dsChar`, dla znaków.

  `dsString`, dla napisów.

  `dsComment`, dla komentarzy.

  `dsOthers`, dla 'pozostałych' elementów.

  `dsAlert`, dla komunikatów i ostrzeżeń.

  `dsFunction`, dla wywołań funkcji.

  `dsRegionMarker`, dla wyświetlania znaczników regionów.

  `dsError`, dla podświetlenia błędów w kodzie i błędnej składni.

## Reguły interpretacji składni

Poniższa sekcja opisuje reguły rozpoznawania składni.

Każda reguła może zostać dopasowana do zera lub większej liczby znaków, począwszy od początku napisu podlegającego interpretacji. Jeżeli reguła zostaje dopasowana, to określonym znakom przypisany zostaje styl lub atrybut określony przez tę regułę. Może też zostać przełączony kontekst analizy treści.

Reguła wykrywania zapisana jest następująco:

    <RuleName attribute="(identyfikator)" context="(identyfikator)" [atrybuty specyficzne dla reguły] />

Element attribute określa nazwę stylu wyświetlania dla dopasowanego napisu, zaś context określa kontekst, który powinien obowiązywać począwszy od tego miejsca.

Atrybut context może zostać zapisany jako:

- Identyfikator stanowiący nazwę kontekstu.

- Kolejność tzn. określenie czy system ma pozostać w bieżącym kontekście(`#stay`) czy też zmienić kontekst na poprzedni (`#pop`).

  Przejście o kilka kontekstów wstecz możliwe jest za pomocą powtórzeń słowa #pop, np: `#pop#pop#pop`

Niektóre reguły mogą posiadać reguły powiązane, które są przetwarzane w przypadku zaistnienia dopasowania reguły podstawowej. Całość dopasowanego napisu otrzyma atrybut zdefiniowany przez regułę podstawową. Przykładowa reguła zawierająca regułę powiązaną wygląda tak:

    <RuleName (atrybuty)>
      <ChildRuleName (atrybuty) />
      ...
    </RuleName>

Atrybuty dotyczące poszczególnych reguł mogą się różnić, a ich charakterystyka zamieszczona jest poniżej.

## Atrybuty wspólne

Wszystkie reguły posiadają pewne wspólne zestawy atrybutów, co zaznaczone jest w opisie reguły określeniem: `(atrybuty wspólne)`. Atrybuty attribute oraz context są wymagane, a wszystkie pozostałe są opcjonalne.

- attribute: Atrybut odnoszący się do zdefiniowanego elementu itemData.

- context: Określa kontekst, na który ma przełączyć się system podświetlania składni, jeżeli reguła zostanie dopasowana.

- beginRegion: Definiuje początek bloku zwijania kodu. Wartość domyślna: nie ustawione.

- endRegion: Kończy blok dla zwijania kodu. Wartość domyślna: nie ustawione.

- lookAhead: Jeżeli jest true, to system podświetlania nie będzie przetwarzał całej długości dopasowania. Wartość domyślna to: false.

- firstNonSpace: Dopasowuje regułę, ale tylko wtedy gdy dany napis jest pierwszym napisem w wierszu, nie rozpoczynającym się od spacji. Wartość domyślna: false.

- column: Dopasowuje regułę tylko jeżeli kolumna też jest dopasowana. Wartość domyślna: nie ustawione.

## Zasady dynamiczne

Niektóre reguły dopuszczają stosowanie atrybutu logicznego `dynamic`, który ma wartość domyślną false. Jeżeli nadana zostanie mu wartość true, to reguła może wtedy wykorzystać znacznik pozycji dla tekstu dopasowanego przez regułę z wyrażeniem regularnym, która spowodowała przełączenie się do bieżącego kontekstu. Dla `napisu` znacznik miejsca `%N` (gdzie N to liczba) będzie zamieniony przez tekst odpowiadający `N`-temu podwyrażeniu w wyrażeniu regularnym. Dla `znaku` znacznik ten też musi być liczbą i zostanie zamieniony na pierwszy znak `N`-tego podwyrażenia w wyrażeniu regularnym. Jeżeli reguła dopuszcza istnienie tego atrybutu, to zostanie oznaczona napisem (dynamiczna) w poniższej dokumentacji.

- dynamic może przyjmować wartości (true|false).

### Reguły - charakterystyka

DetectChar

- Wykrywa określony znak. Często używane na przykład do wykrywania końca napisów w cudzysłowach.

      <DetectChar char="(znak)" (atrybuty wspólne) (dynamiczna) />

  Atrybut `char` określa poszukiwany znak.

Detect2Chars

- Wykrywa dwa następujące po sobie znaki.

      <Detect2Chars char="(znak)" char1="(znak)" (atrybuty wspólne) (dynamiczna) />

  `char` określa pierwszy znak do wykrycia, zaś `char1` określa drugi znak.

AnyChar

- Wykrywa jeden znak ze zdefiniowanego zbioru znaków.

      <AnyChar String="(napis)" (atrybuty wspólne) />

  Atrybut `String` definiuje zbiór znaków.

StringDetect

- Wykrywa dokładne wystąpienie napisu.

      <StringDetect String="(napis)" [insensitive="true|false"] (atrybuty wspólne) (dynamiczna) />

  Atrybut `String` określa napis wyszukiwany. Atrybut `insensitive` ma wartość domyślną false i jest przekazywany do funkcji porównywania napisów. Jeżeli wartość tego atrybutu jest true, to dopasowanie tekstów będzie wrażliwe na wielkość liter.

RegExpr

- Wyszukuje fragment zdefiniowany wyrażeniem regularnym.

      <RegExpr String="(napis)" [insensitive="true|false"] [minimal="true|false"] (atrybuty wspólne) (dynamiczna) />

  Atrybut `String` zawiera wyrażenie regularne.

  Atrybut `insensitive` ma wartość domyślną false i jest przekazywany jako parametr do systemu interpretacji wyrażeń regularnych.

  `minimal` ma wartość domyślnąfalse i jest przekazywany jako parametr do systemu interpretacji wyrażeń regularnych.

  Ponieważ reguły są zawsze dopasowywane od początku bieżącego tekstu, wyrażenie regularne rozpoczynające się od znaku karetki (`^`) będzie oznaczać, iż reguła powinna być dopasowana tylko na początku wiersza.

  Więcej informacji na ten temat w części: Wyrażenia regularne.

keyword

- Wykrywa słowo kluczowe z podanej listy.

      <keyword String="(nazwa listy)" (atrybuty wspólne) />

  Atrybut `String` określa listę słów kluczowych poprzez jej nazwę. Lista o tej nazwie musi istnieć.

Int

- Wykrywa liczbę całkowitą.

      <Int (atrybuty wspólne) (dynamiczna) />

  Reguła ta nie posiada dodatkowych atrybutów. Reguły powiązane są zwykle wykorzystywane do wykrywania kombinacji znaków `L` oraz `U`, następujących po liczbie, określających zwykle typ liczby całkowitej w kodzie programu. Jako regułę powiązaną można wykorzystać dowolną inną regułę mimo tego, że definicja składni DTD dopuszcza jedynie powiązanie z regułą `StringDetect`.

  Poniższy przykład przedstawia regułę, która dopasowuje liczbę całkowitą po której wystąpi litera 'L'.

      <Int attribute="Decimal" context="#stay" >
        <StringDetect attribute="Decimal" context="#stay" String="L" insensitive="true"/>
      </Int>

Float

- Wykrywa liczbę zmiennoprzecinkową.

      <Float (atrybuty wspólne) />

  Ta reguła nie ma dodatkowych atrybutów. Może być powiązana z regułą `AnyChar`, która wykorzystywana jest często do wyszukiwania różnych wariantów. Podobne zastosowanie przedstawiono przy omawianiu reguły `Int`.

HlCOct

- Wykrywa liczbę zapisaną w formacie ósemkowym.

      <HlCOct (atrybuty wspólne) />

  Ta reguła nie ma dodatkowych atrybutów.

HlCHex

- Wykrywa liczbę zapisaną w formacie szesnastkowym.

      <HlCHex (atrybuty wspólne) />

  Ta reguła nie ma dodatkowych atrybutów.

HlCStringChar

- Wykrywa znak specjalny zapisany za pomocą odwrotnego ukośnika.

      <HlCStringChar (atrybuty wspólne) />

  Ta reguła nie ma dodatkowych atrybutów.

  Dopasowuje sekwencje specjalne, reprezentujące znaki specjalne często używane w kodach źródłowych programów, np. `\n` (znak nowego wiersza) lub `\t` (znak tabulacji).

  Zostaną dopasowane następujące znaki zapisane po odwrotnym ukośniku (`\`) : `abefnrtv"'?\`. Dodatkowo dopasowane zostaną sekwencje zawierające liczby szesnastkowe: `\xff` lub ósemkowe `\033`.

HlCChar

- Wykrywa znak w języku C.

      <HlCChar (atrybuty wspólne) />

  Ta reguła nie ma dodatkowych atrybutów.

  Reguła dopasowuje pojedynczy znak w języku C zamknięty apostrofami (np.:`'c'`). Wewnątrz apostrofów może znajdować się pojedynczy znak lub sekwencja specjalna opisująca pojedynczy znak. Więcej o dopasowaniu sekwencji specjalnych znajduje się w opisie reguły HlCStringChar.

RangeDetect

- Wykrywa napis rozpoczynający się i kończący określonymi znakami.

      <RangeDetect char="(znak)"  char1="(znak)" (atrybuty wspólne) />

  `char` określa początkowy znak zakresu znaków, zaś `char1` określa znak kończący zakres.

  Reguła może być wykorzystywana do wykrywania krótkich napisów w cudzysłowach, należy jednak pamiętać, iż system podświetlania składni analizuje pojedyncze wiersze, tak więc nie zostaną wykryte napisy wielowierszowe.

LineContinue

- Wykrywa koniec wiersza.

      <LineContinue (atrybuty wspólne) />

  Ta reguła nie ma dodatkowych atrybutów.

  Reguła ta jest przydatna przy przełączaniu kontekstu po osiągnięciu końca wiersza, jeżeli ostatnim znakiem jest odwrotny ukośnik (`'\'`). Jest to wykorzystywane na przykład w językach C i C++ do zapisu makr w wielu wierszach kodu.

IncludeRules

- Dołącza reguły z innego kontekstu lub pliku definicji języka.

      <IncludeRules context="odnośnikkontekstu" [includeAttrib="true|false"] />

  Parametr `context` określa kontekst, który należy dołączyć.

  Jeżeli parametr jest nazwą innego kontekstu to spowoduje, to przyłączenie wszystkich określonych w innym kontekście reguł do bieżącego kontekstu, np.:

      <IncludeRules context="anotherContext" />

  Jeżeli podany napis rozpoczyna się od `##`, to system podświetlania składni odszuka definicji innego języka o podanej nazwie, np.:

      <IncludeRules context="##C++" />

  Jeżeli atrybut `includeAttrib` ma wartość true, to nastąpi zmiana atrybutów na występujący w źródle. Może to być przydatne do podświetlania fragmentów z przykładami w innym formacie dokumentu, tzn. gdy tekst dopasowany przez dołączony kontekst wykorzystuje inną definicję dla podświetlania składni.

DetectSpaces

- Wykrywa spacje.

      <DetectSpaces (atrybuty wspólne) />

  Ta reguła nie ma dodatkowych atrybutów.

  Regułę tę wykorzystuje się w przypadkach, gdy wiadome jest, iż w wierszu znajduje się wiele spacji, np. przy wciętych wierszach. Spowoduje ona pominięcie wszystkich spacji jednocześnie zamiast testowania wszystkich reguł znak po znaku dla każdej z nich.

DetectIdentifier

- Wykrywa identyfikatory (określone wyrażeniem regularnym: [a-zA-Z_][a-zA-Z0-9_]*).

      <DetectIdentifier (atrybuty wspólne) />

  Ta reguła nie ma dodatkowych atrybutów.

  Reguła powyższa służy do pomijania całego napisu składającego się ze znaków składających się na wyraz, zamiast sprawdzania wielu reguł z powodu braku dopasowania.

### Porady

Po zrozumieniu zasady działania mechanizmu przełączania kontekstów tworzenie definicji reguł podświetlania stanie się proste. Należy jednak zawsze dokładnie sprawdzić dostosowanie wybranej reguły do konkretnej sytuacji. Wyrażenia regularne dają ogromne możliwości, ale działają wolno w porównaniu z innymi regułami. Poniżej opisano kilka porad pomocnych w tworzeniu plików definicji reguł podświetlania.

- Jeżeli poszukiwane są tylko dwa znaki to należy wykorzystywać regułę `Detect2Chars` zamiast `StringDetect` (to samo dotyczy reguły `DetectChar`).

- Użycie wyrażeń regularnych jest proste, jednak często istnieją inne, dużo szybsze sposoby osiągnięcie tego samego rezultatu. Zakładając, iż konieczne jest dopasowanie znaku `'#'` jako pierwszego w wierszu. Odpowiednie wyrażenie regularne miałoby postać:

      <RegExpr attribute="Macro" context="macro" String="^\s*#" />

  To samo można uzyskać poprzez:

      <DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" />

  Zamiast wyrażenia regularnego `'^#'` można zastosować regułę `DetectChar` z atrybutem `column="0"`. Atrybut `column` odnosi się do znaków w tekście, tak więc znak tabulatora zostanie policzony jako jeden znak.

- Możliwe jest przełączanie kontekstów bez przetwarzania znaków. Przypuśćmy, iż konieczne jest przełączenie kontekstu po napotkaniu napisu `*/` ale konieczne jest przetworzenie tego napisu w kolejnym kontekście. Poniższa reguła zostanie dopasowana, zaś atrybut `lookAhead` spowoduje zachowanie dopasowanego napisu do przetwarzania w kolejnym kontekście.

      <Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" />

- Można skorzystać z `DetectSpaces`, jeżeli spodziewane jest wystąpienie wielu spacji.

- Zamiast wyrażenia regularnego `'[a-zA-Z_]\w*'` można wykorzystać `DetectIdentifier`.

- Należy w miarę możliwości używać styli domyślnych, dzięki temu użytkownik będzie miał spójne środowisko pracy z różnymi plikami.

- Można podejrzeć zawartość innych plików definicji reguł podświetlania, aby zorientować się w sposobie definiowania bardziej skomplikowanych reguł.

- Sprawdzenie poprawności stworzonego pliku XML możliwe jest z wykorzystaniem polecenia: `xmllint --dtdvalid language.dtd mySyntax.xml`.

- W przypadku częstego korzystania z wyrażeń regularnych można skorzystać z mechanizmu ENTITIES, np:

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE language SYSTEM "language.dtd"
      [
              <!ENTITY myref    "[A-Za-z_:][\w.:_-]*">
      ]>

  Dzięki temu można zastosować &myref; zamiast wyrażenia regularnego.