HFL Filename String Functions:

• HFL provides helper functions for manipulating file names and paths.
• parentDirOf (<path>)
  • Returns the parent directory portion of a Windows path.
  • EXAMPLE:

    • $path = 'Vdoc\Documentation\index.hfl';
      
      // Sets $parent_dir = 'Vdoc\Documentation'
      $parent_dir = parentDirOf($path);
      

• nthParentDirOf (<path>, <num-levels>)
  • Returns the parent directory path that is the number of levels specified above the file of the given Windows path.
  • EXAMPLE:

    • $path = 'Vdoc\Documentation\index.hfl';
      
      // Sets $parent_dir = 'Vdoc'
      $grandparent_dir = nthParentDirOf($path, 2);
      

• fileNameOf (<path>)
  • Returns the filename portion of a Windows path.
  • EXAMPLE:

    • $path = 'Vdoc\Documentation\index.hfl';
      
      // Sets $fname = 'index.hfl'
      $fname = fileNameOf($fname);
      

• fileNameNoExtOf (<path>)
  • Returns the filename portion of a Windows path, without the file extension.
  • EXAMPLE:

    • $path = 'Vdoc\Documentation\index.hfl';
      
      // Sets $fname_base = 'index'
      $fname_base = fileNameNoExtOf($path);
      

• filenameExtOf (<path>)
  • Returns the file extension portion of a Windows path
  • EXAMPLE:

    • $path = 'Vdoc\Documentation\index.hfl';
      
      // Sets $ext = 'hfl'
      $ext = filenameExtOf($path);
      

• fileExists (<path>)
  • Returns true if the given file of the path currently exists, false if not.
  • EXAMPLE:

    • // Init 'bootstrap' code if have a bootstrap options file
      if (fileExists("$ROOT\bootstrap_options.hfl")) {
        apply_format("bootstrap_init.hfmt");
        load("$ROOT\bootstrap_options.hfl");
        }
      

• isDir (<path>)
  • Returns true if the given path refers to an existing directory, false if not.
  • EXAMPLE:

    • // Write out current contents into a file if have the directory
      if (isDir($my_path)) {
        writeFile("$my_path\$myfile");
        }
      

• webPath (<path-string>)
  • Converts a filename path string into a Web-compatible version, by replacing all '\' characters with '/'.
  • If the string is empty, returns ".".
  • EXAMPLE:

    • $VER_SUBPATH = 'Vdoc\Documentation';
      
      // Sets $WEB_VER_SUBPATH = 'Vdoc/Documentation'
      $WEB_VER_SUBPATH = webPath($VER_SUBPATH);
      

• appendWebSubpath (<parent_dir>, <path-string>)
  • Converts a filename path string into a Web-compatible version that is relative to the given parent directory then replaces all '\' characters with '/'.
  • If the string is empty, returns ".".
  • EXAMPLE:

    • $ROOT = '../..';
      BUILD_DIR = 'Build';
      
      // Sets $BUILD_ROOT = '../../Build'
      $BUILD_ROOT = appendWebSubpath($ROOT, $BUILD_DIR);
      

• relWebDir (<path-string>)
  • Converts a directory path string into a Web-compatible relative directory path string, then replaces all '\' characters with '/'.
  • If the string is empty, returns ".".
  • EXAMPLE:

    • $VER_SUBPATH = 'Vdoc\Documentation';
      
      // $ROOT will be '../..'
      $ROOT = relWebDir("$VER_SUBPATH");
      

• webPathRelativeTo (<path-string>, <path-string-relative-to>)
  • Converts a path string into a Web-compatible path string that is relative to the <path-string-relative-to> path string. For example, if both path strings have the same parent directory paths, the returned path will be just the filename. path.
  • In effect, it strips the leading parent directory path that the two paths have in common, then converts the rest of the directory path fields to "..".
  • If the <path-string> has no parent paths in common with the <path-string-relative-to>, it leaves the path unmodified.
  • Finally, it replaces all '\' characters of the path with '/'.
  • EXAMPLE:

    • $file1 = 'Vdoc\Documentation\concepts.hfl';
      $file2 = 'Vdoc\Documentation\intro.hfl';
      $file3 = 'Vdoc\Documentation\images\main-bg.png';
      
      // Prints "file1 relative to file2 = concepts.hfl"
      print("file1 relative to file2 = "+webPathRelativeTo(file1, file2));
      
      // Prints "file3 relative to file2 = images/main-bg.png"
      print("file3 relative to file2 = "+webPathRelativeTo(file3, file2));
      
      // Prints "file2 relative to file3 = ../intro.hfl"
      print("file3 relative to file2 = "+webPathRelativeTo(file3, file2));
      

• webSubpath (<parent_dir>', <path-string>)'
  • Converts a path string into a Web-compatible path string that is relative to the <parent_dir> path string. If successful, the returned path string can then be appended to the <parent_dir> path string to reconstitute the original path.
  • In effect, it strips the leading <parent_dir> path characters from the front of the <path-string>, if possible.
  • If the <parent_dir> path does not match the leading characters of the <path-string>, it leaves the path unmodified.
  • Finally, it replaces all '\' characters of the path with '/'.
  • EXAMPLE:

    • // Convert the page's filename to one relative to dir $_PAGE_DIR_
      $PAGE_DIR = env("_PAGE_DIR_");
      $REL_FNAME = webSubpath($_PAGE_DIR_, $page_filename);
      

• winPath (<path-string>)
  • Converts a filename path string into a Windows-compatible version, by replacing all '/' characters with '\'.
  • If the string is empty, returns ".".
  • EXAMPLE:

    • $WEB_VER_SUBPATH = 'Vdoc/Documentation';
      
      // Sets $VER_SUBPATH = 'Vdoc\Documentation'
      $VER_SUBPATH = webPath($WEB_VER_SUBPATH);
      

• appendWebSubpath (<parent_dir>, <path-string>)
  • Converts a filename path string into a Windows-compatible version that is relative to the given parent directory then replaces all '/' characters with '\'.
  • If the string is empty, returns ".".
  • EXAMPLE:

    • $FMT = '..\Vdoc.base.hfl';
      HFL_DIR = '..\Src';
      
      // Sets $FMT_PATH = '..\Vdoc.base.hfl'
      $FMT_PATH = appendWebSubpath($HFL_DIR, $FMT);
      

• winPathRelativeTo (<path-string>, <path-string-relative-to>)
  • Converts a path string into a Windows-compatible path string that is relative to the <path-string-relative-to> path string. For example, if both path strings have the same parent directory paths, the returned path will be just the filename. path.
  • In effect, it strips the leading parent directory path that the two paths have in common, then converts the rest of the directory path fields to "..".
  • If the <path-string> has no parent paths in common with the <path-string-relative-to>, it leaves the path unmodified.
  • Finally, it replaces all '/' characters of the path with '\'.
  • EXAMPLE:

    • $file1 = 'Vdoc/Documentation/concepts.hfl';
      $file2 = 'Vdoc/Documentation/intro.hfl';
      $file3 = 'Vdoc/Documentation/images\main-bg.png';
      
      // Prints "file1 relative to file2 = concepts.hfl"
      print("file1 relative to file2 = "+winPathRelativeTo(file1, file2));
      
      // Prints "file3 relative to file2 = images\main-bg.png"
      print("file3 relative to file2 = "+winPathRelativeTo(file3, file2));
      
      // Prints "file2 relative to file3 = ..\intro.hfl"
      print("file3 relative to file2 = "+winPathRelativeTo(file3, file2));
      

• winSubpath (<parent_dir>', <path-string>)'
  • Converts a path string into a Windows-compatible path string that is relative to the <parent_dir> path string. If successful, the returned path string can then be appended to the <parent_dir> path string to reconstitute the original path.
  • In effect, it strips the leading <parent_dir> path characters from the front of the <path-string>, if possible.
  • If the <parent_dir> path does not match the leading characters of the <path-string>, it leaves the path unmodified.
  • Finally, it replaces all '/' characters of the path with '\'.
  • EXAMPLE:

    • // Convert the page's filename to one relative to dir $_PAGE_DIR_
      $PAGE_DIR = env("_PAGE_DIR_");
      $REL_FNAME = winSubpath($_PAGE_DIR_, $page_filename);
      

• relWinDir (<path-string>)
  • Converts a directory path string into a Windows-compatible relative directory path string, then replaces all '/' characters with '\'.
  • If the string is empty, returns ".".
  • EXAMPLE:

    • // Sets $SUBPATH to 'Src\Documentation' from an environment variable
      $SUBPATH = env("_SUBPATH_");
      
      // $HFL_DIR will be '..\..'
      $HFL_DIR = relWinDir($SUBPATH);