[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 punkshell_module_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]
[keywords module path filesystem]
[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]  [opt {option value...}] [opt {globpattern...}]]
[para]basic (glob based) list of filenames matching each pattern in tailglobs - recursive
[para] options:
[para] [opt -dir] <path>
[para]     defaults to [lb]pwd[rb] - base path for tree to search
[para] [opt -antiglob_paths] <list>
[para]     list of path patterns to exclude - may include * and ** path segments e.g /usr/**
[para]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  punk::path::relative /etc /etC
      will return ../etC
[para]    On windows, the drive-letter component (only) is not case sensitive
[example_begin]
    P% punk::path::relative c:/etc  C:/etc
    -  .
[example_end]
[para] The part following the driveletter is case sensitive so in the following cases it recognises the driveletter matches but not the tail
[example_begin]
    P% punk::path::relative c:/etc C:/Etc
    -  ../Etc
[example_end]
[para]    On windows, if the paths are absolute and specifiy different volumes, only the location will be returned.
[example_begin]
    P% punk::path::relative c:/etc d:/etc/blah
    -  d:/etc/blah
[example_end]
[para] Unix-like examples:
[example_begin]
   P% punk::path::relative /usr/local/etc/ /usr/local/etc/somewhere/below
   - somewhere/below
   P% punk::path::relative /usr/local/etc/somewhere /usr/local/lib/here
   - ../../lib/here
[example_end]
[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]