Hugo v1.1.0

* Hugo Syntax: * Merge `hugo-lang-dev` branch into `master` with new Hugo v1.1.0 syntax, as submitted to Highlight (See: saalen/highlight!122). This should make the Highlight GitLab CI tests for Hugo pass, since the Hugo syntax has changed considerably and the old tests no longer apply. * Repository Settings: * Tweak and optimize Git setting. * Add Hugo patterns to Git and EditorConfig setting. * Polish all Hugo files to pass EClint validation. NOTE: Had to disable `charset = latin1` for Hugo in `.editorconfig` due to a bug reporting acute accents as an invalid Latin1 chars. ( See: jednano/eclint#169 )
tajmone · Nov 14, 2019 · 518ca8e · 518ca8e
1 parent a89fb68
commit 518ca8e
Show file tree

Hide file tree

Showing 17 changed files with 892 additions and 213 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -1,11 +1,20 @@
-################################################################################
-# Highlight Languages Test Suite:                                              #
-#   https://gitlab.com/tajmone/highlight-test-suite                            #
-#   https://github.com/tajmone/highlight-test-suite                            #
-################################################################################
+#####################################################
+#  Highlight Languages Test Suite                   #
+#  https://gitlab.com/tajmone/highlight-test-suite  #
+#####################################################
+
+; EditoConfig settings to enforce consistent code styles:
+;   https://editorconfig.org
+
+; For validating and fixing files against these settings:
+;   https://www.npmjs.com/package/eclint
 
 root = true
 
+# ===================
+# REPOSITORY SETTINGS
+# ===================
+# These settings apply to the whole project.
 
 ## Configurations
 #################
@@ -18,8 +27,8 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 
 
-## Lua Scripts
-##############
+## Highlight (Lua) Scripts
+##########################
 [*.{lua,lang,theme}]
 indent_style = space
 indent_size = 2
@@ -38,4 +47,26 @@ charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
 
+# ====================
+# TEST-LANGUAGES FILES
+# ====================
+# When a new language is added to the tests, all its associated files extensions
+# should be added to this section to ensure correct editor/IDE configurations
+# and EditorConfig validation.
+
+
+## Hugo Interactive Fiction
+###########################
+; Hugo sources are strictly in ISO-8859-1 (aka Latin1).
+;   https://www.generalcoffee.com/hugo
+
+[hugo/*.{hug,h,g}]
+; charset = latin1  # BUGGY: reports acute accent as invalid char.
+;                            (see: github.com/jedmao/eclint#169)
+indent_style = space
+indent_size = unset
+end_of_line = unset
+trim_trailing_whitespace = true
+insert_final_newline = true
+
 # EOF #
diff --git a/.gitattributes b/.gitattributes
@@ -1,16 +1,22 @@
-################################################################################
-# Highlight Languages Test Suite:                                              #
-#   https://gitlab.com/tajmone/highlight-test-suite                            #
-#   https://github.com/tajmone/highlight-test-suite                            #
-################################################################################
+#####################################################
+#  Highlight Languages Test Suite                   #
+#  https://gitlab.com/tajmone/highlight-test-suite  #
+#####################################################
+
+# ===================
+# REPOSITORY SETTINGS
+# ===================
+# These settings apply to the whole project.
+
 * text=auto
-# ==============================================================================
-#                                 PROJECT FILES
-# ==============================================================================
 
-## =============
-## DOCUMENTATION
-## =============
+## Highlight
+############
+*.lang    text
+*.theme   text
+
+## Documentation
+################
 *.adoc       text
 *.asciidoc   text
 *.markdown   text
@@ -19,9 +25,8 @@
 COPYING      text
 LICENSE      text
 
-## ===================
-## REPO CONFIGURATIONS
-## ===================
+## Repository configurations
+############################
 .editorconfig  text eol=lf
 .gitlab-ci.yml text eol=lf
 .travis.yml    text eol=lf
@@ -31,56 +36,37 @@ LICENSE      text
 .gitignore     text eol=lf
 .gitmodules    text eol=lf
 
-## =============
-## SHELL SCRIPTS
-## =============
-*.bat      text eol=crlf
-*.com      text eol=crlf
-*.sh       text eol=lf
-*.ps1      text eol=crlf
+## Shell scripts
+################
+*.bat    text eol=crlf
+*.com    text eol=crlf
+*.sh     text eol=lf
+*.ps1    text eol=crlf
 
-# ==============================================================================
-#                              TEST-LANGUAGES FILES
-# ==============================================================================
+# ====================
+# TEST-LANGUAGES FILES
+# ====================
 # When a new language is added to the tests, all its associated files extensions
 # should be added to this section to ensure correct EOL normalization.
 
 ## PureBasic
-############
-*.pb       text
-*.pbi      text
-*.pbp      text
-*.pbf      text
-*.cfg      text
+###############
+purebasic/*.pb     text
+purebasic/*.pbf    text
+purebasic/*.pbf    gitlab-language=PureBasic
+purebasic/*.pbf    linguist-language=PureBasic
+purebasic/*.pbi    text
 
 ## Nim
-######
-*.nim      text
+#########
+nim/*.nim    text
 
 ## Hugo Interactive Fiction
 ###########################
-*.hug      text
-hugo/*.lst text
-hugo/*.hex binary
-
-# ==============================================================================
-#                                GitHub Linguist
-# ==============================================================================
-#  -- https://github.com/github/linguist
-#
-# Manually define/override some extension so that GitHub's Linguist library can
-# 1) Correctly gather statistics on source files, and
-# 2) Use proper syntax highlighting on GitHub's WebUI.
-
-## PureBASIC project files
-## ---------------------------
-*.cfg    linguist-generated=true
-*.pbf    linguist-language=PureBasic
-*.pbp    linguist-generated=true
-*.pbp    linguist-language=XML
-
-## Hugo Interactive Fiction
-## ---------------------------
-*.hug    linguist-language=Hugo
+hugo/*.hug    text
+hugo/*.hug    gitlab-language=Hugo
+hugo/*.hug    linguist-language=Hugo
+hugo/*.lst    text
+hugo/*.hex    binary
 
 # EOF #
diff --git a/.gitignore b/.gitignore
@@ -1,27 +1,32 @@
-################################################################################
-# Highlight Languages Test Suite:                                              #
-#   https://gitlab.com/tajmone/highlight-test-suite                            #
-#   https://github.com/tajmone/highlight-test-suite                            #
-################################################################################
+#####################################################
+#  Highlight Languages Test Suite                   #
+#  https://gitlab.com/tajmone/highlight-test-suite  #
+#####################################################
 
-# ==============================================================================
-#                                 PROJECT FILES
-# ==============================================================================
+# ===================
+# REPOSITORY SETTINGS
+# ===================
+# These settings apply to the whole project.
 
-# Highlight generated html/css files_
+## Highlight
+############
+# Highlight generated html/css files:
 *.html
 highlight.css
 # NOTE: To test HTML syntax use *.htm extension instead!
 
-# TMP Work Files
-___*.*
-
-# Sass
+## Sass/SCSS
+############
 *.css.map
 
-# ==============================================================================
-#                              TEST-LANGUAGES FILES
-# ==============================================================================
+## TMP Work Files
+#################
+___
+___*.*
+
+# ====================
+# TEST-LANGUAGES FILES
+# ====================
 # When a new language is added to the tests, all its associated temporary files'
 # patterns (created by an editor/IDE or compiler) should be added to this section
 # to exclude them from the project.
@@ -40,9 +45,9 @@ purebasic/project.cfg
 hugo/*.lst
 hugo/*.hex
 
-# ==============================================================================
-#                        GENERAL PURPOSE IGNORE PATTERNS
-# ==============================================================================
+# ===============================
+# GENERAL PURPOSE IGNORE PATTERNS
+# ===============================
 
 # Log Files
 # *.log

diff --git a/hugo/README.adoc b/hugo/README.adoc
@@ -1,15 +1,16 @@
 = Hugo Tests
 Tristano Ajmone
-2019-05-24: hugo.lang v1.0.0 | Hugo v3.1.03 | Highlight 3.51
+: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
-:sectanchors:
 // TOC Settings:
 :toc: left
 :toclevels: 5
-// Sections Numbering:
+// Sections Options:
 :sectnums!:
-:sectnumlevels: 2
+:sectanchors:
 // Cross References:
 :xrefstyle: short
 :section-refsig: Sect.
@@ -18,7 +19,6 @@ Tristano Ajmone
 :icons: font
 :linkattrs:
 :reproducible:
-:sectanchors:
 // GitHub Settings for Admonitions Icons:
 ifdef::env-github[]
 :caution-caption: :fire:
@@ -31,7 +31,8 @@ endif::[]
 // =====================================
 // Custom Attributes for Reference Links
 // =====================================
-:purebasic_lang: pass:q[link: https://gitlab.com/saalen/highlight/blob/master/langDefs/purebasic.lang[`langDefs/purebasic.lang`^]]
+: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/
 
 // *****************************************************************************
 // *                                                                           *
@@ -51,16 +52,16 @@ To execute tests, launch `test.sh` in Bash.
 
 == Source Files Encoding
 
-The test files are in UTF-8 encoding, with the exception of files ending in `-ascii.hug`, which are in ISO-8859-1.
+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),
 
-Hugo source files are likely to be in ISO-8859-1 or ASCII encoding, but 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).
+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
 
 
@@ -95,8 +96,62 @@ This is because prose strings are likely to contain many adjacent escapes of bot
 
 Keywords Groups:
 
-1. Hugo keywords.
-2. ASCII chars constants.
-3. Limit Settings.
+. 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 //