HFL SCOPES

Scope Types

• HFL supports four types of scopes: tag scopes, pattern-based scopes, separator-based scopes and positional scopes.
• Tag Scopes
  Tag scopes are scopes that search for cells with matching HTML tags, classes and or ids. These scope searches are generally quite fast, because the compiler can quickly scan through the cell hierarchy.
• Pattern-based Scopes
  Pattern-based scopes scan the text values of the cells within the parent scope's cell range, matching regular-expression patterns against that text. Because each pattern is a regular-expression (or 'regex'), some quite sophisticated patterns can be expressed. But the downside is that the pattern-match is much slower than matching based upon tags.
• In cases where the same pattern range must be referred to multiple times, performance can be greatly increased by applying a tag to the matched range. Then subsequent scopes can find the range through the much more efficient tag match.
• Separator-based Scopes
  Separator-based Scopes scan the text values of the cells within the parent scope's cell range, matching text strings against that text, and splitting the text at the match points. While the scan itself is not efficient, the result of the scan creates tagged cells, so subsequent scope references to the cells can be made using efficient tag matches.
• For more information on how to define pattern-based and separator-based scopes, see the section on "Defining Custom Scope Tags" ).
• Positional Scopes
  Positional scopes are scopes that are relative to the current execution position, or absolute to the cell hierarchy.
• Examples are the 'before{}' and 'after{}' scopes, and the 'rest{}' scope.
• Whereas the other three types of scopes are restricted to searching inside the confines of the outer scope, positional scopes can refer to content that is outside of the current cell hierarchy.

Page, Tag And Rest Scopes

• The location of an HFL code block within the source file affects the starting point of the scope searches within that block.

• The rules that decide what the base scope (outermost scope restriction) are:
  • If an HFL code block is at the top of its source file, the base scope of all inner scope searches will be the <page> cell. This is known as 'page' base scope.
  • If an HFL code block lies within a tagged block (e.g. <p>) and is the first thing in the block, the base scope of all inner scope searches will be the cell of the tag. This is known as 'tag' base scope.
  • Otherwise the base scope of all inner scope searches will be the from the cell after the format cell of the code block, to the last cell of the code block. This is known as 'rest' base scope, because it contains the rest of the cells past the current point.
• An example of 'page' base scope. The 'p:1' scope starts from the top of the file:

  • <\ 
    // Set the word 'fox' to the color 'brown'
    p:1{word:4{color:brown;}}
    \>
    <p>
    The quick brown fox jumped over the lazy dog.
    </p>
    

• An example of a 'tag' base scope. Since the code block is the first thing inside the <p> tag, the inner 'word' scope specifications only scan the contents of the cell for the <p> tag.

  • <p>
    <\ 
    // Set the word 'good' to the color 'red'
    word:7{red;}
    // Set the word 'aid' to the color 'green'
    word:13{green;}
    \>
    Now is the time for all good men to come
    to the aid of their countrymen
    </p>
    

• An example of inline or 'rest' base scope. Here the code blocks lie within the body of the text of the <p> tag, so the inner 'word' scope specifications only scan the contents of the <p> cell past their physical locations.

  • <p>
    Now is the time for all <\ word:1{red;} \>good men to come
    to the <\ word:1{green;} \>aid of their countrymen
    </p>
    

Scope Specifications

• HFL scopes are specified in code as either a scoped block, which is a list of scope selectors followed by a code block (code enclosed within open and close braces), or through a call to a scope-list function, such as the scope() function.
• The code block is optional in scope-list function calls. If omitted, scope-list functions return a scope-list as their value instead of executing a block of code. That scope-list may be stored and passed as an argument in a later scope-list function call.
• Both syntaxes support multi-level scope specifications.
• Scope-list functions have one big advantage over scoped blocks. While they are less efficient, their scope references may contain variables while references in scoped blocks must be constants. This allows scopes to be parameterized, such as within a function.
• SYNTAX:
  • <scoped-block>

    scope (<scope-refs>) [{ <code-block> }]

     

    where:

    <scoped-block>

    :=

    <scope-selectors> { [<code-block>] }

    <scope-selectors>

    :=

    <scope-selector>+ [, <scope-selector>]*

    <scope-refs>

    :=

    <scope-ref> [, <scope-ref>]*

    <scope-ref>

    :=

    <scope-string> | <cell-num> | <cell-array>

    <scope-string>

    :=

    [../]* <scope-selector>+ | ..

    <scope-selector>

    :=

    [<tag>] [<scope-qualifier>][?]

    <scope-qualifier>

    :=

    [<class-sel>][<id-sel>][<attr-sels>]

    [: [..] <scope-range>]

    <class-sel>

    :=

    .<class-name>

    <id-sel>

    :=

    #<id-name>

    <attr-sels>

    :=

    <attr-sel> [<attr-sel>]*

    <attr-sel>

    :=

    [<attr> <attr-comp> <value>]

    <scope-range>

    :=

    <scope-range-spec> | all | any

    <scope-range-spec>

    :=

    <start> [<thru> {<end> | last} [by <incr>]]]

    <thru>

    :=

    thru | -

    <code-block>

    :=

    <hfl-statement>*

    <cell-array>

    :=

    an array of <cell-num>

    <cell-num>

    :=

    an integer index number of a cell

     

    <start> is value or variable that evaluates to a signed integer

    <end> is value or variable that evaluates to a signed integer

    <incr> is value or variable that evaluates to a signed integer
  • The <class-sel>, <id-sel> and <attr-sels> selectors follow the same syntax as CSS.
  • The '..' allows the pattern to match at any scope level below the current one. The default is to only match cells that are immediate children of the current scope.
  • The 'all' and 'any' qualifiers specify that the scope will match all cells that satisfy the pattern. The default is to only match the first.
  • The '?' makes the pattern optional and suppresses warning messages when a scope is not found.
• Scope selectors are similar to CSS selectors, and in fact most CSS selectors can be used as scope selectors with a minor modification. But scope selectors can express relationships and patterns far beyond what can be be expressed by CSS selectors.
  • Perhaps the biggest semantic difference between HFL scope selectors and CSS selectors is that in CSS, all selectors match all inner tags within their outer scopes regardless of their depth, whereas scope selectors only do so if the 'any' range specifier was used, or if the '..' qualifier was used to specify that the scope can match at any sub-level along with the 'all' range specifier so as to include all matches, not just the first.
  • For example, for the CSS rule:

    • #menu ul li a { color: red; }
      

  • the equivalent HFL scope would look like:

    • #menu ul:any li:any a:any { color: red; }
      

  • or:

    • #menu ul:..all? li:..all? a:..all? { color: red; }
      

  • Without the 'any' or '..all?' qualifiers, the original CSS syntax would match only the first <a> cell within the first <li> cell within the first <ul> cell within the cell of the #menu tag.
• Scope selectors cause the compiler to search the cell hierarchy to match the criteria of the specific scope tag. When a match is found, the instructions of the code block are executed if there is one, or else the range of cells is returned if not (i.e. is a scope-list call).
• Most scope qualifiers are a combination of one or more of a class, an id, or a tag with a numeric range (e.g. 'p:1-3'), with the range being the most common. A scope specified with a range is in effect a 'for' loop. The scope's code block is executed once for each match of the scope range.
• When the scope-qualifiers are not specified, the default range is ':1', which is actually ':1 - 1 by 1', and which executes just once.
• The 'all' qualifier is a short-hand for '1 - last by 1'.
• Scope selectors normally only match immediate child cells one level down from those of the current scope. If a scope range is preceded by '..' however, then it will override the one-level restriction, and then can match any inner descendent cells of the current scope at any level below. In other words '..' allows the search to do a deep scan.
• The 'any' qualifier is similar to '..all', but groups the scope specification with all other 'any' specifications in the parent scope and executes them in one search pass. This can greatly improve performance during compilation when a large number of patterns are specified. Also, unlike most scopes, 'any' scope specifications match not just child cells of the parent scope, but any descendents as well. The restriction is that 'any' specifications can only detect cell tags and classes, and ignore the other <scope-qualifier> values. They do not work with pattern-based scope specifications. (For more information on pattern-based scopes, see the section on "Scope Types" above).
• Scopes that refer to HTML or HFL tags match single cells, and thus the code blocks will be applied to just one cell at a time.
• Scopes that refer to patterns may match a range of cells. In such cases, the code in the code block might misbehave if the range is assumed to be just one cell.
  • For example 'p:3' will be a single cell, but 'word:1' might be several cells.
• EXAMPLES:

  • // Make the first paragraph red
    p {red}
    
    // Make the second and third paragraphs blue
    p:2-3 {blue}
    
    // Make the first five words of the second line of paragraph 5 bold.
    p:5 { line:2 { word:1-5 {bold} }}
    
    // Set the height of a cell specified using a multi-level scope
    div#menu ul li a { height:45px; }
    
    // Set the margin-top value of the 2nd through last rows of the 2nd table to 20px
    table:2 { row:2-last {margin-top:20px;}}
    
    // Indent all lines by 30px and set their fonts to "Verdana"
    line:all {left:30px; font: "Verdana"}
    
    // Convert any deprecated <I> tags to HTML5-compatible <span> tags
    I:any {tag="span" class="italic"}
    
    // Assign the class "MenuBarItemSubmenu" to the first <a> tag
    a:1 { class="MenuBarItemSubmenu"}
    
    // Make every odd word red and every even word green
    word:1-last by 2{red} word:2-last by 2{green}
    
    // Set the width and height of every <p> tag in parent scope
    scope(../p:all) {width:120px; height:30px;}
    
    // Set the width of a multi-level scope whose tags are passed as variables
    scope($parent $child) {width:50px;}
    
    // Paste the cell with id="post_script" and convert it to a 'script' tag
    paste{ #post_script? {id="" tag_final="script" type="text/javascript"}}
    
    // Convert <code> tags at any descendent level to <p> tags and escape all HTML chars
    code:..all?{tag="p" class="code" escapeHtml();}
    
    // Call function MakeSubMenu() on any <p> tags that have prop __menu-level="parent"
    p[__menu-level="parent"]:all { MakeSubMenu(); }