aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSean Whitton <spwhitton@spwhitton.name>2022-04-02 14:06:53 -0700
committerSean Whitton <spwhitton@spwhitton.name>2022-04-02 14:08:56 -0700
commit159ff0bda5c67767599509313468c157118ad70e (patch)
treec53e8a3cbfbb879afa2f49407d3c8bfdb38d9aac /doc
parent8f8c59341e7f420397f79d47af2787ca55fba07b (diff)
downloadconsfigurator-159ff0bda5c67767599509313468c157118ad70e.tar.gz
rename READFILE, WRITEFILE, corresponding generics and some wrappers
Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
Diffstat (limited to 'doc')
-rw-r--r--doc/connections.rst8
-rw-r--r--doc/ideas.rst8
-rw-r--r--doc/properties.rst16
3 files changed, 17 insertions, 15 deletions
diff --git a/doc/connections.rst b/doc/connections.rst
index 236df5b..d03d3a8 100644
--- a/doc/connections.rst
+++ b/doc/connections.rst
@@ -37,10 +37,10 @@ Defining connection types
The code which establishes connections (i.e., implementations of the
``ESTABLISH-CONNECTION`` generic) is like code in ``:posix`` properties -- it
-should restrict its I/O to ``RUN``, ``RUNLINES``, ``READFILE`` and
-``WRITEFILE``, functions which access the currently active connection. This
-is in order to permit the arbitrary nesting of connections. If establishing a
-connection really does require more I/O, such as in the case of
+should restrict its I/O to ``RUN``, ``RUNLINES``, ``READ-REMOTE-FILE`` and
+``WRITE-REMOTE-FILE``, functions which access the currently active connection.
+This is in order to permit the arbitrary nesting of connections. If
+establishing a connection really does require more I/O, such as in the case of
``:CHROOT.FORK`` connections, code can call ``LISP-CONNECTION-P``, and either
signal an error, or fall back to another connection type.
diff --git a/doc/ideas.rst b/doc/ideas.rst
index 80dbcc7..2b9fa25 100644
--- a/doc/ideas.rst
+++ b/doc/ideas.rst
@@ -14,10 +14,10 @@ Connections
- Basic infrastructure for connections which work with just input and output
streams connected to an interactive POSIX sh somewhere, like TRAMP, and
- probably using ``base64 -d`` for WRITEFILE. Probably the basic connection
- type will take a command to start up the shell as a keyword argument, and
- then we can have more specific connection types which take other arguments
- and construct the full command.
+ probably using ``base64 -d`` for WRITE-REMOTE-FILE. Probably the basic
+ connection type will take a command to start up the shell as a keyword
+ argument, and then we can have more specific connection types which take
+ other arguments and construct the full command.
- It might be possible to write an implementation of CONNECTION-UPLOAD for
SSH-CONNECTION which can optimise a common case. If it can see that it is
diff --git a/doc/properties.rst b/doc/properties.rst
index 01a5919..ccd40dd 100644
--- a/doc/properties.rst
+++ b/doc/properties.rst
@@ -18,9 +18,10 @@ Except where specified otherwise in property docstrings, relative paths are
relative to the remote home directory. ``:LISP`` properties may assume they
will be executed in the remote home directory, and ``:POSIX`` properties may
assume that commands will be executed in the remote home directory, and that
-relative paths passed to ``READFILE`` and ``WRITEFILE`` are relative to the
-remote home directory. Use ``WITH-REMOTE-CURRENT-DIRECTORY`` to change the
-remote working directory in a way which ensures it will get changed back.
+relative paths passed to ``READ-REMOTE-FILE`` and ``WRITE-REMOTE-FILE`` are
+relative to the remote home directory. Use ``WITH-REMOTE-CURRENT-DIRECTORY``
+to change the remote working directory in a way which ensures it will get
+changed back.
Property subroutines
--------------------
@@ -98,14 +99,15 @@ Errors in attempting to apply a property are indicated by signalling a
``:posix`` properties should not make any assumptions about what localhost is
-- they may be running in the root Lisp, but they might be running in a Lisp
image running on an intermediary host, or even on the host to be configured.
-They should perform I/O only by calling ``RUN``, ``RUNLINES``, ``READFILE``,
-``WRITEFILE``, requesting prerequisite data, and applying or unapplying other
-``:posix`` properties. Otherwise, they should be pure functions.
+They should perform I/O only by calling ``RUN``, ``RUNLINES``,
+``READ-REMOTE-FILE``, ``WRITE-REMOTE-FILE``, requesting prerequisite data, and
+applying or unapplying other ``:posix`` properties. Otherwise, they should be
+pure functions.
``:lisp`` properties, by contrast, may (and should) assume that they are
running in a Lisp image on the host to which they are to be applied, so they
can perform arbitrary I/O in that context. They can also make use of ``RUN``,
-``RUNLINES``, ``READFILE`` and ``WRITEFILE`` if desired.
+``RUNLINES``, ``READ-REMOTE-FILE`` and ``WRITE-REMOTE-FILE`` if desired.
``:posix`` properties are characterised by the limited set of ways in which
they perform I/O, not by the use of only facilities defined in the Single UNIX