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.
106 lines
5.1 KiB
106 lines
5.1 KiB
[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]
|
|
|