Compiling HFL files

The HFL compiler can be used as either offline as a compiler, or online under a web server as a server to generate a single page.

The two uses have the same capabilities, but due to the different environments, behave slightly differently.

In offline use ('compiling') the compiler is usually invoked from a batch file and generates web content files. These files will later then be directly referenced by the browsers. Typically the HFL compiler will be used to create most of the files for a site (aka a full build). The output is generally some combination of HTML files, CSS files, javascript files, and perhaps other content such as images and videos.

In server use ('server-side'), the compiler is invoked by the web server (e.g. Apache), and generates a single page. Because it is only called one page at a time, server-side HFL scripts typically only deal with that page.

In server use, the HFL compiler performs the tasks that generally require run-time access, such as database queries or responses to user input, in the same manner as other server-side languages such as PHP and Python.

A full site definition will usually be some combination of the two uses. Most of the site would be constructed offline, with a few of the pages either completed or perhaps fully generated at runtime.

Compiling HFL files offline

• To simplify using the HFL compiler offline, a few batch files are provided with the distribution.
• Batch file hflc.bat directly invokes the HFL Compiler (HFLC) from a command line in cmd.exe.
• There are a number of options that can be specified when compiling an HFL file. These options can be passed on the command line.
• Compiler command-line syntax
• hflc <source-file> <output-file> [-opt=<option-file>] [<hfl-options>]

  where:

  <source-file>

  :=

  HFL source file, e.g. "hello.hfl"

  <output-file>

  :=

  HTML output file, e.g. "hello.html"

  <option-file>

  :=

  HFL option file

  <hfl-inline-opts>

  :=

  <hfl-option>[+<hfl-inline-opt>]*

  <hfl-inline-opt>

  :=

  -eol[.on | .off]

  |

  -pp

  |

  -verbose | -v

  |

  -convert<convert-level>

  |

  -debug

  |

  -fo<format-output-opt>

  |

  -tr

  |

  -trs

  |

  -trp

  |

  -nest

  |

  -singlestep | -ss

  <format-output-opt> :=

  .w

  |

  .p

  |

  .c
  • Compiles the <source-file> .hfl file and generates the <output-file> .html file.
  • Inline options can be concatenated using a '+' without any spaces between them. This allows a number of options to be specified without exceeding the limit of 9 batch file variables.
  • EXAMPLE:

    • hflc hello.hfl hello.html -fo.w+-v
      

  • If the '-eol' option is specified, the compiler will convert end-of-line markers in the source files to the type used by the current file system. This is useful when files created under one system (such as Windows) need to be compiled under another (such as Linux). By default, this option is off. If the qualifier '.on' or '.off' is not specified, it will be treated as '.on'. If '.off' is specified, the option will be turned off.
  • The '-fo' option controls the formatting of the output file(s). If specified, it re-formats the output, adjusting indentation and setting line-breaks to make the generated file have a nicer look to the code. This option does not affect the display qualities of the HTML page, only the look of the code. As such, it probably results in an unnecessary overhead when the compiler runs server-side. It has the following sub-options:
    • -fo.w

      Use 'Whitesmith' indentation rules

      -fo.p

      Preserve blank lines of source in output

      -fo.c

      Put a <BR> after the opening HTML tags
    • Multiple sub-options can be specfied in the same '-fo' option.
    • EXAMPLE:

    • hflc hello.hfl hello.html -fo.wp
      

  • The '-pp' inline option if specified causes the source file to be passed through a preprocessor before it is compiled. The 'C' preprocessor directives '#define', '#ifdef' and '#ifndef' are supported among others.
    • EXAMPLE:

    • #ifndef LINUX
      Copy file to C:\Users\Myuser\readme.txt
      #else
      Copy file to /home/myuser/readme.txt
      #endif
      

    • The '-pp' option can be useful when a source file generates multiple versions that have large differences in content, such as when creating documentation for multiple operating systems. In such cases, whole blocks of content can be included or excluded via '#ifdef' statements, and macros can be used to substitute text segments.
    • But for most uses of HFL, this option is unnecessary, and there is a performance loss for its use. As such, this option is best used for static compilations. It is not recommended for use in server-side rendering due to the performance hit.
    • See the section on "The HFL Preprocessor" for more details on the preprocessor and its options.
  • The '-v' inline option if specified displays the names of the various files and formats as they are being compiled. This can be very useful when trying to track down the circumstances that generated an error, as many are dependent upon the order files were executed.
    • EXAMPLE WITHOUT '-v':

    • hflc hello.hfl hello.html
      
      Compiling "hello.hfl"
        Outputting to "hello.html"
      

    • EXAMPLE WITH '-v':

    • hflc hello.hfl hello.html -v
      
      Compiling "hello.hfl"
        Outputting to "hello.html"
      --------------------------------------------
      LOADING FILE |common.hfl|
      --------------------------------------------
      FINISHED LOADING |common.hfl|
      --------------------------------------------
      LOADING FORMAT FILE |V1.hfmt|
      --------------------------------------------
      FINISHED LOADING |V1.hfmt|
      --------------------------------------------
      LOADING FORMAT FILE |topics.hfmt|
      --------------------------------------------
      FINISHED LOADING |topics.hfmt|
      --------------------------------------------
      ...