The nfiles Reference Manual

Table of Contents

The nfiles Reference Manual

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.

1 Systems

The main system appears first, followed by any subsystem dependency.

1.1 nfiles

Author

Atlas Engineer LLC

Home Page

https://github.com/atlas-engineer/nfiles

License

BSD 3-Clause

Description

Manage file persistence and loading.

Version

0.2.2

Dependencies

• alexandria
• hu.dwim.defclass-star
• serapeum
• trivial-garbage
• trivial-package-local-nicknames
• trivial-types

Source

nfiles.asd (file)

Components

• package.lisp (file)
• conditions.lisp (file)
• pathname-helpers.lisp (file)
• gpg.lisp (file)
• nfiles.lisp (file)

2 Files

Files are sorted by type and then listed depth-first from the systems components trees.

2.1 Lisp

2.1.1 nfiles.asd

Location

nfiles.asd

Systems

nfiles (system)

2.1.2 nfiles/package.lisp

Parent

nfiles (system)

Location

package.lisp

Packages

• nfiles
• nfiles/gpg

2.1.3 nfiles/conditions.lisp

Parent

nfiles (system)

Location

conditions.lisp

Exported Definitions

• external-modification (condition)
• process-error (condition)

2.1.4 nfiles/pathname-helpers.lisp

Parent

nfiles (system)

Location

pathname-helpers.lisp

Exported Definitions

• file-group (function)
• (setf file-group) (function)
• file-user (function)
• (setf file-user) (function)
• nil-pathname-p (function)
• parent (function)
• pathname-type* (function)
• permissions (function)
• (setf permissions) (function)

Internal Definitions

+permissions+ (constant)

2.1.5 nfiles/gpg.lisp

Parent

nfiles (system)

Location

gpg.lisp

Exported Definitions

• *gpg-default-recipient* (special variable)
• *gpg-program* (special variable)
• algorithm (method)
• (setf algorithm) (method)
• creation-date (method)
• (setf creation-date) (method)
• expiry-date (method)
• (setf expiry-date) (method)
• fingerprint (method)
• (setf fingerprint) (method)
• gpg-key (class)
• gpg-private-keys (function)
• gpg-uid (class)
• key-id (method)
• (setf key-id) (method)
• key-length (method)
• (setf key-length) (method)
• keygrip (method)
• (setf keygrip) (method)
• uids (method)
• (setf uids) (method)
• user-id (method)
• (setf user-id) (method)
• validity (method)
• (setf validity) (method)
• with-gpg-file (macro)

Internal Definitions

• call-with-gpg-file (function)
• gpg-key-p (function)
• gpg-recipient (function)
• gpg-uid-p (function)
• gpg-write (function)
• parse-gpg-secret-keys-output (function)
• read-new-value (function)
• run-program* (function)

2.1.6 nfiles/nfiles.lisp

Parent

nfiles (system)

Location

nfiles.lisp

Exported Definitions

• *default-profile* (special variable)
• all-files (function)
• backup (function)
• base-path (method)
• cache-file (class)
• config-file (class)
• content (function)
• (setf content) (function)
• data-file (class)
• deserialize (generic function)
• deserialize (method)
• deserialize (method)
• deserialize (method)
• deserialize (method)
• deserialize (method)
• expand (function)
• file (class)
• gpg-file (class)
• gpg-lisp-file (class)
• lisp-file (class)
• name (method)
• (setf name) (method)
• name (method)
• (setf name) (method)
• on-deserialization-error (method)
• (setf on-deserialization-error) (method)
• on-external-modification (method)
• (setf on-external-modification) (method)
• on-read-error (method)
• (setf on-read-error) (method)
• profile (method)
• profile (class)
• read-file (generic function)
• read-file (method)
• read-file (method)
• read-file (method)
• read-file (method)
• read-file (method)
• read-handler (method)
• (setf read-handler) (method)
• read-only-file (class)
• read-only-profile (class)
• resolve (generic function)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• runtime-file (class)
• serialize (generic function)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• virtual-file (class)
• virtual-profile (class)
• with-file-content (macro)
• with-paths (macro)
• write-file (generic function)
• write-file (method)
• write-file (method)
• write-file (method)
• write-file (method)
• write-file (method)
• write-handler (method)
• (setf write-handler) (method)

Internal Definitions

• *cache* (special variable)
• *index* (special variable)
• *timeout* (special variable)
• auto-restarter (function)
• cache-entry (function)
• cache-entry (class)
• cache-entry-p (function)
• cache-file-p (function)
• cached-value (method)
• (setf cached-value) (method)
• clear-cache (function)
• config-file-p (function)
• data-file-p (function)
• drain-semaphore (function)
• expand-user-home (function)
• file-key (function)
• filep (function)
• gpg-file-p (function)
• gpg-lisp-file-p (function)
• last-update (method)
• (setf last-update) (method)
• lisp-file-p (function)
• maybe-xdg (function)
• profilep (function)
• read-only-file-p (function)
• read-only-profile-p (function)
• run-thread (macro)
• runtime-file-p (function)
• source-file (method)
• (setf source-file) (method)
• virtual-file-p (function)
• virtual-profile-p (function)
• worker (method)
• (setf worker) (method)
• worker-notifier (method)
• (setf worker-notifier) (method)
• worker-write (function)
• write-cache-entry (function)

3 Packages

Packages are listed by definition order.

3.1 nfiles

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.

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• *default-profile* (special variable)
• all-files (function)
• backup (function)
• base-path (generic function)
• base-path (method)
• cache-file (class)
• config-file (class)
• content (function)
• (setf content) (function)
• data-file (class)
• deserialize (generic function)
• deserialize (method)
• deserialize (method)
• deserialize (method)
• deserialize (method)
• deserialize (method)
• expand (function)
• external-modification (condition)
• file (class)
• file-group (function)
• (setf file-group) (function)
• file-user (function)
• (setf file-user) (function)
• gpg-file (class)
• gpg-lisp-file (class)
• lisp-file (class)
• name (generic function)
• name (method)
• (setf name) (method)
• name (method)
• (setf name) (method)
• (setf name) (generic function)
• nil-pathname-p (function)
• on-deserialization-error (generic function)
• on-deserialization-error (method)
• (setf on-deserialization-error) (method)
• (setf on-deserialization-error) (generic function)
• on-external-modification (generic function)
• on-external-modification (method)
• (setf on-external-modification) (method)
• (setf on-external-modification) (generic function)
• on-read-error (generic function)
• on-read-error (method)
• (setf on-read-error) (method)
• (setf on-read-error) (generic function)
• parent (function)
• pathname-type* (function)
• permissions (function)
• (setf permissions) (function)
• process-error (condition)
• profile (generic function)
• profile (method)
• profile (class)
• read-file (generic function)
• read-file (method)
• read-file (method)
• read-file (method)
• read-file (method)
• read-file (method)
• read-handler (generic function)
• read-handler (method)
• (setf read-handler) (method)
• (setf read-handler) (generic function)
• read-only-file (class)
• read-only-profile (class)
• resolve (generic function)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• runtime-file (class)
• serialize (generic function)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• virtual-file (class)
• virtual-profile (class)
• with-file-content (macro)
• with-paths (macro)
• write-file (generic function)
• write-file (method)
• write-file (method)
• write-file (method)
• write-file (method)
• write-file (method)
• write-handler (generic function)
• write-handler (method)
• (setf write-handler) (method)
• (setf write-handler) (generic function)

Internal Definitions

• *cache* (special variable)
• *index* (special variable)
• *timeout* (special variable)
• +permissions+ (constant)
• auto-restarter (function)
• cache-entry (function)
• cache-entry (class)
• cache-entry-p (function)
• cache-file-p (function)
• cached-value (generic function)
• cached-value (method)
• (setf cached-value) (method)
• (setf cached-value) (generic function)
• clear-cache (function)
• config-file-p (function)
• data-file-p (function)
• drain-semaphore (function)
• expand-user-home (function)
• file-key (function)
• filep (function)
• gpg-file-p (function)
• gpg-lisp-file-p (function)
• last-update (generic function)
• last-update (method)
• (setf last-update) (method)
• (setf last-update) (generic function)
• lisp-file-p (function)
• maybe-xdg (function)
• profilep (function)
• read-only-file-p (function)
• read-only-profile-p (function)
• run-thread (macro)
• runtime-file-p (function)
• source-file (generic function)
• source-file (method)
• (setf source-file) (method)
• (setf source-file) (generic function)
• virtual-file-p (function)
• virtual-profile-p (function)
• worker (generic function)
• worker (method)
• (setf worker) (method)
• (setf worker) (generic function)
• worker-notifier (generic function)
• worker-notifier (method)
• (setf worker-notifier) (method)
• (setf worker-notifier) (generic function)
• worker-write (function)
• write-cache-entry (function)

3.2 nfiles/gpg

A thin wrapper around the GPG command line tool.

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• *gpg-default-recipient* (special variable)
• *gpg-program* (special variable)
• algorithm (generic function)
• algorithm (method)
• (setf algorithm) (method)
• (setf algorithm) (generic function)
• creation-date (generic function)
• creation-date (method)
• (setf creation-date) (method)
• (setf creation-date) (generic function)
• expiry-date (generic function)
• expiry-date (method)
• (setf expiry-date) (method)
• (setf expiry-date) (generic function)
• fingerprint (generic function)
• fingerprint (method)
• (setf fingerprint) (method)
• (setf fingerprint) (generic function)
• gpg-key (class)
• gpg-private-keys (function)
• gpg-uid (class)
• key-id (generic function)
• key-id (method)
• (setf key-id) (method)
• (setf key-id) (generic function)
• key-length (generic function)
• key-length (method)
• (setf key-length) (method)
• (setf key-length) (generic function)
• keygrip (generic function)
• keygrip (method)
• (setf keygrip) (method)
• (setf keygrip) (generic function)
• uids (generic function)
• uids (method)
• (setf uids) (method)
• (setf uids) (generic function)
• user-id (generic function)
• user-id (method)
• (setf user-id) (method)
• (setf user-id) (generic function)
• validity (generic function)
• validity (method)
• (setf validity) (method)
• (setf validity) (generic function)
• with-gpg-file (macro)

Internal Definitions

• call-with-gpg-file (function)
• gpg-key-p (function)
• gpg-recipient (function)
• gpg-uid-p (function)
• gpg-write (function)
• parse-gpg-secret-keys-output (function)
• read-new-value (function)
• run-program* (function)

4 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

4.1 Exported definitions

4.1.1 Special variables

Special Variable: *default-profile*

Package

nfiles

Source

nfiles.lisp (file)

Special Variable: *gpg-default-recipient*

Package

nfiles/gpg

Source

gpg.lisp (file)

Special Variable: *gpg-program*

Package

nfiles/gpg

Source

gpg.lisp (file)

4.1.2 Macros

Macro: with-file-content (CONTENT FILE &key DEFAULT) &body BODY

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.

Package

nfiles

Source

nfiles.lisp (file)

Macro: with-gpg-file (VAR PATHNAME &rest KEYS) &body BODY

Trivial wrapper around ‘call-with-gpg-file’.

Package

nfiles/gpg

Source

gpg.lisp (file)

Macro: with-paths BINDINGS &body BODY

Bind let-style BINDINGS to ‘file’ path expansions, then run BODY if all these paths or non-nil after ‘nil-pathname-p’.

Package

nfiles

Source

nfiles.lisp (file)

4.1.3 Functions

Function: all-files &rest PACKAGES

Return all instantiated ‘file’ objects belong to PACKAGES. If no package is specified, return all ‘file’ objects.

Package

nfiles

Source

nfiles.lisp (file)

Function: backup PATH

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.

Package

nfiles

Source

nfiles.lisp (file)

Function: content FILE &key FORCE-READ WAIT-P

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.

Package

nfiles

Source

nfiles.lisp (file)

Writer

(setf content) (function)

Function: (setf content) VALUE FILE

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.

Package

nfiles

Source

nfiles.lisp (file)

Reader

content (function)

Function: expand FILE

Return the pathname corresponding to FILE and its ‘profile’.
It’s a convenience wrapper around ‘resolve’ (to avoid specifying the ‘profile’).

Package

nfiles

Source

nfiles.lisp (file)

Function: file-group PATH

Return PATH group name.

Package

nfiles

Source

pathname-helpers.lisp (file)

Writer

(setf file-group) (function)

Function: (setf file-group) NEW-GROUP PATH

Set PATH group to NEW-GROUP (a string).

Package

nfiles

Source

pathname-helpers.lisp (file)

Reader

file-group (function)

Function: file-user PATH

Return PATH owner name.

Package

nfiles

Source

pathname-helpers.lisp (file)

Writer

(setf file-user) (function)

Function: (setf file-user) NEW-USER PATH

Set PATH owner to NEW-USER (a string).

Package

nfiles

Source

pathname-helpers.lisp (file)

Reader

file-user (function)

Function: gpg-private-keys ()

Return list of private ‘gpg-key’s.

Package

nfiles/gpg

Source

gpg.lisp (file)

Function: nil-pathname-p PATHNAME

Return non-nil if PATHNAME is ‘uiop:*nil-pathname*’ or nil.

Package

nfiles

Source

pathname-helpers.lisp (file)

Function: parent PATH

Return the parent directory of PATH.

Package

nfiles

Source

pathname-helpers.lisp (file)

Function: pathname-type* PATHNAME

Like ‘pathname-type’ but return NIL instead of "" or :UNSPECIFIC.

Package

nfiles

Source

pathname-helpers.lisp (file)

Function: permissions PATH

Return a list of permissions as per ‘+permissions+’.

Package

nfiles

Source

pathname-helpers.lisp (file)

Writer

(setf permissions) (function)

Function: (setf permissions) PERMISSIONS PATH

Set the PERMISSIONS or PATH as per ‘+permissions+’.

Package

nfiles

Source

pathname-helpers.lisp (file)

Reader

permissions (function)

4.1.4 Generic functions

Generic Function: algorithm OBJECT

Generic Function: (setf algorithm) NEW-VALUE OBJECT

Package

nfiles/gpg

Methods

Method: algorithm (GPG-KEY gpg-key)

automatically generated reader method

Source

gpg.lisp (file)

Method: (setf algorithm) NEW-VALUE (GPG-KEY gpg-key)

automatically generated writer method

Source

gpg.lisp (file)

Generic Function: base-path OBJECT

Package

nfiles

Methods

Method: base-path (FILE file)

The pathname used by the ‘resolve’ method to yield the final path.

Source

nfiles.lisp (file)

Generic Function: creation-date OBJECT

Generic Function: (setf creation-date) NEW-VALUE OBJECT

Package

nfiles/gpg

Methods

Method: creation-date (GPG-KEY gpg-key)

Method: (setf creation-date) NEW-VALUE (GPG-KEY gpg-key)

Stored as in Unix format.

Source

gpg.lisp (file)

Generic Function: deserialize PROFILE FILE STREAM &key &allow-other-keys

Transform STREAM into a useful form ready to be manipulated on the Lisp side. See ‘serialize’ for the reverse action.

Package

nfiles

Source

nfiles.lisp (file)

Methods

Method: deserialize (PROFILE virtual-profile) (FILE file) STREAM &key

Method: deserialize (PROFILE profile) (FILE virtual-file) STREAM &key

Method: deserialize (PROFILE profile) (FILE lisp-file) STREAM &key

Method: deserialize (PROFILE profile) (FILE file) STREAM &key around

Don’t try deserialize if there is no file.
Handle errors gracefully. See ‘on-deserialization-error’.

Method: deserialize (PROFILE profile) (FILE file) STREAM &key

Generic Function: expiry-date OBJECT

Generic Function: (setf expiry-date) NEW-VALUE OBJECT

Package

nfiles/gpg

Methods

Method: expiry-date (GPG-KEY gpg-key)

Method: (setf expiry-date) NEW-VALUE (GPG-KEY gpg-key)

Stored as in Unix format.

Source

gpg.lisp (file)

Generic Function: fingerprint OBJECT

Generic Function: (setf fingerprint) NEW-VALUE OBJECT

Package

nfiles/gpg

Methods

Method: fingerprint (GPG-KEY gpg-key)

automatically generated reader method

Source

gpg.lisp (file)

Method: (setf fingerprint) NEW-VALUE (GPG-KEY gpg-key)

automatically generated writer method

Source

gpg.lisp (file)

Generic Function: key-id OBJECT

Generic Function: (setf key-id) NEW-VALUE OBJECT

Package

nfiles/gpg

Methods

Method: key-id (GPG-KEY gpg-key)

automatically generated reader method

Source

gpg.lisp (file)

Method: (setf key-id) NEW-VALUE (GPG-KEY gpg-key)

automatically generated writer method

Source

gpg.lisp (file)

Generic Function: key-length OBJECT

Generic Function: (setf key-length) NEW-VALUE OBJECT

Package

nfiles/gpg

Methods

Method: key-length (GPG-KEY gpg-key)

automatically generated reader method

Source

gpg.lisp (file)

Method: (setf key-length) NEW-VALUE (GPG-KEY gpg-key)

automatically generated writer method

Source

gpg.lisp (file)

Generic Function: keygrip OBJECT

Generic Function: (setf keygrip) NEW-VALUE OBJECT

Package

nfiles/gpg

Methods

Method: keygrip (GPG-KEY gpg-key)

automatically generated reader method

Source

gpg.lisp (file)

Method: (setf keygrip) NEW-VALUE (GPG-KEY gpg-key)

automatically generated writer method

Source

gpg.lisp (file)

Generic Function: name OBJECT

Generic Function: (setf name) NEW-VALUE OBJECT

Package

nfiles

Methods

Method: name (FILE file)

Method: (setf name) NEW-VALUE (FILE file)

Name used to identify the object in a human-readable manner.

Source

nfiles.lisp (file)

Method: name (PROFILE profile)

Method: (setf name) NEW-VALUE (PROFILE profile)

The name of the profile to refer it with.

Source

nfiles.lisp (file)

Generic Function: on-deserialization-error OBJECT

Generic Function: (setf on-deserialization-error) NEW-VALUE OBJECT

Package

nfiles

Methods

Method: on-deserialization-error (FILE file)

Method: (setf on-deserialization-error) NEW-VALUE (FILE 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.

Source

nfiles.lisp (file)

Generic Function: on-external-modification OBJECT

Generic Function: (setf on-external-modification) NEW-VALUE OBJECT

Package

nfiles

Methods

Method: on-external-modification (FILE file)

Method: (setf on-external-modification) NEW-VALUE (FILE file)

Whether to reload or overwrite the file if it was modified since it was last loaded.

Source

nfiles.lisp (file)

Generic Function: on-read-error OBJECT

Generic Function: (setf on-read-error) NEW-VALUE OBJECT

Package

nfiles

Methods

Method: on-read-error (FILE file)

Method: (setf on-read-error) NEW-VALUE (FILE file)

What to do on file read error.
See ‘on-deserialization-error’ for the meaning of the different actions.

Source

nfiles.lisp (file)

Generic Function: profile OBJECT

Package

nfiles

Methods

Method: profile (FILE file)

The ‘profile’ of the ‘file’.
File expansion is performed against it. The profile is only set at instantiation time.

Source

nfiles.lisp (file)

Generic Function: read-file PROFILE FILE &key &allow-other-keys

Load FILE by calling ‘deserialize’ on a stream opened on the file. See ‘write-file’ for the reverse action.

Package

nfiles

Source

nfiles.lisp (file)

Methods

Method: read-file (PROFILE virtual-profile) (FILE file) &key

Don’t load anything when using the ‘virtual-profile’.

Method: read-file (PROFILE profile) (FILE virtual-file) &key

Don’t load anything for virtual files.

Method: read-file (PROFILE profile) (FILE gpg-file) &key

Decrypt FILE with GPG and return resulting stream. See ‘*gpg-default-recipient*’.

Method: read-file (PROFILE profile) (FILE file) &key

Open FILE and call ‘deserialize’ on its content.

Method: read-file (PROFILE profile) (FILE file) &key around

Don’t try to load the file if it does not exist.

Generic Function: read-handler OBJECT

Generic Function: (setf read-handler) NEW-VALUE OBJECT

Package

nfiles

Methods

Method: read-handler (FILE file)

Method: (setf read-handler) NEW-VALUE (FILE file)

Function of one argument, the condition that may be raised in the reader thread.

Source

nfiles.lisp (file)

Generic Function: resolve PROFILE 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.

Package

nfiles

Source

nfiles.lisp (file)

Methods

Method: resolve (PROFILE profile) (FILE runtime-file)

Method: resolve (PROFILE profile) (FILE data-file)

Method: resolve (PROFILE profile) (FILE cache-file)

Method: resolve (PROFILE profile) (FILE config-file)

Method: resolve (PROFILE profile) (FILE gpg-file)

Method: resolve (PROFILE profile) (FILE lisp-file)

Method: resolve (PROFILE profile) (FILE file) around

Clean up the result before returning it.

Method: resolve (PROFILE profile) (FILE file)

Generic Function: serialize PROFILE FILE STREAM &key &allow-other-keys

Transform ‘file’ content meant to
be persisted to a file.

See ‘deserialize’ for the reverse action.

Package

nfiles

Source

nfiles.lisp (file)

Methods

Method: serialize (PROFILE read-only-profile) (FILE file) STREAM &key

Method: serialize (PROFILE profile) (FILE read-only-file) STREAM &key

Method: serialize (PROFILE profile) (FILE lisp-file) STREAM &key

Method: serialize (PROFILE profile) (FILE file) STREAM &key around

Method: serialize (PROFILE profile) (FILE file) STREAM &key

Generic Function: uids OBJECT

Generic Function: (setf uids) NEW-VALUE OBJECT

Package

nfiles/gpg

Methods

Method: uids (GPG-KEY gpg-key)

automatically generated reader method

Source

gpg.lisp (file)

Method: (setf uids) NEW-VALUE (GPG-KEY gpg-key)

automatically generated writer method

Source

gpg.lisp (file)

Generic Function: user-id OBJECT

Generic Function: (setf user-id) NEW-VALUE OBJECT

Package

nfiles/gpg

Methods

Method: user-id (GPG-UID gpg-uid)

automatically generated reader method

Source

gpg.lisp (file)

Method: (setf user-id) NEW-VALUE (GPG-UID gpg-uid)

automatically generated writer method

Source

gpg.lisp (file)

Generic Function: validity OBJECT

Generic Function: (setf validity) NEW-VALUE OBJECT

Package

nfiles/gpg

Methods

Method: validity (GPG-UID gpg-uid)

automatically generated reader method

Source

gpg.lisp (file)

Method: (setf validity) NEW-VALUE (GPG-UID gpg-uid)

automatically generated writer method

Source

gpg.lisp (file)

Generic Function: write-file PROFILE FILE &key DESTINATION &allow-other-keys

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.

Package

nfiles

Source

nfiles.lisp (file)

Methods

Method: write-file (PROFILE read-only-profile) (FILE file) &key DESTINATION

Don’t write anything when using the ‘read-only-profile’.

Method: write-file (PROFILE profile) (FILE read-only-file) &key DESTINATION

Don’t write anything for ‘read-only-file’.

Method: write-file (PROFILE profile) (FILE gpg-file) &key DESTINATION

Crypt to FILE with GPG. See ‘*gpg-default-recipient*’.

Method: write-file (PROFILE profile) (FILE file) &key DESTINATION

Write the result of ‘serialize’ to the ‘file’ path.

Method: write-file (PROFILE profile) (FILE file) &key DESTINATION around

Generic Function: write-handler OBJECT

Generic Function: (setf write-handler) NEW-VALUE OBJECT

Package

nfiles

Methods

Method: write-handler (FILE file)

Method: (setf write-handler) NEW-VALUE (FILE file)

Function of one argument, the condition that may be raised in the writer thread.

Source

nfiles.lisp (file)

4.1.5 Conditions

Condition: external-modification ()

Package

nfiles

Source

conditions.lisp (file)

Direct superclasses

error (condition)

Direct slots

Slot: path

Initargs

:path

Condition: process-error ()

Package

nfiles

Source

conditions.lisp (file)

Direct superclasses

subprocess-error (condition)

Direct slots

Slot: message

Initargs

:message

4.1.6 Classes

Class: cache-file ()

Like regular ‘file’ but set directory to ‘uiop:xdg-cache-home’

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

file (class)

Direct methods

resolve (method)

Class: config-file ()

Like regular ‘file’ but set directory to ‘uiop:xdg-config-home’.

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

file (class)

Direct methods

resolve (method)

Class: data-file ()

Like regular ‘file’ but set directory to ‘uiop:xdg-data-home’

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

file (class)

Direct methods

resolve (method)

Class: file ()

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.

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• lisp-file (class)
• config-file (class)
• cache-file (class)
• data-file (class)
• runtime-file (class)
• gpg-file (class)
• read-only-file (class)

Direct methods

• read-file (method)
• read-file (method)
• read-file (method)
• write-file (method)
• write-file (method)
• write-file (method)
• serialize (method)
• serialize (method)
• serialize (method)
• deserialize (method)
• deserialize (method)
• deserialize (method)
• resolve (method)
• resolve (method)
• initialize-instance (method)
• on-read-error (method)
• on-read-error (method)
• on-deserialization-error (method)
• on-deserialization-error (method)
• on-external-modification (method)
• on-external-modification (method)
• write-handler (method)
• write-handler (method)
• read-handler (method)
• read-handler (method)
• name (method)
• name (method)
• profile (method)
• base-path (method)

Direct slots

Slot: base-path

The pathname used by the ‘resolve’ method to yield the final path.

Type

pathname

Initform

#p"."

Readers

base-path (generic function)

Slot: profile

The ‘profile’ of the ‘file’.
File expansion is performed against it. The profile is only set at instantiation time.

Type

nfiles:profile

Initargs

:profile

Initform

nfiles:*default-profile*

Readers

profile (generic function)

Slot: name

Name used to identify the object in a human-readable manner.

Type

string

Initargs

:name

Initform

""

Readers

name (generic function)

Writers

(setf name) (generic function)

Slot: read-handler

Function of one argument, the condition that may be raised in the reader thread.

Type

trivial-types:function-designator

Initargs

:read-handler

Initform

(function identity)

Readers

read-handler (generic function)

Writers

(setf read-handler) (generic function)

Slot: write-handler

Function of one argument, the condition that may be raised in the writer thread.

Type

trivial-types:function-designator

Initargs

:write-handler

Initform

(function identity)

Readers

write-handler (generic function)

Writers

(setf write-handler) (generic function)

Slot: on-external-modification

Whether to reload or overwrite the file if it was modified since it was last loaded.

Type

(member nfiles:ask nfiles:reload nfiles:overwrite)

Initargs

:on-external-modification

Initform

(quote nfiles:ask)

Readers

on-external-modification (generic function)

Writers

(setf on-external-modification) (generic function)

Slot: on-deserialization-error

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.

Type

(member nfiles:ask nfiles:backup delete)

Initargs

:on-deserialization-error

Initform

(quote nfiles:ask)

Readers

on-deserialization-error (generic function)

Writers

(setf on-deserialization-error) (generic function)

Slot: on-read-error

What to do on file read error.
See ‘on-deserialization-error’ for the meaning of the different actions.

Type

(member nfiles:ask nfiles:backup delete)

Initargs

:on-read-error

Initform

(quote nfiles:ask)

Readers

on-read-error (generic function)

Writers

(setf on-read-error) (generic function)

Class: gpg-file ()

The file is automatically crypted and decrypted using the specified recipient key.
The ’.gpg’ extension is automatically added if missing.

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

file (class)

Direct subclasses

gpg-lisp-file (class)

Direct methods

• read-file (method)
• write-file (method)
• resolve (method)

Class: gpg-key ()

Package

nfiles/gpg

Source

gpg.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• keygrip (method)
• keygrip (method)
• fingerprint (method)
• fingerprint (method)
• uids (method)
• uids (method)
• expiry-date (method)
• expiry-date (method)
• creation-date (method)
• creation-date (method)
• key-id (method)
• key-id (method)
• algorithm (method)
• algorithm (method)
• key-length (method)
• key-length (method)

Direct slots

Slot: key-length

Initargs

:key-length

Readers

key-length (generic function)

Writers

(setf key-length) (generic function)

Slot: algorithm

Initargs

:algorithm

Readers

algorithm (generic function)

Writers

(setf algorithm) (generic function)

Slot: key-id

Initargs

:key-id

Readers

key-id (generic function)

Writers

(setf key-id) (generic function)

Slot: creation-date

Stored as in Unix format.

Initargs

:creation-date

Readers

creation-date (generic function)

Writers

(setf creation-date) (generic function)

Slot: expiry-date

Stored as in Unix format.

Initargs

:expiry-date

Readers

expiry-date (generic function)

Writers

(setf expiry-date) (generic function)

Slot: uids

Initargs

:uids

Readers

uids (generic function)

Writers

(setf uids) (generic function)

Slot: fingerprint

Initargs

:fingerprint

Readers

fingerprint (generic function)

Writers

(setf fingerprint) (generic function)

Slot: keygrip

Initargs

:keygrip

Readers

keygrip (generic function)

Writers

(setf keygrip) (generic function)

Class: gpg-lisp-file ()

The file is automatically crypted and decrypted using the specified recipient key.
The ’.lisp.gpg’ extension is automatically added if missing.

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

• lisp-file (class)
• gpg-file (class)

Class: gpg-uid ()

Package

nfiles/gpg

Source

gpg.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• user-id (method)
• user-id (method)
• validity (method)
• validity (method)

Direct slots

Slot: validity

Initargs

:validity

Readers

validity (generic function)

Writers

(setf validity) (generic function)

Slot: user-id

Initargs

:user-id

Readers

user-id (generic function)

Writers

(setf user-id) (generic function)

Class: lisp-file ()

Like regular ‘file’ but assume a ‘.lisp’ extension, even if not provided.

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

file (class)

Direct subclasses

gpg-lisp-file (class)

Direct methods

• serialize (method)
• deserialize (method)
• resolve (method)

Class: profile ()

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.

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

read-only-profile (class)

Direct methods

• read-file (method)
• read-file (method)
• read-file (method)
• read-file (method)
• write-file (method)
• write-file (method)
• write-file (method)
• write-file (method)
• serialize (method)
• serialize (method)
• serialize (method)
• serialize (method)
• deserialize (method)
• deserialize (method)
• deserialize (method)
• deserialize (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• resolve (method)
• name (method)
• name (method)

Direct slots

Slot: name

The name of the profile to refer it with.

Type

string

Initargs

:name

Initform

"default"

Readers

name (generic function)

Writers

(setf name) (generic function)

Class: read-only-file ()

File that’s not written to on change.
Note that the file’s ‘content’ can still be modified in-memory.

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

file (class)

Direct subclasses

virtual-file (class)

Direct methods

• write-file (method)
• serialize (method)

Class: read-only-profile ()

In this profile, files by default don’t get written to.

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

profile (class)

Direct subclasses

virtual-profile (class)

Direct methods

• write-file (method)
• serialize (method)

Class: runtime-file ()

Like regular ‘file’ but set directory to ‘uiop:xdg-runtime-dir’

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

file (class)

Direct methods

resolve (method)

Class: virtual-file ()

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*’.

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

read-only-file (class)

Direct methods

• read-file (method)
• deserialize (method)

Class: virtual-profile ()

In this profile, files are neither read nor written to by default.

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

read-only-profile (class)

Direct methods

• read-file (method)
• deserialize (method)

4.2 Internal definitions

4.2.1 Constants

Constant: +permissions+

Package

nfiles

Source

pathname-helpers.lisp (file)

4.2.2 Special variables

Special Variable: *cache*

Internal ‘*cache*’ associating expanded paths with a dedicated ‘cache-entry’.

Package

nfiles

Source

nfiles.lisp (file)

Special Variable: *index*

Set of all ‘file’s objects.
It’s a weak hash table to that garbage-collected files are automatically removed.

Package

nfiles

Source

nfiles.lisp (file)

Special Variable: *timeout*

Time in seconds to wait for other write requests.

Package

nfiles

Source

nfiles.lisp (file)

4.2.3 Macros

Macro: run-thread NAME HANDLER &body BODY

Package

nfiles

Source

nfiles.lisp (file)

4.2.4 Functions

Function: auto-restarter RESTART

Call RESTART if valid.

Package

nfiles

Source

nfiles.lisp (file)

Function: cache-entry FILE &optional FORCE-READ

Files that expand to ‘uiop:*nil-pathname*’ have their own cache entry.

Package

nfiles

Source

nfiles.lisp (file)

Function: cache-entry-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: cache-file-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: call-with-gpg-file GPG-FILE OPTIONS FUN

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.

Package

nfiles/gpg

Source

gpg.lisp (file)

Function: clear-cache ()

Package

nfiles

Source

nfiles.lisp (file)

Function: config-file-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: data-file-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: drain-semaphore SEMAPHORE &optional TIMEOUT

Decrement the semaphore counter down to 0.
Return the number of decrements, or NIL if there was none.

Package

nfiles

Source

nfiles.lisp (file)

Function: expand-user-home STRING

Package

nfiles

Source

nfiles.lisp (file)

Function: file-key FILE

Package

nfiles

Source

nfiles.lisp (file)

Function: filep OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: gpg-file-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: gpg-key-p OBJECT

Package

nfiles/gpg

Source

gpg.lisp (file)

Function: gpg-lisp-file-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: gpg-recipient FILE

Return the key of FILE’s recipient if any, ‘*gpg-default-recipient*’ otherwise. As second value the email.
As third value the name.

Package

nfiles/gpg

Source

gpg.lisp (file)

Function: gpg-uid-p OBJECT

Package

nfiles/gpg

Source

gpg.lisp (file)

Function: gpg-write STREAM GPG-FILE &optional RECIPIENT

Write STREAM to GPG-FILE using RECIPIENT key. If RECIPIENT is not provided, use default key.

Package

nfiles/gpg

Source

gpg.lisp (file)

Function: lisp-file-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: maybe-xdg XDG-FUN PATH

Package

nfiles

Source

nfiles.lisp (file)

Function: parse-gpg-secret-keys-output OUTPUT-STRING

Return the list of sections as a list of strings.

Package

nfiles/gpg

Source

gpg.lisp (file)

Function: profilep OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: read-new-value PROMPT

PROMPT takes no trailing colon nor trailing space.

Package

nfiles/gpg

Source

gpg.lisp (file)

Function: read-only-file-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: read-only-profile-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: run-program* COMMAND &key INPUT

Like ‘uiop:run-program’ but raise a ‘nfiles:process-error’ on error.

Package

nfiles/gpg

Source

gpg.lisp (file)

Function: runtime-file-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: virtual-file-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: virtual-profile-p OBJECT

Package

nfiles

Source

nfiles.lisp (file)

Function: worker-write FILE CACHE-ENTRY

Package

nfiles

Source

nfiles.lisp (file)

Function: write-cache-entry FILE ENTRY

Package

nfiles

Source

nfiles.lisp (file)

4.2.5 Generic functions

Generic Function: cached-value OBJECT

Generic Function: (setf cached-value) NEW-VALUE OBJECT

Package

nfiles

Methods

Method: cached-value (CACHE-ENTRY cache-entry)

automatically generated reader method

Source

nfiles.lisp (file)

Method: (setf cached-value) NEW-VALUE (CACHE-ENTRY cache-entry)

automatically generated writer method

Source

nfiles.lisp (file)

Generic Function: last-update OBJECT

Generic Function: (setf last-update) NEW-VALUE OBJECT

Package

nfiles

Methods

Method: last-update (CACHE-ENTRY cache-entry)

Method: (setf last-update) NEW-VALUE (CACHE-ENTRY cache-entry)

The date at which the cache entry was last updated.

Source

nfiles.lisp (file)

Generic Function: source-file OBJECT

Generic Function: (setf source-file) NEW-VALUE OBJECT

Package

nfiles

Methods

Method: source-file (CACHE-ENTRY cache-entry)

Method: (setf source-file) NEW-VALUE (CACHE-ENTRY cache-entry)

This is the ‘file’ object that was used to instantiate the entry’s ‘cached-value’.

Source

nfiles.lisp (file)

Generic Function: worker OBJECT

Generic Function: (setf worker) NEW-VALUE OBJECT

Package

nfiles

Methods

Method: worker (CACHE-ENTRY cache-entry)

automatically generated reader method

Source

nfiles.lisp (file)

Method: (setf worker) NEW-VALUE (CACHE-ENTRY cache-entry)

automatically generated writer method

Source

nfiles.lisp (file)

Generic Function: worker-notifier OBJECT

Generic Function: (setf worker-notifier) NEW-VALUE OBJECT

Package

nfiles

Methods

Method: worker-notifier (CACHE-ENTRY cache-entry)

automatically generated reader method

Source

nfiles.lisp (file)

Method: (setf worker-notifier) NEW-VALUE (CACHE-ENTRY cache-entry)

automatically generated writer method

Source

nfiles.lisp (file)

4.2.6 Classes

Class: cache-entry ()

Package

nfiles

Source

nfiles.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• initialize-instance (method)
• worker-notifier (method)
• worker-notifier (method)
• worker (method)
• worker (method)
• cached-value (method)
• cached-value (method)
• last-update (method)
• last-update (method)
• source-file (method)
• source-file (method)

Direct slots

Slot: source-file

This is the ‘file’ object that was used to instantiate the entry’s ‘cached-value’.

Type

nfiles:file

Initargs

:source-file

Initform

(error "source file must be given.")

Readers

source-file (generic function)

Writers

(setf source-file) (generic function)

Slot: last-update

The date at which the cache entry was last updated.

Type

integer

Initargs

:last-update

Initform

(get-universal-time)

Readers

last-update (generic function)

Writers

(setf last-update) (generic function)

Slot: cached-value

Initargs

:cached-value

Readers

cached-value (generic function)

Writers

(setf cached-value) (generic function)

Slot: worker

Type

(or null bordeaux-threads:thread)

Initargs

:worker

Readers

worker (generic function)

Writers

(setf worker) (generic function)

Slot: worker-notifier

Type

(or null bordeaux-threads:semaphore)

Initargs

:worker-notifier

Readers

worker-notifier (generic function)

Writers

(setf worker-notifier) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions