1098
1098
@section File Tree Walk
1099
1099
@cindex file tree walk
1101
@cindex file system traversal
1102
@cindex directory traversal
1101
1104
The functions in this section traverse a tree of files and
1102
directories, in a fashion similar to the C @code{ftw} and @code{nftw}
1103
routines (@pxref{Working with Directory Trees,,, libc, GNU C Library
1105
directories. They come in two flavors: the first one is a high-level
1106
functional interface, and the second one is similar to the C @code{ftw}
1107
and @code{nftw} routines (@pxref{Working with Directory Trees,,, libc,
1108
GNU C Library Reference Manual}).
1107
1111
(use-modules (ice-9 ftw))
1111
@defun ftw startname proc ['hash-size n]
1115
@deffn {Scheme Procedure} file-system-tree file-name [enter? [stat]]
1116
Return a tree of the form @code{(@var{file-name} @var{stat}
1117
@var{children} ...)} where @var{stat} is the result of @code{(@var{stat}
1118
@var{file-name})} and @var{children} are similar structures for each
1119
file contained in @var{file-name} when it designates a directory.
1121
The optional @var{enter?} predicate is invoked as @code{(@var{enter?}
1122
@var{name} @var{stat})} and should return true to allow recursion into
1123
directory @var{name}; the default value is a procedure that always
1124
returns @code{#t}. When a directory does not match @var{enter?}, it
1125
nonetheless appears in the resulting tree, only with zero children.
1127
The @var{stat} argument is optional and defaults to @code{lstat}, as for
1128
@code{file-system-fold} (see below.)
1130
The example below shows how to obtain a hierarchical listing of the
1131
files under the @file{module/language} directory in the Guile source
1132
tree, discarding their @code{stat} info:
1135
(use-modules (ice-9 match))
1138
;; Remove the `stat' object the `file-system-tree' provides
1139
;; for each file in the tree.
1141
((name stat) ; flat file
1143
((name stat children ...) ; directory
1144
(list name (map remove-stat children)))))
1146
(let ((dir (string-append (assq-ref %guile-build-info 'top_srcdir)
1147
"/module/language")))
1148
(remove-stat (file-system-tree dir)))
1152
(("value" ("spec.go" "spec.scm"))
1156
"compile-tree-il.scm"
1157
"decompile-tree-il.scm"
1158
"decompile-tree-il.go"
1159
"compile-tree-il.go"))
1174
@cindex file system combinator
1176
It is often desirable to process directories entries directly, rather
1177
than building up a tree of entries in memory, like
1178
@code{file-system-tree} does. The following procedure, a
1179
@dfn{combinator}, is designed to allow directory entries to be processed
1180
directly as a directory tree is traversed; in fact,
1181
@code{file-system-tree} is implemented in terms of it.
1183
@deffn {Scheme Procedure} file-system-fold enter? leaf down up skip error init file-name [stat]
1184
Traverse the directory at @var{file-name}, recursively, and return the
1185
result of the successive applications of the @var{leaf}, @var{down},
1186
@var{up}, and @var{skip} procedures as described below.
1188
Enter sub-directories only when @code{(@var{enter?} @var{path}
1189
@var{stat} @var{result})} returns true. When a sub-directory is
1190
entered, call @code{(@var{down} @var{path} @var{stat} @var{result})},
1191
where @var{path} is the path of the sub-directory and @var{stat} the
1192
result of @code{(false-if-exception (@var{stat} @var{path}))}; when it is
1193
left, call @code{(@var{up} @var{path} @var{stat} @var{result})}.
1195
For each file in a directory, call @code{(@var{leaf} @var{path}
1196
@var{stat} @var{result})}.
1198
When @var{enter?} returns @code{#f}, or when an unreadable directory is
1199
encountered, call @code{(@var{skip} @var{path} @var{stat}
1202
When @var{file-name} names a flat file, @code{(@var{leaf} @var{path}
1203
@var{stat} @var{init})} is returned.
1205
When an @code{opendir} or @var{stat} call fails, call @code{(@var{error}
1206
@var{path} @var{stat} @var{errno} @var{result})}, with @var{errno} being
1207
the operating system error number that was raised---e.g.,
1208
@code{EACCES}---and @var{stat} either @code{#f} or the result of the
1209
@var{stat} call for that entry, when available.
1211
The special @file{.} and @file{..} entries are not passed to these
1212
procedures. The @var{path} argument to the procedures is a full file
1213
name---e.g., @code{"../foo/bar/gnu"}; if @var{file-name} is an absolute
1214
file name, then @var{path} is also an absolute file name. Files and
1215
directories, as identified by their device/inode number pair, are
1216
traversed only once.
1218
The optional @var{stat} argument defaults to @code{lstat}, which means
1219
that symbolic links are not followed; the @code{stat} procedure can be
1220
used instead when symbolic links are to be followed (@pxref{File System,
1223
The example below illustrates the use of @code{file-system-fold}:
1226
(define (total-file-size file-name)
1227
"Return the size in bytes of the files under FILE-NAME (similar
1228
to `du --apparent-size' with GNU Coreutils.)"
1230
(define (enter? name stat result)
1231
;; Skip version control directories.
1232
(not (member (basename name) '(".git" ".svn" "CVS"))))
1233
(define (leaf name stat result)
1234
;; Return RESULT plus the size of the file at NAME.
1235
(+ result (stat:size stat)))
1237
;; Count zero bytes for directories.
1238
(define (down name stat result) result)
1239
(define (up name stat result) result)
1241
;; Likewise for skipped directories.
1242
(define (skip name stat result) result)
1244
;; Ignore unreadable files/directories but warn the user.
1245
(define (error name stat errno result)
1246
(format (current-error-port) "warning: ~a: ~a~%"
1247
name (strerror errno))
1250
(file-system-fold enter? leaf down up skip error
1251
0 ; initial counter is zero bytes
1254
(total-file-size ".")
1257
(total-file-size "/dev/null")
1262
The alternative C-like functions are described below.
1264
@deffn {Scheme Procedure} scandir name [select? [entry<?]]
1265
Return the list of the names of files contained in directory @var{name}
1266
that match predicate @var{select?} (by default, all files). The
1267
returned list of file names is sorted according to @var{entry<?}, which
1268
defaults to @code{string-locale<?} such that file names are sorted in
1269
the locale's alphabetical order (@pxref{Text Collation}). Return
1270
@code{#f} when @var{name} is unreadable or is not a directory.
1272
This procedure is modeled after the C library function of the same name
1273
(@pxref{Scanning Directory Content,,, libc, GNU C Library Reference
1277
@deffn {Scheme Procedure} ftw startname proc ['hash-size n]
1112
1278
Walk the file system tree descending from @var{startname}, calling
1113
1279
@var{proc} for each file and directory.
1441
1607
being the new @var{state} for the next call. For the first call
1442
1608
@var{state} is the given @var{initial-state}. At the end of the
1443
1609
stream, @var{proc} should return some non-pair object.
1446
@defun stream-car stream
1612
@deffn {Scheme Procedure} stream-car stream
1447
1613
Return the first element from @var{stream}. @var{stream} must not be
1451
@defun stream-cdr stream
1617
@deffn {Scheme Procedure} stream-cdr stream
1452
1618
Return a stream which is the second and subsequent elements of
1453
1619
@var{stream}. @var{stream} must not be empty.
1456
@defun stream-null? stream
1622
@deffn {Scheme Procedure} stream-null? stream
1457
1623
Return true if @var{stream} is empty.
1460
@defun list->stream list
1461
@defunx vector->stream vector
1626
@deffn {Scheme Procedure} list->stream list
1627
@deffnx {Scheme Procedure} vector->stream vector
1462
1628
Return a stream with the contents of @var{list} or @var{vector}.
1464
1630
@var{list} or @var{vector} should not be modified subsequently, since
1465
1631
it's unspecified whether changes there will be reflected in the stream
1469
@defun port->stream port readproc
1635
@deffn {Scheme Procedure} port->stream port readproc
1470
1636
Return a stream which is the values obtained by reading from
1471
1637
@var{port} using @var{readproc}. Each read call is
1472
1638
@code{(@var{readproc} @var{port})}, and it should return an EOF object
1478
1644
(port->stream (open-input-file "/foo/bar.txt") read-char)
1482
@defun stream->list stream
1648
@deffn {Scheme Procedure} stream->list stream
1483
1649
Return a list which is the entire contents of @var{stream}.
1486
@defun stream->reversed-list stream
1652
@deffn {Scheme Procedure} stream->reversed-list stream
1487
1653
Return a list which is the entire contents of @var{stream}, but in
1491
@defun stream->list&length stream
1657
@deffn {Scheme Procedure} stream->list&length stream
1492
1658
Return two values (@pxref{Multiple Values}), being firstly a list
1493
1659
which is the entire contents of @var{stream}, and secondly the number
1494
1660
of elements in that list.
1497
@defun stream->reversed-list&length stream
1663
@deffn {Scheme Procedure} stream->reversed-list&length stream
1498
1664
Return two values (@pxref{Multiple Values}) being firstly a list which
1499
1665
is the entire contents of @var{stream}, but in reverse order, and
1500
1666
secondly the number of elements in that list.
1503
@defun stream->vector stream
1669
@deffn {Scheme Procedure} stream->vector stream
1504
1670
Return a vector which is the entire contents of @var{stream}.
1507
@defun stream-fold proc init stream0 @dots{} streamN
1673
@deffn {Scheme Procedure} stream-fold proc init stream0 @dots{} streamN
1508
1674
Apply @var{proc} successively over the elements of the given streams,
1509
1675
from first to last until the end of the shortest stream is reached.
1510
1676
Return the result from the last @var{proc} call.
added
removed
doc/ref/misc-modules.texi
