You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
85 lines
4.3 KiB
85 lines
4.3 KiB
1 year ago
|
[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]
|