.. zsh-module-meta::
   :name: zsh/ksh93
   :summary: Extended ksh93 compatibility for "emulate ksh"

.. index:: single: ksh93; Command

The ``zsh/ksh93`` module provides one builtin and several parameters to
improve compatibility with ksh93.  As of this writing, several ksh93
features are still missing.

Ksh Builtins
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The single builtin provided by this module is:

.. index:: single: nameref; Function

.. index:: single: named references, creating; Command

``nameref`` [ ``-gpur`` ] :var:`pname`\[``=``:var:`rname`]
    
    Equivalent to ``typeset -n`` :var:`pname`\ ``=``:var:`rname`
    
    However, ``nameref`` is a builtin command rather than a reserved word,
    so handling of assigments in the argument list may differ.
    

Ksh Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. index:: single: parameters, ksh; Command

Parameters supplied by this module that are marked with \`<K>' below
are available only when ksh emulation is active before entry to the
shell function, that is, ``emulate ksh`` locally to a function does
not populate these parameters for that function.

.. index:: single: .sh.command; Variable

``.sh.command``
    
    A named reference to ``ZSH_DEBUG_CMD``
    

.. index:: single: .sh.edchar; Variable

``.sh.edchar`` <K>
    
    In a ZLE widget, equivalent to the ``KEYS`` special parameter.  In a
    future release, assignments to this parameter will affect the input
    stream seen by ZLE.
    

.. index:: single: .sh.edcol; Variable

``.sh.edcol``
    
    A named reference to the ZLE special parameter ``CURSOR``.
    

.. index:: single: .sh.edmode; Variable

``.sh.edmode`` <K>
    
    In a ZLE widget, this parameter has the value ``ESC`` (``$'\e'``) if the
    ``VI`` option is set and the ``main`` keymap is selected.  This is
    intended for use with vi-mode key bindings (``bindkey -v``).  In a
    future revision, assigning ``.sh.edchar=${.sh.edmode}`` is expected
    to initiate ``vicmd`` mode when ``viins`` is active, and do
    nothing when ``vicmd`` is already active.
    

.. index:: single: .sh.edtext; Variable

``.sh.edtext``
    
    A named reference to the ``BUFFER`` special ZLE parameter.
    

.. index:: single: .sh.file; Variable

``.sh.file``
    
    A named reference to the ``ZSH_SCRIPT`` parameter.
    

.. index:: single: .sh.fun; Variable

``.sh.fun`` <K>
    
    In a shell function, the function's name.  Usually the same as ``$0``,
    but not affected by ``POSIX_ARGZERO`` or ``FUNCTION_ARGZERO`` options.
    

.. index:: single: .sh.level; Variable

``.sh.level`` <K>
    
    In a shell function, initially set to the depth of the call stack. This
    may be assigned to change the apparent depth.  However, such assignment
    does not affect the scope of local parameters.
    

.. index:: single: .sh.lineno; Variable

``.sh.lineno``
    
    A named reference to the ``LINENO`` special parameter.
    

.. index:: single: .sh.match; Variable

``.sh.match``
    
    An array equivalent to the ``match`` parameter as assigned by the
    ``(#b)`` extended globbing flag.  When the
    ``KSH_ARRAYS`` option is set, ``${.sh.match[0]}`` gives the value of
    the ``MATCH`` parameter as set by the ``(#m)`` extended
    globbing flag.  Currently, the ``EXTENDED_GLOB`` option must be enabled
    and those flags must be explicitly used in a pattern in order for these
    values of ``.sh.match`` to be set.
    

.. index:: single: .sh.name; Variable

``.sh.name`` <K>
    
    When the ``vared`` command is used, this parameter may be used in
    user-defined ZLE widgets to get the name of the variable being edited.
    A future release is expected to use this parameter in the implementation
    of "discipline functions".
    

.. index:: single: .sh.subscript; Variable

``.sh.subscript`` <K>
    
    When ``vared`` has been used on an array element, this parameter holds
    the array index (either a number, or an associative array key).
    

.. index:: single: .sh.subshell; Variable

``.sh.subshell``
    
    A named reference to the ``ZSH_SUBSHELL`` parameter.
    

.. index:: single: .sh.value; Variable

``.sh.value`` <K>
    
    In ``vared`` this is a named reference to the ZLE special ``BUFFER``.
    A future release is expected to use this parameter in the implementation
    of "discipline functions".
    

.. index:: single: .sh.version; Variable

``.sh.version``
    
    A named reference to ``ZSH_PATCHLEVEL``.
    

Future Compatibility
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following features of ksh93 are not currently supported but may be
available in a future release.

``namespace`` :var:`ident` ``{`` :var:`list` ``}``
    
    This reserved word executes the current shell compound command
    ``{`` :var:`list` ``}``, with the special behavior that all functions
    and parameters :var:`name` declared within :var:`list` are implicitly
    prefixed to become ``.``:var:`ident`\ ``.``:var:`name`, and similarly any
    reference to a function or parameter :var:`name` is searched for as
    ``.``:var:`ident`\ ``.``:var:`name` before falling back to :var:`name`.
    
    :emphasis:`THIS FEATURE IS NOT YET IMPLEMENTED.`
    

``.sh.math`` <K>
    
    This parameter is more accurately considered a namespace.  A function
    definition of the form
    
    
    .. 
    

        ``function .sh.math.``:var:`name` :var:`ident` ``... {`` :var:`list` ``}``
    
    
    is equivalent to the native zsh definition
    
    
    
    .. parsed-literal::
       :class: example

        ``function`` :var:`name` ``{``
          ``local`` :var:`ident`\ ``=$1 ...``
          :var:`list`
        ``}``
        ``functions -M`` :var:`name` ``1 3``
    
    
    
    Up to 3 :var:`ident` arguments, interpreted as floating point numbers,
    may be provided for a function defined with ``.sh.math`` in this way.
    The names (but not definitions) of all such functions are available
    via ``${.sh.math[@]}``.
    
    :emphasis:`THIS FEATURE IS NOT YET IMPLEMENTED.`
    

``:var:`name``\`.get````
    
    A shell function having this name, if defined, is invoked whenever the
    parameter ``${``:var:`name`\ ``}`` is referenced, including by commands
    such as ``typeset -p``.  If the special variable ``.sh.value`` is
    assigned by the function, that value is substituted instead of the
    true value of :var:`name`.  This does not change the value of :var:`name`,
    but there is no way to access the actual value without first removing
    the function.
    
    Additionally, an explicit reference to ``${``:var:`name`\ ``.get}``
    calls the function :var:`name`\ ``.get`` even if there is no parameter
    :var:`name` and substitutes the standard output of the function.
    
    :emphasis:`THIS FEATURE IS NOT YET IMPLEMENTED.`
    

``:var:`name``\`.set````

``:var:`name``\`.append````
    
    Shell functions having these names are invoked when the parameter
    :var:`name` is assigned or (for array types) has a new field appended.
    The function may change the result of the operation by assigning to
    the ``.sh.value`` special parameter, or block the change by
    unsetting ``.sh.value``.
    
    Explicit reference to ``${``:var:`name`\ ``.set}`` or ``${``:var:`name`\ ``.append}``
    substitutes the standard output of the function.
    
    :emphasis:`THIS FEATURE IS NOT YET IMPLEMENTED.`
    

``:var:`name``\`.unset````
    
    When a function of this name is defined, it is called whenever the
    parameter :var:`name` would be unset.  The function must explicitly
    ``unset`` :var:`name`, otherwise the variable remains set.
    
    :emphasis:`THIS FEATURE IS NOT YET IMPLEMENTED.`
    

``typeset -C`` :var:`name`\[``=``:var:`values` ``...``]
    
    Creates a :emphasis:`compound variable`.
    
    :emphasis:`THIS FEATURE IS NOT YET IMPLEMENTED, and the syntax of :var:`\values`
    is unlikely to be fully ksh compatible.`
    

Other Differences
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following features of ksh93 are not currently supported and there are
no plans to implement them.

:var:`pathdir`\ ``/.paths``
    
    Each directory :var:`pathdir` in the ``PATH`` parameter may contain a
    text file ``.paths`` which may define additional directories to
    be searched for function definitions (``FPATH``), external executables
    (``PATH``), and plugin files (similar to ``MODULE_PATH``).
    
    :emphasis:`THIS FEATURE IS UNLIKELY EVER TO BE IMPLEMENTED.`
    

``builtin -f`` :var:`file`
    
    Installs a new shell builtin command dynamically linked from :var:`file`,
    where :var:`file` is found by a path search and the base name of the file
    is the name of the builtin to be added.
    
    Similar to ``zmodload -F zsh/``:var:`file` ``+b:``:var:`file`.
    
    :emphasis:`THIS FEATURE IS UNLIKELY EVER TO BE IMPLEMENTED.`
    

``typeset -H`` :var:`name`\[``=``:var:`value`]
    
    Used for :emphasis:`host-name file mapping` on some operating systems.
    
    :emphasis:`THIS FEATURE IS UNLIKELY EVER TO BE IMPLEMENTED.`
    

``typeset {+|-}M`` :var:`mapname` :var:`name`\[``=``:var:`value`]
    
    Declares a character translation :var:`mapname` for values assigned to :var:`name`.
    

``typeset -S``

``typeset -T``  [``-f``] [ :var:`tname`\ ``=(``:var:`values`\ ``)`` ]

``typeset -h`` :var:`str`
    
    Used to define :emphasis:`typed variables` and properties of their :emphasis:`sub-variables`.
    The ``-T`` and ``-h`` options conflict with existing zsh usage.
    

``typeset -X`` :var:`name`\[``=``:var:`value`]
    
    Declares a floating-point variable displayed in hexadecimal format.
    

``typeset -b`` :var:`name`\[``=``:var:`value`]
    
    Declares a parameter stored in :emphasis:`base64` format.
    

``typeset -m`` :var:`newname`\ ``=``:var:`oldname`
    
    :emphasis:`Moves` :var:`oldname` to :var:`newname`.  Conflicts with native zsh usage.
    

