.. 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 ` can come in handy. .. sourcecode:: unicon map("Dd/Mm/yYxX", "yYxX/Mm/Dd", &date) Will map the date from yyyy/mm/dd to dd/mm/yyyy form. Note this map is in (transpositions, labels, source) order. The second argument (the labels) can have no duplicate characters, and must be the same size as the third argument for, the transposition type mapping to occur. *But, stick with the default* ``&date`` *format if you can. It's not ambiguous, and it's easily machine sortable*. .. seealso:: :ref:`&clock`, :ref:`&dateline`, :ref:`&now`, :ref:`&time` -------- .. index:: &dateline, keyword; &dateline .. _&dateline: &dateline --------- - Read-only - Produces a :ref:`string ` with the current date in human readable form. The ``&dateline`` keyword gives a nice time stamp, with day of the week, date and time (to the minute). .. literalinclude:: examples/dateline.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/dateline.icn` Giving: .. command-output:: unicon -s dateline.icn -x :cwd: examples .. seealso:: :ref:`&clock`, :ref:`&date`, :ref:`&now`, :ref:`&time` -------- .. index:: &digits, keyword; &digits .. _&digits: &digits ------- - Read-only - Produces a :ref:`cset ` that includes the ten decimal digits. .. index:: digits.icn .. literalinclude:: examples/digits.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/digits.icn` Giving: .. command-output:: unicon -s digits.icn -x :cwd: examples .. seealso:: :ref:`&ascii`, :ref:`&cset`, :ref:`&lcase`, :ref:`&letters`, :ref:`&ucase`, :ref:`Cset` -------- .. index:: &dump, keyword; &dump .. _&dump: &dump ----- - Read-Write - An :ref:`integer ` that controls the generation of a program dump. If ``&dump`` is non-zero when a program halts, all local and global variables are shown, along with their values. .. index:: dump.icn .. literalinclude:: examples/dump.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/dump.icn` Sample run (ends with a stop, error code set to 1, the value of ``&dump``): .. command-output:: unicon -s dump.icn -x :cwd: examples :returncode: 1 -------- .. index:: &e, keyword; &e .. _&e: &e --- - Read-only - Produces a :ref:`Real `, representing Euler's number, the base of the natural logarithms. ``e`` is a marvelous, magical number. .. index:: e.icn .. literalinclude:: examples/e.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/e.icn` Giving: .. command-output:: unicon -s e.icn -x :cwd: examples .. seealso:: :ref:`&phi`, :ref:`&pi` -------- .. index:: &errno, keyword; &errno .. _&errno: &errno ------ - Read-only - Produces: :ref:`integer ` Variable containing *transient* error number from previous POSIX command. .. literalinclude:: examples/errno.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/errno.icn` Sample run: .. command-output:: unicon -s errno.icn -x :cwd: examples -------- .. index:: &error, keyword; &error .. _&error: &error ------ - Read-Write - An :ref:`integer ` that controls how runtime errors are handled. If ``&error`` is non-zero then runtime errors are converted into expression failure. ``&error`` is decremented each time a runtime error occurs. Setting ``&error`` to -1 (minus one) effectively disables runtime errors indefinitely. .. index:: error.icn .. literalinclude:: examples/error.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/error.icn` Sample run (eventually ends with failure): .. command-output:: unicon -s error.icn -x :cwd: examples :returncode: 1 Side comment: *Unicon style expression failure, should be in every language.* .. seealso:: :ref:`&errornumber`, :ref:`&errortext`, :ref:`&errorvalue` -------- .. index:: &errornumber, keyword; &errornumber .. _&errornumber: &errornumber ------------ - Read-only - Produces an :ref:`integer ` ``&errornumber`` is the number of the last error converted to failure, if any. .. index:: errornumber.icn .. literalinclude:: examples/errornumber.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/errornumber.icn` Sample run (eventually ends with failure code): .. command-output:: unicon -s errornumber.icn -x :cwd: examples :returncode: 1 On program startup, ``&errornumber`` is undefined, the first ``write`` expression fails. .. seealso:: :ref:`&error`, :ref:`&errortext`, :ref:`&errorvalue` -------- .. index:: &errortext, keyword; &errortext .. _&errortext: &errortext ---------- - Read-only - Produces a :ref:`string ` ``&errortext`` is the last error message that was converted to failure, if any. .. literalinclude:: examples/errortext.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/errortext.icn` Sample run (eventually ends with failure code): .. command-output:: unicon -s errortext.icn -x :cwd: examples :returncode: 1 On program startup, ``&errortext`` is undefined, the first ``write`` expression fails. .. seealso:: :ref:`&error`, :ref:`&errornumber`, :ref:`&errorvalue` -------- .. index:: &errorvalue, keyword; &errorvalue .. _&errorvalue: &errorvalue ----------- - Read-only - Produces a value ``&errorvalue`` is the value involved in the last error that was converted to failure, if any. .. literalinclude:: examples/errorvalue.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/errorvalue.icn` Sample run (eventually ends with failure code): .. command-output:: unicon -s errorvalue.icn -x :cwd: examples :returncode: 1 On program startup, ``&errorvalue`` is undefined. As this value can be any value, ``image`` is used to show the type of value. .. seealso:: :ref:`&error`, :ref:`&errornumber`, :ref:`&errortext` -------- .. index:: &errout, keyword; &errout .. _&errout: &errout ------- - Read-only - Produces the current standard error file stream .. literalinclude:: examples/errout.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/errout.icn` Giving: .. command-output:: unicon -s errout.icn -x :cwd: examples .. seealso:: :ref:`&input`, :ref:`&output` -------- .. index:: &eventcode, keyword; &eventcode .. _&eventcode: &eventcode ---------- - Read-only - Produces: An :ref:`integer ` Event code in monitored program, set from last :ref:`EvGet` .. literalinclude:: examples/eventcode.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/eventcode.icn` Sample run: .. command-output:: unicon -s eventcode.icn -x :cwd: examples .. seealso:: :ref:`&eventsource`, :ref:`&eventvalue`, :ref:`EvGet` -------- .. index:: &eventsource, keyword; &eventsource .. _&eventsource: &eventsource ------------ - Read-only - Produces: A :ref:`co-expression ` Source co-expression of event in monitoring program, set during :ref:`EvGet`. .. literalinclude:: examples/eventsource.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/eventsource.icn` Sample run: .. command-output:: unicon -s eventsource.icn -x :cwd: examples .. seealso:: :ref:`&eventcode`, :ref:`&eventvalue`, :ref:`EvGet` -------- .. index:: &eventvalue, keyword; &eventvalue .. _&eventvalue: &eventvalue ----------- - Read-only - Produces: *any* Value being processed when :ref:`EvGet` returns an execution monitoring event. .. literalinclude:: examples/eventvalue.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/eventvalue.icn` Sample run: .. command-output:: unicon -s eventvalue.icn -x :cwd: examples .. seealso:: :ref:`&eventcode`, :ref:`&eventsource`, :ref:`EvGet` -------- .. index:: &fail, keyword; &fail .. _&fail: &fail ----- - Read-only, *but fails when accessed* - Causes failure, as soon as it is evaluated. .. literalinclude:: examples/fail-keyword.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/fail-keyword.icn` Giving: .. command-output:: unicon -s fail-keyword.icn -x :cwd: examples Which produces no output; both of the expressions, ``type`` and ``image`` fail, so ``write`` is never evaluated. .. seealso:: :ref:`failure`, :ref:`fail` -------- .. index:: &features, keyword; &features .. _&features: &features --------- - Read-only - Generates :ref:`string ` data that indicates the optional, and non-portable features supported by the current ``unicon`` build. A reflective aspect of ``Unicon`` that can be used for purely informational purposes, or to decide at runtime what code fragments are safe to use on the current platform. .. index:: features.icn .. literalinclude:: examples/features.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/features.icn` Giving: .. command-output:: unicon -s features.icn -x :cwd: examples The ``unicon -feature`` command line option will display the ``&features`` data as well. .. seealso:: :ref:`$ifdef`, :ref:`$ifndef`, :ref:`predefined symbols`, :ref:`&version` -------- .. index:: &file, keyword; &file .. _&file: &file ----- - Read-only - Produces the :ref:`string ` of the source used to compile the current execution point. .. literalinclude:: examples/file.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/file.icn` Giving: .. command-output:: unicon -s file.icn -x :cwd: examples .. seealso:: :ref:`&column`, :ref:`&line`, :ref:`&level`, :ref:`&progname`, :ref:`&trace`, :ref:`Execution Monitoring` -------- .. index:: &host, keyword; &host .. _&host: &host ----- - Read-only - Produces a :ref:`string ` representing the current network hostname. .. literalinclude:: examples/host.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/host.icn` Giving: .. command-output:: unicon -s host.icn -x :cwd: examples .. seealso:: :ref:`&version` -------- .. index:: &input, keyword; &input .. _&input: &input ------ - Read-only - Produces a :ref:`file ` representing the standard input stream. .. literalinclude:: examples/input.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/input.icn` Giving: .. command-output:: unicon -s input.icn -x :cwd: examples .. seealso:: :ref:`&errout`, :ref:`&output` -------- .. _&interval: &interval --------- - Read-only - Produces: An :ref:`integer ` Milliseconds since previous windowing event. .. literalinclude:: examples/interval.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/interval.icn` Sample run: .. command-output:: unicon -s interval.icn -x :cwd: examples .. seealso:: :ref:`Event` -------- .. index:: &lcase, keyword; &lcase .. _&lcase: &lcase ------ - Read-only - Produces a :ref:`cset ` of the lower case letters, a through z. .. literalinclude:: examples/lcase.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/lcase.icn` Giving: .. command-output:: unicon -s lcase.icn -x :cwd: examples .. seealso:: :ref:`&ascii`, :ref:`&cset`, :ref:`&digits`, :ref:`&letters`, :ref:`&ucase`, :ref:`Cset` -------- .. index:: &ldrag, keyword; &ldrag .. _&ldrag: &ldrag ------ - Read-only - Produces: the :ref:`integer ` that indicates a left mouse button drag event code. left button drag event code. .. literalinclude:: examples/button-values.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/button-values.icn` Sample run: .. command-output:: unicon -s button-values.icn -x :cwd: examples .. seealso:: :ref:`&lpress`, :ref:`&lrelease`, :ref:`&mpress`, :ref:`&mrelease`, :ref:`&mdrag` :ref:`&rpress`, :ref:`&rrelease`, :ref:`&rdrag` -------- .. index:: &letters, keyword; &letters .. _&letters: &letters -------- - Read-only - Produces a :ref:`cset ` of all letter, A-Za-z. .. literalinclude:: examples/letters.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/letters.icn` Giving: .. command-output:: unicon -s letters.icn -x :cwd: examples .. seealso:: :ref:`&ascii`, :ref:`&cset`, :ref:`&digits`, :ref:`&lcase`, :ref:`&ucase`, :ref:`Cset` -------- .. index:: &level, keyword; &level .. _&level: &level ------ - Read-only - Produces the current execution depth, one level for each nested procedure. .. literalinclude:: examples/level.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/level.icn` Giving: .. command-output:: unicon -s level.icn -x :cwd: examples .. seealso:: :ref:`&error`, :ref:`&trace` -------- .. index:: &line, keyword; &line .. _&line: &line ----- - Read-only - Produces an :ref:`integer `. Returns the :ref:`integer ` line, from the program source code, of the current execution point. .. index:: line.icn .. literalinclude:: examples/line.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/line.icn` Giving: .. command-output:: unicon -s line.icn -x :cwd: examples .. seealso:: :ref:`&column`, :ref:`&file`, :ref:`&level`, :ref:`&progname`, :ref:`&trace`, :ref:`Execution monitoring` -------- .. index:: &lpress, keyword; &lpress .. _&lpress: &lpress ------- - Read-only - Produces: the :ref:`integer ` that indicates a left mouse button press event code. left button press event code. .. literalinclude:: examples/button-values.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/button-values.icn` Sample run: .. command-output:: unicon -s button-values.icn -x :cwd: examples .. seealso:: :ref:`&lrelease`, :ref:`&ldrag`, :ref:`&mpress`, :ref:`&mrelease`, :ref:`&mdrag` :ref:`&rpress`, :ref:`&rrelease`, :ref:`&rdrag` -------- .. index:: &lrelease, keyword; &lrelease .. _&lrelease: &lrelease --------- - Read-only - Produces: the :ref:`integer ` that indicates a left mouse button release event code. left button release event code. .. literalinclude:: examples/button-values.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/button-values.icn` Sample run: .. command-output:: unicon -s button-values.icn -x :cwd: examples .. seealso:: :ref:`&lpress`, :ref:`&ldrag`, :ref:`&mpress`, :ref:`&mrelease`, :ref:`&mdrag` :ref:`&rpress`, :ref:`&rrelease`, :ref:`&rdrag` -------- .. index:: &main, keyword; &main .. _&main: &main ----- - Read-only - Produces the main :ref:`co-expression ` .. literalinclude:: examples/main.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/main.icn` Giving: .. command-output:: unicon -s main.icn -x :cwd: examples .. seealso:: :ref:`¤t`, :ref:`&source` -------- .. index:: &mdrag, keyword; &mdrag .. _&mdrag: &mdrag ------ - Read-only - Produces: the :ref:`integer ` that indicates a middle mouse button drag event code. middle button drag event code. .. literalinclude:: examples/button-values.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/button-values.icn` Sample run: .. command-output:: unicon -s button-values.icn -x :cwd: examples .. seealso:: :ref:`&lpress`, :ref:`&lrelease`, :ref:`&ldrag`, :ref:`&mpress`, :ref:`&mrelease`, :ref:`&rpress`, :ref:`&rrelease`, :ref:`&rdrag` -------- .. index:: &meta, keyword; &meta .. _&meta: &meta ----- - Read-only - Produces: :ref:`&null <&null>` or fail null if meta key was down on last X event, otherwise a reference to ``&meta`` fails. .. literalinclude:: examples/meta.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/meta.icn` Sample run: .. command-output:: unicon -s meta.icn -x :cwd: examples .. seealso:: :ref:`&control`, :ref:`&shift` -------- .. index:: &mpress, keyword; &mpress .. _&mpress: &mpress ------- - Read-only - Produces: the :ref:`integer ` that indicates a middle mouse button press event code. middle button press event code. .. literalinclude:: examples/button-values.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/button-values.icn` Sample run: .. command-output:: unicon -s button-values.icn -x :cwd: examples .. seealso:: :ref:`&lpress`, :ref:`&lrelease`, :ref:`&ldrag`, :ref:`&mrelease`, :ref:`&mdrag`, :ref:`&rpress`, :ref:`&rrelease`, :ref:`&rdrag` -------- .. index:: &mrelease, keyword; &mrelease .. _&mrelease: &mrelease --------- - Read-only - Produces: the :ref:`integer ` that indicates a middle mouse button release event code. middle button release event code. .. literalinclude:: examples/button-values.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/button-values.icn` Sample run: .. command-output:: unicon -s button-values.icn -x :cwd: examples .. seealso:: :ref:`&lpress`, :ref:`&lrelease`, :ref:`&ldrag`, :ref:`&mrelease`, :ref:`&mdrag`, :ref:`&rpress`, :ref:`&rrelease`, :ref:`&rdrag` -------- .. index:: &now .. _&now: &now ---- - Read-only - Produces an :ref:`integer ` representing the current time as a count of seconds since the :ref:`Unix epoch` reference standard, which is midnight January 1st, 1970. .. literalinclude:: examples/now.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/now.icn` Giving: .. command-output:: unicon -s now.icn -x :cwd: examples .. seealso:: :ref:`&clock`, :ref:`&date`, :ref:`&dateline`, :ref:`&time`, :ref:`y2k`, :ref:`Year 2038 problem` -------- .. index:: &null, keyword; &null .. _&null: &null ----- - Read-only - Represents the null value. The :ref:`null ` value is a special case in ``Unicon``. Unset variables return &null, and unused arguments test as &null. There are some operators that help manage this special value. - ``\var`` will fail if the variable ``var`` is null - ``/var`` will succeed and return the (empty) variable reference if ``var`` is null which is great for setting optional default values .. literalinclude:: examples/null.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/null.icn` Giving: .. command-output:: unicon -s null.icn -x :cwd: examples .. seealso:: :ref:`&fail`, :ref:`null` -------- .. index:: &output, keyword; &output .. _&output: &output ------- - Read-only - Produces the standard output stream .. literalinclude:: examples/output.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/output.icn` Giving: .. command-output:: unicon -s output.icn -x :cwd: examples .. seealso:: :ref:`&errout`, :ref:`&input` -------- .. index:: &phi, keyword; &phi .. _&phi: &phi ---- - Read-only - Produces a :ref:`real ` constant equal to the Golden Ratio .. literalinclude:: examples/phi.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/phi.icn` Giving: .. command-output:: unicon -s phi.icn -x :cwd: examples .. seealso:: :ref:`&pi`, :ref:`&e` -------- .. index:: &pi, keyword; &pi .. _&pi: &pi --- - Read-only - Produces a :ref:`Real ` representing the ratio of the diameter of a circle compared to the radius. .. literalinclude:: examples/pi.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/pi.icn` Giving: .. command-output:: unicon -s pi.icn -x :cwd: examples .. seealso:: :ref:`&e`, :ref:`&phi` -------- .. index:: &pick, keyword; &pick .. _&pick: &pick ----- - Read-only - Generates: :ref:`string* ` [*3D Graphics*] ``pick`` generates the object IDs selected at point(:ref:`&x`, :ref:`&y`) from the most recent windowing :ref:`Event`; *if* the event was read from a 3D window with attribute "pick=on". Objects need to be registered with :ref:`WSection` so Unicon knows which elements to generate for ``&pick``. .. literalinclude:: examples/pick.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/pick.icn` Sample run, clicking on the sphere: :: prompt$ unicon -s pick.icn -x -1 &x:46 &y:24 &row:2 &col:8 &pick:sphere .. image:: images/pick.png .. only:: html .. rst-class:: leftalign :download:`images/pick.png` .. seealso:: :ref:`&x`, :ref:`&y`, :ref:`Event`, :ref:`WSection` -------- .. index:: &pos, keyword; &pos .. _&pos: &pos ---- - Read-write - Holds the current :ref:`string scanning position `, as an :ref:`integer `. &pos is set to 1 at the start of a string scanning expression. &pos can be set to arbitrary values, but will be constrained internally to always be a valid string scanning index. When set to a negative indexing value, it will be reset to a valid positive index value. .. literalinclude:: examples/pos.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/pos.icn` Giving: .. command-output:: unicon -s pos.icn -x :cwd: examples .. seealso:: :ref:`&subject`, :ref:`string scanning` -------- .. index:: &progname, keyword; &progname .. _&progname: &progname --------- - Read-only - Returns a :ref:`string ` Produces the currently executing program name. .. index:: progname.icn .. literalinclude:: examples/progname-sample.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/progname-sample.icn` Giving: .. command-output:: unicon -s progname-sample.icn -x :cwd: examples .. seealso:: :ref:`&column`, :ref:`&line`, :ref:`&file`, :ref:`&level`, :ref:`&trace`, :ref:`Execution monitoring` -------- .. index:: &random, keyword; &random .. _&random: &random ------- - Read-write - Produces an :ref:`integer ` from the internal pseudo-random number generator used by the unary :ref:`? ` operator. The ``&random`` seed is initialized to a different value by Unicon for each program run, but can be set to a known value for reproducible sequences during testing. .. literalinclude:: examples/random.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/random.icn` Giving: .. notetoself The command-output is cached if the commands are identical .. command-output:: unicon -s random.icn -x :cwd: examples The first value and set of letters will be random (*psuedo-random*) for every run, the seed uniquely initialized at program startup. The second set of characters and the last numeric value will be the same for every run, using a known seed value of ``1``. When testing you can set a known seed to get a predictable, and consistent sequence of random values. Otherwise just let Unicon reset the seed for each run, and the results are almost\ [#psuedo]_ unpredictable. Don't set a known value for things like games that need random elements, or each play through will be predictable and in the worst case, the same, over and over again. .. command-output:: unicon -quiet -s random.icn -x :cwd: examples .. [#psuedo] Psuedo-random number generators are never completely unpredictable, given enough effort. If you need cryptographically secure random values, you will need to augment the default algorithms used in Unicon and mix things up a bit, in order to defeat any bad actors that may try and predict the order and numeric sequences of the psuedo-random numbers. *Even players out to cheat on your game might try and guess at sequencing, so mix it up.* -------- .. index:: &rdrag, keyword; &rdrag .. _&rdrag: &rdrag ------ - Read-only - Produces: the :ref:`integer` that indicates a right mouse button drag event right button drag. .. literalinclude:: examples/button-values.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/button-values.icn` Sample run: .. command-output:: unicon -s button-values.icn -x :cwd: examples .. seealso:: :ref:`&lpress`, :ref:`&lrelease`, :ref:`&ldrag` :ref:`&mpress`, :ref:`&mrelease`, :ref:`&mdrag` :ref:`&rpress`, :ref:`&rrelease` -------- .. index:: ®ions, keyword; ®ions .. _®ions: ®ions -------- - Read-only - Generates 3 :ref:`integer`\ s A generator that produces 3 :ref:`Integer`\ s; the cumulative number of bytes used for the - static (always zero in Unicon, for backward compatibility) - string - block memory regions. .. literalinclude:: examples/regions.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/regions.icn` Giving: .. command-output:: unicon -s regions.icn -x :cwd: examples .. seealso:: :ref:`&allocated`, :ref:`&collections`, :ref:`&storage` -------- .. index:: &resize, keyword; &resize .. _&resize: &resize ------- - Read-only - Produces: :ref:`integer` Windowing resize event code. .. literalinclude:: examples/resize.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/resize.icn` Sample run: .. command-output:: unicon -s resize.icn -x :cwd: examples .. seealso:: :ref:`Event` -------- .. index:: &row, keyword; &row .. _&row: &row ---- - Read-only - Produces: :ref:`integer` for the effective row of a windowing event mouse vertical position in text rows. .. literalinclude:: examples/row.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/row.icn` Sample run: .. command-output:: unicon -s row.icn -x :cwd: examples .. seealso:: :ref:`&col`, :ref:`&x`, :ref:`&y` -------- .. index:: &rpress, keyword; &rpress .. _&rpress: &rpress ------- - Read-only - Produces: the :ref:`integer` that indicates a right mouse button press event Right mouse button press event code. .. literalinclude:: examples/button-values.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/button-values.icn` Sample run: .. command-output:: unicon -s button-values.icn -x :cwd: examples .. seealso:: :ref:`&lpress`, :ref:`&lrelease`, :ref:`&ldrag` :ref:`&mpress`, :ref:`&mrelease`, :ref:`&mdrag` :ref:`&rpress`, :ref:`&rdrag` -------- .. index:: &rrelease, keyword; &rrelease .. _&rrelease: &rrelease --------- - Read-only - Produces: the :ref:`integer` that indicates a right mouse button release event code. right button release. .. literalinclude:: examples/button-values.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/button-values.icn` Sample run: .. command-output:: unicon -s button-values.icn -x :cwd: examples .. seealso:: :ref:`&lpress`, :ref:`&lrelease`, :ref:`&ldrag` :ref:`&mpress`, :ref:`&mrelease`, :ref:`&mdrag` :ref:`&rpress`, :ref:`&rdrag` -------- .. index:: &shift, keyword; &shift .. _&shift: &shift ------ - Read-only - Produces: :ref:`&null` or fail null if shift key was down on last X event, otherwise a reference to ``&shift`` with fail. .. literalinclude:: examples/shift.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/shift.icn` Sample run: .. command-output:: unicon -s shift.icn -x :cwd: examples .. seealso:: :ref:`&control`, :ref:`&meta` -------- .. index:: &source, keyword; &source .. _&source: &source ------- - Read-only - Produces the source :ref:`co-expression` of the :ref:`current <¤t>`\ ly running co-expression. .. literalinclude:: examples/source.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/source.icn` Giving: .. command-output:: unicon -s source.icn -x :cwd: examples .. seealso:: :ref:`¤t`, :ref:`&main` -------- .. index:: &storage, keyword; &storage .. _&storage: &storage -------- - Read-only - Generates 3 :ref:`integer`\ s A generator that produces 3 :ref:`Integer`\ s; the bytes used for the - static (always zero in Unicon, for backward compatibility) - string - block memory regions. .. literalinclude:: examples/storage.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/storage.icn` Giving: .. command-output:: unicon -s storage.icn -x :cwd: examples .. seealso:: :ref:`&allocated`, :ref:`&collections`, :ref:`®ions` -------- .. index:: &subject, keyword; &subject .. _&subject: &subject -------- - Read-write - Holds the current :ref:`string scanning` subject, always a :ref:`string`. When ``&subject`` is explicitly assigned a new string value, :ref:`&pos` is automatically set to 1. .. literalinclude:: examples/subject.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/subject.icn` Giving: .. command-output:: unicon -s subject.icn -x :cwd: examples .. seealso:: :ref:`&pos`, :ref:`string scanning` -------- .. index:: &time .. _&time: &time ----- - Read-only - Produces an :ref:`Integer` of the number of milliseconds (1/1000ths of a second) of CPU time that have elapsed since program execution began. .. literalinclude:: examples/time.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/time.icn` Giving: .. command-output:: unicon -s time.icn -x :cwd: examples This short program starts and completes in less than a tenth of a second under normal circumstances. Most runs of that example will show a relatively small number. Maybe as high as 100 if the system is extremely busy. .. seealso:: :ref:`&clock`, :ref:`&date`, :ref:`&dateline`, :ref:`&now`, -------- .. index:: &trace, keyword; &trace .. _&trace: &trace ------ - Read-write - Holds an :ref:`integer` that determines the level of procedure depth for execution tracing. Set to 0 (default) for no tracing, negative for infinite level tracing or to a desired depth. Unicon examines the environment variable ``TRACE`` on startup and there is also a ``-t`` compile time option to turn on tracing. .. literalinclude:: examples/trace.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/trace.icn` Giving: .. command-output:: unicon -s -t trace.icn -x :cwd: examples .. seealso:: :ref:`Execution monitoring` -------- .. index:: &ucase, keyword; &ucase .. _&ucase: &ucase ------ - Read-only - Produces .. literalinclude:: examples/ucase.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/ucase.icn` Giving: .. command-output:: unicon -s ucase.icn -x :cwd: examples .. seealso:: :ref:`&ascii`, :ref:`&cset`, :ref:`&digits`, :ref:`&lcase`, :ref:`&letters`, :ref:`Cset` -------- .. index:: &version, keyword; &version .. _&version: &version -------- - Read-only - Produces .. literalinclude:: examples/version.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/version.icn` Giving: .. command-output:: unicon -s version.icn -x :cwd: examples .. seealso:: :ref:`&features` -------- .. index:: &window, keyword; &window .. _&window: &window ------- - Read-only - Produces: :ref:`window` A variable containing a default window value. Most graphic functions will default to using ``&window`` when no initial ``window`` argument is given. .. literalinclude:: examples/window.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/window.icn` Sample run: .. command-output:: unicon -s window.icn -x :cwd: examples .. image:: images/window.png .. only:: html .. rst-class:: leftalign :download:`images/window.png` -------- .. index:: &x, keyword; &x .. _&x: &x --- - Read-only - Produces: :ref:`integer` Holds the horizontal mouse position. Set by calling :ref:`Event`. .. literalinclude:: examples/x.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/x.icn` Sample run: .. command-output:: unicon -s x.icn -x :cwd: examples .. seealso:: :ref:`&col`, :ref:`&y` -------- .. index:: &y, keyword; &y .. _&y: &y --- - Read-only - Produces: :ref:`integer` Holds the mouse vertical position after :ref:`Event` is called. .. literalinclude:: examples/y.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/y.icn` Sample run: .. command-output:: unicon -s y.icn -x :cwd: examples .. seealso:: :ref:`&x` .. only:: html .. -------- :ref:`genindex` | Previous: :doc:`functions` | Next: :doc:`preprocessor` |