source: project/wiki/eggref/3/vfs @ 14113

Last change on this file since 14113 was 14113, checked in by sjamaan, 11 years ago

Rename "The User's Manual" to simply 'index', so we can refer to /manual, or /man/N, where N is a Chicken major release

File size: 6.2 KB
Line 
1[[toc:]]
2[[tags: egg]]
3
4== Introduction
5
6[[tinyclos|TinyCLOS]] wrappers for some file operations, which are:
7
8 open-input-file
9 open-output-file
10 file-exists?
11 delete-file
12 rename-file
13
14When this extension is used, all of the above procedures invoke
15user-defined generic functions implementing the actual file system
16operations. Since nearly all file operations (with the exception of
17those invoking operations from the [[/man/3/Unit posix|posix]] library unit)
18most procedures working on files can take advantage of this facility.
19
20To distinguish between different file-systems, a pathname may be
21preceded by an URI scheme of the form "{{<scheme>://}}".  If no scheme
22is given the current ''default file system'' is used.
23
24== Requirements
25
26[[tinyclos]], [[http://www.call-with-current-continuation.org/eggs/regex-case.html|regex-case]]
27
28
29== Documentation
30
31=== class vfs:file-system
32
33 [class] <vfs:file-system>
34
35Represents an object that can be accessed via file-system operations.
36
37=== vfs:open-input-file
38=== vfs:open-output-file
39
40 [generic] (vfs:open-file FILESYSTEM PATHNAME OUTPUT? MODES)
41 [generic] (vfs:open-input-file FILESYSTEM PATHNAME MODES)
42 [generic] (vfs:open-output-file FILESYSTEM PATHNAME MODES)
43
44Called for {{FILESYSTEM}} (an instance of {{<vfs:file-system>}}) when a file
45should be opened for reading or writing. {{PATHNAME}} is a string representing
46the path to the desired file.
47{{MODES}} is a list of one or more keywords specifying extra attributes
48for the file to be opened which are:
49
50 #:append
51 #:binary
52 #:text
53
54See the [[/man/3|The User's Manual]] for a description
55of these modes. If the {{vfs:open-file}} method is not implemented for
56a given file system, then either {{vfs:open-input-file}} or
57{{vfs:open-output-file}} are called, depending on the boolean
58{{OUTPUT?}}.
59
60All of these generic functions should return a port object.
61
62=== vfs:file-exists?
63
64 [generic] (vfs:file-exists? FILESYSTEM PATHNAME)
65
66Called for {{file-exists?}} when the given pathname refers to {{FILESYSTEM}}.
67Should return true when the designated file exists or {{#f}} if not.
68
69=== vfs:delete-file
70
71 [generic] (vfs:delete-file FILESYSTEM PATHNAME)
72
73Called for {{delete-file!}} and should delete the entity represented by
74{{PATHNAME}} in the given filesystem.
75
76=== vfs:rename-file
77
78 [generic] (vfs:rename-file FILESYSTEM OLDPATHNAME NEWPATHNAME)
79
80Called for {{rename-file}}.
81
82=== vfs:register-file-system
83
84 [procedure] (vfs:register-file-system SCHEME FILESYSTEM)
85
86Registers a filesystem prefix named {{SCHEME}} (a string) for
87{{FILESYSTEM}}. Any of the above mentioned file operations that refer to
88a pathname prefixed with {{<SCHEME>://}} will invoke the appropriate
89method implemented for {{FILESYSTEM}} or a default method that signals
90an error. The actual path passed to the file operation methods will
91receive the pathname with the prefix removed.
92
93=== vfs:unregister-file-system
94
95 [procedure] (vfs:unregister-file-system SCHEME)
96
97Un-registers a filesystem prefix.
98
99=== class vfs:local-file-system
100
101 [class] <vfs:local-file-system>
102
103A subclass of {{<vfs:file-system>}} representing the default local,
104native fileystem. Implements all methods and does the usual stuff.
105
106=== vfs:current-file-system
107
108 [parameter] vfs:current-file-system
109
110Holds the current file system, which is used if a pathname has no
111filesystem prefix.
112
113== Examples
114
115<enscript highlight=scheme>
116; hash-fs: a simple hash-table based file system
117
118(use vfs tinyclos)
119
120
121(define-class <hash-file-system> (<vfs:file-system>) (table))
122
123(define-method (vfs:open-input-file (fs <hash-file-system>) name modes)
124  (open-input-string
125   (hash-table-ref
126    (slot-ref fs 'table) name
127    (cut error 'open-input-file "file not found" name fs)) ) )
128
129(define-method (vfs:open-output-file (fs <hash-file-system>) name modes)
130  (let ((o (open-output-string))
131        (t (slot-ref fs 'table)))
132    (when (memq #:append modes)
133      (display (hash-table-ref/default t name "") o) )
134    (make-output-port
135     (cut display <> o)
136     (cut hash-table-set! t name (get-output-string o)) ) ) )
137
138(define-method (vfs:file-exists? (fs <hash-file-system>) name)
139  (and (hash-table-exists? (slot-ref fs 'table) name)
140       name) )
141
142(define-method (vfs:delete-file (fs <hash-file-system>) name)
143  (hash-table-delete! (slot-ref fs 'table) name) )
144
145(define-method (vfs:rename-file (fs <hash-file-system>) old new)
146  (let* ((t (slot-ref fs 'table))
147         (x (hash-table-ref
148             t old
149             (cut error 'rename-file "file not found" old fs)) ) )
150    (hash-table-delete! t old)
151    (hash-table-set! t new x) ) )
152
153(define-method (initialize (fs <hash-file-system>) initargs)
154  (set! (slot-ref fs 'table) (make-hash-table string=?)) )
155
156(vfs:register-file-system "hash" (make <hash-file-system>))
157</enscript>
158
159== Author
160
161[[felix winkelmann]]
162
163== License
164
165 Copyright (c) 2007, Felix L. Winkelmann
166 All rights reserved.
167
168 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
169 conditions are met:
170
171   Redistributions of source code must retain the above copyright notice, this list of conditions and the following
172     disclaimer.
173   Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
174     disclaimer in the documentation and/or other materials provided with the distribution.
175   Neither the name of the author nor the names of its contributors may be used to endorse or promote
176     products derived from this software without specific prior written permission.
177
178 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
179 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
180 AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
181 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
182 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
183 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
184 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
185 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
186 POSSIBILITY OF SUCH DAMAGE.
187
188
189== Version History
190
191; 0.1 : Initial version
Note: See TracBrowser for help on using the repository browser.