Scoped Input/Output Functions

• These functions open files and read their contents into or write from the cells of the current scope.
• applyFormat (<format-ref>) [{ <code-block> }]

  where:

  <format-ref>

  :=

  <format-name> | <format-object>

  <format-name>

  :=

  an expression that evaluates to a file name

  <format-object>

  :=

  a format object returned by getFormat()
  • Locates an HFL format file and applies its instructions and content to the current scope. It is an optional-scope function, and thus can be invoked as either a function call or a scope with a code block.
  • For more details on using format files, see the section on "Using HFL Formats" .
• load (<file-path> [, <how>] [, 'opt'] [, 'raw' [, <range>]])

  where:

  <how>

  :=

  'once' | 'cache'

  <range>

  :=

  <start-line> [, <end-line>]
  • Loads the .hfl file <file-path> into the current cell, and executes the instructions.
  • If the optional 'once' argument is specified, the file is not loaded nor executed if it has already been loaded.
  • If the optional 'raw' argument is specified, the file contents are not executed, but rather treated as just text.
  • If the optional <range> sub-argument to 'raw' is specified, only the lines specified will be loaded.
  • If the optional 'cache' argument is specified, the loader first searches to see if the file has already been loaded, and uses the pre-fetched code. This can reduce memory requirements when including the same piece of code in multiple locations.
  • EXAMPLES

  • // Load file 'agenda.hfl' once.  Any subsequent calls will re-use loaded cache
    load('agenda.hfl', 'cache');
    
    // Load file 'test.hfl' as just text.  Do not parse as HFL code
    load('test.hfl', 'raw');
    

• include (<file-path> [, <how>] [, 'opt'] [, 'raw' [, <range>]])

  where:

  <how>

  :=

  'once' | 'cache'

  <range>

  :=

  <start-line> [, <end-line>]
  • Same functionality as the load() function, except when the calling include() statement is inside the body of a scope, application function or scoped function (such as an if). In those cases the external symbols of any code loaded by the operation will be stored within the calling body's closure.
  • A closure is an independent symbol (variable-name) table, that is separate from the main symbol table used to associate symbols (names) with storage elements. Each scope and function has a closure, which is its local symbol table. And each function defined lexically inside that scope/function is only added to the enclosing function's closure, and thus visible only to the outer scope/function and any other functions also defined within the closure.
  • When the include() statement is called from within an outer scope/function, all code that is loaded behaves as if it were lexically inside the outer scope/function.
  • If the calling code is at top-level, i.e. not inside the body of a scope, application function or scoped function (such as an if), then include() and load() behave the same way.
  • EXAMPLES

  • // Replace contents of tag <example1> with lines 1-17 of file "intro.hfl"
    //  then escape them so they display properly under HTML
    example1:..1 {
      include("intro.hfl", 'raw', 1, 17);
      class="code" escapeHtml('full');
      }
    
    // Include the contents of file "generated_code.hfl", which will create
    //  closures for any functions defined within that file.
    function foo () {
      include("generated_code.hfl");
      }
    

• require (<file-path>)
  • Requires that the file already be loaded, or to load it if not. It is a simpler version of load(), that loads from cache, if already cached.
• writeFile (<file-path>, <cell-array> [, <option>]*)

  where:

  <file-path>

  :=

  a path string

  <cell-array>

  :=

  an array of cells

  <option>

  :=

  'code'

  |

  'pretty'

  |

  'append'

  |

  'cut[<clip-pool>]'
  • Writes out the content of each cell in the array of cells in <cell-array> to a single file.
  • The <cell-array> array can be created as an ordinary array, or though one of the scope-list functions such as scope().
  • If the 'code' option is chosen, the output will be as generated code. Otherwise it will be as straight text.
  • If the 'pretty' option is chosen, the output will pretty-printed, in other words, formatted to look nice.
  • If the 'append' option is chosen, the file will be opened in 'append' mode, so the content will be written to the end of the file's current contents.
  • If the 'cut' option is chosen, the cells in the cell array will be moved to the specified clip pool, or to the default pool for the page if the <clip-pool> is not specified.
  • EXAMPLE:

  • writeFile('myscripts.js', scope(javascript:all), 'append', 'cut#discard');
    

• writeDir (<dir-path>, <cell-array>, <ext> [, <option>]*)

  where:

  <dir-path>

  :=

  a path string

  <cell-array>

  :=

  an array of cells

  <ext>

  :=

  the file extension to give the files, e.g. '.css'

  <option>

  :=

  'by_id'

  |

  'code'

  |

  'pretty'

  |

  'append'

  |

  'cut[<clip-pool>]'
  • Writes out the content of each cell in the scope list to a directory, with one file per cell in the scope list.
  • The 'by_id' option is a filter that specifies how to name each file.
  • If the 'by_id' filter is chosen, the file will be given by the cell's ID property. If the cell has no ID, the file path will be 'common'. It is recommended that if multiple formats write to the 'common' file, that the file mode be 'append' to prevent later formats from replacing earlier format's data.
  • The other <option> values are the same as for writeFile() above.
  • EXAMPLE:

  • writeDir("bootstrap_files", scope(css_bootstrap:all), '.less', 'by_id');