.. zsh-module-meta::
   :name: zsh/mapfile
   :summary: Access to external files via a special associative array.

.. index:: single: parameter, file access via; Command

The ``zsh/mapfile`` module provides one special associative array parameter of
the same name.

.. index:: single: mapfile; Variable

``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, ``vared mapfile[myfile]'``' works as expected,
    editing the file ``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 ``${(k)mapfile}`` has the same effect as the glob operator
    ``*(D)``, since files beginning with a dot are not special.  Care must be
    taken with expressions such as ``rm ${(k)mapfile}``, which will delete
    every file in the current directory without the usual ``rm *`` test.
    
    The parameter ``mapfile`` may be made read-only; in that case, files
    referenced may not be written or deleted.
    
    A file may conveniently be read into an array as one line per element
    with the form
    :var:`array`\ ``=("${(f@)mapfile[``:var:`filename`\ ``]}")``.
    The double quotes and the ``@`` are necessary to prevent empty lines
    from being removed.  Note that if the file ends with a newline,
    the shell will split on the final newline, generating an additional
    empty field; this can be suppressed by using
    :var:`array`\ ``=("${(f@)${mapfile[``:var:`filename`\ ``]%$\n'}}")``'.
    

Limitations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Although reading and writing of the file in question is efficiently
handled, zsh's internal memory management may be arbitrarily baroque;
however, ``mapfile`` is usually very much more efficient than
anything involving a loop.  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 substitution
operations).  In particular, this means handling of sufficiently long files
(greater than the machine's swap space, or than the range of the pointer
type) will be incorrect.

No errors are printed or flagged for non-existent, unreadable, or
unwritable 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.
