Initial revision

1 files changed, 46 insertions, 0 deletions

diff --git a/Doc/Zsh/mod_mapfile.yo b/Doc/Zsh/mod_mapfile.yo
new file mode 100644
index 000000000..6d0475711
--- /dev/null
+++ b/Doc/Zsh/mod_mapfile.yo
@@ -0,0 +1,46 @@
+texinode(The mapfile Module)(The parameter Module)(The files Module)(Zsh Modules)
+sect(The mapfile Module)
+cindex(parameter, file access via)
+The tt(mapfile) module provides one special associative array parameter of
+the same name.
+
+startitem()
+vindex(mapfile)
+item(tt(mapfile))(
+This associative array takes as keys the names of files; the resulting
+value is the content of the file.  The value is treated identically to any
+other text coming from a parameter.  The value may also be assigned to, in
+which case the file in question is written (whether or not it originally
+existed); or an element may be unset, which will delete the file in
+question.  For example, `tt(vared mapfile[myfile])' works as expected,
+editing the file `tt(myfile)'.
+
+When the array is accessed as a whole, the keys are the names of files in
+the current directory, and the values are empty (to save a huge overhead in
+memory).  Thus tt(${(k)mapfile}) has the same affect as the glob operator
+tt(*(D)), since files beginning with a dot are not special.  Care must be
+taken with expressions such as tt(rm ${(k)mapfile}), which will delete
+every file in the current directory without the usual `tt(rm *)' test.
+
+The parameter tt(mapfile) may be made read-only; in that case, files
+referenced may not be written or deleted.
+)
+enditem()
+
+subsect(Limitations)
+
+Although reading and writing of the file in question is efficiently
+handled, zsh's internal memory management may be arbitrarily baroque.  Thus
+it should not automatically be assumed that use of tt(mapfile) represents a
+gain in efficiency over use of other mechanisms.  Note in particular that
+the whole contents of the file will always reside physically in memory when
+accessed (possibly multiple times, due to standard parameter subsitution
+operations).
+
+No errors are printed or flagged for non-existent, unreadable, or
+unwriteable files, as the parameter mechanism is too low in the shell
+execution hierarchy to make this convenient.
+
+It is unfortunate that the mechanism for loading modules does not yet allow
+the user to specify the name of the shell parameter to be given the special
+behaviour.