.. meta::
:description: Unicon keywords
:keywords: unicon, icon, keywords
========
Keywords
========
.. Modified: 2019-10-20/20:40-0400 btiffin
.. Copyright 2016 Brian Tiffin
.. This file is part of the Unicon Programming document
.. GPL 3.0+ :ref:`license`
.. image:: images/unicon.png
:align: center
.. only:: html
:ref:`genindex`
:floatright:`Unicon`
Keywords in :ref:`Icon ` and ``Unicon`` provide access to wide
assortment of environmental data, constants, and feature settings and control.
All keywords start with an ampersand symbol ``&``.
*History sidetrip:* Unicon keywords are an evolution of :ref:`SNOBOL`
keywords. In ``SNOBOL``, some keywords were also called ``trapped
variables``, as accessing the keywords would cause special processing in
``SNOBOL``.
Unicon Keywords
===============
.. index:: &allocated
.. _&allocated:
&allocated
----------
- Read-only
- Generates :ref:`integers `
A generator that produces 4 :ref:`integers `; the cumulative number of bytes
used for the
- heap
- static
- string
- block
memory regions.
.. index:: allocated.icn
.. literalinclude:: examples/allocated.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/allocated.icn`
Giving:
.. command-output:: unicon -s allocated.icn -x
:cwd: examples
.. seealso::
:ref:`&collections`,
:ref:`&storage`,
:ref:`®ions`
--------
.. index:: &ascii, keyword; &ascii
.. _&ascii:
&ascii
------
- Read-only
- Produces a :ref:`Cset ` that includes the 128 :ref:`ASCII `
characters.
.. index:: ascii.icn
.. literalinclude:: examples/ascii.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/ascii.icn`
Giving:
.. command-output:: unicon -s ascii.icn -x
:cwd: examples
Note that Icon indexing is 1 relative, so the 65th item is byte code 64.
A handy :ref:`Cset ` keyword, but be wary with displaying this value in
full, as it includes unprintable control codes.
.. seealso::
:ref:`&cset`,
:ref:`&digits`,
:ref:`&lcase`,
:ref:`&letters`,
:ref:`&ucase`,
:ref:`Cset`
--------
.. index:: &clock, keyword; &clock
.. _&clock:
&clock
------
- Read-only
- Produces a :ref:`string ` with the current time in ``hh:mm:ss``
form.
.. literalinclude:: examples/clock.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/clock.icn`
Giving:
.. command-output:: unicon -s clock.icn -x
:cwd: examples
.. seealso::
:ref:`&date`,
:ref:`&dateline`,
:ref:`&now`,
:ref:`&time`
--------
.. index:: &col, keyword; &col
.. _&col:
&col
----
- Read-write
- Produces: an :ref:`integer `
``&col`` is the mouse horizontal position in text columns, from the most
recent :ref:`Event() `. If ``&col`` is assigned, :ref:`&x` is set to a
corresponding pixel location using the current font of :ref:`&window`.
.. literalinclude:: examples/col.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/col.icn`
Sample run:
.. command-output:: unicon -s col.icn -x
:cwd: examples
.. seealso:: :ref:`&x`, :ref:`Event`
--------
.. index:: &collections, keyword; &collections
.. _&collections:
&collections
------------
- Read-only
- Generates integers
A generator that produces 4 :ref:`integers `; the number of times
memory has been reclaimed from the
- heap
- static
- string
- block
memory regions.
.. index:: collections.icn
.. literalinclude:: examples/collections.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/collections.icn`
Giving:
.. command-output:: unicon -s collections.icn -x
:cwd: examples
.. seealso::
:ref:`&allocated`,
:ref:`&storage`,
:ref:`®ions`
--------
.. index:: &column, keyword; &column
.. _&column:
&column
-------
- Read-only
- Returns an integer
Produces the :ref:`integer ` column, from the program source code, of
the current execution point.
.. index:: column.icn
.. literalinclude:: examples/column.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/column.icn`
Giving:
.. command-output:: unicon -s column.icn -x
:cwd: examples
.. seealso::
:ref:`&line`,
:ref:`&file`,
:ref:`&level`,
:ref:`&progname`,
:ref:`&trace`,
:ref:`Execution monitoring`
--------
.. index:: &control, keyword; &control
.. _&control:
&control
--------
- Read-only
- Produces: :ref:`&null` or failure
null if control key was down on last X event, otherwise a reference to
&control fails.
.. literalinclude:: examples/control.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/control.icn`
Sample run:
.. command-output:: unicon -s control.icn -x
:cwd: examples
.. seealso:: :ref:`&meta`, :ref:`&shift`
--------
.. index:: &cset, keyword; &cset
.. _&cset:
&cset
------
- Read-only
- Produces a :ref:`cset ` that includes all characters.
.. index:: cset.icn
.. literalinclude:: examples/cset.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/cset.icn`
Giving:
.. command-output:: unicon -s cset.icn -x
:cwd: examples
Note that Icon indexing is 1 relative, so the 41st item is byte code 40.
A very handy keyword, as subsets of character sequences can easily
be made by indexing ``&cset``. Includes unprintable character codes.
.. seealso::
:ref:`&ascii`,
:ref:`&digits`,
:ref:`&lcase`,
:ref:`&letters`,
:ref:`&ucase`,
:ref:`Cset`
--------
.. index:: ¤t, keyword; ¤t
.. _¤t:
¤t
--------
- Read-only
- Produces a :ref:`co-expression `.
Produces the :ref:`co-expression ` that is currently executing.
.. index:: current.icn
.. literalinclude:: examples/current.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/current.icn`
Giving:
.. command-output:: unicon -s current.icn -x
:cwd: examples
.. seealso::
:ref:`&source`,
:ref:`create`,
:ref:`Execution monitoring`
Side comment: :ref:`co-expressions `, are *cool*.
--------
.. index:: &date, keyword; &date
.. _&date:
&date
-----
- Read-only
- Produces a :ref:`string ` with the current date in ``yyyy/mm/dd``
form.
.. literalinclude:: examples/date.icn
:language: unicon
:start-after: ##+
.. only:: html
.. rst-class:: rightalign
:download:`examples/date.icn`
Giving:
.. command-output:: unicon -s date.icn -x
:cwd: examples
The sample code highlights a powerful Unicon idiom, for transposing strings
around, called ``labelling``. It converts from system ``yyyy/mm/dd`` to
``mm/dd/yyyy`` format.
If you prefer other forms, the advanced transposition features of function
:ref:`map