module

Hwaro::Content::Processors::Includes

Constants

ATX_RE = /\A {0,3}(\#{1,6})(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*\r?\n?\z/
CODE_REGION_RE = /\A[ \t]*(?:\/\/+|\/\*+|<!--|--|;+|#)?[ \t]*#(end)?region\b[ \t]*([\w.]+(?:-[\w.]+)*)?/

#region name / #endregion name after any comment leader (//, #, --, <!--, /*, ;). A name is a word run that may hold . and inner -, so <!-- #region brew--> still reads brew.

FENCE_OPTION_KEYS = ["title", "name", "hl_lines", "hide_lines", "linenos", "linenostart", "copy"] of ::String

The fence-option keys include_code passes through, in the order they are written (title is the alias FenceOptions reads as name).

HLJS_NAMES = {"react" => "jsx", "mysql" => "sql", "cassandra_cql" => "sql", "protocol_buffer" => "protobuf", "txtpb" => "protobuf", "c#" => "csharp", "c++" => "cpp", "batchfile" => "dos", "bash_session" => "shell", "viml" => "vim", "vb_net" => "vbnet", "common_lisp" => "lisp", "emacslisp" => "lisp", "systemverilog" => "verilog", "objectpascal" => "delphi", "nginx_configuration_file" => "nginx", "apacheconf" => "apache", "standard_ml" => "sml", "docker" => "dockerfile"}

Tartrazine lexer names highlight.js knows under another name. Client mode puts the lexer in the fence's class; server mode needs it as is.

LINES_RE = /\A[ \t]*(\d+)(?:[ \t]*-[ \t]*(\d+))?[ \t]*\z/
MAX_DEPTH = 8
MAX_SPLICES = 10000

Splices (includes + transclusions) one page may expand in total. MAX_DEPTH bounds the chain, not the fan-out: ten includes per file, eight deep, is 10^8 splices from nine tiny files — a build that never finishes. Far above what any real page includes.

MD_REGION_RE = /\A[ \t]*<!--[ \t]*#(end)?region\b[ \t]*([\w.]+(?:-[\w.]+)*)?[ \t]*-->[ \t]*\r?\n?\z/

Markdown only takes the HTML-comment form: any other leader is text (or code inside a fence) in a Markdown file.

REF_DEF_RE = /\A {0,3}\[(?!\^)[^\]]+\]:/
SETEXT_RE = /\A {0,3}(=+|-+)[ \t]*\r?\n?\z/
THEMATIC_RE = /\A {0,3}(?:(?:\*[ \t]*){3,}|(?:_[ \t]*){3,}|(?:-[ \t]*){3,})\r?\n?\z/

Instance methods

clean(text : String) : String

Invalid UTF-8 scrubbed, a BOM dropped, and NUL replaced the way CommonMark does: the shortcode and Markdown passes use NUL-delimited tokens, and a NUL in source would forge one.

Source
dedent(text : String) : String

text without the leading whitespace every non-blank line shares.

Source
fenced(code : String, lang : String, options : Hash(String, String)) : String

A fenced code block of code, longer than any backtick run inside it. options are fence options (title, hl_lines, …); a value loses the characters the fence-option grammar cannot hold.

Source
heading_id(markdown : String, heading : String) : String | Nil

The custom id (## Setup {#install}, {#install .cls}) of the first ATX heading of markdown that heading_section would match, or nil when that heading has none (its id is then the slug).

Source
heading_section(markdown : String, heading : String) : String | Nil

The section of markdown under the heading (ATX or setext) whose slug matches heading's, through the line before the next heading of the same or a higher level. A heading is matched by the text it renders (link and image syntax, tags and entities reduced to what the reader sees), the id the build gives it. Headings inside code fences do not count.

Source
hljs_language(lexer : String) : String

The highlight.js language for a Tartrazine lexer name.

Source
language_for(path : String) : String

The highlighter's lexer for path: the whole-name entry in Tartrazine's filename table (Makefile, CMakeLists.txt), else its *.ext entry, else the first glob matching the base name (Dockerfile.dev). The table's names are lowercase, so the base name is matched lowercased. "" when nothing matches.

Source
lines(text : String, spec : String) : String

Lines spec ("a-b" or "a", 1-based, inclusive) of text.

Source
read(relative : String, output_dir : String | Nil) : String

The bytes of the project file relative (see clean). Refused when its path — as written, and with symlinks resolved — leaves the project root or lands in .hwaro/ or the build output: reading the output would be a rebuild loop.

Source
region(text : String, name : String, markdown : Bool) : String

The lines between #region name and its #endregion, with every marker inside dropped. A bare #endregion closes the innermost open region.

Source
relative_path(path : String) : String

path as a project-relative path, or an Error for an absolute path or one that climbs out (..). Lexical only: read re-checks the real path, so a symlink cannot reach outside either. The decoded segments only decide the refusal (%2e%2e climbs too); the path read is the literal one, so a%20b.txt names that file.

Source
strip_front_matter(text : String) : String
Source

Nested types