This is the nfiles Reference Manual, version 0.2.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 05:40:02 2022 GMT+0.
• Systems | The systems documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
The main system appears first, followed by any subsystem dependency.
• The nfiles system |
Atlas Engineer LLC
BSD 3-Clause
Manage file persistence and loading.
0.2.2
nfiles.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
• The nfiles.asd file | ||
• The nfiles/package.lisp file | ||
• The nfiles/conditions.lisp file | ||
• The nfiles/pathname-helpers.lisp file | ||
• The nfiles/gpg.lisp file | ||
• The nfiles/nfiles.lisp file |
Next: The nfiles/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
nfiles.asd
nfiles (system)
Next: The nfiles/conditions․lisp file, Previous: The nfiles․asd file, Up: Lisp files [Contents][Index]
nfiles (system)
package.lisp
Next: The nfiles/pathname-helpers․lisp file, Previous: The nfiles/package․lisp file, Up: Lisp files [Contents][Index]
nfiles (system)
conditions.lisp
Next: The nfiles/gpg․lisp file, Previous: The nfiles/conditions․lisp file, Up: Lisp files [Contents][Index]
nfiles (system)
pathname-helpers.lisp
+permissions+ (constant)
Next: The nfiles/nfiles․lisp file, Previous: The nfiles/pathname-helpers․lisp file, Up: Lisp files [Contents][Index]
nfiles (system)
gpg.lisp
Previous: The nfiles/gpg․lisp file, Up: Lisp files [Contents][Index]
nfiles (system)
nfiles.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The nfiles package | ||
• The nfiles/gpg package |
Next: The nfiles/gpg package, Previous: Packages, Up: Packages [Contents][Index]
The main data structures are ‘file’ and ‘profile’.
Call ‘expand’ to return the final ‘file’ path.
Call ‘content’ (setf-able) to get the ‘file’ content.
Specialize ‘resolve’ to configure how a file path is expanded depending on the
file type and the ‘profile’.
The content serialization and deserialization can be specialized via the
‘serialize’ and ‘deserialize’ methods.
The file reading and writing can be specialized via the ‘file-read’ and ‘file-write’ methods.
package.lisp (file)
common-lisp
Previous: The nfiles package, Up: Packages [Contents][Index]
A thin wrapper around the GPG command line tool.
package.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported special variables | ||
• Exported macros | ||
• Exported functions | ||
• Exported generic functions | ||
• Exported conditions | ||
• Exported classes |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
nfiles.lisp (file)
gpg.lisp (file)
gpg.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Bind CONTENT to FILE’s content in BODY.
In case there’s no content, bind CONTENT to DEFAULT.
The new value of CONTENT is saved to FILE on exit.
nfiles.lisp (file)
Trivial wrapper around ‘call-with-gpg-file’.
gpg.lisp (file)
Bind let-style BINDINGS to ‘file’ path expansions, then run BODY if all these paths or non-nil after ‘nil-pathname-p’.
nfiles.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Return all instantiated ‘file’ objects belong to PACKAGES. If no package is specified, return all ‘file’ objects.
nfiles.lisp (file)
Rename PATH to a file of the same name with a unique suffix appended. The file is guaranteed to not conflict with any existing file.
nfiles.lisp (file)
Return the content of FILE.
When FORCE-READ is non-nil, the cache is skipped and the file is re-read.
The read is asynchronous. By default, ‘content’ waits for the read to finish before returning the result. But if ‘wait-p’ is nil, it returns directly with (VALUES NIL THREAD) if the reading THREAD is not done yet.
nfiles.lisp (file)
(setf content) (function)
Set FILE content to VALUE and persist change to disk.
While the content of the FILE object is updated instantly, the file is persisted
in the background.
Return a ‘bt:thread’ object. Call ‘bt:join-thread’ on it to know when it’s done writing the file.
nfiles.lisp (file)
content (function)
Return the pathname corresponding to FILE and its ‘profile’.
It’s a convenience wrapper around ‘resolve’ (to avoid specifying the ‘profile’).
nfiles.lisp (file)
Return PATH group name.
pathname-helpers.lisp (file)
(setf file-group) (function)
Set PATH group to NEW-GROUP (a string).
pathname-helpers.lisp (file)
file-group (function)
Return PATH owner name.
pathname-helpers.lisp (file)
(setf file-user) (function)
Set PATH owner to NEW-USER (a string).
pathname-helpers.lisp (file)
file-user (function)
Return list of private ‘gpg-key’s.
gpg.lisp (file)
Return non-nil if PATHNAME is ‘uiop:*nil-pathname*’ or nil.
pathname-helpers.lisp (file)
Return the parent directory of PATH.
pathname-helpers.lisp (file)
Like ‘pathname-type’ but return NIL instead of "" or :UNSPECIFIC.
pathname-helpers.lisp (file)
Return a list of permissions as per ‘+permissions+’.
pathname-helpers.lisp (file)
(setf permissions) (function)
Set the PERMISSIONS or PATH as per ‘+permissions+’.
pathname-helpers.lisp (file)
permissions (function)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
The pathname used by the ‘resolve’ method to yield the final path.
nfiles.lisp (file)
Stored as in Unix format.
gpg.lisp (file)
Transform STREAM into a useful form ready to be manipulated on the Lisp side. See ‘serialize’ for the reverse action.
nfiles.lisp (file)
Don’t try deserialize if there is no file.
Handle errors gracefully. See ‘on-deserialization-error’.
Stored as in Unix format.
gpg.lisp (file)
Name used to identify the object in a human-readable manner.
nfiles.lisp (file)
The name of the profile to refer it with.
nfiles.lisp (file)
What to do on deserialization error.
The offending file may be backed up with the ‘backup’ function.
Or it may simply be deleted.
‘ask’ leaves the condition is unhandled, so unless you handle it it will prompt the debugger with the other options.
nfiles.lisp (file)
Whether to reload or overwrite the file if it was modified since it was last loaded.
nfiles.lisp (file)
What to do on file read error.
See ‘on-deserialization-error’ for the meaning of the different actions.
nfiles.lisp (file)
The ‘profile’ of the ‘file’.
File expansion is performed against it.
The profile is only set at instantiation time.
nfiles.lisp (file)
Load FILE by calling ‘deserialize’ on a stream opened on the file. See ‘write-file’ for the reverse action.
nfiles.lisp (file)
Don’t load anything when using the ‘virtual-profile’.
Don’t load anything for virtual files.
Decrypt FILE with GPG and return resulting stream. See ‘*gpg-default-recipient*’.
Open FILE and call ‘deserialize’ on its content.
Don’t try to load the file if it does not exist.
Function of one argument, the condition that may be raised in the reader thread.
nfiles.lisp (file)
Return the final expanded path for ‘file’ depending on its ‘profile’.
This method is meant to be specialized against the user-defined ‘profile’s and ‘file’s.
See ‘expand’ for a convenience wrapper.
nfiles.lisp (file)
Clean up the result before returning it.
Transform ‘file’ content meant to
be persisted to a file.
See ‘deserialize’ for the reverse action.
nfiles.lisp (file)
Persist FILE to disk.
DESTINATION is set by default to a staged pathname (using
‘uiop:with-staging-pathname’) which is renamed to the final name (the result
‘expand’ on FILE) if everything went well.
This guarantees that on error the original file is left untouched.
See ‘read-file’ for the reverse action.
nfiles.lisp (file)
Don’t write anything when using the ‘read-only-profile’.
Don’t write anything for ‘read-only-file’.
Crypt to FILE with GPG. See ‘*gpg-default-recipient*’.
Write the result of ‘serialize’ to the ‘file’ path.
Function of one argument, the condition that may be raised in the writer thread.
nfiles.lisp (file)
Next: Exported classes, Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
conditions.lisp (file)
error (condition)
:path
conditions.lisp (file)
subprocess-error (condition)
:message
Previous: Exported conditions, Up: Exported definitions [Contents][Index]
Like regular ‘file’ but set directory to ‘uiop:xdg-cache-home’
nfiles.lisp (file)
file (class)
resolve (method)
Like regular ‘file’ but set directory to ‘uiop:xdg-config-home’.
nfiles.lisp (file)
file (class)
resolve (method)
Like regular ‘file’ but set directory to ‘uiop:xdg-data-home’
nfiles.lisp (file)
file (class)
resolve (method)
The main object to manipulate and subclass.
The ‘profile’ slot can be used to drive the specializations of multiple ‘file’ methods.
See ‘resolve’, ‘serialize’, ‘etc’.
The ‘name’ slot can be used to refer to ‘file’ objects in a human-readable fashion.
nfiles.lisp (file)
standard-object (class)
The pathname used by the ‘resolve’ method to yield the final path.
pathname
#p"."
base-path (generic function)
The ‘profile’ of the ‘file’.
File expansion is performed against it.
The profile is only set at instantiation time.
nfiles:profile
:profile
nfiles:*default-profile*
profile (generic function)
Name used to identify the object in a human-readable manner.
string
:name
""
name (generic function)
(setf name) (generic function)
Function of one argument, the condition that may be raised in the reader thread.
trivial-types:function-designator
:read-handler
(function identity)
read-handler (generic function)
(setf read-handler) (generic function)
Function of one argument, the condition that may be raised in the writer thread.
trivial-types:function-designator
:write-handler
(function identity)
write-handler (generic function)
(setf write-handler) (generic function)
Whether to reload or overwrite the file if it was modified since it was last loaded.
(member nfiles:ask nfiles:reload nfiles:overwrite)
:on-external-modification
(quote nfiles:ask)
on-external-modification (generic function)
(setf on-external-modification) (generic function)
What to do on deserialization error.
The offending file may be backed up with the ‘backup’ function.
Or it may simply be deleted.
‘ask’ leaves the condition is unhandled, so unless you handle it it will prompt the debugger with the other options.
(member nfiles:ask nfiles:backup delete)
:on-deserialization-error
(quote nfiles:ask)
on-deserialization-error (generic function)
(setf on-deserialization-error) (generic function)
What to do on file read error.
See ‘on-deserialization-error’ for the meaning of the different actions.
(member nfiles:ask nfiles:backup delete)
:on-read-error
(quote nfiles:ask)
on-read-error (generic function)
(setf on-read-error) (generic function)
The file is automatically crypted and decrypted using the
specified recipient key.
The ’.gpg’ extension is automatically added if missing.
nfiles.lisp (file)
file (class)
gpg-lisp-file (class)
gpg.lisp (file)
standard-object (class)
:key-length
key-length (generic function)
(setf key-length) (generic function)
:algorithm
algorithm (generic function)
(setf algorithm) (generic function)
:key-id
key-id (generic function)
(setf key-id) (generic function)
Stored as in Unix format.
:creation-date
creation-date (generic function)
(setf creation-date) (generic function)
Stored as in Unix format.
:expiry-date
expiry-date (generic function)
(setf expiry-date) (generic function)
:uids
uids (generic function)
(setf uids) (generic function)
:fingerprint
fingerprint (generic function)
(setf fingerprint) (generic function)
:keygrip
keygrip (generic function)
(setf keygrip) (generic function)
The file is automatically crypted and decrypted using the
specified recipient key.
The ’.lisp.gpg’ extension is automatically added if missing.
nfiles.lisp (file)
gpg.lisp (file)
standard-object (class)
:validity
validity (generic function)
(setf validity) (generic function)
:user-id
user-id (generic function)
(setf user-id) (generic function)
Like regular ‘file’ but assume a ‘.lisp’ extension, even if not provided.
nfiles.lisp (file)
file (class)
gpg-lisp-file (class)
This is the default profile.
Subclass this profile to make your own, possibly carrying more data.
‘file’ path expansion is specialized against its ‘profile’ slot throught the ‘resolve’ method.
nfiles.lisp (file)
standard-object (class)
read-only-profile (class)
The name of the profile to refer it with.
string
:name
"default"
name (generic function)
(setf name) (generic function)
File that’s not written to on change.
Note that the file’s ‘content’ can still be modified in-memory.
nfiles.lisp (file)
file (class)
virtual-file (class)
In this profile, files by default don’t get written to.
nfiles.lisp (file)
profile (class)
virtual-profile (class)
Like regular ‘file’ but set directory to ‘uiop:xdg-runtime-dir’
nfiles.lisp (file)
file (class)
resolve (method)
File that’s not read nor written to. It’s meant to handle data
in-memory.
Note that if multiple ‘virtual-file’ expand to the same path, they share the
same content.
To disable content-sharing for specific ‘file’, have their ‘resolve’ method return ‘uiop:*nil-pathname*’.
nfiles.lisp (file)
read-only-file (class)
In this profile, files are neither read nor written to by default.
nfiles.lisp (file)
read-only-profile (class)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal constants | ||
• Internal special variables | ||
• Internal macros | ||
• Internal functions | ||
• Internal generic functions | ||
• Internal classes |
Next: Internal special variables, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
pathname-helpers.lisp (file)
Next: Internal macros, Previous: Internal constants, Up: Internal definitions [Contents][Index]
Internal ‘*cache*’ associating expanded paths with a dedicated ‘cache-entry’.
nfiles.lisp (file)
Set of all ‘file’s objects.
It’s a weak hash table to that garbage-collected files are automatically
removed.
nfiles.lisp (file)
Time in seconds to wait for other write requests.
nfiles.lisp (file)
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
nfiles.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
Call RESTART if valid.
nfiles.lisp (file)
Files that expand to ‘uiop:*nil-pathname*’ have their own cache entry.
nfiles.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
Like ‘call-with-open-file’ but use ‘gpg’ to read and write to file.
OPTIONS are as for ‘open”s ‘:direction’.
Other options are not supported. File is overwritten if it exists, while
nothing is done if file is missing.
gpg.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
Decrement the semaphore counter down to 0.
Return the number of decrements, or NIL if there was none.
nfiles.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
gpg.lisp (file)
nfiles.lisp (file)
Return the key of FILE’s recipient if any, ‘*gpg-default-recipient*’ otherwise.
As second value the email.
As third value the name.
gpg.lisp (file)
gpg.lisp (file)
Write STREAM to GPG-FILE using RECIPIENT key. If RECIPIENT is not provided, use default key.
gpg.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
Return the list of sections as a list of strings.
gpg.lisp (file)
nfiles.lisp (file)
PROMPT takes no trailing colon nor trailing space.
gpg.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
Like ‘uiop:run-program’ but raise a ‘nfiles:process-error’ on error.
gpg.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
nfiles.lisp (file)
Next: Internal classes, Previous: Internal functions, Up: Internal definitions [Contents][Index]
automatically generated reader method
nfiles.lisp (file)
automatically generated writer method
nfiles.lisp (file)
The date at which the cache entry was last updated.
nfiles.lisp (file)
This is the ‘file’ object that was used to instantiate the entry’s ‘cached-value’.
nfiles.lisp (file)
automatically generated reader method
nfiles.lisp (file)
automatically generated writer method
nfiles.lisp (file)
automatically generated reader method
nfiles.lisp (file)
automatically generated writer method
nfiles.lisp (file)
Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
nfiles.lisp (file)
standard-object (class)
This is the ‘file’ object that was used to instantiate the entry’s ‘cached-value’.
nfiles:file
:source-file
(error "source file must be given.")
source-file (generic function)
(setf source-file) (generic function)
The date at which the cache entry was last updated.
integer
:last-update
(get-universal-time)
last-update (generic function)
(setf last-update) (generic function)
:cached-value
cached-value (generic function)
(setf cached-value) (generic function)
(or null bordeaux-threads:thread)
:worker
worker (generic function)
(setf worker) (generic function)
(or null bordeaux-threads:semaphore)
:worker-notifier
worker-notifier (generic function)
(setf worker-notifier) (generic function)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | F L N |
---|
Jump to: | F L N |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | (
A B C D E F G K L M N O P R S U V W |
---|
Jump to: | (
A B C D E F G K L M N O P R S U V W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | *
+
A B C E F K L M N O P R S U V W |
---|
Jump to: | *
+
A B C E F K L M N O P R S U V W |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | C D E F G L N P R S V |
---|
Jump to: | C D E F G L N P R S V |
---|