Skip to content

Commit 3ee1317

Browse files
ringaboutringabout
committed
add documentation
1 parent a50d1e1 commit 3ee1317

File tree

4 files changed

+469
-12
lines changed

4 files changed

+469
-12
lines changed

‎lib/std/dirs.nim

Lines changed: 140 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,41 +6,173 @@ from std/private/osdirs import dirExists, createDir, existsOrCreateDir, removeDi
66

77
export PathComponent
88

9-
proc dirExists*(dir: Path): bool {.tags: [ReadDirEffect].} =
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.
1012
result = dirExists(dir.string)
1113

12-
proc createDir*(dir: Path) {.tags: [WriteDirEffect, ReadDirEffect].} =
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`_
1329
createDir(dir.string)
1430

15-
proc existsOrCreateDir*(dir: Path): bool {.tags: [WriteDirEffect, ReadDirEffect].} =
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`_
1643
result = existsOrCreateDir(dir.string)
1744

1845
proc removeDir*(dir: Path, checkDir = false
19-
) {.tags: [WriteDirEffect, ReadDirEffect].} =
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+
## * `tryRemoveFile proc`_
55+
## * `removeFile proc`_
56+
## * `existsOrCreateDir proc`_
57+
## * `createDir proc`_
58+
## * `copyDir proc`_
59+
## * `copyDirWithPermissions proc`_
60+
## * `moveDir proc`_
2061
removeDir(dir.string, checkDir)
2162

22-
proc moveDir*(source, dest: Path) {.tags: [ReadIOEffect, WriteIOEffect].} =
63+
proc moveDir*(source, dest: Path) {.inline, tags: [ReadIOEffect, WriteIOEffect].} =
64+
## Moves a directory from `source` to `dest`.
65+
##
66+
## Symlinks are not followed: if `source` contains symlinks, they themself are
67+
## moved, not their target.
68+
##
69+
## If this fails, `OSError` is raised.
70+
##
71+
## See also:
72+
## * `moveFile proc`_
73+
## * `copyDir proc`_
74+
## * `copyDirWithPermissions proc`_
75+
## * `removeDir proc`_
76+
## * `existsOrCreateDir proc`_
77+
## * `createDir proc`_
2378
moveDir(source.string, dest.string)
2479

2580
iterator walkPattern*(pattern: Path): Path {.tags: [ReadDirEffect].} =
81+
## Iterate over all the files and directories that match the `pattern`.
82+
##
83+
## On POSIX this uses the `glob`:idx: call.
84+
## `pattern` is OS dependent, but at least the `"*.ext"`
85+
## notation is supported.
86+
##
87+
## See also:
88+
## * `walkFiles iterator`_
89+
## * `walkDirs iterator`_
90+
## * `walkDir iterator`_
91+
## * `walkDirRec iterator`_
2692
for p in walkPattern(pattern.string):
2793
yield Path(p)
2894

2995
iterator walkFiles*(pattern: Path): Path {.tags: [ReadDirEffect].} =
96+
## Iterate over all the files that match the `pattern`.
97+
##
98+
## On POSIX this uses the `glob`:idx: call.
99+
## `pattern` is OS dependent, but at least the `"*.ext"`
100+
## notation is supported.
101+
##
102+
## See also:
103+
## * `walkPattern iterator`_
104+
## * `walkDirs iterator`_
105+
## * `walkDir iterator`_
106+
## * `walkDirRec iterator`_
30107
for p in walkFiles(pattern.string):
31108
yield Path(p)
32109

33110
iterator walkDirs*(pattern: Path): Path {.tags: [ReadDirEffect].} =
111+
## Iterate over all the directories that match the `pattern`.
112+
##
113+
## On POSIX this uses the `glob`:idx: call.
114+
## `pattern` is OS dependent, but at least the `"*.ext"`
115+
## notation is supported.
116+
##
117+
## See also:
118+
## * `walkPattern iterator`_
119+
## * `walkFiles iterator`_
120+
## * `walkDir iterator`_
121+
## * `walkDirRec iterator`_
34122
for p in walkDirs(pattern.string):
35123
yield Path(p)
36124

37125
iterator walkDir*(dir: Path; relative = false, checkDir = false):
38-
tuple[kind: PathComponent, path: Path] {.tags: [ReadDirEffect].} =
39-
for (k, p) in walkDir(dir.string, relative, checkDir):
40-
yield (k, Path(p))
126+
tuple[kind: PathComponent, path: Path] {.tags: [ReadDirEffect].} =
127+
## Walks over the directory `dir` and yields for each directory or file in
128+
## `dir`. The component type and full path for each item are returned.
129+
##
130+
## Walking is not recursive. If ``relative`` is true (default: false)
131+
## the resulting path is shortened to be relative to ``dir``.
132+
##
133+
## If `checkDir` is true, `OSError` is raised when `dir`
134+
## doesn't exist.
135+
for (k, p) in walkDir(dir.string, relative, checkDir):
136+
yield (k, Path(p))
41137

42138
iterator walkDirRec*(dir: Path,
43139
yieldFilter = {pcFile}, followFilter = {pcDir},
44140
relative = false, checkDir = false): Path {.tags: [ReadDirEffect].} =
141+
## Recursively walks over the directory `dir` and yields for each file
142+
## or directory in `dir`.
143+
##
144+
## If ``relative`` is true (default: false) the resulting path is
145+
## shortened to be relative to ``dir``, otherwise the full path is returned.
146+
##
147+
## If `checkDir` is true, `OSError` is raised when `dir`
148+
## doesn't exist.
149+
##
150+
## .. warning:: Modifying the directory structure while the iterator
151+
## is traversing may result in undefined behavior!
152+
##
153+
## Walking is recursive. `followFilter` controls the behaviour of the iterator:
154+
##
155+
## ===================== =============================================
156+
## yieldFilter meaning
157+
## ===================== =============================================
158+
## ``pcFile`` yield real files (default)
159+
## ``pcLinkToFile`` yield symbolic links to files
160+
## ``pcDir`` yield real directories
161+
## ``pcLinkToDir`` yield symbolic links to directories
162+
## ===================== =============================================
163+
##
164+
## ===================== =============================================
165+
## followFilter meaning
166+
## ===================== =============================================
167+
## ``pcDir`` follow real directories (default)
168+
## ``pcLinkToDir`` follow symbolic links to directories
169+
## ===================== =============================================
170+
##
171+
##
172+
## See also:
173+
## * `walkPattern iterator`_
174+
## * `walkFiles iterator`_
175+
## * `walkDirs iterator`_
176+
## * `walkDir iterator`_
45177
for p in walkDirRec(dir.string, yieldFilter, followFilter, relative, checkDir):
46178
yield Path(p)

‎lib/std/files.nim

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,58 @@ from std/private/osfiles import fileExists, tryRemoveFile, removeFile,
55

66

77
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.
811
result = fileExists(filename.string)
912

1013
proc tryRemoveFile*(file: Path): bool {.inline, tags: [WriteDirEffect].} =
14+
## Removes the `file`.
15+
##
16+
## If this fails, returns `false`. 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+
## * `copyFile proc`_
23+
## * `copyFileWithPermissions proc`_
24+
## * `removeFile proc`_
25+
## * `moveFile proc`_
1126
result = tryRemoveFile(file.string)
1227

1328
proc removeFile*(file: Path) {.inline, tags: [WriteDirEffect].} =
29+
## Removes the `file`.
30+
##
31+
## If this fails, `OSError` is raised. This does not fail
32+
## if the file never existed in the first place.
33+
##
34+
## On Windows, ignores the read-only attribute.
35+
##
36+
## See also:
37+
## * `removeDir proc`_
38+
## * `copyFile proc`_
39+
## * `copyFileWithPermissions proc`_
40+
## * `tryRemoveFile proc`_
41+
## * `moveFile proc`_
1442
removeFile(file.string)
1543

1644
proc moveFile*(source, dest: Path) {.inline,
1745
tags: [ReadDirEffect, ReadIOEffect, WriteIOEffect].} =
46+
## Moves a file from `source` to `dest`.
47+
##
48+
## Symlinks are not followed: if `source` is a symlink, it is itself moved,
49+
## not its target.
50+
##
51+
## If this fails, `OSError` is raised.
52+
## If `dest` already exists, it will be overwritten.
53+
##
54+
## Can be used to `rename files`:idx:.
55+
##
56+
## See also:
57+
## * `moveDir proc`_
58+
## * `copyFile proc`_
59+
## * `copyFileWithPermissions proc`_
60+
## * `removeFile proc`_
61+
## * `tryRemoveFile proc`_
1862
moveFile(source.string, dest.string)

0 commit comments

Comments
 (0)