[comment {--- punk::docgen generated from inline doctools comments ---}]
[comment {--- punk::docgen DO NOT EDIT DOCS HERE UNLESS YOU REMOVE THESE COMMENT LINES ---}]
[comment {--- punk::docgen overwrites this file ---}]
[manpage_begin punk::path 0 0.1.0]
[copyright "2023"]
[titledesc {Filesystem path utilities}]  [comment {-- Name section and table of contents description --}]
[moddesc {punk path filesystem utils}]             [comment {-- Description at end of page heading --}]
[require punk::path]
[description]
[section Overview]
[para] overview of punk::path
[para] Filesystem path utility functions
[subsection Concepts]
[para] -
[subsection dependencies]
[para] packages used by punk::path
[list_begin itemized]
[item] [package {Tcl 8.6}]
[list_end]
[section API]
[subsection {Namespace punk::path::class}]
[para] class definitions
[list_begin enumerated]
[list_end] [comment {--- end class enumeration ---}]
[subsection {Namespace punk::path}]
[para] Core API functions for punk::path
[list_begin definitions]
[call [fun pathglob_as_re] [arg pathglob]]
[para] Returns a regular expression for matching a path to a glob pattern which can contain glob chars *|? in any segment of the path structure
[para] ** matches any number of subdirectories.
[para] e.g /etc/**/*.txt will match any .txt files at any depth below /etc  (except directly within /etc itself)
[para] e.g /etc/**.txt will match any .txt files at any depth below /etc
[para] any segment that does not contain ** must match exactly one segment in the path
[para] e.g the glob /etc/*/*.doc  - will match any .doc files that are exactly one tree level below /etc
[para] The pathglob doesn't have to contain glob characters, in which case the returned regex will match the pathglob exactly as specified.
[para] Regular expression syntax is deliberateley not supported within the pathglob string so that supplied regex characters will be treated as literals
[call [fun globmatchpath] [arg pathglob] [arg path] [opt {option value...}]]
[para] Return true if the pathglob matches the path
[para] see [fun pathglob_as_re] for pathglob description
[para] Caller must ensure that file separator is forward slash. (e.g use file normalize on windows)
[para]
[para] Known options:
[para]     -nocase 0|1  (default 0 - case sensitive)
[para] If -nocase is not supplied - default to case sensitive *except for driveletter*
[para] ie - the driveletter alone in paths such as c:/etc will still be case insensitive. (ie c:/ETC/* will match C:/ETC/blah but not C:/etc/blah)
[para] Explicitly specifying -nocase 0 will require the entire case to match including the driveletter.
[call [fun treefilenames] [arg basepath] [arg tailglob] [opt {option value...}]]
basic (glob based) list of filenames matching tailglob - recursive
no natsorting - so order is dependent on filesystem
[call [fun relative] [arg reference] [arg location]]
[para]    Taking two directory paths, a reference and a location, computes the path
    of the location relative to the reference.
[list_begin itemized]
[item]
[para] Arguments:
       [list_begin arguments]
       [arg_def string reference]       The path from which the relative path to location is determined.
       [arg_def string location]        The location path which may be above or below the reference path
       [list_end]
[item]
[para] Results:
[para]    The relative path of the location to the reference path.
[para]    Will return a single dot "." if the paths are the same
[item]
[para] Notes:
[para]    Both paths must be the same type - ie both absolute or both relative
[para]    Case sensitive.  ie  relative /etc /etC
      will return ../etC
[para]    On windows, the drive-letter component (only) is not case sensitive
[para]    ie relative c:/etc  C:/etc  returns .
[para]    but relative c:/etc C:/Etc returns ../Etc
[para]    On windows, if the paths are absolute and specifiy different volumes, only the location will be returned.
    ie  relative c:/etc d:/etc/blah
    returns d:/etc/blah
[list_end]
[list_end] [comment {--- end definitions namespace punk::path ---}]
[subsection {Namespace punk::path::lib}]
[para] Secondary functions that are part of the API
[list_begin definitions]
[list_end] [comment {--- end definitions namespace punk::path::lib ---}]
[section Internal]
[subsection {Namespace punk::path::system}]
[para] Internal functions that are not part of the API
[manpage_end]