Colorer-take5 beta2 library HRC Reference. September 2003

# HRC Language Reference

12 September 2003
take5.beta2
12 September 2003
(Available as HTML, PDF, DocBook)
take5.beta1
30 March 2003
take5.alpha3
1 March 2003
take5.alpha2
30 January 2003
Igor Ruskih

          cail at nm.ru

2003 Igor Ruskih (Cail Lomecb)

Abstract

This reference defines syntax and semantic of HRC language, used in Colorer-take5 Library to represent and describe syntax and lexical structure of target programming language. This description is used by library to parse and colourise text in editors or other systems.

## Introduction

HRC is a script language, describing parse process of text files to produce syntax highlighting. It is based on XML language, and defines its own XML vocabulary and structure. HRC language was developed to achieve most flexible and efficient process of describing programming language structure.

Started nearly in year 1999, it was a simple XML-like structure, describing some common language construction. But later it has grown into the much more complex and powerful language, describing complex relations between different languages, syntax contexts.

## Core Syntax

HRC language allows describing and storing syntax rules for numerous languages. All language descriptions are divided into two parts: Informal part, used to describe this language properties, language choose rules (`prototype`), and Formal part, which defines syntax and semantic of target parsed language (`type`). Prototypes are used to determine, which type to apply to the currently opened file, they define some internal application-dependent properties and other useful information about language.

Structure

Each HRC file contains declaration of one or more prototypes or one language type. Root XML content starts with `hrc` element, which contains all other definitions.

Each HRC language object is defined using XML elements and attributes. You can find definition of HRC XML Syntax in . Each element in HRC can be documented with XML Schema-like standard elements:

Annotation object can be used anywhere in HRC context to document and describe any of the HRC elements.

### File Types

Each language prototype requires definition of language name and description. These properties are used to determine language in context of other language definitions and in inter-languages linkage.

#### Prototypes

Each language must be chosen by library before starting syntax highlighting process. This is made with help of `firstline` and `filename` parameters. Each matched instance of one of these parameters adds some additional weight to total language weight. This value is taken by default, or could be changed explicitly with `weight` attribute of these elements. When total weights of all types are evaluated, first language with maximum weight is selected to assign to opened file.

If any of these two operators is used more than one time, each its matched instance adds specified weight to the total language weight.

#### Types

Each prototype defines its linkage with real file type, describing information, specific for the syntax parsing process. This information is stored in basic units, called `type`s.

### Schemas

### Namespaces

xxxxxx

## Scheme syntax

### Keyword lists

### Regular Expressions

### Blocked context switch

### Scheme boundaries and priority

## Inter-scheme links

### Inheritance

### Schemes substitutions

## Regular Expressions syntax

### Introduction

All work of the Colorer library and HRC language is based on the regular expressions (RE) usage. They allows you to create universal syntax rules of highlighting in HRC.

Regular expressions consist of the set of characters. Some of these are simple, and some are special metacharacters. All metacharacters (escapes) are divided into three categories: first - zerolength (words boundaries and so on); second - class metacharacters (`\w`, `\s` `.`); and the third class is operators. RE operators could be applied to single character, to block, enwrapped in brackets or into other operators. You can use brackets to group any sequence of characters. Regular expressions in HRC Language are like Perl regexp in their base syntax. There are some differences in extended operators.

### Syntax

All regexps must be in slashes `/.../` After the end slash there could be parameters:

- `i` - ignore symbol case

- `x` - ignore direct spaces and crlf (for comfort)

- `s` - suppose, that regexp is single line - it means, than '.' class should include \r\n symbols.

Each symbol in RE is linearly compared with the target string. Everything, that doesn't looks like metacharacters, means simple character.

### Metacharacters

Metacharacters

`^` | Match the beginning of the line
`$` | Match the end of the line
`.` | Match any character (except \r\n)
`[...]` | Match characters in set
`[^...]` | Match characters not in set. Here all the operators are disabled, but you can use other metacharacters, and range operator: a-z means all chars from first to second (a - z)
`\#` | Next symbol '#' after slash (except a-z and 1-9)
`\b` | Start of word
`\B` | End of word
`\xNN` | `NN` - ASCII char (hex)
`\n` | 0x10 (lf)
`\r` | 0x13 (cr)
`\t` | 0x09 (tab)
`\s` | tab/space/cr/lf
`\S` | Non-space
`\w` | Word symbol (chars, digits, _)
`\W` | Non-word symbol
`\d` | Digit
`\D` | Non-Digit
`\u` | Uppercase symbol
`\l` | Lowercase symbol

### Extended metacharacter

These metacharacters are incompatible with Perl

Extended Metacharacters

`\c` | means 'non-word before'
`\N` | Link inside of regexp to one of its brackets. `N` - needed brackets pair. This operator works only with non-operator symbols in a bracket.

And these could be disabled during compilaton as highlight-dependent

Extended Metacharacters

`~` | Matches for the start of parent scheme (end of start start).
`\m` | Change start of regexp
`\M` | Change end of regexp
`\yN` | Link to the external regexp (in End to the Start param). N - requeried brackets pair.

### Operators

Operators couldn't be used without some preceding character sequence. Each operator must be applied to the appropriate character, metacharacter, or block of their combination (enclosed with brackets).

Operators

`( )` | Group and remember characters to form one pattern.
`|` | Match previous or next pattern.
`*` | Match previous pattern 0 or more times.
`+` | Match previous pattern 1 or more times.
`?` | Match previous pattern 0 or 1 times.
`{n}` | Repeat n times.
`{n,}` | Repeat n or more times.
`{n,m}` | Repeat from n to m times.

If you'll add `?` after operator, it becomes nongreedy. For example `*` operator becomes nongreedy if placing `*?` Greedy operator tries to take as much in string, as it can. Nongreedy takes by minimum.

### Extended operators

Extended Operators

`?#N` | Look-behind. N - symbol count.
`?~N` | Inverted Look-behind.
`?=` | Look-ahead.
`?!` | Inverted Look-ahead.

Note, that two last operators exist in Perl - in form of `(?=foobar)`. But colorer uses syntax `(foobar)?=`

### Examples

RE examples

`/foobar/`

  will match "foobar", "foobar barfoo"

`/ FOO bar /ix`

  will match "foobar" "FOOBAR" "foobar and two other foos"

`/(foo)?bar/`

  will match "foobar", "bar"

`/^foobar$/`

  will match _only_ with "foobar"

`/([\d\.])+/`

  will match any number

`/(foo|bar)+/`

  will match "foofoofoobarfoobar", "bar"

`/f[obar]+r/`

  will match "foobar", "for", "far"

## HRC Coding Recommendations

Пока хочу сказать, что нужно править всю базу на предмет появившихся пространств имен. Так как раньше ничего этого не было, каждая схема именовалась со своим префиксом. И теперь это все надо убирать нафиг. Иными словами, в описании каждого типа файлов схемы нужно переименовывать, убирать префиксы и называть их нормальными именами. То же самое относится к использованию сущностей и определений регионов.

По возможности не надо использовать функции импорта других типов, потому как это уменьшает читабельность. Исключением может быть только тип def, и случаи, когда очень много ссылок на объекты других типов. Намного понятней выглядит `scheme='c:StringCore'` чем просто `scheme='StringCore'`.

changes:

Возможно, `<import>` я вообще уберу.

## Format of `catalog.xml` file

Catalog of all Colorer Library resources is a convenient way to unify creation and management of all the Colorer features. This catalog is stored in `catalog.xml` file, and mapped into the ParserFactory class. Catalog supports storing of all installed HRC modules, management of error logging and listing of available HRD sets.

## Format of `HRD` color schemes

HRD storage is used to assign each HRC Region with some editor-specific properties. Commonly, these include color and style information. HRD file consists of the list of the entries, each of them describing one HRC Region.

It is possible to maintain different HRD settings for different languages, or to compile them into one single HRD file. The former allows you to distribute recommended settings with each language, and the latter - to unify modifying and storing changed HRD settings with provided UI.

## XML Schema for HRC Language

This XML Schema instance was automatically generated from original hrc.xsd source, available at http://colorer.sf.net/2003/hrc.xsd. All comments and documentation tags were stripped to achieve more compact format. To use this schema in other, than informational purposes, use up-to-date version, available on the link above.

## References

XML 1.0Tim Bray, Jean Paoli, and C. M. Sperberg-McQueen, Eve Maler, editors. Extensible Markup Language (XML) 1.0 Second Edition. W3C (World Wide Web Consortium), 2000.
XSLT 1.0James Clark, editor. XSL Transformations (XSLT) 1.0. W3C (World Wide Web Consortium), 1999.
W3C XML Schema Structures Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, editors. XML Schema Part 1: Structures. W3C (World Wide Web Consortium), 2001.
W3C XML Schema DatatypesPaul V. Biron, Ashok Malhotra, editors. XML Schema Part 2: Datatypes. W3C (World Wide Web Consortium), 2001.