1
1
module CompSci
2
2
3
+ # Overview
4
+ # ===
5
+ #
3
6
# This is a simplification of common Unix paths, as used in Linux, OS X, etc.
4
7
# It is intended to cover 99.9% of the "good use cases" and "best practices"
5
8
# for path and filename conventions on Unix filesystems.
6
-
9
+ #
7
10
# Some primary distinctions:
8
11
# 1. Absolute vs Relative paths
9
- # 2. File vs directory
10
-
12
+ # 2. File vs Directory
13
+ #
11
14
# Absolute paths are indicated with a leading slash (/)
15
+ # e.g. /etc/passwd or /home/user/.emacs
16
+ #
12
17
# Relative paths are primarily indicated with a leading dot-slash (./)
13
18
# or they may omit the leading ./ for brevity.
19
+ # e.g. ./a.out or path/to/file.txt
14
20
21
+ # Directories and Files
22
+ # ===
23
+ #
15
24
# In string form, directories are indicated with a trailing slash (/).
16
25
# With no trailing slash, the last segment of a path is treated as a filename.
26
+ #
17
27
# Internally, there is a @filename string, and if it is empty, this has
18
28
# semantic meaning: the UnixPath is a directory.
19
29
30
+ # Basename and Extension
31
+ # ===
32
+ #
20
33
# For nonempty @filename, it may be further broken down into basename
21
34
# and extension, with an overly simple rule:
22
35
#
@@ -34,14 +47,22 @@ module CompSci
34
47
# If @filename is empty, basename and extension are nil.
35
48
36
49
# Internal Representation
50
+ # ===
51
+ #
37
52
# * abs: boolean indicating abspath vs relpath
38
53
# * subdirs: array of strings, like %w[home user docs]
39
54
# * filename: string, possibly empty
40
55
56
+ # Strings
57
+ # ===
58
+ #
41
59
# Consume a string path with UnixPath.parse, creating a UnixPath instance.
42
60
# Emit a string with UnixPath#to_s.
43
- # Relative paths are emitted with leading ./
61
+ # Relative paths are emitted with leading dot-slash (./)
44
62
63
+ # Creation
64
+ # ===
65
+ #
45
66
# Combine path components with `slash`, aliased to /, yielding a UnixPath
46
67
# * UnixPath.parse('/etc') / 'systemd' / 'system'
47
68
# * UnixPath.parse('/etc').slash('passwd')
@@ -53,6 +74,9 @@ module CompSci
53
74
# Or construct by hand:
54
75
# * UnixPath.new(abs: true, subdirs: %w[etc systemd system])
55
76
77
+ # Implementation Details
78
+ # ===
79
+ #
56
80
# Most of UnixPath is implemented via PathMixin and its FactoryMethods
57
81
# These modules are mixed in to base classes ImmutablePath and MutablePath.
58
82
# ImmutablePath is based on Ruby's Data.define, using Data.with for efficient
@@ -62,11 +86,14 @@ module CompSci
62
86
# This pattern of assigning a constant can allow you to create your own Path
63
87
# in your own context. e.g. MyPath = CompSci::MutablePath
64
88
65
- # Note that these are logical paths and have no connection to any filesystem.
89
+ # Nota Bene
90
+ # ===
91
+ #
92
+ # These are logical paths and have no connection to any filesystem.
66
93
# This library never looks at the local filesystem that it runs on.
67
-
68
- # ImmutablePath and MutablePath both mix in this module via include
69
- # N.B. @ivar references will not work with Data.define, so use self.ivar
94
+ # ImmutablePath and MutablePath both mix in this module via `include`.
95
+ # They also pull in class methods via `extend` via the `included` hook.
96
+ # @ivar references will not work with Data.define, so use self.ivar
70
97
module PathMixin
71
98
include Comparable
72
99
0 commit comments