Skip to content

Commit 3c12b72

Browse files
ringaboutringabout
authored
add typesafe std/paths, std/files, std/dirs, std/symlinks (#20582)
* split std/os; add typesafe std/paths * add more files, dirs, paths * add documentation * add testcase * remove tryRemoveFile * clean up * Delete test.nim * apply changes * add `add` and fixes
1 parent 66cbcaa commit 3c12b72

File tree

6 files changed

+775
-0
lines changed

6 files changed

+775
-0
lines changed

‎lib/std/dirs.nim

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
from paths import Path, ReadDirEffect, WriteDirEffect
2+
3+
from std/private/osdirs import dirExists, createDir, existsOrCreateDir, removeDir,
4+
moveDir, walkPattern, walkFiles, walkDirs, walkDir,
5+
walkDirRec, PathComponent
6+
7+
export PathComponent
8+
9+
proc dirExists*(dir: Path): bool {.inline, tags: [ReadDirEffect].} =
10+
## Returns true if the directory `dir` exists. If `dir` is a file, false
11+
## is returned. Follows symlinks.
12+
result = dirExists(dir.string)
13+
14+
proc createDir*(dir: Path) {.inline, tags: [WriteDirEffect, ReadDirEffect].} =
15+
## Creates the `directory`:idx: `dir`.
16+
##
17+
## The directory may contain several subdirectories that do not exist yet.
18+
## The full path is created. If this fails, `OSError` is raised.
19+
##
20+
## It does **not** fail if the directory already exists because for
21+
## most usages this does not indicate an error.
22+
##
23+
## See also:
24+
## * `removeDir proc`_
25+
## * `existsOrCreateDir proc`_
26+
## * `copyDir proc`_
27+
## * `copyDirWithPermissions proc`_
28+
## * `moveDir proc`_
29+
createDir(dir.string)
30+
31+
proc existsOrCreateDir*(dir: Path): bool {.inline, tags: [WriteDirEffect, ReadDirEffect].} =
32+
## Checks if a `directory`:idx: `dir` exists, and creates it otherwise.
33+
##
34+
## Does not create parent directories (raises `OSError` if parent directories do not exist).
35+
## Returns `true` if the directory already exists, and `false` otherwise.
36+
##
37+
## See also:
38+
## * `removeDir proc`_
39+
## * `createDir proc`_
40+
## * `copyDir proc`_
41+
## * `copyDirWithPermissions proc`_
42+
## * `moveDir proc`_
43+
result = existsOrCreateDir(dir.string)
44+
45+
proc removeDir*(dir: Path, checkDir = false
46+
) {.inline, tags: [WriteDirEffect, ReadDirEffect].} =
47+
## Removes the directory `dir` including all subdirectories and files
48+
## in `dir` (recursively).
49+
##
50+
## If this fails, `OSError` is raised. This does not fail if the directory never
51+
## existed in the first place, unless `checkDir` = true.
52+
##
53+
## See also:
54+
## * `removeFile proc`_
55+
## * `existsOrCreateDir proc`_
56+
## * `createDir proc`_
57+
## * `copyDir proc`_
58+
## * `copyDirWithPermissions proc`_
59+
## * `moveDir proc`_
60+
removeDir(dir.string, checkDir)
61+
62+
proc moveDir*(source, dest: Path) {.inline, tags: [ReadIOEffect, WriteIOEffect].} =
63+
## Moves a directory from `source` to `dest`.
64+
##
65+
## Symlinks are not followed: if `source` contains symlinks, they themself are
66+
## moved, not their target.
67+
##
68+
## If this fails, `OSError` is raised.
69+
##
70+
## See also:
71+
## * `moveFile proc`_
72+
## * `copyDir proc`_
73+
## * `copyDirWithPermissions proc`_
74+
## * `removeDir proc`_
75+
## * `existsOrCreateDir proc`_
76+
## * `createDir proc`_
77+
moveDir(source.string, dest.string)
78+
79+
iterator walkPattern*(pattern: Path): Path {.tags: [ReadDirEffect].} =
80+
## Iterate over all the files and directories that match the `pattern`.
81+
##
82+
## On POSIX this uses the `glob`:idx: call.
83+
## `pattern` is OS dependent, but at least the `"*.ext"`
84+
## notation is supported.
85+
##
86+
## See also:
87+
## * `walkFiles iterator`_
88+
## * `walkDirs iterator`_
89+
## * `walkDir iterator`_
90+
## * `walkDirRec iterator`_
91+
for p in walkPattern(pattern.string):
92+
yield Path(p)
93+
94+
iterator walkFiles*(pattern: Path): Path {.tags: [ReadDirEffect].} =
95+
## Iterate over all the files that match the `pattern`.
96+
##
97+
## On POSIX this uses the `glob`:idx: call.
98+
## `pattern` is OS dependent, but at least the `"*.ext"`
99+
## notation is supported.
100+
##
101+
## See also:
102+
## * `walkPattern iterator`_
103+
## * `walkDirs iterator`_
104+
## * `walkDir iterator`_
105+
## * `walkDirRec iterator`_
106+
for p in walkFiles(pattern.string):
107+
yield Path(p)
108+
109+
iterator walkDirs*(pattern: Path): Path {.tags: [ReadDirEffect].} =
110+
## Iterate over all the directories that match the `pattern`.
111+
##
112+
## On POSIX this uses the `glob`:idx: call.
113+
## `pattern` is OS dependent, but at least the `"*.ext"`
114+
## notation is supported.
115+
##
116+
## See also:
117+
## * `walkPattern iterator`_
118+
## * `walkFiles iterator`_
119+
## * `walkDir iterator`_
120+
## * `walkDirRec iterator`_
121+
for p in walkDirs(pattern.string):
122+
yield Path(p)
123+
124+
iterator walkDir*(dir: Path; relative = false, checkDir = false):
125+
tuple[kind: PathComponent, path: Path] {.tags: [ReadDirEffect].} =
126+
## Walks over the directory `dir` and yields for each directory or file in
127+
## `dir`. The component type and full path for each item are returned.
128+
##
129+
## Walking is not recursive. If ``relative`` is true (default: false)
130+
## the resulting path is shortened to be relative to ``dir``.
131+
##
132+
## If `checkDir` is true, `OSError` is raised when `dir`
133+
## doesn't exist.
134+
for (k, p) in walkDir(dir.string, relative, checkDir):
135+
yield (k, Path(p))
136+
137+
iterator walkDirRec*(dir: Path,
138+
yieldFilter = {pcFile}, followFilter = {pcDir},
139+
relative = false, checkDir = false): Path {.tags: [ReadDirEffect].} =
140+
## Recursively walks over the directory `dir` and yields for each file
141+
## or directory in `dir`.
142+
##
143+
## If ``relative`` is true (default: false) the resulting path is
144+
## shortened to be relative to ``dir``, otherwise the full path is returned.
145+
##
146+
## If `checkDir` is true, `OSError` is raised when `dir`
147+
## doesn't exist.
148+
##
149+
## .. warning:: Modifying the directory structure while the iterator
150+
## is traversing may result in undefined behavior!
151+
##
152+
## Walking is recursive. `followFilter` controls the behaviour of the iterator:
153+
##
154+
## ===================== =============================================
155+
## yieldFilter meaning
156+
## ===================== =============================================
157+
## ``pcFile`` yield real files (default)
158+
## ``pcLinkToFile`` yield symbolic links to files
159+
## ``pcDir`` yield real directories
160+
## ``pcLinkToDir`` yield symbolic links to directories
161+
## ===================== =============================================
162+
##
163+
## ===================== =============================================
164+
## followFilter meaning
165+
## ===================== =============================================
166+
## ``pcDir`` follow real directories (default)
167+
## ``pcLinkToDir`` follow symbolic links to directories
168+
## ===================== =============================================
169+
##
170+
##
171+
## See also:
172+
## * `walkPattern iterator`_
173+
## * `walkFiles iterator`_
174+
## * `walkDirs iterator`_
175+
## * `walkDir iterator`_
176+
for p in walkDirRec(dir.string, yieldFilter, followFilter, relative, checkDir):
177+
yield Path(p)

‎lib/std/files.nim

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
from paths import Path, ReadDirEffect, WriteDirEffect
2+
3+
from std/private/osfiles import fileExists, removeFile,
4+
moveFile
5+
6+
7+
proc fileExists*(filename: Path): bool {.inline, tags: [ReadDirEffect].} =
8+
## Returns true if `filename` exists and is a regular file or symlink.
9+
##
10+
## Directories, device files, named pipes and sockets return false.
11+
result = fileExists(filename.string)
12+
13+
proc removeFile*(file: Path) {.inline, tags: [WriteDirEffect].} =
14+
## Removes the `file`.
15+
##
16+
## If this fails, `OSError` is raised. This does not fail
17+
## if the file never existed in the first place.
18+
##
19+
## On Windows, ignores the read-only attribute.
20+
##
21+
## See also:
22+
## * `removeDir proc`_
23+
## * `copyFile proc`_
24+
## * `copyFileWithPermissions proc`_
25+
## * `moveFile proc`_
26+
removeFile(file.string)
27+
28+
proc moveFile*(source, dest: Path) {.inline,
29+
tags: [ReadDirEffect, ReadIOEffect, WriteIOEffect].} =
30+
## Moves a file from `source` to `dest`.
31+
##
32+
## Symlinks are not followed: if `source` is a symlink, it is itself moved,
33+
## not its target.
34+
##
35+
## If this fails, `OSError` is raised.
36+
## If `dest` already exists, it will be overwritten.
37+
##
38+
## Can be used to `rename files`:idx:.
39+
##
40+
## See also:
41+
## * `moveDir proc`_
42+
## * `copyFile proc`_
43+
## * `copyFileWithPermissions proc`_
44+
## * `removeFile proc`_
45+
moveFile(source.string, dest.string)

0 commit comments

Comments
 (0)