= Hugo Tests
Tristano Ajmone
:HL_VER: 3.54
:HugoLang_VER: 1.1.0
2019-11-14: hugo.lang v{HugoLang_VER} | Hugo v3.1.03 | Highlight {HL_VER}
:version-label: v
:lang: en
// TOC Settings:
:toc: left
:toclevels: 5
// Sections Options:
:sectnums!:
:sectanchors:
// Cross References:
:xrefstyle: short
:section-refsig: Sect.
// Misc Settings:
:experimental:
:icons: font
:linkattrs:
:reproducible:
// GitHub Settings for Admonitions Icons:
ifdef::env-github[]
:caution-caption: :fire:
:important-caption: :heavy_exclamation_mark:
:note-caption: :information_source:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]

// =====================================
// Custom Attributes for Reference Links
// =====================================
:hugo-book: http://htmlpreview.github.io/?https://github.com/tajmone/hugo-book/blob/draft/docs_src/hugo-book.html
:hugo-src: https://github.com/tajmone/hugo/blob/master/source/

// *****************************************************************************
// *                                                                           *
// *                            Document Preamble                              *
// *                                                                           *
// *****************************************************************************



== Tests Contents

To execute tests, launch `test.sh` in Bash.

* `test.sh` -- executes all tests.
* `errors.log` -- failed tests log file.


== Source Files Encoding

The test files are all in ISO-8859-1, since Hugo doesn't support Unicode and the most common encoding for text adventures is Latin1 (although other single-byte encodings are allowed).
Technically speaking, Hugo sources should be strictly in Ascii, using escape sequences to handle special characters not present in the Ascii character set; but use of Latin1 strings is permissible (without guarantees that they will display properly on all supported OSs and terminal interpreters),

Although Hugo source files are likely to be in ISO-8859-1 or ASCII encoding, in documentation projects chances are they'll come as snippets inside UTF-8 documents, or converted to UTF-8 due to toolchain requirements (e.g. Asciidoctor requires included files to be in UTF-8).

Some escape sequences characters (defined as `Interpolation`) might differ depending on the encoding of the Hugo source -- e.g. to cover the acute accent in the `\´` escape, the Hugo syntax tries to match it both in ASCII (`´`) and UTF-8 (`\xC2\xB4`).

This is an example of how old languages from the pre-Unicode era might need extra care when they might be highlighted in context demanding UTF-8 conversion of the original source, for some edge-cases might be encountered for those characters from the (so called) "`extended ASCII`" charset (in this case, ISO-8859-1) which end up being econded with two bytes in UTF-8.


== About Hugo


The Hugo Interactive Fiction Development System (1995-2006) is bot a language and a set of cross-platform tools for creating text-adventures with sound and graphics, developed by Kent Tessman for The General Coffee Company Film Productions, released under BSD-2-Clause License.

* http://www.generalcoffee.com/hugo/gethugo.html
* http://ifwiki.org/index.php/Hugo

== About Hugo LangDef

Syntax definition for Hugo language v3.1.03 (2006).

Hugo's Highlight definition was created by Tristano Ajmone in May 2019.

Released into the public domain according to the Unlicense terms:

* http://unlicense.org

=== Syntax Elements

Hugo's langDef highlights the following elements:

* Comments: Single line and block.
* Strings:
** Literal: Delimiters `"`.
* Escape/Interpolation: Hugo has many escape sequences (only inside strings), including some to control text style and others to produce special characters (accented letters, etc.).
So I've placed the latter under the `Interpolation` element, to provide visual separation between the two groups.
This is because prose strings are likely to contain many adjacent escapes of both types.
* Operators.
* Digits: integers only.
* Preprocessor: compiler directives.

Keywords Groups:

. Hugo keywords.
. Built-in global variables, properties and engine variables.
. ASCII chars constants, system words, properties qualifiers, boolean constants (`true`/`false`).
. Limit settings.


== Hugo References

Some useful links to link:{hugo-book}[_The Hugo Book_^,title="Read 'The Hugo Book' online version"] and link:{hugo-src}[Hugo source files^] for understanding the Hugo syntax.

* link:{hugo-book}[_The Hugo Book_^,title="Read 'The Hugo Book' online version"] -- online HTML version.
* link:https://github.com/tajmone/hugo[Hugo sources^] -- on GitHub.


=== Hugo Tokens


* link:{hugo-src}htokens.h#L78[Hugo sources: `htokens.h`^] -- array with all Hugo tokens.
* link:{hugo-book}#tokens[_The Hugo Book_: 15.1. Tokens^] -- lists all all Hugo tokens.


=== Built-in Engine Globals

* link:{hugo-book}#before_we_get_to_the_routines[_The Hugo Book_: §8.1^] -- lists the twelve global variables pre-defined by the engine.
* link:{hugo-book}#globals[_The Hugo Book_: Appendix B.2^] -- lists the twelve globals pre-defined by the engine.
* link:{hugo-src}he.c#L18[Hugo sources: `he.c`^] -- predefined engine globals.


=== Built-in Engine Properties

* link:{hugo-book}#before_we_get_to_the_routines[_The Hugo Book_: §8.1^] -- lists the six properties pre-defined by the engine.
* link:{hugo-book}#properties_2[_The Hugo Book_: Appendix B.5^] -- lists the six properties pre-defined by the engine.
* link:{hugo-src}hcmisc.c#L1651[Hugo sources: `hcmisc.c`^] -- predefined engine properties.
* link:{hugo-src}he.c#L32[Hugo sources: `he.c`^] -- predefined engine properties.
* link:{hugo-src}he.c#L39[Hugo sources: `he.c`^] -- predefined "`display`" object properties properties.


=== Built-in Engine Functions

:fn6: pass:a,m,q[link:{hugo-book}++#_footnotedef_6++[The Hugo Book: footnote 6.^]]

[quote, {fn6}]
____
Built-in functions are just like other Hugo functions except that they're never defined anywhere in source code or any library file: the compiler and engine always know about them.
To distinguish them, they're generally printed in lowercase, whereas program-defined routines (including library routines) are almost always capitalized.
____


=== Limit Settings

* link:{hugo-book}#limit_settings_2[_The Hugo Book_: Appendix C: Limit Settings^].


=== Compiler Directives

* link:{hugo-book}#compiler_directives[_The Hugo Book_: §2.7. Compiler Directives^].
* link:{hugo-src}hccomp.c#L22[Hugo sources: `hccomp.c`^] -- contains all compiler directives.

// EOF //
