Writing language definition files
Bluefish language definition files
All syntax highlighting and autocompletion is defined in bluefish language definition files, saved in .bflang2 files. In the source code they can be found in data/bflang/
On Linux they are installed in /usr/share/bluefish/bflang/
Example files
shell.bflang2 is the most simple example of what a language definition can look like. php.bflang2 is probably the most complex example with many included files and many different syntax types supported within another syntax (javascript, css, html and php itself). There is also sample.bflang2 that describes more or less the same as this wikipage.
Editing bflang files
If you store a bflang2 file in your bluefish settings directory ~/.bluefish/ it has higher priority than the system wide installed files. So if you are going to change a bflang2 file, just copy it into ~/.bluefish/
If you start bluefish from the commandline it will output errors and warnings about the bflang2 files that are loaded. So after you have edited a bflang2 file, test it, and look at the output in the terminal.
Including files
The top of a bflang file may define new entities that will include another file. For example the line
<!ENTITY css-rules SYSTEM "css-rules.bfinc">
defines that &css-rules; should be replaced by the contents of css-rules.bfinc
This makes it easier to re-use syntax. CSS is for example used in html, php and css itself.
Deep understanding of the Bluefish syntax scanning
If you want a deep understanding how the syntax scanner works, please read the documentation written in src/bftextview2.h included in the Bluefish source code.
The format of the file
The file format is XML.
It starts with a root tag <bflang>:
<bflang name="Shell" version="2.0" > </bflang>
Inside the root tag there are three sections
The header section
The header section is always loaded for each bflang2 file. The rest of the file is loaded "on demand", so only if it is needed.
<header> <mime type="application/x-shellscript"/> <option name="show_in_menu" default="1"/> <highlight name="value" style="value" /> </header>
The mime tag in the header
The mime tag specifies for which mime types this definition file is used. There can be multiple mime types specified. Sometimes a file doesn't have a specific mime type, or the mime type is not defined on many systems. In that case the mime type is often something like text/plain Bluefish supports a combination of mime type and extension. To detect a file type that ends on .fake you add
<mime type="application/x-fake"/> <mime type="text/plain?fake"/>
The option tag in the header
The option tag defines an option that is used further on in the language file
<option name="allphpfunctions" default="1" description="All php functions" />
A special note: All language files share one list of option names and their description. So if two or more options have the same name, they will get the same description in Bluefish. If they have a different description inside the file, it is not defined which description is used!!!
There are a few special (hardcoded) option names:
In this example a block named 'php block' is made optionally foldable (or not). The '_foldable' suffix is hardcoded in bluefish.
<option name="php block_foldable" default="1" description="Allow the PHP block to fold"/>
Whether or not to load the reference data for this language (saves memory)
<option name="load_reference" default="1"/>
Whether or not to load the auto completion data for this language (saves memory)
<option name="load_completion" default="1" />
Whether or not to close <tag> in the auto-completion <option name="autocomplete_tags" default="1" />
Whether or not to show this language by default in the menu
<option name="show_in_menu" default="0"/>
The highlight tag in the header
The higlight tag defines which element-types that are defined in the file, and which styles should be applied for each of these types. THESE CAN BE ALTERED BY THE USER IN THE PREFERENCES PANEL..
So if an element in this file has attribute highlight="foo", this section should have <highlight name="foo" style="somestyle"/>. Look at other language files and try to re-use styles !!!!!!!!!
For the end-user it is convenient if styles are re-used. All languages that define a comment should use style 'comment' by default.
<highlight name="comment" style="comment" />
Some users may like the same color for all keywords, other may like a different style for storage types and language keywords. So use a different 'highlight' name for them, such that users may assign a different textstyle if they want.
<highlight name="storage-types" style="keyword" /> <highlight name="keyword" style="keyword" />
The properties section
The properties section is similar to the header, but it is loaded on-demand. As long as there is no syntax scanning needed for this type of file, the properties section is not yet loaded.
The comment tag in the properties section
the comment tag defines which type of line comments and block comments that could exist in this language. The smart comment function shift-ctrl-c uses this information to comment or uncomment
<comment id="cm.cblockcomment" type="block" start="/*" end="*/" /> <comment id="cm.htmlcomment" type="block" start="<!--" end="-->" /> <comment id="cm.cpplinecomment" type="line" start="//" /> <comment id="cm.scriptcomment" type="line" start="#" />
The smartindent and smartoutdent tags in the properties section
smartindent characters specify which characters, followed by a return, should increase the indenting. Smartoutdent means that this character, typed immediately after auto-indenting has set the indenting, should decrease the previous auto-indenting
<smartindent characters="{" />
<smartoutdent characters="}" />
The default_spellcheck tag in the properties section
default_spellcheck defines if regions that are not highlighted will be checked by the spell checker. This is typically enabled for markup languages like HTML and XML, and disabled (or left out, because the default=0) for all programming languages
<default_spellcheck enabled="1" />
The definition section
The definition section is where the syntax is really described.
A language definition always starts with a <context> tag, and contains ONE SINGLE context tag (which may have other context tags as children).
The concept of contexts
Different positions in a file may have a different syntax. An HTML example: inside a comment you can have a < character without breaking the syntax. That means that the syntax scanner inside a HTML comment is only looking for the end of the comment. But outside the comment it is looking for tags, or entities. Thus the syntax scanner runs in two different contexts: the main context (where a tag, entity or comment may be started), and the comment context (where only the end of the comment is relevant). But inside a tag we have again a new context, because we only look for attributes. And we may have CSS inside HTML, or javascript. And inside javascript we can again have a comment. Etc. etc. etc. The HTML syntax currently has 465 contexts.
The syntax scanner always is in one single context.
The context tag in the definition section
<context symbols="><&; 	 " commentid_block="cm.htmlcomment" commentid_line="none">
Or
<context symbols="LIST OF CHARACTERS" highlight="HIGHLIGHT-TYPE" id="IDENTIFIER" >
A <context> tag should always define symbols. Symbols are those characters that may start or end an element.
The optional attribute highlight may specify a highlight type that is valid for the complete text region that has this context. Useful for 'comment' or 'string' type of contexts where the complete context is highlighted
The optional attributes commentid_block and commentid_line may specify how the comment toggle function should work in this context. The value should refer to the comment section in the properties.
What are symbols
Symbols are characters that may start or end a pattern. Try to highlight for example:
char *rc_char(char*chara); ^^^^ ^^^^
Only two of the four 'char' need to be highlighted. How does the scanner know which one to highlight? In the above example there are several symbols such as whitespace , brackets and operators:
char *rc_char(char*chara); ^ ^^ ^ ^ ^^
see that the occurences of 'char' that should be highlighted are all in between symbols?!
To detect function strlen in the following examples (language C):
i=strlen(a); i+strlen(a); i*strlen (a);
we need at least symbols =+*(
In most languages all whitespace is a symbol ( =space, 	=tab, =newline, =carriange return).
In xml/sgml/html only '<>&;' are symbols, but withtin a tag also " and ' are symbols.
Advanced use of context tags
The optional attribute id is used to define an identifier which can be used to re-use this context. To re-use a context, use
<context idref="IDENTIFIER" />
where IDENTIFIER refers to a previously defined context with an id. The file is parsed top to bottom, so previous must be earlier in the file.
Inside a context tag
Inside a context tag are usually the tags element, tag, group. For advanced usage it can have another context.
Advanced use of context tags
If there is a context inside another context, it must have it's id set. This context is defined but not yet used. It can be used if it is referred to with <context idref="" />
The element tag in the definition section
<element pattern="while" highlight="keyword"/>
<element> defines an element that is highlighted, or can be autocompleted, or an element that starts a new context
it always needs attribute 'pattern' which defines the pattern that will be looked for in this context
the pattern can be defined in 'regular expression' style, to do this add attribute is_regex="1". however, there is only limited regular expression support. you may use - a range of characters such as [a-z0-9;'] - an inverted range such as [^0-9] - operators such as ? (zero or one), + (one or more), and * (zero or more) - subpatterns such as ab(fg)?
<element pattern="'[^']*'" is_regex="1" highlight="string"/>
a pattern may be case insensitive, set case_insens="1"
to highlight the pattern use attribute highlight="TYPE", where TYPE should be defined within the <header> section of the language file
Element re-use
<element> may have attribute 'id' so this element may be referred to later. To re-use element 'foo' later in the file use
<element idref="foo" />
Block detection
Next is a block detection example
<element id="bracket{" pattern="{" starts_block="1" highlight="brackets" block_name="Bracket block" />
<element pattern="}" ends_block="1" blockstartelement="bracket{" highlight="brackets" />
an element may start or end a block. a block consists of two patterns (start and end) where the contents between the start and the end may be hidden when the block is 'folded'.
to make a pattern a block start define starts_block="1" and use the 'id' attribute
to specify a pattern that ends a block use ends_block="1" and use blockstartelement="FOO" where FOO is the id of the start-of-block-element
Because this block has a name ('Bracket block') it can be selected by the user in the expand/collapse popup menu. You can also create an option 'Bracket block_foldable' in the header options so the user may decide if this block may fold or not. If you don't need either the block_name can be left empty.
An element may start a new context
Next is an context example, a javascript comment
<element pattern="/*" highlight="c-style-comment"> <context symbols="*/	 " highlight="c-style-comment"> <element pattern="*/" highlight="c-style-comment" ends_context="1" /> </context> </element>
whenever this pattern is found the engine switches to this context and starts scanning only the patterns defined in this context. To do this define <context></context> between <element> and </element>. within this <context> there are entirely different patterns. There can be only 1 context within an element.
There is an end of the context too in most languages. To make the scanner switch back to the previous context an element INSIDE the inner context that has ends_context="NUM" where NUM specifies the number of contexts that are ended by this element. Because context may be nested there may be several contexts inside each other.
Basically context switches work like a stack. Lets take the example
i = 1; /* text */ i = 1 + 1;
pattern '/*' exists in the initial context, but when it is found, the initial context is pushed on the context stack, and the scanner switches to a new context context (for c-style-comment). In this context there exists only a single pattern: '*/' The scanner now continues until it finds */, at this point it pops 1 context from the stack, and thus in this example it continues with the initial context
Next is a nested context example, inside a php comment, there may be the end of the php block. Note that this element has ends_context=2
<element pattern="<?php" highlight="php-block"> <context symbols="?*/+-=*&<>	 "> <element pattern="?>" highlight="php-block" ends_context="1" /> <element pattern="/*" highlight="c-style-comment"> <context symbols="*/	 " highlight="c-style-comment"> <element pattern="*/" highlight="c-style-comment" ends_context="1" /> <element pattern="?>" highlight="php-block" ends_context="2" /> </context> </element> </context> </element>
Auto completion
an pattern may also be autocompletable. to enable this add <autocomplete /> often it is convenient if not only the pattern itself can be completed but some common characters are appended. use append="STRING" to define any characters that will be autocompleted. The cursor position AFTER auto completion can be set back a couple of characters. This is defined by attribute backup_cursor
a regular expession pattern may be autocompletable as well. but to autocomplete the pattern itself usually makes no sense because it matches various other patterns. use string="STRING" to autocomplete STRING in this context