punkshell_module_punk::path(0) 0.1.0 doc "punk path filesystem utils"

Name

punkshell_module_punk::path - Filesystem path utilities

overview of punk::path

Filesystem path utility functions

packages used by punk::path

class definitions

Core API functions for punk::path

pathglob_as_re pathglob

Returns a regular expression for matching a path to a glob pattern which can contain glob chars *|? in any segment of the path structure

** matches any number of subdirectories.

e.g /etc/**/*.txt will match any .txt files at any depth below /etc (except directly within /etc itself)

e.g /etc/**.txt will match any .txt files at any depth below /etc

any segment that does not contain ** must match exactly one segment in the path

e.g the glob /etc/*/*.doc - will match any .doc files that are exactly one tree level below /etc

The pathglob doesn't have to contain glob characters, in which case the returned regex will match the pathglob exactly as specified.

Regular expression syntax is deliberateley not supported within the pathglob string so that supplied regex characters will be treated as literals

globmatchpath pathglob path ?option value...?

Return true if the pathglob matches the path

see pathglob_as_re for pathglob description

Caller must ensure that file separator is forward slash. (e.g use file normalize on windows)

Known options:

-nocase 0|1 (default 0 - case sensitive)

If -nocase is not supplied - default to case sensitive *except for driveletter*

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)

Explicitly specifying -nocase 0 will require the entire case to match including the driveletter.

treefilenames ?option value...? ?globpattern...?

basic (glob based) list of filenames matching each pattern in tailglobs - recursive

options:

?-dir? <path>

defaults to [pwd] - base path for tree to search

?-antiglob_paths? <list>

list of path patterns to exclude - may include * and ** path segments e.g /usr/**

no natsorting - so order is dependent on filesystem

relative reference location

Taking two directory paths, a reference and a location, computes the path of the location relative to the reference.

Arguments:

string reference

The path from which the relative path to location is determined.

string location

The location path which may be above or below the reference path
Results:

The relative path of the location to the reference path.

Will return a single dot "." if the paths are the same
Notes:

Both paths must be the same type - ie both absolute or both relative

Case sensitive. ie punk::path::relative /etc /etC will return ../etC

On windows, the drive-letter component (only) is not case sensitive
```
    P% punk::path::relative c:/etc  C:/etc
    -  .
```
The part following the driveletter is case sensitive so in the following cases it recognises the driveletter matches but not the tail
```
    P% punk::path::relative c:/etc C:/Etc
    -  ../Etc
```
On windows, if the paths are absolute and specifiy different volumes, only the location will be returned.
```
    P% punk::path::relative c:/etc d:/etc/blah
    -  d:/etc/blah
```
Unix-like examples:
```
   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
```