|
5 | 5 | -- Maintainer : streamly@composewell.com |
6 | 6 | -- Portability : GHC |
7 | 7 | -- |
8 | | --- File system paths supporting flexible (gradual) typing; extensible, |
9 | | --- high-performance, preserving the OS and filesystem encoding. |
10 | | --- |
11 | | --- /Flexible typing/: you can choose the level of type safety you want. 'Path' |
12 | | --- is the basic path type which can represent a file, directory, absolute or |
13 | | --- relative path with no restrictions. Depending on how much type safety you |
14 | | --- want, you can choose appropriate type wrappers or a combination of those to |
15 | | --- wrap the 'Path' type in stricter types. |
| 8 | +-- File system paths; extensible, high-performance, preserving the OS and |
| 9 | +-- filesystem encoding. |
16 | 10 | -- |
17 | 11 | -- = Rooted Paths vs Branches |
18 | 12 | -- |
|
32 | 26 | -- unsafe append operation. Alternatively, you can drop the root explicitly |
33 | 27 | -- and use the safe append. |
34 | 28 | -- |
35 | | --- The "Streamly.FileSystem.Path.Seg" module provides explicit types for path |
36 | | --- segments, distinguishing rooted paths from branches. Rooted paths use the |
37 | | --- @Rooted Path@ type, and branches use the @Branch Path@ type. If you use the |
38 | | --- generic 'Path' type, append may fail at run time if you attempt to append |
39 | | --- a rooted path to another rooted path. In contrast, using the @Rooted Path@ |
40 | | --- and @Branch Path@ types guarantees compile-time safety, preventing such errors. |
41 | | --- |
42 | 29 | -- Since we distinguish between rooted and branch-type paths, a separate |
43 | 30 | -- distinction between absolute and relative paths is not required. Both are |
44 | 31 | -- considered rooted paths, and all rooted paths are protected from invalid |
45 | 32 | -- append operations. Only branch-type paths can be appended. |
46 | 33 | -- |
47 | 34 | -- = File vs. Directory Paths |
48 | 35 | -- |
49 | | --- Independent of the rooted or branch distinction, you can also make a |
50 | | --- type-level distinction between file and directory nodes using the |
51 | | --- "Streamly.FileSystem.Path.Node" module. The type @File Path@ represents a |
52 | | --- file, whereas @Dir Path@ represents a directory. This distinction provides |
53 | | --- safety against appending to file type paths — append operations are not |
54 | | --- allowed on paths of type 'File'. |
55 | | --- |
56 | 36 | -- By default, a path with a trailing separator is implicitly considered a |
57 | 37 | -- directory path. However, the absence of a trailing separator does not |
58 | 38 | -- indicate whether the path is a file or a directory — it could be either. |
59 | 39 | -- Therefore, when using the @Path@ type, the append operation allows appending |
60 | | --- to paths even if they lack a trailing separator. However, when creating a |
61 | | --- typed path of type 'File', the conversion fails unless the trailing |
62 | | --- separator is explicitly removed. |
63 | | --- |
64 | | --- = Flexible Typing |
65 | | --- |
66 | | --- You can use the 'Rooted', 'Branch', 'Dir', and 'File' types independently by |
67 | | --- importing only the required modules. If you want both types of distinctions, |
68 | | --- you can use them together via the "Streamly.FileSystem.Path.SegNode" module. |
69 | | --- For example, @Rooted (Dir Path)@ represents a rooted path that is a |
70 | | --- directory. You can append other paths only to paths that have a 'Dir' type, |
71 | | --- and only a path of type 'Branch' can be appended. |
72 | | --- |
73 | | --- You may choose to use the basic 'Path' type or any combination of the safer |
74 | | --- types. You can upgrade or downgrade the safety level by converting between |
75 | | --- types using the @adapt@ operation. When converting from a less restrictive |
76 | | --- type to a more restrictive one, run-time checks are performed, and the |
77 | | --- conversion may fail. However, converting from a more restrictive type to a |
78 | | --- less restrictive one is always allowed. |
79 | | --- |
80 | | --- = Extensibility |
81 | | --- |
82 | | --- You can define your own newtype wrappers similar to 'File' or 'Dir' to |
83 | | --- provide custom restrictions if you want. |
| 40 | +-- to paths even if they lack a trailing separator. |
84 | 41 | -- |
85 | 42 | -- = Compatibility |
86 | 43 | -- |
|
90 | 47 | -- types use an underlying representation which is compatible with the 'OsPath' |
91 | 48 | -- type. |
92 | 49 | -- |
93 | | --- = String Creation Quasiquoter |
| 50 | +-- = Path Creation Quasiquoter |
| 51 | +-- |
| 52 | +-- The 'path' quasiquoter is useful in creating valid paths that are checked |
| 53 | +-- during the compile time. |
94 | 54 | -- |
95 | | --- You may find the 'str' quasiquoter from "Streamly.Unicode.String" to be |
96 | | --- useful in creating paths. |
97 | 55 | -- |
98 | 56 |
|
99 | 57 | module Streamly.FileSystem.Path |
@@ -168,4 +126,55 @@ module Streamly.FileSystem.Path |
168 | 126 | ) |
169 | 127 | where |
170 | 128 |
|
| 129 | +{- Documentation on typed paths. We can add this back into the module level |
| 130 | + documentation when we introduce the typed paths. |
| 131 | +
|
| 132 | +-- = Rooted Paths vs Branches |
| 133 | +-- |
| 134 | +-- /Flexible typing/: you can choose the level of type safety you want. 'Path' |
| 135 | +-- is the basic path type which can represent a file, directory, absolute or |
| 136 | +-- relative path with no restrictions. Depending on how much type safety you |
| 137 | +-- want, you can choose appropriate type wrappers or a combination of those to |
| 138 | +-- wrap the 'Path' type in stricter types. |
| 139 | +
|
| 140 | +-- The "Streamly.FileSystem.Path.Seg" module provides explicit types for path |
| 141 | +-- segments, distinguishing rooted paths from branches. Rooted paths use the |
| 142 | +-- @Rooted Path@ type, and branches use the @Branch Path@ type. If you use the |
| 143 | +-- generic 'Path' type, append may fail at run time if you attempt to append |
| 144 | +-- a rooted path to another rooted path. In contrast, using the @Rooted Path@ |
| 145 | +-- and @Branch Path@ types guarantees compile-time safety, preventing such errors. |
| 146 | +
|
| 147 | +-- = File vs. Directory Paths |
| 148 | +-- |
| 149 | +-- Independent of the rooted or branch distinction, you can also make a |
| 150 | +-- type-level distinction between file and directory nodes using the |
| 151 | +-- "Streamly.FileSystem.Path.Node" module. The type @File Path@ represents a |
| 152 | +-- file, whereas @Dir Path@ represents a directory. This distinction provides |
| 153 | +-- safety against appending to file type paths — append operations are not |
| 154 | +-- allowed on paths of type 'File'. |
| 155 | +
|
| 156 | +-- = Flexible Typing |
| 157 | +-- |
| 158 | +-- You can use the 'Rooted', 'Branch', 'Dir', and 'File' types independently by |
| 159 | +-- importing only the required modules. If you want both types of distinctions, |
| 160 | +-- you can use them together via the "Streamly.FileSystem.Path.SegNode" module. |
| 161 | +-- For example, @Rooted (Dir Path)@ represents a rooted path that is a |
| 162 | +-- directory. You can append other paths only to paths that have a 'Dir' type, |
| 163 | +-- and only a path of type 'Branch' can be appended. |
| 164 | +-- |
| 165 | +-- You may choose to use the basic 'Path' type or any combination of the safer |
| 166 | +-- types. You can upgrade or downgrade the safety level by converting between |
| 167 | +-- types using the @adapt@ operation. When converting from a less restrictive |
| 168 | +-- type to a more restrictive one, run-time checks are performed, and the |
| 169 | +-- conversion may fail. However, converting from a more restrictive type to a |
| 170 | +-- less restrictive one is always allowed. |
| 171 | +-- |
| 172 | +-- = Extensibility |
| 173 | +-- |
| 174 | +-- You can define your own newtype wrappers similar to 'File' or 'Dir' to |
| 175 | +-- provide custom restrictions if you want. |
| 176 | +-- |
| 177 | +
|
| 178 | +-} |
| 179 | + |
171 | 180 | import Streamly.Internal.FileSystem.Path |
0 commit comments