========= Functions ========= .. Modified: 2019-10-20/21:06-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` Unicon has a large repertoire of built-in functions. A function is equivalent to a user defined :ref:`procedure `, in terms of syntax, argument management, and semantics. Functions cover a wide range of usage; from initializing data structures (``list`` and ``table``, for instance) to adding utility to Unicon (``left`` and ``right`` formatting), to supporting Execution Monitoring, and graphics, along with many other operations and system services that make Unicon what it is. Unicon Functions ================ There are 310 functions built into Unicon (as of 2016-08-20), but no builds will include all of them, as some few are platform dependent. This list includes all core and all optional functions that can be part of Unicon. .. note:: A lot of the reference material here is courtesy of Programming with Unicon, Second edition; by Clinton Jeffery, Shamim Mohamed, Jafar Al Gharaibeh, Ray Pereda, Robert Parlett. That book ships with the Unicon sources in the ``doc/book/`` subdirectory. .. index:: Abort, function; Abort .. _Abort: Abort ----- .. function:: Abort() :type: *pattern* :versionadded: Unicon 13. A :ref:`SNOBOL` inspired pattern matching operation. Causes immediate match failure, no further alternatives are attempted. .. literalinclude:: examples/Abort.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Abort.icn` Sample run: .. program-output:: unicon -s Abort.icn -x :cwd: examples -------- .. index:: abs, function; abs .. _abs: abs --- .. function:: abs(n : number) -> number :type: number, *integer* or *real* :argument n: numeric value :returns: absolute value The absolute value function. Produces the maximum of ``n`` and ``-n``, :math:`|n|`. .. literalinclude:: examples/abs.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/abs.icn` Sample run: .. program-output:: unicon -s abs.icn -x :cwd: examples -------- .. index:: acos, function; acos .. _acos: acos ---- .. function:: acos(r : real) -> real :type: real :argument r: real, :math:`-1 \leq r \leq 1` :returns: arc cosine of r, :math:`arccos(r)` Produces the inverse cosine of :math:`r`, result in :math:`\mathrm{radians}`. "arc" is an abbreviation of "arcus", inverse circular. .. literalinclude:: examples/acos.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/acos.icn` Sample run: .. program-output:: unicon -s acos.icn -x :cwd: examples .. todo:: fix plot range and domain handling Graphical plot: .. literalinclude:: examples/plot-arccos.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/plot-arccos.icn` .. command-output:: unicon -s plot-arccos.icn -x acos :cwd: examples .. image:: images/plot-acos.png .. only:: html .. rst-class:: leftalign :download:`images/plot-acos.png` .. seealso:: :ref:`asin`, :ref:`atan`, :ref:`sin`, :ref:`cos`, :ref:`tan` -------- .. index:: Active, function; Active .. _Active: Active ------ ``Active()`` : *window* ``Active()`` produces a Window value that has one or more events pending. If there are no events pending, ``Active()`` will block and wait. ``Active()`` produces different windows on each call to help ensure windows are serviced and don't starve for attention. .. literalinclude:: examples/Active.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Active.icn` Sample run: .. command-output:: unicon -s Active.icn -x :cwd: examples -------- .. index:: Alert, function; Alert .. _Alert: Alert ----- .. function:: Alert() -> window :type: *window* Produces a visual flash or audible sound to signal notable events. ``Alert()`` : *window* ``Alert()`` produces a visual flash or audible sound to signal notable events. .. literalinclude:: examples/Alert.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Alert.icn` Sample run: .. program-output:: unicon -s Alert.icn -x :cwd: examples -------- .. index:: any, function; any .. _any: any --- ``any(c, s, i, i)`` : *integer* or *fail* ``any()`` is a string scanning function that produces the first index, |i1| + 1, if *s*\ [|i1|:\ |i2|][1] is in the :ref:`cset ` *c*. It fails otherwise. *Match this character to any of the characters in the* :ref:`cset `. *s* defaults to :ref:`&subject` and the indexes default to the character at :ref:`&pos`. .. literalinclude:: examples/any.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/any.icn` Sample run: .. program-output:: unicon -s any.icn -x :cwd: examples -------- .. index:: Any, function; Any .. _AnyPattern: Any --- ``Any(c)`` : *pattern* ``Any(c)`` is the SNOBOL pattern that :ref:`any` is based on. Produces a :ref:`pattern` that matches the next subject character if it appears in the :ref:`cset `. .. literalinclude:: examples/Any.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Any.icn` Sample run: .. program-output:: unicon -s Any.icn -x :cwd: examples -------- .. index:: Arb, function; Arb .. _Arb: Arb --- ``Arb()`` : *success* ``Arb()`` is part of the SNOBOL inspired pattern feature set. Matches an arbitrary number of characters from the subject string. ``Arb()`` matches the shortest possible substring, which includes the empty string. Patterns on either side of ``Arb()`` determine what is actually matched. .. literalinclude:: examples/Arb.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Arb.icn` Sample run: .. program-output:: unicon -s Arb.icn -x :cwd: examples -------- .. index:: Arbno, function; Arbno .. _Arbno: Arbno ----- ``Arbno(pat)`` : *string* ``Arbno()`` matches an arbitrary number of the pattern ``pat``, including zero matches. .. literalinclude:: examples/Arbno.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Arbno.icn` Sample run: .. program-output:: unicon -s Arbno.icn -x :cwd: examples -------- .. index:: args, function; args .. _args: args ---- ``args(x, i)`` : *any* ``args(p)`` produces the number of arguments expected by procedure *p*. *This is sometimes referred to as the* ``arity`` *of a function*. For variable argument prototypes, ``args(p)`` will return a negative number, representing the final list argument position. E.g. .. sourcecode:: unicon procedure sample(x, y, z[]) write(args(sample)) end In that case, ``args(sample)`` returns ``-3``. ``args(C)`` produces the number of arguments in the current instance of :ref:`co-expression ` *C*. ``args(C, i)`` produces the *i*\ th argument within co-expression *C*. .. literalinclude:: examples/args.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/args.icn` Sample run: .. program-output:: unicon -s args.icn -x :cwd: examples args as common main argument ............................ Of special note with ``args``. Historically, many Unicon programs have defined main as .. sourcecode:: unicon procedure main(args) That definition will hide the ``args`` built-in function. When maintaining such a program, a developer can either rename the list variable passed into ``main`` (and all references), or fallback to using :ref:`proc ` to retrieve the built-in function. .. sourcecode:: unicon procedure main(args) write("arity of main: ", proc("args", 0)(main)) end -------- .. index:: array, function; array .. _array: array ----- .. attention:: multi-dimensional array referencing is a pending feature ``array()`` : *array* ``array()`` produces an efficient :ref:`list ` of homogeneous numeric data (:ref:`integer ` or :ref:`real `). .. literalinclude:: examples/array.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/array.icn` Sample run: .. program-output:: unicon -s array.icn -x :cwd: examples -------- .. index:: asin, function; asin .. _asin: asin ---- ``asin(r)`` : *real* ``asin(r)`` produces the arc sine of the angle *r*, given in radians as a :ref:`real `. .. literalinclude:: examples/asin.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/asin.icn` Sample run: .. program-output:: unicon -s asin.icn -x :cwd: examples Graphical plot: .. literalinclude:: examples/plot-arcfunction.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/plot-arcfunction.icn` .. command-output:: unicon -s plot-arcfunction.icn -x asin :cwd: examples .. image:: images/plot-asin.png .. only:: html .. rst-class:: leftalign :download:`images/plot-asin.png` .. seealso:: :ref:`acos`, :ref:`atan`, :ref:`sin`, :ref:`cos`, :ref:`tan` -------- .. index:: atan, function; atan .. _atan: atan ---- ``atan(r, r:1.0)`` : *real* ``atan(r)`` produces the arc tangent of *r*. ``atan(r1, r2)`` produces the arc tangent of *r1* and *r2*. Arguments and given in radians. .. literalinclude:: examples/atan.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/atan.icn` Sample run: .. command-output:: unicon -s atan.icn -x :cwd: examples .. todo: plot atan .. image:: images/no-image.png .. only:: html .. rst-class:: leftalign :download:`images/no-image.png` -------- .. index:: atanh, function; atanh .. _atanh: atanh ----- ``atanh(r)`` : *real* ``atanh(r)`` produces the inverse hyperbolic tangent of *r*. Argument given in radians. .. literalinclude:: examples/atanh.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/atanh.icn` Sample run: .. command-output:: unicon -s atanh.icn -x :cwd: examples .. todo:: plot image of atanh -------- .. index:: Attrib, function; Attrib .. _Attrib: Attrib ------ ``Attrib(T, i, x,...)`` : *any* [*Concurrency*] ``Attrib()`` read/write thread attributes for thread handle ``T``. .. literalinclude:: examples/Attrib.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Attrib.icn` Sample run: .. program-output:: unicon -s Attrib.icn -x :cwd: examples -------- .. index:: Bal, function; Bal .. _BalPattern: Bal --- ``Bal()`` : *type* [*Patterns*] ``Bal()`` SNOBOL style balanced parentheses pattern match .. literalinclude:: examples/Bal.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Bal.icn` Sample run: .. program-output:: unicon -s Bal.icn -x :cwd: examples -------- .. index:: bal, function; bal .. _bal: bal --- ``bal(c1:&cset, c2:')', c3:')', s, i1, i2)`` : *integer*\* ``bal()`` is a string scanning function that generates the integer positions in ``s`` where a member of ``c1`` in ``s[i1:i2]`` is balanced with respect to ``c2`` and ``c3``. .. literalinclude:: examples/bal.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/bal.icn` Sample run: .. program-output:: unicon -s bal.icn -x :cwd: examples -------- .. index:: Bg, function; Bg .. _Bg: Bg -- ``Bg(w, s)`` : *string* ``Bg(w)`` retrieves the background colour of the window, ``w``. ``Bg(w, s)`` attempts to set the background colour by name, rgb or :ref:`mutable colour ` value. Fails if the background cannot be set to the specified colour. .. literalinclude:: examples/Bg.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Bg.icn` Sample run: .. command-output:: unicon -s Bg.icn -x :cwd: examples .. image:: images/Bg.png .. only:: html .. rst-class:: leftalign :download:`images/Bg.png` -------- .. index:: Break, function; Break .. _Break-function: Break ----- ``Break(c)`` : *string*? [*Patterns*] ``Break(c)`` matches any characters in the subject string up to but not including any of the characters in the :ref:`cset ` ``c``. .. literalinclude:: examples/Break.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Break.icn` Sample run: .. program-output:: unicon -s Break.icn -x :cwd: examples See :ref:`Breakx`. -------- .. index:: Breakx, function; Breakx .. _Breakx: Breakx ------ ``Breakx(c)`` : *string*? ``Breakx(c)`` is an extended :ref:`Break `. It will match any characters in the subject string up to any of the subject characters in the :ref:`cset`, ``c``. ``Breakx`` will search beyond the break position for any possible longer match if resumed due to subsequent pattern failure. This means that ``Breakx`` might return characters in ``c``, unlike the :ref:`Break ` that will not. .. literalinclude:: examples/Breakx.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Breakx.icn` Sample run: .. program-output:: unicon -s Breakx.icn -x :cwd: examples See :ref:`Break `. -------- .. index:: callout, function; callout .. _callout: callout ------- ``callout()`` : *type* .. todo:: entry for function callout ``callout()`` .. pending literalinclude:: examples/callout.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/callout.icn` Sample run: .. pending program-output:: unicon -s callout.icn -x :cwd: examples -------- .. index:: center, function; center .. _center: center ------ ``center(s, i:1, s2:" ")`` : *string* ``center()`` produces a centred string, ``s`` within width ``i``, padded on either side by ``s2``. If ``i`` is less than the size of ``s``, the centre ``i`` characters of ``s`` are produced. .. literalinclude:: examples/center.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/center.icn` Sample run: .. program-output:: unicon -s center.icn -x :cwd: examples -------- .. index:: char, function; char .. _char: char ---- ``char(i)`` : *string* ``char()`` produces a string consisting of the character encoded by the integer ``i``. Unicon is :ref:`ASCII` based. ``char(0)`` is the null byte, the first ASCII character, and anything outside of the range 0-255 will cause a runtime error. .. literalinclude:: examples/char.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/char.icn` This sample run fails with a runtime error when asking for ``char(257)``, an out of range integer. .. program-output:: unicon -s char.icn -x :cwd: examples :returncode: 1 -------- .. index:: chdir, function; chdir .. _chdir: chdir ----- ``chdir(s)`` : *string* ``chdir(s)`` changes the current working directory to ``s``. ``s`` will be operating system dependent. ``chdir()`` produces the current working directory as a :ref:`string ` .. literalinclude:: examples/chdir.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/chdir.icn` Sample run: .. program-output:: unicon -s chdir.icn -x :cwd: examples -------- .. index:: chmod, function; chmod .. _chmod: chmod ----- ``chmod(f, m)`` : *?* ``chmod()`` changes a file access mode. ``f`` can be a string name or open file handle. Mode ``m`` is encoded with +/- (permit/deny) - r, read - w, write - x, execute Who can access is also encoded by - u, user, (owner) of the file - g, group membership of the file - o, other - a, all Mode bits also include - s, setuid or setgid for allowing the process to assume a uid/gid when executing the resource - t, sticky bit. Asks the kernel to retain the process image in memory when executing the resource terminates. Sticky bits on the directory prevents renaming, moving or deleting the files in the directory if not the owning user. POSIX also allows a numeric, octal value for mode settings. rwx as bit 2, 1, 0 of an octal value. 8r7 being 2r111, rwx, 8r5 being 2r101, rx, no w, and 8r0 is no permission in that grouping. Values are by owner, group and other, 3 octal digits. 8r707 is rwx for user, no group access, rwx for other. *A poor example; not sharing with friends, but allowing outsiders*. .. literalinclude:: examples/chmod.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/chmod.icn` Sample run: .. program-output:: unicon -s chmod.icn -x :cwd: examples -------- .. index:: chown, function; chown .. _chown: chown ----- ``chown(f, u, g)`` : *null* ``chown()`` change or retrieve (if permitted) the owner/group of the filename ``f``. ``u`` and ``g`` can be strings or numeric identifiers as known by the operating system. .. literalinclude:: examples/chown.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/chown.icn` Sample run, very likely to fail without permissions. .. program-output:: unicon -s chown.icn -x :cwd: examples -------- .. index:: chroot, function; chroot .. _chroot: chroot ------ ``chroot(s)`` : *null* ``chroot(f)`` changes the root directory, ``/``, of the current filesystem to ``f``. ``chroot`` was an early Unix attempt at protecting filesystems. Still in use by some applications, web servers for instance, to ensure that files outside of a permissible tree are inaccessible by normal users. Modern equivalents BSD jails and new LCX/LXD Linux container technology have superseded use of ``chroot``. This is normally a privileged operation. .. literalinclude:: examples/chroot.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/chroot.icn` Sample run, very likely to fail without permissions. .. program-output:: unicon -s chroot.icn -x :cwd: examples -------- .. index:: classname, function; classname .. _classname: classname --------- ``classname(r)`` : *string* ``classname(r)`` will produce the name of the :ref:`class ` of ``r``. .. literalinclude:: examples/classname.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/classname.icn` This sample run includes the linkage details to give an example of how Unicon classes are managed. .. command-output:: unicon classname.icn -x :cwd: examples -------- .. index:: Clip, function; Clip .. _Clip: Clip ---- ``Clip(w:&window, x:0, y:0, wid:0, h:0)`` : *window* [*graphics*] ``Clip()`` sets a clipping rectangle for a window. Top left corner starts at ``x``, ``y``. If width ``wid`` is 0, the clipping region extends from ``x`` to the right side of the window. When height ``h`` is 0, the clip region extends from ``y`` to the bottom of the window. Graphic writes outside of the clipping region will not occur. .. literalinclude:: examples/Clip.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Clip.icn` Sample run: .. command-output:: unicon -s Clip.icn -x :cwd: examples .. image:: images/Clip.png .. only:: html .. rst-class:: leftalign :download:`images/Clip.png` -------- .. index:: Clone, function; Clone .. _Clone: Clone ----- ``Clone(w1, attributes...)`` : *window* [*graphics*] ``Clone()`` creates a window that couples the drawing canvas of ``w1`` with a new graphics context. Attributes from ``w1`` are inherited, overridden by any attributes specified in the ``Clone()`` function. .. literalinclude:: examples/Clone.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Clone.icn` Sample run: .. command-output:: unicon -s Clone.icn -x :cwd: examples .. image:: images/Clone.png .. only:: html .. rst-class:: leftalign :download:`images/Clone.png` -------- .. index:: close, function; close .. _close: close ----- ``close(x)`` : *file* | *integer* ``close()`` a file, pipe, window, network, message or database connection. Resources are freed. Closing a window will cause it to disappear, but will remain active until all open bindings are closed. If a pipe or network connection is closed, an integer exit status is returned, otherwise the value produced is the closed file handle. .. literalinclude:: examples/close.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/close.icn` Sample run: .. program-output:: unicon -s close.icn -x :cwd: examples -------- .. index:: cofail, function; cofail .. _cofail: cofail ------ ``cofail(CE)`` : *any* ``cofail(ce)`` activates :ref:`co-expression ` *ce*, transmitting failure instead of a result. .. literalinclude:: examples/cofail.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/cofail.icn` Sample run (ends with an error): .. program-output:: unicon -s cofail.icn -x :cwd: examples :returncode: 1 -------- .. index:: collect, function; collect .. _collect: collect ------- ``collect(i1:0, i2:0)`` : *null* ``collect()`` runs the garbage collector to ensure that ``i2`` bytes are available in region ``i1``, where ``i1`` can be: - 0, no region in particular - 1, static region - 2, string region - 3, block region .. literalinclude:: examples/collections.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/collections.icn` Sample run: .. program-output:: unicon -s collections.icn -x :cwd: examples -------- .. index:: Color, function; Color .. _Color: Color ----- ``Color(w, i, s,...)`` : *window* [*graphics*] ``Color(w, i)`` produces the current setting of mutable colour ``i``. ``Color(w, i, s,...)`` set the colour map entries referenced by ``i[j]`` to the colours specified by ``s[j]``.. .. literalinclude:: examples/Color.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Color.icn` Sample run: .. command-output:: unicon -s Color.icn -x :cwd: examples .. image:: images/Color.png .. only:: html .. rst-class:: leftalign :download:`images/Color.png` -------- .. index:: ColorValue, function; ColorValue .. _ColorValue: ColorValue ---------- ``ColorValue(w, s)`` : *string* [*graphics*] ``ColorValue(w, s)`` converts the string colour name ``s`` into a string with three 16-bit integer values representing the RGB components. ``ColorValue()`` fails if the string ``s`` is not a recognized name, or valid RGB decimal or hex encoded colour. .. literalinclude:: examples/ColorValue.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/ColorValue.icn` Sample run: .. command-output:: unicon -s ColorValue.icn -x :cwd: examples .. image:: images/ColorValue.png .. only:: html .. rst-class:: leftalign :download:`images/ColorValue.png` -------- .. index:: condvar, function; condvar .. _condvar: condvar ------- ``condvar(mutex)`` : *condition variable* ``condvar()`` creates a new condition variable for use with :ref:`wait` or :ref:`signal`. The optional ``mutex`` argument associated the condition variable with the mutually exclusive lock. The returned variable can be used with ``wait(cv)`` to block the current thread until a ``signal(cv)`` is invoked (from another thread). .. literalinclude:: examples/condvar.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/condvar.icn` Sample run: .. program-output:: unicon -s condvar.icn -x :cwd: examples -------- .. index:: constructor, function; constructor .. _constructor: constructor ----------- ``constructor(s, ...)`` : *procedure* ``constructor(label, field, field, ...)`` creates a new :ref:`record` type, named ``label`` with fields named from the subsequent arguments (as strings). A constructor procedure is returned for creating records of this type. .. literalinclude:: examples/constructor.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/constructor.icn` Sample run: .. program-output:: unicon -s constructor.icn -x :cwd: examples -------- .. index:: copy, function; copy .. _copy: copy ---- ``copy(any)`` : *any* ``copy(x)`` produces a copy of ``x``. For immutable types, this is a no-op. For structures, a one-level deep copy of the object is made. The :ref:`IPL ` contains a ``deepcopy`` procedure when a nested structure needs to be copied. .. literalinclude:: examples/copy.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/copy.icn` Sample run: .. program-output:: unicon -s copy.icn -x :cwd: examples -------- .. index:: CopyArea, function; CopyArea .. _CopyArea: CopyArea -------- ``CopyArea(w1, w2, x:0, y:0, wid:0, h:0, x2:0, y2:0)`` : *window* [*graphics*] ``CopyArea()`` copies the rectangle ``x,y,wid,h`` from ``w1`` to ``x2,y2`` of ``w2``. .. literalinclude:: examples/CopyArea.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/CopyArea.icn` Sample run: .. command-output:: unicon -s CopyArea.icn -x :cwd: examples .. image:: images/CopyArea.png .. only:: html .. rst-class:: leftalign :download:`images/CopyArea.png` -------- .. index:: cos, function; cos .. _cos: cos --- ``cos(r)`` : *real* ``cos(r)`` returns the Cosine of the given angle, *r* (in radians) .. literalinclude:: examples/cos.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: leftalign :download:`examples/cos.icn` Sample run: .. program-output:: unicon -s cos.icn -x :cwd: examples Graphical plot: .. literalinclude:: examples/plot-function.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/plot-function.icn` .. command-output:: unicon -s plot-function.icn -x cos :cwd: examples .. image:: images/plot-cos.png .. only:: html .. rst-class:: leftalign :download:`images/plot-cos.png` -------- .. index:: Couple, function; Couple .. _Couple: Couple ------ ``Couple(w1, w2)`` : *window* [*graphics*] ``Couple(w1, w2)`` produces a new value that binds the window associated with *w1* to the graphics context of *w2*. .. literalinclude:: examples/Couple.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Couple.icn` Sample run: .. program-output:: unicon -s Couple.icn -x :cwd: examples .. image:: images/Couple.png .. only:: html .. rst-class:: leftalign :download:`images/Couple.png` -------- .. index:: crypt, function; crypt .. _crypt: crypt ----- ``crypt(s1, s2)`` : *string* [*POSIX*] ``crypt(s1, s2)`` encrypts the password ``s1`` using the salt ``s2``. The first two characters of the result string will be the salt. .. literalinclude:: examples/crypt.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/crypt.icn` Sample run: .. program-output:: unicon -s crypt.icn -x :cwd: examples A word of warning. Modern computers are fast. Short passwords are very susceptible to brute force trials, especially when a bad actor gets hold of a copy of the encrypted form. It makes it easy to run through millions of attempts, comparing guesses that are ``crypt``\ ed to the encrypted form. Do yourself a favour and use strong passwords. Every letter and symbol makes it 96 times harder\ [#pass]_ to guess (assuming printable ASCII character codes are used). One character, 96 tries maximum, two characters, 96 * 96 tries. When you get to eight, the numbers start to be reasonable for thwarting casual bad actors. 7,213,895,789,838,336 potential combinations. Modern machines can attempt millions of brute force guesses per second. .. [#pass] That's over simplifying the issue. There are highly sophisticated algorithms in play now, with many common human behavioural aspects programmed in. And machines are fast. -------- .. index:: cset, function; cset .. _cset-function: cset ---- ``cset(any)`` : *cset*? ``cset(x)`` attempts to convert ``x`` to a :ref:`cset `. Fails if the conversion can not be performed. .. literalinclude:: examples/cset-function.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/cset-function.icn` Sample run: .. program-output:: unicon -s cset-function.icn -x :cwd: examples -------- .. index:: ctime, function; ctime .. _ctime: ctime ----- ``ctime(i)`` : *string* ``ctime(i)`` converts the integer time ``i``, given in seconds since the epoch of Jan 1st, 1970 00:00:00 Greenwich Mean Time, into a string using the local timezone. .. literalinclude:: examples/ctime.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/ctime.icn` Sample run: .. program-output:: unicon -s ctime.icn -x :cwd: examples .. seealso:: :ref:`&clock`, :ref:`&dateline`, :ref:`gtime`, :ref:`&now` -------- .. index:: dbcolumns, function; dbcolumns .. _dbcolumns: dbcolumns --------- ``dbcolumns(D, s)`` : *list* ``dbcolumns(db, tablename)`` returns a :ref:`list` of :ref:`record` data. .. literalinclude:: examples/dbcolumns.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/dbcolumns.icn` Sample run: .. program-output:: unicon -s dbcolumns.icn -x :cwd: examples ``dbcolumns`` is one of the reflective ODBC functions available to a Unicon programmer. As can be seen in the example above, it can be used for self-documenting purposes (make a run to get all the record fields, then code to suit), or for writing utility applications with user defined naming. See :ref:`odbc` for details on the example setup. -------- .. index:: dbdriver, function; dbdriver .. _dbdriver: dbdriver -------- ``dbdriver(D)`` : *record* ``dbdriver(db)`` produces a record of current ODBC driver information:: record driver(name, ver, odbcver, connections, statements, dsn) Or, write a program and look at the data fields using the reflective properties inherent in Unicon. .. literalinclude:: examples/dbdriver.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/dbdriver.icn` Sample run: .. command-output:: unicon -s dbdriver.icn -x :cwd: examples See :ref:`odbc` for details on the example ODBC setup. -------- .. index:: dbkeys, function; dbkeys .. _dbkeys: dbkeys ------ ``dbkeys(D, string)`` : *list* [*ODBC*] ``dbkeys(db, tablename)`` produces a list of record pairs (col, seq) containing information about the primary keys in the given table. .. literalinclude:: examples/dbkeys.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/dbkeys.icn` Sample run: .. command-output:: unicon -s dbkeys.icn -x :cwd: examples -------- .. index:: dblimits, function; dblimits .. _dblimits: dblimits -------- ``dblimits(D)`` : *record* [*ODBC*] ``dblimits(db)`` produces a record that contains the upper bounds of many parameters associated with the given database. .. literalinclude:: examples/dblimits.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/dblimits.icn` Sample run: .. command-output:: unicon -s dblimits.icn -x :cwd: examples -------- .. index:: dbproduct, function; dbproduct .. _dbproduct: dbproduct --------- ``dbproduct(D)`` : *record* [*ODBC*] ``dbproduct(db)`` produces a record the gives the name and version of the DBMS product containing the given database. .. literalinclude:: examples/dbproduct.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/dbproduct.icn` Sample run: .. command-output:: unicon -s dbproduct.icn -x :cwd: examples -------- .. index:: dbtables, function; dbtables .. _dbtables: dbtables -------- ``dbtables(D)`` : *list* [*ODBC*] ``dbtables(db)`` returns a list of records that describe all the tables in the given database. .. literalinclude:: examples/dbtables.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/dbtables.icn` Sample run: .. command-output:: unicon -s dbtables.icn -x :cwd: examples -------- .. index:: delay, function; delay .. _delay: delay ----- ``delay(i)`` : *null* ``delay(i)`` pauses a program for at least *i* milliseconds. .. literalinclude:: examples/delay.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/delay.icn` A sample run: .. command-output:: unicon -s delay.icn -x :cwd: examples -------- .. index:: delete, function; delete .. _delete: delete ------ ``delete(x1, x2,...)`` : *x1* ``delete(x1, x2,...)`` removes one or more elements *x2, [x3....]* from structure *x1*. *x1* can be list, set, table, DBM database, or POP connection. .. literalinclude:: examples/delete.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/delete.icn` Sample run: .. command-output:: unicon -s delete.icn -x :cwd: examples -------- .. index:: detab, function; detab .. _detab: detab ----- ``detab(string, i:9,...)`` : *string* ``detab(s, i,...)`` replaces tabs with spaces with stops are columns indicated by the second and following arguments, which must be integers. Tabs stops are extended using the interval between the last two specified stops. .. literalinclude:: examples/detab.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/detab.icn` Sample run: .. command-output:: unicon -s detab.icn -x :cwd: examples -------- .. index:: display, function; display .. _display: display ------- ``display(i:&level, f:&errout, CE:¤t)`` : *null* ``display()`` writes the local variables of the *i* most recent procedure activations from co-expression *CE*, plus all global variables, to the file *f* .. literalinclude:: examples/display.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/display.icn` Sample run: .. command-output:: unicon -s display.icn -x :cwd: examples -------- .. index:: DrawArc, function; DrawArc .. _DrawArc: DrawArc ------- ``DrawArc(w, x, y, wid, h, a1:0.0, a2:&pi*2, ...)`` : *window* [*graphics*] ``DrawArc(w, x, y, width, height, a1, a2, ...)`` draws arcs or ellipses. Each arc is defined by 4 given and 2 derived coordinates. *x*, *y*, *width, *height* define a bounding rectangle around the arc; the centre of the arc is the point (*x*\ +(*width*)/2, *y*\ +(*height*)/2. Angle *a1* is the starting position of the arc. The angle *a2* is not an end position but specifies the direction and extent of the arc. Angles are given in radians. Multiple arcs can be drawn with one call to the function. .. literalinclude:: examples/DrawArc.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawArc.icn` Sample run: .. command-output:: unicon -s DrawArc.icn -x :cwd: examples .. image:: images/DrawArc.png .. only:: html .. rst-class:: leftalign :download:`images/DrawArc.png` -------- .. index:: DrawCircle, function; DrawCircle .. _DrawCircle: DrawCircle ---------- ``DrawCircle(w, x, y, radius, a1:0.0, a2:&pi*2, ...)`` : *window* [*graphics*] ``DrawCircle(w, x, y, r, a1, a2)`` draws a circle centred at *x*\ ,\ *y*. Otherwise similar to :ref:`DrawArc` with width equal to height. .. literalinclude:: examples/DrawCircle.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawCircle.icn` Sample run: .. command-output:: unicon -s DrawCircle.icn -x :cwd: examples .. image:: images/DrawCircle.png .. only:: html .. rst-class:: leftalign :download:`images/DrawCircle.png` -------- .. index:: DrawCube, function; DrawCube .. _DrawCube: DrawCube -------- ``DrawCube(w, x, y, z, len, ...)`` : *record* [*3D graphics*] ``DrawCube(w, x, y, z, len)`` draws a cube with sides of length *len* at the position *x*\, *y*\, *z* on the 3D window *w*. The display list element is returned. This procedure fails if the graphic context attribute *dim* is set to 2. .. todo:: Not working .. literalinclude:: examples/DrawCube.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawCube.icn` Sample run: .. skipped command-output:: unicon -s DrawCube.icn -x :cwd: examples .. image:: images/DrawCube.png .. only:: html .. rst-class:: leftalign :download:`images/DrawCube.png` -------- .. index:: DrawCurve, function; DrawCurve .. _DrawCurve: DrawCurve --------- ``DrawCurve(w, x1, y1, ...)`` : *window* ``DrawCurve(w, x1,y1, x2,y2, x3,y3, ...)`` draws a smooth curve between each *x,y* pair in the argument list. If the first and last point are the same, the curve is smoothed and closed at that point. .. literalinclude:: examples/DrawCurve.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawCurve.icn` Sample run: .. command-output:: unicon -s DrawCurve.icn -x :cwd: examples .. image:: images/DrawCurve.png .. only:: html .. rst-class:: leftalign :download:`images/DrawCurve.png` -------- .. index:: DrawCylinder, function; DrawCylinder .. _DrawCylinder: DrawCylinder ------------ ``DrawCylinder(w, x,y,z, h, r1,r2,...)`` : *record* [*3D graphics*] ``DrawCylinder(w, x,y,z, h, rt,rb)`` draws a cylinder with a top radius *rt*, a bottom with radius *rb*, a height *h* centred at *x,y,z* on window *w*. A display list element is returned. ``DrawCylinder`` fails if window attribute ``dim`` is set to 2. .. literalinclude:: examples/DrawCylinder.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawCylinder.icn` Sample output: .. skipped command-output:: unicon -s DrawCylinder.icn -x :cwd: examples .. image:: images/DrawCylinder.png .. only:: html .. rst-class:: leftalign :download:`images/DrawCylinder.png` -------- .. index:: DrawDisk, function; DrawDisk .. _DrawDisk: DrawDisk -------- ``DrawDisk(w, x,y,z, r1,r2, a1,a2,...)`` : *record* ``DrawDisk(w, x,y,z, ri, ro, astart, asweep)`` draws a (partial) disk centred at *x,y,z*, with an inner circle of radius *ri*, an outer circle of radius *ro*, a starting angle of *astart*, and a sweeping angle of *asweep*, on window *w*. The parameters *a1* and *a2* are optional, and a full disk is rendered if they are not provided. The display list element is returned. .. literalinclude:: examples/DrawDisk.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawDisk.icn` Sample output: .. skipped command-output:: unicon -s DrawDisk.icn -x :cwd: examples .. image:: images/DrawDisk.png .. only:: html .. rst-class:: leftalign :download:`images/DrawDisk.png` -------- .. index:: DrawImage, function; DrawImage .. _DrawImage: DrawImage --------- ``DrawImage(w, x, y, s)`` : *window* ``DrawImage(w, x, y, s)`` draws image string *s* at *x,y* in window *w*. Unicon image strings are of the form "*width*, *palette*, *pixels*". .. literalinclude:: examples/DrawImage.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawImage.icn` Sample run: .. command-output:: unicon -s DrawImage.icn -x :cwd: examples .. image:: images/DrawImage.png .. only:: html .. rst-class:: leftalign :download:`images/DrawImage.png` -------- .. index:: DrawLine, function; DrawLine .. _DrawLine: DrawLine -------- ``DrawLine(w, x1, y1, z1, ...)`` : *window | list* [*graphics/3D graphics*] ``DrawLine(w, x1, y1,...,xn,yn)`` draws lines between each adjacent *x*\, *y* pair of arguments. In 3D, ``DrawLine`` takes from 2-4 coordinate per vertex and returns a list the represents the lines on the display list *for refresh purposes*. .. literalinclude:: examples/DrawLine.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawLine.icn` Sample run: .. command-output:: unicon -s DrawLine.icn -x :cwd: examples .. image:: images/DrawLine.png .. only:: html .. rst-class:: leftalign :download:`images/DrawLine.png` A more sophisticated line drawing example is in the :ref:`GPI` book, pages 73-75. Using ``DrawLine`` to produce polygons (see also :ref:`DrawPolygon`) and star shapes; with a single function that depends on a ``skip`` value to draw the stars. .. literalinclude:: examples/linedrawing.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/linedrawing.icn` With a run sample of: .. command-output:: unicon -s linedrawing.icn -x :cwd: examples .. image:: images/linedrawing.png .. only:: html .. rst-class:: leftalign :download:`images/linedrawing.png` -------- .. index:: DrawPoint, function; DrawPoint .. _DrawPoint: DrawPoint --------- ``DrawPoint(w, x1,y1, ...)`` : *window* [list] ``DrawPoint(w, x1,y1,...,xn,yn)`` draws points given by *x,y* pairs on window *w*. With 3D graphics, ``DrawPoint()`` takes from 2 to 4 coordinates per vertex and returns the list that represents the points on the display list for refresh purposes. .. literalinclude:: examples/DrawPoint.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawPoint.icn` Sample run: .. command-output:: unicon -s DrawPoint.icn -x :cwd: examples .. image:: images/DrawPoint.png .. only:: html .. rst-class:: leftalign :download:`images/DrawPoint.png` .. todo:: 3D points With 3D graphics, points are x,y,z .. literalinclude:: examples/DrawPoint-3D.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawPoint-3D.icn` Sample output: .. skipped command-output:: unicon -s DrawPoint-3D.icn -x :cwd: examples .. image:: images/DrawPoint-3D.png .. only:: html .. rst-class:: leftalign :download:`images/DrawPoint-3D.png` -------- .. index:: DrawPolygon, function; DrawPolygon .. _DrawPolygon: DrawPolygon ----------- ``DrawPolygon(w, x1,y1[,z1], ..., xn,yn[,zn])`` : *window | list* ``DrawPolygon(w, x1,y1, x2,y2, xn,yn)`` draws a polygon connecting each *x,y* pair (in 2D). In 3D, ``DrawPolygon()`` takes from 2 to 4 coordinates per vertex and returns the list that represents the polygon on the display list. .. literalinclude:: examples/DrawPolygon.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawPolygon.icn` Sample run: .. command-output:: unicon -s DrawPolygon.icn -x :cwd: examples .. image:: images/DrawPolygon.png .. only:: html .. rst-class:: leftalign :download:`images/DrawPolygon.png` .. todo:: 3D polygons -------- .. index:: DrawRectangle, function; DrawRectangle .. _DrawRectangle: DrawRectangle ------------- ``DrawRectangle(w, x1,y1, wid1, h1, ...)`` : *window* ``DrawRectangle(w, x, y, width, hieght)`` draws a rectangle with a top right corner of *x,y* and a perceived width and height. Actual rectangle is *width+1* pixels wide, and *height+1* pixels high. .. literalinclude:: examples/DrawRectangle.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawRectangle.icn` Sample run: .. command-output:: unicon -s DrawRectangle.icn -x :cwd: examples .. image:: images/DrawRectangle.png .. only:: html .. rst-class:: leftalign :download:`images/DrawRectangle.png` -------- .. index:: DrawSegment, function; DrawSegment .. _DrawSegment: DrawSegment ----------- ``DrawSegment(w, x1,y1[,z1], x2,y2[,z2],...)`` : *window|list* ``DrawSegment(w, x1,y1, x2,y2,...)`` draws lines between alternating *x,y* pairs in the argument list. In 3D, ``DrawSegment`` takes from 2 to 4 coordinates per vertex and returns the list that represents the segments. .. literalinclude:: examples/DrawSegment.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawSegment.icn` Sample run: .. command-output:: unicon -s DrawSegment.icn -x :cwd: examples .. image:: images/DrawSegment.png .. only:: html .. rst-class:: leftalign :download:`images/DrawSegment.png` -------- .. index:: DrawSphere, function; DrawSphere .. _DrawSphere: DrawSphere ---------- ``DrawSphere(w, x,y,z, r,...)`` : *record* [*Graphics, 3D*] ``DrawSphere(w, x,y,z, r,...)`` draws a sphere with radius *r* centred at *(x,y,z)* on 3D window *w*. The display list is returned. Fails when used on windows with :ref:`WAttrib` "dim=2". .. literalinclude:: examples/DrawSphere.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawSphere.icn` Sample output: .. skipped command-output:: unicon -s DrawSphere.icn -x :cwd: examples .. image:: images/DrawSphere.png .. only:: html .. rst-class:: leftalign :download:`images/DrawSphere.png` -------- .. index:: DrawString, function; DrawString .. _DrawString: DrawString ---------- ``DrawString(w, x1, y1, s1,...)`` : *window* ``DrawString(w, x, y, s)`` draws string *s* on window *w* at *x*\, *y*, without effecting the current text cursor position. When used with ``drawop=reverse`` it is possible to draw erasable test. No background is drawn, only the actual pixels of the characters. .. literalinclude:: examples/DrawString.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawString.icn` Sample run: .. command-output:: unicon -s DrawString.icn -x :cwd: examples .. image:: images/DrawString.png .. only:: html .. rst-class:: leftalign :download:`images/DrawString.png` -------- .. index:: DrawTorus, function; DrawTorus .. _DrawTorus: DrawTorus --------- ``DrawTorus(w, x,y,z, r1,r2,...)`` : *record* ``DrawTorus(w, x,y,z, ri, ro)`` draws a torus with inner radius *ri*, outside radius *r2*, centred at *x,y,z* on 3D window *w*. The display list element is returned. ``DrawTorus`` fails if the window attribute ``dim`` is set to 2. .. literalinclude:: examples/DrawTorus.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/DrawTorus.icn` Sample output: .. skipped command-output:: unicon -s DrawTorus.icn -x :cwd: examples .. image:: images/DrawTorus.png .. only:: html .. rst-class:: leftalign :download:`images/DrawTorus.png` -------- .. index:: dtor, function; dtor .. _dtor: dtor ---- ``dtor(r)`` : *real* ``dtor(r)`` produces the equivalent of *r* degrees, in radians. .. literalinclude:: examples/dtor.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/dtor.icn` Sample run: .. command-output:: unicon -s dtor.icn -x :cwd: examples -------- .. index:: entab, function; entab .. _entab: entab ----- ``entab(s, i:9,...)`` : *string* ``entab(s, i,...)`` replaces spaces with tabs, with stops at the columns indicated. Tab stops are extended using the interval between the last two specified stops. Defaults give 8 space tabs, with stops at 1, 9, 17, etcetera. .. literalinclude:: examples/entab.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/entab.icn` Sample run: .. command-output:: unicon -s entab.icn -x | cat -T :cwd: examples :shell: -------- .. index:: EraseArea, function; EraseArea .. _EraseArea: EraseArea --------- ``EraseArea(w, x:0,y:0, wid:0, h:0, ...)`` : *window* ``EraseArea(w, x,y, width,height)`` erases a rectangular area to the background colour. If *width* is 0, the region extends from *x* to the right. If *height* is 0, the region extends from *y* to the bottom. In 3D, ``EraseArea(w)`` clears the contents of the entire window. .. literalinclude:: examples/EraseArea.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/EraseArea.icn` Sample run: .. command-output:: unicon -s EraseArea.icn -x :cwd: examples .. image:: images/EraseArea.png .. only:: html .. rst-class:: leftalign :download:`images/EraseArea.png` -------- .. index:: errorclear, function; errorclear .. _errorclear: errorclear ---------- ``errorclear()`` : *null* ``errorclear()`` resets the keywords :ref:`&errornumber`, :ref:`&errortext`, :ref:`&errorvalue` to indicate that no error is present. .. literalinclude:: examples/errorclear.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/errorclear.icn` A contrived example: .. command-output:: unicon -s errorclear.icn -x :cwd: examples -------- .. index:: Event, function; Event .. _Event: Event ----- ``Event(w, i:infinity)`` : *string|integer* ``Event(w, i)`` produces the next event available for window *w*. If no events are available, ``Event()`` waits *i* milliseconds. Keyboard events are returned as :ref:`string` while mouse events are returned as :ref:`integer`. When an event is retrieved the keywords :ref:`&x`, :ref:`&y`, :ref:`&row`, :ref:`&col`, :ref:`&interval`, :ref:`&control`, :ref:`&shift`, and :ref:`&meta` are also set. If the 3D attribute "pick=on" is active, :ref:`&pick` is also set. ``Event()`` fails is there is a timeout before an event is available. .. literalinclude:: examples/Event.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Event.icn` Sample run, right-click while holding down shift and control keys: .. command-output:: unicon -s Event.icn -x :cwd: examples -------- .. index:: eventmask, function; eventmask .. _eventmask: eventmask --------- ``eventmask(CE, cset, T)`` : *cset | null* ``eventmask(ce)`` returns the event mask associated with the program that created *ce*, or :ref:`&null` if there is no event mask. ``eventmask(ce, cs)`` sets that program's event mask to *cs*. These settings control the :ref:`execution monitoring` triggers of a running program. A third :ref:`table` argument, *T*, specifies a different value mask for each event code in the table; handy for filtering virtual machine instructions (which is event code ``E_Opcode`` as defined in ``evdefs.icn``). Individual instruction codes are defined in ``opdefs.icn`` a file designed to be used with :ref:`$include`. .. literalinclude:: examples/eventmask.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/eventmask.icn` Sample run: .. command-output:: unicon -s eventmask.icn -x :cwd: examples .. seealso:: :ref:`execution monitoring` -------- .. index:: EvGet, function; EvGet .. _EvGet: EvGet ----- ``EvGet(c, flag)`` : *string* [*Execution Monitoring*] ``EvGet(c, flag)`` activates a program being monitored until an event in :ref:`cset ` mask *c* occurs. Normally ``EvGet()`` returns a one character event code. *c* default is all events encoded in :ref:`eventmask `. *flag* controls the handling of out-of-band data, a null flag rejects out-of-band event data. .. literalinclude:: examples/EvGet.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/EvGet.icn` Sample run: .. command-output:: unicon -s EvGet.icn -x :cwd: examples -------- .. index:: EvSend, function; EvSend .. _EvSend: EvSend ------ ``EvSend(i, x, CE)`` : *any* ``EvSend(c, v, ce)`` transmits event code *c* with value *v* to a monitored co-expression *ce*. .. literalinclude:: examples/EvSend.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/EvSend.icn` Sample run (DANGEROUS, as this author doesn't get the whole picture yet): .. command-output:: unicon -s EvSend.icn -x :cwd: examples -------- .. index:: exec, function; exec .. _exec: exec ---- ``exec(string, string,...)`` : *null* [*POSIX*] ``exec(s, arg0, arg1,...)`` replaces the currently executing Unicon program with a new program, named *s*. Other arguments are passed to the program as the argument list. *s* must be a path to a binary executable program. To evaluate scripts, the *s* should be a shell such as ``/bin/sh``. .. literalinclude:: examples/exec.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/exec.icn` .. literalinclude:: examples/exec-replacement.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/exec-replacement.icn` Sample run: .. command-output:: unicon -s -C exec-replacement.icn :cwd: examples .. command-output:: unicon -s exec.icn -x :cwd: examples -------- .. index:: exit, function; exit .. _exit: exit ---- ``exit(i)`` ``exit()`` terminates the current program execution, returning a normal termination status code to the operating system (which will be system dependent, normally zero). ``exit(i)`` returns status code *i*. .. literalinclude:: examples/exit.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/exit.icn` Sample run: .. command-output:: unicon -s exit.icn ; ./exit ; echo $? :cwd: examples :shell: -------- .. index:: exp, function; exp .. _exp: exp --- ``exp(r)`` : *real* ``exp(r)`` returns :ref:`&e` raised to the power *r*. .. literalinclude:: examples/exp.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/exp.icn` Sample run: .. command-output:: unicon -s exp.icn -x :cwd: examples -------- .. index:: Eye, function; Eye .. _Eye: Eye --- ``Eye(w, s)`` : *window* ``Eye(w)`` retrieves the current 3D eye parameters. ``Eye(w, s)`` sets the ``eyedir`` (direction), ``eyepos`` (position), ``eyeup`` (up vector) graphic attributes. Each of these is an *x,y,z* coordinate; defaulting to "0,0,0,0,0,-1,0,1,0". For a 3D scene, changing the ``Eye()`` values will cause the entire window to be rendered from the new point of view. - eyepos, where the eye (camera) is located in *x,y,z*. Default is 0,0,0. - eyedir, where the eye is looking, defaults to looking into the *negative z* axis. 0,0,-1. - eyeup, what point in the 3D space is the up direction, defaults to the positive *y* axis. 0,1,0. .. literalinclude:: examples/Eye.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Eye.icn` Sample run (not auto captured): .. skipped command-output:: unicon -s Eye.icn -x :cwd: examples :: prompt$ unicon -s Eye.icn -x 0.00,0.00,0.00,0.00,0.00,-100.00,0.00,1.00,0.00 4.00,-4.00,8.00,0.00,0.00,-100.00,0.00,1.00,0.00 4.00,-4.00,8.00,1.00,0.00,0.40,0.00,1.00,0.00 .. seealso:: :ref:`WAttrib` -------- .. index:: Fail, function; Fail .. _Fail-function: Fail ---- ``Fail()`` : *fail* [*Patterns*] The ``Fail()`` pattern signals a failure in a local portion of a pattern match. It causes the goal-directed evaluation engine to backtrack and seek alternatives. This is different from :ref:`Abort` which stops pattern matching, ``Fail()`` tells the system to back and try alternatives. .. literalinclude:: examples/Fail.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Fail.icn` Sample run (taken from Unicon Technical Report 18, page 15): .. command-output:: unicon -s Fail.icn -x :cwd: examples -------- .. index:: fcntl, function; fcntl .. _fcntl: fcntl ----- ``fcntl(f, s, s)`` : *integer|string|record* [*POSIX*] ``fcntl(file, cmd, arg)`` performs miscellaneous operations on the open file *file*. Directories and DBM files cannot be arguments to ``fcntl()``. See :manpage:`fcntl(2)`. The following characters are possible values for *cmd*: - f, Get flags (F_GETFL) - F, Set flags (F_SETFL) - x, Get close on exec flags (F_GETFD) - X, Set close on exec flags (F_SETFD) - l, Get file lock (F_GETLK) - L, Set file lock (F_SETLK) - W, Set file lock and wait (F_SETLKW) - o, Get file owner or process group (F_GETOWN) - O, Set file owner or process group (F_SETOWN) In the case of ``L``, the *arg* value should be a string that describes the lock, otherwise *arg* value is an :ref:`integer`. The lock string consists of three parts separated by commas: - the type of lock (r, w, or u) - the starting position - the length The starting position can be an offset from the beginning of the file, *n*, the end of the file *-n*, or a relative position *+n*. A length of 0 means lock till EOF. These characters represent the file flags set by F_SETFL and retrieved with F_SETFL: - d, FNDELAY - s, FASYNC - a, FAPPEND .. literalinclude:: examples/fcntl.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/fcntl.icn` Sample run: .. command-output:: unicon -s fcntl.icn -x :cwd: examples -------- .. index:: fdup, function; fdup .. _fdup: fdup ---- ``fdup(f, f)`` : *?* [*POSIX*] ``fdup(src, dst)`` duplicates a file descriptor, by closing *dst* and setting *src* to that file descriptor; the *dst* fd is replaced by the *src* fd. See :manpage:`dup2(2)`. Commonly used with :ref:`exec` to manage standard in and standard out streams. .. literalinclude:: examples/fdup.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/fdup.icn` Sample run: .. command-output:: unicon -s fdup.icn -x :cwd: examples -------- .. index:: Fence, function; Fence .. _Fence: Fence ----- ``Fence()`` : *type* .. todo:: entry for function Fence ``Fence()`` .. pending literalinclude:: examples/Fence.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Fence.icn` Sample run: .. pending command-output:: unicon -s Fence.icn -x :cwd: examples -------- .. index:: fetch, function; fetch .. _fetch: fetch ----- ``fetch(D, s)`` : *string | row?* ``fetch(db, k)`` fetches the value corresponding to key *k* from a DBM or SQL database *db*. The result is a :ref:`string` for DBM or a *row* for SQL. If the key *k* is omitted for a current SQL query, ``fetch(db)`` produces the next row of the selection and advances the cursor to the next row. A *row* is a :ref:`record` where the field names and types are determined by the current query. ``fetch`` will fail if there are no more rows. Typically a call to :ref:`sql` will be followed by a while loop that calls ``fetch(db)`` until it fails. .. literalinclude:: examples/fetch.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/fetch.icn` Sample run: .. command-output:: unicon -s fetch.icn -x :cwd: examples -------- .. index:: Fg, function; Fg .. _Fg: Fg -- ``Fg(w, s)`` : *string* [*graphics*] ``Fg(w)`` retrieves the current foreground colour. ``Fg(w, s)`` sets the foreground colour by name or value. ``Fg()`` fails if the foreground cannot be set to the given colour. In 3D graphics, ``Fg(w, s)`` changes the material properties of subsequently drawn objects to those requested by *s*. The string *s* must be a semi-colon separated list of material properties. A material property is of the form:: diffuse | ambient | specular | emission | colour name | shininess n Where shininess values range from 0 thru 128. ``Fg(w)`` retrieves the current values of the material properties. .. literalinclude:: examples/Fg.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Fg.icn` Sample run: .. command-output:: unicon -s Fg.icn -x :cwd: examples -------- .. index:: fieldnames, function; fieldnames .. _fieldnames: fieldnames ---------- ``fieldnames(R)`` : *strings*\* ``fieldnames(r)`` generates the names of the fields in the :ref:`record` *r*. .. literalinclude:: examples/fieldnames.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/fieldnames.icn` Sample run: .. command-output:: unicon -s fieldnames.icn -x :cwd: examples -------- .. index:: filepair, function; filepair .. _filepair: filepair -------- ``filepair()`` : *list* [*POSIX*] ``filepair()`` creates a bi-directional pair of file, analogous to the POSIX ``socketpair(2)`` function. It returns a list of two *indistinguishable* files. Writes on one will be avaialable on the other. The connection is bi-directional, unlike that of the :ref:`pipe` function. File pairs are typically created just before a :ref:`fork` operation. After forking, one process should close *L[1]* and the other should close *L[2]* for end of file notifications to work properly. .. literalinclude:: examples/filepair.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/filepair.icn` Sample run (skipped, bug report pending): .. pending command-output:: unicon -s filepair.icn -x :cwd: examples -------- .. index:: FillArc, function; FillArc .. _FillArc: FillArc ------- ``FillArc(w, x, y, wid, h, a1:0.0, a2:&pi*2, ...)`` : *window* [*graphics*] ``FillArc(w, x, y, width, height, a1, a2, ...)`` draws filled arcs or ellipses. Each arc is defined by 4 given and 2 derived coordinates. *x*, *y*, *width, *height* define a bounding rectangle around the arc; the centre of the arc is the point (*x*\ +(*width*)/2, *y*\ +(*height*)/2. Angle *a1* is the starting position of the arc. The angle *a2* is not an end position but specifies the direction and extent of the arc. Angles are given in radians. Multiple arcs can be drawn with one call to the function. .. literalinclude:: examples/FillArc.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/FillArc.icn` Sample run: .. command-output:: unicon -s FillArc.icn -x :cwd: examples -------- .. index:: FillCircle, function; FillCircle .. _FillCircle: FillCircle ---------- ``FillCircle(w, x, y, radius, a1:0.0, a2:&pi*2, ...)`` : *window* [*graphics*] ``FillCircle(w, x, y, r, a1, a2)`` fills a circle centred at *x*\ ,\ *y*. Otherwise similar to :ref:`FillArc` with width equal to height. .. literalinclude:: examples/FillCircle.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/FillCircle.icn` Sample run: .. command-output:: unicon -s FillCircle.icn -x :cwd: examples .. image:: images/FillCircle.png .. only:: html .. rst-class:: leftalign :download:`images/FillCircle.png` -------- .. index:: FillPolygon, function; FillPolygon .. _FillPolygon: FillPolygon ----------- ``FillPolygon(w, x1,y1[,z1], ..., xn,yn[,zn])`` : *window | list* ``FillPolygon(w, x1,y1, x2,y2, xn,yn)`` draws a filled polygon connecting each *x,y* pair (in 2D). In 3D, ``FillPolygon()`` takes from 2 to 4 coordinates per vertex and returns the list that represents the polygon on the display list. .. literalinclude:: examples/FillPolygon.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/FillPolygon.icn` Sample run: .. command-output:: unicon -s FillPolygon.icn -x :cwd: examples .. image:: images/FillPolygon.png .. only:: html .. rst-class:: leftalign :download:`images/FillPolygon.png` -------- .. index:: FillRectangle, function; FillRectangle .. _FillRectangle: FillRectangle ------------- ``FillRectangle(w, x1,y1, wid1, h1, ...)`` : *window* ``FillRectangle(w, x, y, width, hieght)`` fills a rectangle with a top right corner of *x,y* and a perceived width and height. Actual rectangle is *width+1* pixels wide, and *height+1* pixels high. .. literalinclude:: examples/FillRectangle.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/FillRectangle.icn` Sample run: .. command-output:: unicon -s FillRectangle.icn -x :cwd: examples .. image:: images/FillRectangle.png .. only:: html .. rst-class:: leftalign :download:`images/DrawRectangle.png` -------- .. index:: find, function; find .. _find: find ---- ``find(s, s:&subject, i:&pos, i:0)`` : *integer*\* The string scanning function ``find(s1, s2, i1, i2)`` generates the positions where *s1* occurs within *s2[i1:i2]* .. literalinclude:: examples/find.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/find.icn` Sample run: .. command-output:: unicon -s find.icn -x :cwd: examples -------- .. index:: flock, function; flock .. _flock: flock ----- ``flock(f, s)`` : *?* ``flock(f, s)`` applies an advisory lock to file *f*, given options *s*. Advisory locks can be shared or exclusive, but do not enforce exclusive access. The options can be - "s", shared lock - "x", exclusive lock - "b", don't block when locking - "u", unlock ``flock()`` cannot be used with window, directory or database files. See :manpage:`flock(2)` for more information. .. literalinclude:: examples/flock.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/flock.icn` Sample run: .. command-output:: unicon -s flock.icn -x :cwd: examples -------- .. index:: flush, function; flush .. _flush: flush ----- ``flush(f)`` : *file* ``flush(f)`` flushes all pending or buffered output to file *f*. This will be hard to demonstrate in a document, but flushing output buffers can help with keeping full lines of output in synch on screen when threading, mixing I/O models or other times when buffering would get in the way of application goals. .. literalinclude:: examples/flush.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/flush.icn` Sample run: .. command-output:: unicon -s flush.icn -x :cwd: examples -------- .. index:: Font, function; Font .. _Font: Font ---- ``Font(w, s)`` : *string* ``Font(w)`` produces the name of the current font for window *w*. ``Font(w, s)`` sets the font to *s* for window *w* and produces the name, or fails if the font name is invalid. .. index:: fonts; default Unicon ships with four portable fonts: - sans, proportional font without :ref:`serif`\ s - serif, proportional font with serifs - mono (or fixed), mono spaced font without serifs - typewriter, mono spaced font with serifs Most other font names are system-dependent, and follow the format ``family[,styles],size``. Styles can optionally add ``bold`` and/or ``italic``. ``Font()`` fails if the requested font name does not exist. .. literalinclude:: examples/Font.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Font.icn` Sample run: .. command-output:: unicon -s Font.icn -x :cwd: examples .. image:: images/Font.png .. only:: html .. rst-class:: leftalign :download:`images/Font.png` -------- .. index:: fork, function; fork .. _fork: fork ---- ``fork()`` : *integer* ``fork()`` creates a new process that is effectively identical to the current process except in the return value from ``fork`` (and some small amount of operating system "paperwork"). The current process will receive the PID (see :ref:`getpid`) of the child process. The forked process will receive a ``0``. Negative return values denote an error, a failure when the operating system attempted to create a new process. .. literalinclude:: examples/fork.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/fork.icn` Sample run: .. command-output:: unicon -s fork.icn -x :cwd: examples -------- .. index:: FreeColor, function; FreeColor .. _FreeColor: FreeColor --------- ``FreeColor(w, s,...)`` : *window* ``FreeColor(w, s)`` release colour *s* from the window system color map entries. If a colour is still in use when it is freed, unpredictable results will occur. This is not deprecated, but is unnecessary with modern display technology. :ref:`NewColor` and ``FreeColor`` were initially developed at a time when display screens and graphics cards could only handle a limited palette of colours at any one time. A feature not required with monitors and cards that can handle millions of simultaneous colours. .. literalinclude:: examples/FreeColor.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/FreeColor.icn` Sample run: .. command-output:: unicon -s FreeColor.icn -x :cwd: examples .. image:: images/FreeColor.png .. only:: html .. rst-class:: leftalign :download:`images/FreeColor.png` -------- .. index:: FreeSpace, function; FreeSpace .. _FreeSpace: FreeSpace --------- ``FreeSpace(A)`` : *null* [*MS-DOS*] This is an outdated MS-DOS specific feature of Unicon. ``FreeSpace(A)`` frees an allocated memory block returned from :ref:`GetSpace`. .. literalinclude:: examples/FreeSpace.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/FreeSpace.icn` Sample run (skipped on this GNU/Linux build machine): .. skipped command-output:: unicon -s FreeSpace.icn -x :cwd: examples .. seealso:: :ref:`GetSpace`, :ref:`Peek`, :ref:`Poke`, :ref:`Int86` -------- .. index:: function, function; function .. _function: function -------- ``function()`` : *string*\* ``function()`` generates the names of the built-in functions. .. literalinclude:: examples/function.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/function.icn` Sample run: .. command-output:: unicon -s function.icn -x :cwd: examples -------- .. index:: get, function; get .. _get: get --- ``get(L, i:1)`` : *any?* ``get(L)`` returns an element, which is removed from the head of the queue *L*. ``get(L, i)`` removes the first *i* elements, returning the last one removed. .. literalinclude:: examples/get.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/get.icn` Sample run: .. command-output:: unicon -s get.icn -x :cwd: examples -------- .. index:: getch, function; getch .. _getch: getch ----- ``getch()`` : *string?* ``getch()`` waits (if necessary) for a character types at the console keyboard, *even if standard input is redirected*. The character is not echoed. .. note:: On GNU/Linux getch doesn't wait when stdin redirected .. literalinclude:: examples/getch.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getch.icn` A sample run (captured outside document generation in this case) :: prompt$ unicon -s getch.icn -x read: stdin data stdin data getch: line from &input: stdin data character from getch(): "w" -------- .. index:: getche, function; getche .. _getche: getche ------ ``getche()`` : *type* ``getche()`` waits (if necessary) for a character types at the console keyboard, *even if standard input is redirected*. The character is echoed. .. note:: On GNU/Linux getche doesn't wait when redirected, fails if no keypresses are pending .. literalinclude:: examples/getche.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getche.icn` A sample run (captured outside document generation in this case) :: read: typed from stdin typed from stdin getche: g line from &input: typed from stdin character from getche(): "g" -------- .. index:: getegid, function; getegid .. _getegid: getegid ------- ``getegid()`` : *string* ``getegid()`` produces the effective group identity of the current process. A name is returned if available, otherwise the numeric code is returned. .. literalinclude:: examples/getegid.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getegid.icn` Sample run: .. command-output:: unicon -s getegid.icn -x :cwd: examples -------- .. index:: getenv, function; getenv .. _getenv: getenv ------ ``getenv(s)`` : *string* ``getenv(s)`` retrieves the value of the environment variable *s* from the current process space. .. literalinclude:: examples/getenv.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getenv.icn` Sample run: .. command-output:: unicon -s getenv.icn -x :cwd: examples .. seealso:: :ref:`setenv` -------- .. index:: geteuid, function; geteuid .. _geteuid: geteuid ------- ``geteuid()`` : *string* ``geteuid()`` returns the effective user identity for the current process. A name is returned if available, otherwise the numeric code is returned. .. literalinclude:: examples/geteuid.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/geteuid.icn` Sample run: .. command-output:: unicon -s geteuid.icn -x :cwd: examples -------- .. index:: getgid, function; getgid .. _getgid: getgid ------ ``getgid()`` : *string* ``getgid()`` produces the current group identity for the current process. A name is returned if available, otherwise a numeric code is produced. .. literalinclude:: examples/getgid.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getgid.icn` Sample run: .. command-output:: unicon -s getgid.icn -x :cwd: examples -------- .. index:: getgr, function; getgr .. _getgr: getgr ----- ``getgr(g)`` : *record* ``getgr(g)`` produces a record the contains group file information for group *g*, a string group name of the integer group code. If *g* is null, each successive call to ``getgr()`` returns the next entry. As in :ref:`read` this value is given with :ref:`return` and is not a generator :ref:`suspend`. Record is ``record posix_group(name, passwd, gid, members)`` .. literalinclude:: examples/getgr.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getgr.icn` Sample run: .. command-output:: unicon -s getgr.icn -x :cwd: examples -------- .. index:: gethost, function; gethost .. _gethost: gethost ------- ``gethost(x)`` : *record|string* ``gethost(n)`` for network connection *n* produces a string containing the IP address and port number this machine is using for the connection. ``gethost(s)`` returns a record that contains the host information for the name *s*. If *s* is null, each successive call to ``gethost()`` returns the next entry. :ref:`sethostent` resets the sequence to the beginning. Aliases and addressed are comma separated lists (in ``a.b.c.d`` format). The record type returned is ``record posix_hostent(name, aliases, addresses)``. As in :ref:`read` this value is given with :ref:`return` and is not a generator :ref:`suspend`. .. literalinclude:: examples/gethost.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/gethost.icn` Sample run: .. command-output:: unicon -s gethost.icn -x :cwd: examples -------- .. index:: getpgrp, function; getpgrp .. _getpgrp: getpgrp ------- ``getpgrp()`` : *integer* ``getpgrp()`` produces the process group of the current process. .. literalinclude:: examples/getpgrp.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getpgrp.icn` Sample run: .. command-output:: unicon -s getpgrp.icn -x :cwd: examples -------- .. index:: getpid, function; getpid .. _getpid: getpid ------ ``getpid()`` : *integer* ``getpid()`` produces the process identification (pid) of the current process. .. literalinclude:: examples/getpid.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getpid.icn` Sample run: .. command-output:: unicon -s getpid.icn -x :cwd: examples -------- .. index:: getppid, function; getppid .. _getppid: getppid ------- ``getppid()`` : *integer?* ``getppid()`` produces the process id of the parent of the current process. .. literalinclude:: examples/getppid.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getppid.icn` Sample run: .. command-output:: unicon -s getppid.icn -x :cwd: examples -------- .. index:: getpw, function; getpw .. _getpw: getpw ----- ``getpw(u)`` : *record* ``getpw(u)`` produces a record that contains account password file information. *u* can be a numeric uid or a user name. If *u* is null, each successive call to ``getpw()`` returns the next entry. As in :ref:`read` this value is given with :ref:`return` and is not a generator :ref:`suspend`. :ref:`setpwent` resets the sequence to the beginning. Record type is:: record posix_password(name, passwd, uid, gid, age, comment, gecos, dir, shell) Most systems now contain a special marker ``x`` for the passwd field and the actual data is saved in a shadow file, safe from prying eyes. Even with access to the shadow data, the password is stored using :ref:`crypt`. The encrypted form makes it just that little bit easier to brute force guess the original password so the shadow data file was developed, with more restrictive permissions than the global passwd file that ``getpw`` accesses. .. literalinclude:: examples/getpw.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getpw.icn` Sample run: .. command-output:: unicon -s getpw.icn -x :cwd: examples -------- .. index:: getrusage, function; getrusage .. _getrusage: getrusage --------- ``getrusage(s)`` : *record* ``getrusage(s)`` produces resource usage for *s*, where *s* can be "self", "thread" or "children". ``getrusage`` fails if resource usage cannot be retrieved for *s*. Record type is:: record posix_rusage(utime, stime, maxrss, minflt, majflt, inblock, oublock, nvcsw, nivcsw) The ``utime`` and ``stime`` fields are ``record posix_timeval(sec, usec)``. From :manpage:`getruage(2)`: .. sourcecode:: c struct rusage { struct timeval ru_utime; /* user CPU time used */ struct timeval ru_stime; /* system CPU time used */ long ru_maxrss; /* maximum resident set size */ long ru_ixrss; /* integral shared memory size */ long ru_idrss; /* integral unshared data size */ long ru_isrss; /* integral unshared stack size */ long ru_minflt; /* page reclaims (soft page faults) */ long ru_majflt; /* page faults (hard page faults) */ long ru_nswap; /* swaps */ long ru_inblock; /* block input operations */ long ru_oublock; /* block output operations */ long ru_msgsnd; /* IPC messages sent */ long ru_msgrcv; /* IPC messages received */ long ru_nsignals; /* signals received */ long ru_nvcsw; /* voluntary context switches */ long ru_nivcsw; /* involuntary context switches */ }; /**/ .. literalinclude:: examples/getrusage.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getrusage.icn` Sample run: .. command-output:: unicon -s getrusage.icn -x :cwd: examples -------- .. index:: getserv, function; getserv .. _getserv: getserv ------- ``getserv(s, s)`` : *record* ``getserv(service, proto)`` retrieves the service database entry named *s* using protocol *proto*. If *s* is null, each successive call to ``getserv()`` returns the next entry. :ref:`setservent` resets the sequence to the beginning. As in :ref:`read` these values are given with :ref:`return` and not a generator :ref:`suspend`. The record type returned is ``record posix_servent(name, aliases, port, proto)``. .. literalinclude:: examples/getserv.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getserv.icn` Sample run: .. command-output:: unicon -s getserv.icn -x :cwd: examples For GNU/Linux the services data set is usually a plain text file, ``/etc/services``. -------- .. index:: GetSpace, function; GetSpace .. _GetSpace: GetSpace -------- ``GetSpace(i)`` : *A* [*MSDOS*] This is an outdated MS-DOS specific feature of Unicon. ``GetSpace(i)`` retrieves *i* bytes of memory outside normal Unicon control and garbage collection. The return value is an "address", effectively a long integer. .. literalinclude:: examples/GetSpace.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/GetSpace.icn` Sample run (skipped on this GNU/Linux build machine): .. skipped command-output:: unicon -s GetSpace.icn -x :cwd: examples .. seealso:: :ref:`FreeSpace`, :ref:`Peek`, :ref:`Poke`, :ref:`Int86` -------- .. index:: gettimeofday, function; gettimeofday .. _gettimeofday: gettimeofday ------------ ``gettimeofday()`` : *record* ``gettimeofday()`` returns the current time in seconds and microseconds since the epoch, January 1st, 1970 at 00:00:00, Greenwich Mean Time. The ``sec`` field may be converted to a date string with the :ref:`ctime` or :ref:`gtime` functions. Returns ``record posix_timeval(sec, usec)``. .. literalinclude:: examples/gettimeofday.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/gettimeofday.icn` Sample run: .. command-output:: unicon -s gettimeofday.icn -x :cwd: examples .. seealso:: :ref:`&clock`, :ref:`&dateline`, :ref:`&now`, :ref:`gtime`, :ref:`ctime` -------- .. index:: getuid, function; getuid .. _getuid: getuid ------ ``getuid()`` : *string* [*POSIX*] ``getuid()`` produces the real user identity of the current process. .. literalinclude:: examples/getuid.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/getuid.icn` Sample run: .. command-output:: unicon -s getuid.icn -x :cwd: examples -------- .. index:: globalnames, function; globalnames .. _globalnames: globalnames ----------- ``globalnames(CE)`` : *string*\* ``globalnames(ce)`` generates the names of the global variable in the program that create the co-expression *ce*. .. literalinclude:: examples/globalnames.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/globalnames.icn` Sample run: .. command-output:: unicon -s globalnames.icn -x :cwd: examples Note how ``other`` isn't listed. It would need to be set to show up. .. seealso:: :ref:`localnames`, :ref:`staticnames` -------- .. index:: GotoRC, function; GotoRC .. _GotoRC: GotoRC ------ ``GotoRC(w, row:1, col:1)`` : *window* [*Graphics*] ``GotoRC(w, r, c)`` moves the text cursor to row *r*, column *c*, on window *w*. Row and column are given in character positions. The upper left is ``(1,1)``. The column is calculated using the pixel width of the widest character in the current font. Works best with fixed width fonts. Row is determined by the height of the current font. .. literalinclude:: examples/GotoRC.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/GotoRC.icn` Sample run: .. command-output:: unicon -s GotoRC.icn -x :cwd: examples .. image:: images/GotoRC.png .. only:: html .. rst-class:: leftalign :download:`images/GotoRC.png` -------- .. index:: GotoXY, function; GotoXY .. _GotoXY: GotoXY ------ ``GotoXY(w:&window, x:0, y:0)`` : *window* [*Graphics*] ``GotoXY(w, x, y)`` moves the text cursor to a specific cursor location, *x, y* (given in pixels) on window *w*. .. literalinclude:: examples/GotoXY.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/GotoXY.icn` Sample run: .. command-output:: unicon -s GotoXY.icn -x :cwd: examples .. image:: images/GotoXY.png .. only:: html .. rst-class:: leftalign :download:`images/GotoXY.png` -------- .. index:: gtime, function; gtime .. _gtime: gtime ----- ``gtime(i)`` : *string* ``gtime(i)`` converts the integer time ``i``, given in seconds since the epoch of Jan 1st, 1970 00:00:00 Greenwich Mean Time, into a string, based on GMT. .. literalinclude:: examples/gtime.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/gtime.icn` Sample run: .. program-output:: unicon -s gtime.icn -x :cwd: examples .. seealso:: :ref:`&clock`, :ref:`ctime`, :ref:`&dateline`, :ref:`&now` -------- .. index:: hardlink, function; hardlink .. _hardlink: hardlink -------- ``hardlink(s, s)`` : *?* [*POSIX*] ``hardlink(src, dst)`` creates a hard link on the file system, *dst* becomes a directory entry referencing the same file system i-node as *src*. This creates a new name for *src*, and changes to *dst* will effect *src*. .. literalinclude:: examples/hardlink.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/hardlink.icn` Sample run: .. command-output:: unicon -s hardlink.icn -x :cwd: examples With that link, if ``tt.src`` started out containing:: tt.src file data A change to ``tt.dst``, say with:: prompt$ echo 'tt.dst file data' The disk data blocks in ``tt.src`` have been changed:: prompt$ cat tt.src tt.dst file data See :ref:`symlink` for the more frequently used soft link. -------- .. index:: iand, function; iand .. _iand: iand ---- ``iand(i, i)`` : *integer* ``iand(i1, i2)`` produces the bitwise AND of *i1* and *i2*. .. literalinclude:: examples/iand.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/iand.icn` Sample run: .. command-output:: unicon -s iand.icn -x :cwd: examples -------- .. index:: icom, function; icom .. _icom: icom ---- ``icom(i)`` : *integer* ``icom(i)`` produces the bitwise one's complement of *i*. .. literalinclude:: examples/icom.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/icom.icn` Sample run: .. command-output:: unicon -s icom.icn -x :cwd: examples -------- .. index:: IdentityMatrix, function; IdentityMatrix .. _IdentityMatrix: IdentityMatrix -------------- .. function:: IdentityMatrix(window) -> record :type: *pattern* :requires: *3D graphics* Replaces the current 3D graphic matrix to the identity matrix. Returns the display list element. .. literalinclude:: examples/IdentityMatrix.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/IdentityMatrix.icn` Sample run (not auto captured): .. skipped command-output:: unicon -s IdentityMatrix.icn -x :cwd: examples :: prompt$ unicon -s IdentityMatrix.icn -x gl_pushmatrix("PopMatrix",224) .. seealso:: :ref:`PushMatrix`, :ref:`PopMatrix`, :ref:`Eye` -------- .. index:: image, function; image .. _image: image ----- ``image(x)`` : *string* ``image(x)`` produces a string image of *x*. .. literalinclude:: examples/image.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/image.icn` Sample run: .. command-output:: unicon -s image.icn -x :cwd: examples -------- .. index:: InPort, function; InPort .. _InPort: InPort ------ ``InPort(i)`` : *integer* [*MS-DOS*] ``InPort(i)`` will read a byte value from port *i*. This is an MS-DOS specific feature of Unicon. .. literalinclude:: examples/InPort.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/InPort.icn` Sample run (skipped on this GNU/Linux build machine): .. skipped command-output:: unicon -s InPort.icn -x :cwd: examples .. seealso:: :ref:`OutPort` -------- .. index:: insert, function; insert .. _insert: insert ------ ``insert(x1, x2, x3:&null, ...)`` : *x1* ``insert(x1, x2, x3)`` inserts element *x2* into :ref:`list`, :ref:`set`, :ref:`table` or DBM database *x1*, if it is not already a :ref:`member`. For lists, tables and databases the assigned value for *x2* is *x3*. For lists, *x2* is an integer index, and for other types *x2* is a key. For sets, *x3* is taken as another element to insert. ``insert()`` always succeeds and returns *x1*. In Unicon, multiple elements can be inserted in one call. .. literalinclude:: examples/insert.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/insert.icn` Sample run: .. command-output:: unicon -s insert.icn -x :cwd: examples -------- .. index:: Int86, function; Int86 .. _Int86: Int86 ----- ``Int86(list)`` : *list* [*MS-DOS*] This is an MS-DOS specific Unicon feature. ``Int86(L)`` performs an MS-DOS interrupt routine. The list *L* must contain *nine* integer values. The first value is a *flag* value, the rest will be stored in *ax,bx,cx,dx,si,di,es,ds* CPU registers, in that order. After the dispatch to the interrupt vector in *flag*, via the ``int386x`` C library function, the returned list will be set with the *cflag* and register values as set by DOS. .. attention:: This feature is specific to MS-DOS on Intel chips and is relatively dangerous. A programmer must know what are safe values for the registers before using this, now mostly outdated, feature. .. literalinclude:: examples/Int86.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Int86.icn` Sample run (skipped on this GNU/Linux build machine): .. skipped command-output:: unicon -s Int86.icn -x :cwd: examples See ``ipl/procs/io.icn`` for an old working example of ``Int86()``. .. seealso:: :ref:`GetSpace`, :ref:`Peek`, :ref:`Poke` -------- .. index:: integer, function; integer .. _integer-function: integer ------- ``integer(any)`` : *integer?* ``integer(x)`` converts the value *x* to an integer, or fails if the conversion cannot be performed. .. literalinclude:: examples/integer.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/integer.icn` Sample run: .. command-output:: unicon -s integer.icn -x :cwd: examples -------- .. index:: ioctl, function; ioctl .. _ioctl: ioctl ----- ``ioctl(f, i, s)`` : *integer* ``ioctl(f, i, s)`` passes the options in *s* to the open special device file channel *f*, given an integer action specified in *i*. .. literalinclude:: examples/ioctl.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/ioctl.icn` .. todo:: ioctl demo Sample run (pending): .. pending command-output:: unicon -s ioctl.icn -x :cwd: examples -------- .. index:: ior, function; ior .. _ior: ior --- ``ior(i, i)`` : *integer* ``ior(i1, i2)`` produces the bitwise OR of *i1* and *i2*. .. literalinclude:: examples/ior.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/ior.icn` Sample run: .. command-output:: unicon -s ior.icn -x :cwd: examples -------- .. index:: ishift, function; ishift .. _ishift: ishift ------ ``ishift(i, i)`` : *integer* ``ishift(i, j)`` produces the value from shifting *i* by *j* bit positions. Shift left for positive *j* and shift right for negative *j*. Zero bits are shifted in. .. literalinclude:: examples/ishift.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/ishift.icn` Sample run: .. command-output:: unicon -s ishift.icn -x :cwd: examples -------- .. index:: istate, function; istate .. _istate: istate ------ ``istate(CE, s)`` : *integer* ``istate(ce, attrib)`` reports selected virtual machine interpreter state information for *ce*. Used by monitors. *attrib* must be one of: - "count" - "ilevel" - "ipc" - "ipc_offset" - "sp" - "efp" - "gfp" .. todo:: what do the attribute fields actually mean .. literalinclude:: examples/istate.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/istate.icn` Sample run: .. command-output:: unicon -s istate.icn -x :cwd: examples -------- .. index:: ixor, function; ixor .. _ixor: ixor ---- ``ixor(i, i)`` : *integer* ``ixor()`` produces the bitwise exclusive OR (XOR) of *i1* and *i2*. .. literalinclude:: examples/ixor.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/ixor.icn` Sample run: .. command-output:: unicon -s ixor.icn -x :cwd: examples -------- .. index:: kbhit, function; kbhit .. _kbhit: kbhit ----- ``kbhit()`` : *?* ``kbhit()`` checks to see if there is a keyboard character waiting to be read. Returns null or fails when no events are pending. .. literalinclude:: examples/kbhit.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/kbhit.icn` Sample run (captured outside documentation generation) :: prompt$ unicon -s kbhit.icn -x a key press pending:"a" The echo of ``a`` (tapped during the delay) was from the GNU/Linux console, ``stty`` set to echo. -------- .. index:: key, function; key .. _key: key --- ``key(x)`` : *any*\* ``key(T)`` generates the key values from :ref:`table` *T*. ``key(L)`` generates the indices from ``1`` to ``*L`` in :ref:`list` *L*. ``key(R)`` generates the string field names of :ref:`record` *R*. .. literalinclude:: examples/key.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/key.icn` Sample run: .. command-output:: unicon -s key.icn -x :cwd: examples -------- .. index:: keyword, function; keyword .. _keyword: keyword ------- ``keyword(s, CE:¤t,i:0)`` : *any*\* ``keyword(s, ce, i)`` produces the value(s) of keyword *s* in the context of *ce* execution, *i* levels up the stack from the current point of execution. Used in execution monitors .. literalinclude:: examples/keyword.icn :language: unicon :linenos: :lineno-start: 8 :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/keyword.icn` Sample run: .. command-output:: unicon -s keyword.icn -x :cwd: examples -------- .. index:: kill, function; kill .. _kill: kill ---- ``kill(i, x)`` : *?* [*POSIX*] ``kill(pid, signal)`` sends a signal to the process specified by *pid*. The *signal* parameter can be a string name or the integer code for the signal to be sent. From ``src/runtime/rposix.r`` .. sourcecode:: c stringint signalnames[] = { { 0, 40 }, { "SIGABRT", SIGABRT }, { "SIGALRM", SIGALRM }, { "SIGBREAK", SIGBREAK }, { "SIGBUS", SIGBUS }, { "SIGCHLD", SIGCHLD }, { "SIGCLD", SIGCLD }, { "SIGCONT", SIGCONT }, { "SIGEMT", SIGEMT }, { "SIGFPE", SIGFPE }, { "SIGFREEZE", SIGFREEZE }, { "SIGHUP", SIGHUP }, { "SIGILL", SIGILL }, { "SIGINT", SIGINT }, { "SIGIO", SIGIO }, { "SIGIOT", SIGIOT }, { "SIGKILL", SIGKILL }, { "SIGLOST", SIGLOST }, { "SIGLWP", SIGLWP }, { "SIGPIPE", SIGPIPE }, { "SIGPOLL", SIGPOLL }, { "SIGPROF", SIGPROF }, { "SIGPWR", SIGPWR }, { "SIGQUIT", SIGQUIT }, { "SIGSEGV", SIGSEGV }, { "SIGSTOP", SIGSTOP }, { "SIGSYS", SIGSYS }, { "SIGTERM", SIGTERM }, { "SIGTHAW", SIGTHAW }, { "SIGTRAP", SIGTRAP }, { "SIGTSTP", SIGTSTP }, { "SIGTTIN", SIGTTIN }, { "SIGTTOU", SIGTTOU }, { "SIGURG", SIGURG }, { "SIGUSR1", SIGUSR1 }, { "SIGUSR2", SIGUSR2 }, { "SIGVTALRM", SIGVTALRM }, { "SIGWAITING", SIGWAITING }, { "SIGWINCH", SIGWINCH }, { "SIGXCPU", SIGXCPU }, { "SIGXFSZ", SIGXFSZ }, }; .. literalinclude:: examples/kill.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/kill.icn` Sample run (with error termination code, due to kill): .. command-output:: unicon -s kill.icn -x :cwd: examples :returncode: 137 -------- .. index:: left, function; left .. _left: left ---- ``left(s, i:1, s:" ")`` : *string* ``left(s1, i, s2)`` formats *s1* to be a string of length *i*. If *s1* has more than *i* characters, it is truncated. If *s1* has less than *i* characters then it is padded to the right with as many copies of *s2* needed to increase the length to *i*. Last copy of *s2* is left side truncated if necessary ("filler" will pad as "ller" for instance). .. literalinclude:: examples/left.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/left.icn` Sample run: .. command-output:: unicon -s left.icn -x :cwd: examples -------- .. index:: Len, function; Len .. _Len: Len --- ``Len(i)`` : *string* [*Patterns*] ``Len(n)`` is a SNOBOL pattern that matches the next *n* characters, or fails if not enough characters remain in the subject. ``Len(0)`` matches the empty string. .. literalinclude:: examples/Len.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Len.icn` Sample run: .. command-output:: unicon -s Len.icn -x :cwd: examples -------- .. index:: list, function; list .. _list-function: list ---- ``list(i:0, any:&null)`` : *list* ``list(i, x)`` creates a list of size *i*, with all initial values set to *x*. If *x* is a mutable value, such as a list, all elements refer to the same value, not a separate copy. .. literalinclude:: examples/list.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/list.icn` Sample run: .. command-output:: unicon -s list.icn -x :cwd: examples -------- .. index:: load, function; load .. _load: load ---- ``load(s, L, f:&input, f:&output, f:&errout,i,i,i)`` : *co-expression* ``load(s, arglist, input, output, error, block, string, stack)`` loads the :ref:`icode` file named *s* and returns the program as a co-expression, ready to start in the loaded ``main()`` procedure with *arglist* as the command line arguments. The three file parameters are used as the :ref:`&input`, :ref:`&output` and :ref:`&errout` for the program co-expression. The three integers are used to set initial memory region sizes for ``block``, ``string``, and ``stack``. .. literalinclude:: examples/load.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/load.icn` .. literalinclude:: examples/load-module.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/load-module.icn` Sample run: .. command-output:: unicon -s load-module.icn :cwd: examples .. command-output:: unicon -s load.icn -x :cwd: examples -------- .. index:: loadfunc, function; loadfunc .. _loadfunc: loadfunc -------- .. function:: loadfunc(libname:string, funcname:string) -> procedure ``loadfunc()`` reads ``libname`` to load a C foreign function ``funcname`` returning a *procedure* value. Uses the :ref:`ipl` support file, ``icall.h``. .. literalinclude:: examples/loadfunc.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/loadfunc.icn` All loadable functions require a Unicon compatible prototype: .. c:function:: int cfunction(int argc, descriptor *argv) or, *equivalent* .. c:function:: int cfunction(int argc, struct descriptor argv[]) That is, a function returning an integer that accepts a count of arguments and a pointer to a special array of structures that hold encoded argument values. The C function is expected to return an integer, 0 for success, -1 for failure with positive values being error codes. Arguments are marshalled to and from Icon with a special bit encoded structure with slots for data or pointer to data. Unicon Integer, Real, String and List data can be encoded for passing between C and Unicon. .. c:type:: descriptor A ``descriptor`` is an opaque internal data structure. .. sourcecode:: c typedef long word; typedef struct descrip { word dword; union { word integr; /* integer value */ #if defined(DescriptorDouble) double realval; #endif char *sptr; /* pointer to character string */ union block *bptr; /* pointer to a block */ struct descrip *descptr; /* pointer to a descriptor */ } vword; } descriptor, *dptr; /**/ argv[0] is reserved for the actual value delivered to Unicon on return from the external C function. .. literalinclude:: examples/loaded.c :language: c .. only:: html .. rst-class:: rightalign :download:`examples/loaded.c` That code exercises some of the helper macros defined in ``icall.h``. .. c:function:: void ArgInteger(int index) ``ArgInteger`` ensures the argument at ``argv[index]`` is an native integer, or fails and returns an errorcode. Marked ``void`` as ``ArgInteger`` is actually a code fragment macro, not an actual function. .. c:function:: void ArgError(int index, int errorcode) ``ArgError`` returns argv[index] as an offending value, with errorcode. Marked ``void`` as ``ArgError`` is actually a code fragment macro, not an actual function. .. c:function:: int RetInteger(int result) ``RetInteger`` returns an integer for use as a Unicon function result. Sample run: .. command-output:: gcc -shared -fpic -o loaded.so loaded.c :cwd: examples .. command-output:: unicon -s loadfunc.icn -x :cwd: examples Sample with an erroneous value passed: .. command-output:: unicon -s loadfunc.icn -x "abc" :cwd: examples :returncode: 1 See :doc:`programs` for some examples of loading scripting engines, like Ruby, S-Lang and Javascript, into Unicon and integration with other languages, like :ref:`GnuCOBOL`. -------- .. index:: localnames, function; localnames .. _localnames: localnames ---------- ``localnames(C:co-expression, i:integer:0)`` : *string\** ``localnames(C, i)`` generates the names of local variables in co-expression *C*, *i* levels up from the current procedure invocation. The default, level 0, generates names in the currently active procedure inside *C*. .. literalinclude:: examples/localnames.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/localnames.icn` Sample run: .. command-output:: unicon -s localnames.icn -x :cwd: examples .. seealso:: :ref:`globalnames`, :ref:`staticnames` -------- .. index:: lock, function; lock .. _lock: lock ---- ``lock(x)`` : *x* ``lock(x)`` locks the mutex *x*, or the mutex associated with the thread-safe object *x*. .. literalinclude:: examples/lock.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/lock.icn` Sample run: .. command-output:: unicon -s lock.icn -x :cwd: examples -------- .. index:: log, function; log .. _log: log --- ``log(r, r:&e)`` : *real* ``log(r, b)`` generates the logarithm of *r* in base *b*. .. literalinclude:: examples/log.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/log.icn` Sample run: .. command-output:: unicon -s log.icn -x :cwd: examples -------- .. index:: Lower, function; Lower .. _Lower: Lower ----- ``Lower(w)`` : *window* ``Lower(w)`` moves window *w* to the bottom of the window stack. The window may end up obscured, hidden behind other windows. .. literalinclude:: examples/Lower.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Lower.icn` Sample run: .. command-output:: unicon -s Lower.icn -x :cwd: examples .. image:: images/Lower.png .. only:: html .. rst-class:: leftalign :download:`images/Lower.png` .. seealso:: :ref:`Raise` -------- .. index:: lstat, function; lstat .. _lstat: lstat ----- ``lstat(f)`` : *record?* [*POSIX*] ``lstat(f)`` returns a record of filesystem information for file (or path) *f*. Does not follow symbolic links, if *f* is a symlink, then information about the symlink is returned. See :ref:`stat`. Return record is:: record posix_stat(dev, ino, mode, nlink, gid, rdev, size, atime, mtime, ctime, blksize, blocks, symlink) The ``atime``, ``ctime``, and ``mtime`` fields may be formatted with the :ref:`ctime`\ () and :ref:`gtime`\ () functions. ``mode`` is a string form similar to the output of ``ls -l``. ``lstat()`` will fail if the file or path *f* does not exist. .. literalinclude:: examples/lstat.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/lstat.icn` Sample run: .. command-output:: unicon -s lstat.icn -x :cwd: examples -------- .. index:: many, function; many .. _many: many ---- ``many(c, s, i, i)`` : *integer?* ``many(c, s, i1, i2)`` produces the position in *s* after the longest initial sequence of members of *c* within *s[i1:i2]*. A goal directed generator, but returns after the first match. .. literalinclude:: examples/many.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/many.icn` Sample run: .. command-output:: unicon -s many.icn -x :cwd: examples -------- .. index:: map, function; map .. _map: map --- ``map(s, s:&ucase, s:&lcase)`` : *string* ``map(s1, s2, s3)`` maps *s1* using *s2* and *s3*. The resulting string will be a copy of *s1* with any characters that appear in *s2* replaced by characters in the position from *s3*. The defaults allow for upper case to lower case conversions of *s1*. Map transforms are a powerful feature of Unicon. Permutations are possible when ``map()`` is called with *s1* and *s2* as constants and *s3* being a transform target. .. literalinclude:: examples/map.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/map.icn` Sample run: .. command-output:: unicon -s map.icn -x :cwd: examples ``map()`` is usually thought of as source, what-to-change, to-what. When the ``to-what`` is changed to be a variable, Unicon returns a string where character markers in *s1* are replaced by positionally matched characters from *s2*. Characters of the variable *s3* are sourced to feed an *s1* *s2* positional transform. .. index:: transforms .. _transforms: .. blockdiag:: blockdiag transform { default_fontsize = 20; a <-> D; b <-> C; c <-> B; d <-> A; group s1 { orientation = portrait; empty [label=""]; empty -> A -> B -> C -> D [style="none" ]; } group s2 { a -> b -> c -> d [style="none"]; } } Characters of s3 mapped by positional matches between s1 and s2. -------- .. index:: match, function; match .. _match: match ----- ``match(s, s:&subject, i:&pos, i:0`` : *integer* ``match(s1, s2, i1, i2)`` produces *i1+\*s1* if *s1* == *s2[i1 +: \*s1]* but fails otherwise. A string scanning function that returns the index at the end of a match starting at current position (by default). .. literalinclude:: examples/match.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/match.icn` Sample run: .. command-output:: unicon -s match.icn -x :cwd: examples .. seealso:: :ref:`tab`, :ref:`=expr` -------- .. index:: MatrixMode, function; MatrixMode .. _MatrixMode: MatrixMode ---------- .. function:: MatrixMode(w, s) -> record :argument: window :argument: string, "projection" or "modelview" :returns: display list record Sets the current matrix stack mode. The "projection" stack can hold 2 matrices, the "modelview" stack can hold 32 matrices. .. literalinclude:: examples/MatrixMode.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/MatrixMode.icn` Sample run (not auto captured): .. skipped command-output:: unicon -s MatrixMode.icn -x :cwd: examples -------- .. index:: max, function; max .. _max: max --- ``max(n, ...)`` : *number* ``max()`` returns the largest value from the list of arguments. The arguments do not need to be numeric, but reasoning about comparison rules between different structures of possibly different types can be quite tricky. .. literalinclude:: examples/max.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/max.icn` Sample run: .. command-output:: unicon -s max.icn -x :cwd: examples -------- .. index:: member, function; member .. _member: member ------ ``member(x, ...)`` : *x?* ``member(x, ...)`` returns *x* if all other arguments are members of the :ref:`set`, :ref:`cset `, :ref:`list `, or :ref:`table ` *x*, but fails otherwise. If *x* is a ``cset`` all of the characters in subsequent string arguments must be present in *x* in order to succeed. .. literalinclude:: examples/member.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/member.icn` Sample run: .. command-output:: unicon -s member.icn -x :cwd: examples -------- .. index:: membernames, function; membernames .. _membernames: membernames ----------- ``membernames(x)`` : *list* ``membernames(x)`` produces a list containing the string names of the fields of *x*, where *x* is either an object or a string name of a :ref:`class `. .. literalinclude:: examples/membernames.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/membernames.icn` Sample run: .. command-output:: unicon -s membernames.icn -x :cwd: examples -------- .. index:: methodnames, function; methodnames .. _methodnames: methodnames ----------- ``methodnames()`` : *type* ``methodnames(x)`` produces a list containing the string names of the fields of *x*, where *x* is either an object or a string name of a :ref:`class `. .. literalinclude:: examples/methodnames.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/methodnames.icn` Sample run: .. command-output:: unicon -s methodnames.icn -x :cwd: examples -------- .. index:: methods, function; methods .. _methods: methods ------- ``methods(x)`` : *list* ``methods(x)`` produces a :ref:`list ` containing the procedure values of the methods of *x*, where *x* is either an object or the string name of a class. .. literalinclude:: examples/methods.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/methods.icn` Sample run: .. command-output:: unicon -s methods.icn -x :cwd: examples -------- .. index:: min, function; min .. _min: min --- ``min(n, ...)`` : *number* ``min()`` returns the smallest value from the list of arguments, which must be numeric. .. literalinclude:: examples/min.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/min.icn` Sample run: .. command-output:: unicon -s min.icn -x :cwd: examples -------- .. index:: mkdir, function; mkdir .. _mkdir: mkdir ----- ``mkdir(s, x)`` : *?* ``mkdir(path, mode)`` attempts to create directory *path* with permissions *mode*. *mode* can be an integer or a string of the form:: [ugoa]*[+-=][rwxRWXstugo]* See :ref:`chmod ` for more details on mode values. Getting the normal 8r755 value used for most directories is difficult with the mode string, as you need to set ``u=rwx`` but ``go=rx``. It is easiest to leave *mode* as a default, or use the octal notation. .. literalinclude:: examples/mkdir.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/mkdir.icn` Sample run: .. command-output:: unicon -s mkdir.icn -x :cwd: examples -------- .. index:: move, function; move .. _move: move ---- ``move(i:1)`` : *string* ``move(i)`` moves the string scanning position :ref:`&pos` *i* characters from the current position and returns the substring of :ref:`&subject` between the old and new positions. This function will reset an old value if it is resumed during goal-directed evaluation. The ``move()`` function makes little sense outside a string scanning environment but will effect ``&pos`` and read any explicitly set ``&subject``. .. literalinclude:: examples/move.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/move.icn` Sample run: .. command-output:: unicon -s move.icn -x :cwd: examples -------- .. index:: MultMatrix, function; MultMatrix .. _MultMatrix: MultMatrix ---------- .. function:: MultMatrix(w, L) -> record :Returns: Transformation matrix record. Multiplies the current transformation matrix used in 3D window *w* by the 4x4 matrix represented as a list of 16 values in *L*. .. literalinclude:: examples/MultMatrix.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/MultMatrix.icn` Sample run: .. skipped command-output:: unicon -s MultMatrix.icn -x :cwd: examples .. seealso:: :ref:`MatrixMode`, :ref:`PopMatrix`, :ref:`PushMatrix`, :ref:`IdentityMatrix` -------- .. index:: mutex, function; mutex .. _mutex: mutex ----- ``mutex(x, y)`` : *x* ``mutex(x)`` creates a new mutual exclusion control variable for structure *x*, which can be a :ref:`list `, :ref:`set ` or :ref:`table
`. ``mutex(x, y)`` associates an existing mutex *y* (or mutex associated with protecting resoure *y*) with structure *x*. ``mutex()`` returns a new non-associated control variable, which can be used with :ref:`critical `. .. literalinclude:: examples/mutex.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/mutex.icn` Sample run: .. command-output:: unicon -s mutex.icn -x :cwd: examples .. seealso:: :ref:`critical` -------- .. index:: name, function; name .. _name: name ---- ``name(v, CE:¤t)`` : *type* ``name(v, ce)`` returns the name of variable *v* within the program that created co-expression *ce* . Keyword variables are recognized. ``name()`` returns the base type and subscript or field information for variables that are elements within other values, but the returned string will unlikely match the source code for such variables. .. literalinclude:: examples/name.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/name.icn` Sample run (ends with error): .. command-output:: unicon -s name.icn -x :cwd: examples :returncode: 1 -------- .. index:: NewColor, function; NewColor .. _NewColor: NewColor -------- ``NewColor(w, s)`` : *integer* [*Graphics*] ``NewColor(w, s)`` allocates a mutable colour entry in the palette map for the current windowing system, initializing the colour to *s*, and returns a small negative integer for this entry. The colour integer can be used as a colour specification. ``NewColor()`` fails if the entry cannot be allocated/ This is not deprecated, but mostly unnecessary with modern display hardware. Most current graphic displays can handle millions of simultaneous colours, something not possible when older graphics programs had a limited palette of colours to use at any given time, limited by the electronics of the day. .. literalinclude:: examples/NewColor.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/NewColor.icn` Sample run: .. command-output:: unicon -s NewColor.icn -x :cwd: examples .. image:: images/NewColor.png .. only:: html .. rst-class:: leftalign :download:`images/NewColor.png` -------- .. index:: Normals, function; Normals .. _Normals: Normals ------- .. function:: Normals(w, s|l) -> *List* :Returns: Element display list :Requires: 3D graphics Sets texture coordinates to those defined in the argument list or string. .. literalinclude:: examples/Normals.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Normals.icn` Sample run (pending): .. skipped command-output:: unicon -s Normals.icn -x :cwd: examples -------- .. index:: NotAny, function; NotAny .. _NotAny: NotAny ------ ``NotAny(c)`` : *[Pattern]* ``NotAny(c)`` is a SNOBOL based pattern that matches any single character *not* contained in the character set *c*, appearing in the subject string. .. literalinclude:: examples/NotAny.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/NotAny.icn` Sample run: .. command-output:: unicon -s NotAny.icn -x :cwd: examples -------- .. index:: Nspan, function; Nspan .. _NSpan: Nspan ------ ``Nspan(cset)`` : *string* A SNOBOL inspired pattern matching function. ``Nspan(cs)`` will match zero or more subject characters from the :ref:`cset ` *cs*. It is equivalent to the pattern ``Span(cs) .| ""`` (matching the empty string after failing to span across any of the available characters). .. literalinclude:: examples/Nspan.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Nspan.icn` Sample run: .. command-output:: unicon -s Nspan.icn -x :cwd: examples .. seealso:: :ref:`Span`, :ref:`Break`. -------- .. index:: numeric, function; numeric .. _numeric: numeric ------- ``numeric(any)`` : *number* ``numeric(x)`` produces an integer or real number resulting from type conversion of *x*, or fails if the conversion is not possible. .. literalinclude:: examples/numeric.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/numeric.icn` Sample run: .. command-output:: unicon -s numeric.icn -x :cwd: examples -------- .. index:: open, function; open .. _open: open ---- ``open(s, s:"rt", ...)`` : *file?* ``open(s1, s2, ...)`` opens a resource named *s1* with mode *s2* and attributes given in trailing arguments. ``open()`` recognizes the following resource type: - file - socket - tcp, mode "n" for network - udp, mode "nu" for UDP network - http, mode "m" for messaging - https, mode "m-" (be forgiving with certificate authentication) - https, mode "m" (authenticated) - smtp, mode "m" - pop, mode "m" - finger, mode "m" - mailto, mode "m" with email header fields as attribute arguments .. todo:: a constant todo item is keeping this list up to date The mode in *s2* can be - "a" append; write after current contents - "b" open for both reading and writing (b does not mean binary mode!) - "c" create a new file and open it - "d" open a [NG]DBM database - "g" create a 2D graphics window - "gl" create a 3D graphics window - "n" connect to a remote TCP network socket - "na" accept a connection from a TCP network socket - "nau" accept a connection from a UDP network socket - "nl" listen on a TCP network socket - "nu" connect to a UDP network socket - "m" connect to a messaging server (HTTP, SMTP, POP, ...) - "m-" connect to secure HTTPS, unauthenticated certificates allowed - "o" open an ODBC connection to a (typically SQL) database - "p" execute a program given by command line s1 and open a pipe to it - "prw" open an asynchronous pseudo terminal connection - "r" read - "t" use text mode, with newlines translated - "u" use a binary untranslated mode - "w" write - "x" DEPRECATED, old X11 mode, use "g" - "z" libz compressed modifier .. literalinclude:: examples/open.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/open.icn` Sample run: .. command-output:: unicon -s open.icn -x :cwd: examples .. seealso:: :ref:`close`, :ref:`read`, :ref:`reads` -------- .. index:: opencl, function; opencl .. _opencl: opencl ------ ``opencl(list)`` : *integer* An experimental Unicon interface to the Open Computing Language. Integrating CPU, GPU and other auxiliary hardware in a single framework with a backing programming language based on ``C99``. The specification of OpenCL is royalty free, but there will be vendor specific portions, possibly non-free. https://en.wikipedia.org/wiki/OpenCL by the Khronos Group. .. attention:: Not yet officially part of Unicon release 13. ``opencl(L)`` will display information and properties of the given list of devices. .. literalinclude:: examples/opencl.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/opencl.icn` Sample run (skipped for now): .. skipped command-output:: unicon -s opencl.icn -x :cwd: examples -------- .. index:: oprec, function; oprec .. _oprec: oprec ----- ``oprec(x)`` : *record* ``oprec(r)`` produces a variable reference for the class method vector of *r*. .. literalinclude:: examples/oprec.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/oprec.icn` Sample run: .. command-output:: unicon -s oprec.icn -x :cwd: examples -------- .. index:: ord, function; ord .. _ord: ord --- ``ord(s)`` : *integer* ``ord(s)`` produces the character ordinal of the one character string *s*. The :ref:`ASCII ` value of the byte. .. literalinclude:: examples/ord.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/ord.icn` Sample run: .. command-output:: unicon -s ord.icn -x :cwd: examples -------- .. index:: OutPort, function; OutPort .. _OutPort: OutPort ------- ``OutPort(i1, i2)`` : *null* [*MS-DOS*] ``OutPort(i1, i2)`` will write *i2* to port *i1*. This is an MS-DOS specific feature of Unicon. *i2* in the range 0-255, a byte value. .. literalinclude:: examples/OutPort.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/OutPort.icn` Sample run (skipped on this GNU/Linux build machine): .. skipped command-output:: unicon -s OutPort.icn -x :cwd: examples .. seealso:: :ref:`InPort` -------- .. index:: PaletteChars, function; PaletteChars .. _PaletteChars: PaletteChars ------------ .. function:: PaletteChars(w, s) -> *string* :Returns: String :Requires: Graphics Produces a string containing each of the letters in palette *s*. The palettes *c1* through *c6* define different colour encodings of images represented as string data. .. literalinclude:: examples/PaletteChars.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/PaletteChars.icn` Sample run: .. command-output:: unicon -s PaletteChars.icn -x | par :cwd: examples :shell: -------- .. index:: PaletteColor, function; PaletteColor .. _PaletteColor: PaletteColor ------------ .. function:: PaletteColor(w, p, s) -> *string* :Returns: the colour key *s* in palette *p* from window *w*. Returns the colour of key *s* in "r,g,b" form. .. literalinclude:: examples/PaletteColor.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/PaletteColor.icn` Sample run: .. command-output:: unicon -s PaletteColor.icn -x :cwd: examples -------- .. index:: PaletteKey, function; PaletteKey .. _PaletteKey: PaletteKey ---------- .. function:: PaletteKey(w, p, s) -> *string* :Returns: the colour key of the closet colour to *s* in palette *p*. Returns the colour of key *s* in "r,g,b" form. .. literalinclude:: examples/PaletteKey.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/PaletteKey.icn` Sample run: .. command-output:: unicon -s PaletteKey.icn -x :cwd: examples -------- .. index:: paramnames, function; paramnames .. _paramnames: paramnames ---------- ``paramnames(CE, i:0)`` : *string* ``paramnames(ce, i)`` produces the names of the parameters in the procedure activation *i* levels above the current activation in *ce*. .. literalinclude:: examples/paramnames.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/paramnames.icn` Sample run: .. command-output:: unicon -s paramnames.icn -x :cwd: examples -------- .. index:: parent, function; parent .. _parent: parent ------ .. function:: parent(CE) -> co-expression ``parent(ce)`` returns the co-expression that created *ce*. Useful with :ref:`load `. .. literalinclude:: examples/parent.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/parent.icn` .. literalinclude:: examples/load-child.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/load-child.icn` Sample run: .. command-output:: unicon -s load-child.icn :cwd: examples .. command-output:: unicon -s parent.icn -x :cwd: examples -------- .. index:: Pattern, function; Pattern .. _Pattern: Pattern ------- ``Pattern(w, s)`` : *window* ``Pattern(w, s)`` selects a stipple pattern ``s`` for use during draw and fill operations. ``s`` may be the name of a *system-dependent* pattern or a literal, in the form ``"width,bits"``. Patterns are only used when the ``fillstyle`` attribute is ``stippled``, ``opaquestippled`` or ``textured``. ``Pattern()`` fails if a named pattern is not defined. An error occurs if ``s`` is a malformed literal. .. literalinclude:: examples/Pattern.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Pattern.icn` Sample run: .. command-output:: unicon -s Pattern.icn -x :cwd: examples .. image:: images/Pattern.png .. only:: html .. rst-class:: leftalign :download:`images/Pattern.png` -------- .. index:: Peek, function; Peek .. _Peek: Peek ---- ``Peek(A, i)`` : *string* [*MS-DOS*] This is an MS-DOS specific Unicon feature, now outdated. ``Peek(A, i)`` builds a string from an "address" *A* (returned from :ref:`GetSpace `, memory outside of Unicon control and not garbage collected), of length *i*. .. literalinclude:: examples/Peek.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Peek.icn` Sample run (skipped on this GNU/Linux machine): .. skipped command-output:: unicon -s Peek.icn -x :cwd: examples .. seealso:: :ref:`Poke`, :ref:`GetSpace`, :ref:`FreeSpace`, :ref:`Int86` -------- .. index:: Pending, function; Pending .. _Pending: Pending ------- .. function:: Pending(w : window='&window'[, x, ...]) -> list Produce the list of pending events for window *w*, adding optional events *x*, to the end of the list, in a guaranteed order. ``Pending(w)`` produces the list of events waiting on window *w*. ``Pending(w, x1,...,xn)`` adds *x1* through *xn* to the end of *w*'s pending list in the given order. .. literalinclude:: examples/Pending.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Pending.icn` Sample run: .. command-output:: unicon -s Pending.icn -x :cwd: examples -------- .. index:: pipe, function; pipe .. _pipe: pipe ---- .. function:: pipe() -> list :unicon:`pipe()` creates a pipe and returns a list of two file objects. The first is for reading, the second is for writing. .. literalinclude:: examples/pipe.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/pipe.icn` Sample run: .. command-output:: unicon -s pipe.icn -x :cwd: examples -------- .. index:: Pixel, function; Pixel .. _Pixel: Pixel ----- **Pixel(w, ix, iy, iw, ih)** : *integer*\* [*Graphics*] ``Pixel(w, x,y, wid,hgt)`` generates pixel contents from a rectangular area within window *w*. Top left corner is *x.y* and pixel colours are generated in the *wid,hgt* rectangle down each column, from left to right. Pixel values are returned as 16bit RGB values, with mutable colours being negative integers, as returned by :u:func:`NewColor()`. :u:func:`Pixel()` fails if part of the requested rectangle extends beyond the canvas. .. literalinclude:: examples/Pixel.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Pixel.icn` Sample run: .. command-output:: unicon -s Pixel.icn -x :cwd: examples .. image:: images/Pixel.png .. only:: html .. rst-class:: leftalign :download:`images/Pixel.png` -------- .. index:: PlayAudio, function; PlayAudio .. _PlayAudio: PlayAudio --------- ``PlayAudio(s)`` : *integer* [*Audio*] ``PlayAudio(s)`` will attempt to start an audio thread and play the filename *s*. Accepts .wav and .ogg files when Unicon if built with OpenAL and/or Vorbis support. Returns an integer from 0 to 15, representing the thread stream, or fails if the filename cannot be read, is an invalid format, too many channels are already in play, or there are problems with the sound equipment. .. literalinclude:: examples/PlayAudio.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/PlayAudio.icn` Sample run (skipped, you probably wouldn't hear it from here anyway): .. skipped command-output:: unicon -s PlayAudio.icn -x :cwd: examples .. seealso:: :ref:`StopAudio`, :ref:`VAttrib` -------- .. index:: Poke, function; Poke .. _Poke: Poke ---- ``Poke(A, s)`` : *null* This is an outdated MS-DOS specific feature of Unicon. ``Poke(A, s)`` will replace the memory at "address" *A*, with the contents of string *s*. The "address" *A* is usually from :ref:`GetSpace ` outside of Unicon control and garbage collection. .. literalinclude:: examples/Poke.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Poke.icn` Sample run (skipped on this GNU/Linux build machine): .. skipped command-output:: unicon -s Poke.icn -x :cwd: examples .. seealso:: :ref:`Peek`, :ref:`GetSpace`, :ref:`FreeSpace`, :ref:`Int86` -------- .. index:: pop, function; pop .. _pop: pop --- ``pop(L | Message)`` : *any?* ``pop(L)`` remove an element from the top of the stack *L[1]*, and return the value. ``pop(M)`` removes and returns the first message in a POP mailbox connection *M*. *The actual delete occurs on close.* .. literalinclude:: examples/pop.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/pop.icn` Sample run: .. command-output:: unicon -s pop.icn -x :cwd: examples -------- .. index:: PopMatrix, function; PopMatrix .. _PopMatrix: PopMatrix --------- .. function:: PopMatrix(w) -> *record* :Returns: Display list element record PopMatrix(w) pops the top matrix from the either the "projection" or "modelview" matrix stack. The function fails if there is only element on the current matrix stack. .. literalinclude:: examples/PopMatrix.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/PopMatrix.icn` Sample run: .. skipped command-output:: unicon -s PopMatrix.icn -x :cwd: examples .. seealso:: :ref:`PushMatrix`, :ref:`MatrixMode` -------- .. index:: Pos, function; Pos .. _Pos-pattern: Pos --- ``Pos(i)`` : *null* A SNOBOL based pattern matching function, positional test. ``Pos(i)`` will ensure the scanning position is at *i* or will fail. Good for ensuring anchored match strategies along with other position verification uses when validating pattern matches. .. literalinclude:: examples/Pos.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Pos.icn` Sample run: .. command-output:: unicon -s Pos.icn -x :cwd: examples -------- .. index:: pos, function; pos .. _pos: pos --- ``pos(i)`` : *integer?* ``pos(i)`` tests whether :ref:`&pos` is at position *i* in :ref:`&subject`. .. literalinclude:: examples/pos.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/pos.icn` Sample run: .. command-output:: unicon -s pos.icn -x :cwd: examples -------- .. index:: proc, function; proc .. _proc: proc ---- ``proc(any, i:1, CE)`` : *procedure* ``proc(s, i)`` converts *s* to a procedure, if possible. The parameter *i* is used to resolve ambiguous names by argument count. - 0, built-in (for when the procedure name is overridden by a user program) - 1, signature has 1 parameter - 2, procedure has 2 parameters - 3, procedure has 3 parameters ``proc`` can also resolve procedure names in co-expression *CE*, *i* levels up. .. literalinclude:: examples/proc.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/proc.icn` Sample run: .. command-output:: unicon -s proc.icn -x :cwd: examples -------- .. index:: pull, function; pull .. _pull: pull ---- ``pull(L, i:1)`` : *any?* ``pull(L)`` removes and produces an element from the end of the non-empty list *L*. ``pull(L, i)`` removes *i* elements, producing the last one removed. .. literalinclude:: examples/pull.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/pull.icn` Sample run: .. command-output:: unicon -s pull.icn -x :cwd: examples -------- .. index:: push, function; push .. _push: push ---- ``push(L, any, ...)`` : *list* ``push(L, x1, ..., xn)`` pushes elements onto the beginning of :ref:`list `, *L*. The order added to the list is the reverse order they are supplied as parameters to the call to ``push()``. ``push()`` returns the list that is passed as the first parameter, with the new elements added. .. literalinclude:: examples/push.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/push.icn` Sample run: .. command-output:: unicon -s push.icn -x :cwd: examples -------- .. index:: PushMatrix, function; PushMatrix .. _PushMatrix: PushMatrix ---------- .. function:: PushMatrix(w) -> *record* :Returns: Display list element record PushMatrix(w) the current matrix to either the "projection" or "modelview" matrix stack. The function fails if current stack is full, 2 items for "projection" and 32 for "modelview". .. literalinclude:: examples/PushMatrix.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/PushMatrix.icn` Sample run (skipped): .. skipped command-output:: unicon -s PushMatrix.icn -x :cwd: examples .. seealso:: :ref:`PopMatrix`, :ref:`MatrixMode` -------- .. index:: PushRotate, function; PushRotate .. _PushRotate: PushRotate ---------- .. comment function:: PushRotate(w : &window, a, x, y, z) -> record :type: display list element record :argument n: numeric value :argument a: angle of rotation :argument x, y, z: direction of rotatation :returns: 3D display element Equivalent to :ref:`PushMatrix` followed by :ref:`Rotate`. .. literalinclude:: examples/PushRotate.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/PushRotate.icn` Sample run (not auto generated): .. skipped command-output:: unicon -s PushRotate.icn -x :cwd: examples .. seealso:: :ref:`PushMatrix`, :ref:`Rotate` -------- .. index:: PushScale, function; PushScale .. _PushScale: PushScale --------- ``PushScale()`` : *type* .. todo:: entry for function PushScale ``PushScale()`` .. pending literalinclude:: examples/PushScale.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/PushScale.icn` Sample run: .. pending command-output:: unicon -s PushScale.icn -x :cwd: examples -------- .. index:: PushTranslate, function; PushTranslate .. _PushTranslate: PushTranslate ------------- ``PushTranslate()`` : *type* .. todo:: entry for function PushTranslate ``PushTranslate()`` .. pending literalinclude:: examples/PushTranslate.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/PushTranslate.icn` Sample run: .. pending command-output:: unicon -s PushTranslate.icn -x :cwd: examples -------- .. index:: put, function; put .. _put: put --- ``put(L, x1,...,xn)`` : *list* ``put(L, x1,..., xn)`` puts elements on the end of :ref:`list ` *L*. Returns the list *L*, with elements added. .. literalinclude:: examples/put.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/put.icn` Sample run: .. command-output:: unicon -s put.icn -x :cwd: examples -------- .. index:: QueryPointer, function; QueryPointer .. _QueryPointer: QueryPointer ------------ ``QueryPointer(w)`` : *x,y* ``QueryPointer(w)`` generates *x* then *y* of the mouse cursor position relative to window *w*. ``QueryPointer()`` generates *x* then *y* of the mouse position relative to the display screen. .. literalinclude:: examples/QueryPointer.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/QueryPointer.icn` Sample run: .. command-output:: unicon -s QueryPointer.icn -x :cwd: examples -------- .. index:: Raise, function; Raise .. _Raise: Raise ----- ``Raise(w)`` : *window* [*Graphics*] ``Raise(w)`` raises window *w* to the top of the window stack, making it fully visible. Makes the window the active window. .. literalinclude:: examples/Raise.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Raise.icn` Sample run: .. command-output:: unicon -s Raise.icn -x :cwd: examples .. image:: images/Raise.png .. only:: html .. rst-class:: leftalign :download:`images/Raise.png` .. seealso:: :ref:`Lower` -------- .. index:: read, function; read .. _read: read ---- ``read(f:&input)`` : *string?* ``read(f)`` reads a line from file *f*. The end of line marker is discarded. Fails on end of file. .. literalinclude:: examples/read.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/read.icn` Sample run: .. command-output:: unicon -s read.icn -x :cwd: examples -------- .. index:: ReadImage, function; ReadImage .. _ReadImage: ReadImage --------- ``ReadImage(w, s, x:0, y:0)`` : *integer* ``ReadImage(w, s, x, y)`` loads an image from file *s* into window (or texture) *w*, at offset *x,y*. Returns an integer 0 for no errors, or a non zero indicating errors occurred. ``ReadImage()`` fails if *s* could not be read or is an invalid image format. .. literalinclude:: examples/ReadImage.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/ReadImage.icn` Sample run: .. command-output:: unicon -s ReadImage.icn -x :cwd: examples .. image:: images/ReadImage.png .. only:: html .. rst-class:: leftalign :download:`images/ReadImage.png` *Art by Serendel Macphereson* .. seealso:: :ref:`WriteImage` -------- .. index:: readlink, function; readlink .. _readlink: readlink -------- .. function:: readlink(path : string) -> string Produces the filename referenced by the symbolic link, *path*. :argument path: the path to dereference :return: The linked filename ``readlink(s)`` : *string* ``readlink(s)`` produces the filename referred to by the symbolic link at path *s*. .. literalinclude:: examples/readlink.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/readlink.icn` Sample run: .. command-output:: unicon -s readlink.icn -x :cwd: examples -------- .. index:: reads, function; reads .. _reads: reads ----- .. function:: reads(f : file='&input', i : integer='1') -> string Reads up to *i* characters from file *f*. :return: string ``reads(f:&input, i:1)`` : *string?* ``reads(f, i)`` reads up to *i* characters from *f*. It fails on end of file. If *f* is a network connection, *reads()* returns as soon as has input available, even if shorter than *i*. If *i* is ``-1``, ``reads()`` produces the entire file as a string. .. literalinclude:: examples/reads.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/reads.icn` Sample run: .. command-output:: unicon -s reads.icn -x :cwd: examples -------- .. index:: ready, function; ready .. _ready: ready ----- ``ready(f:&input, i:0)`` : *string?* ``ready(f, i)`` reads up to *i* characters from the file *f*. It returns immediately with available data or fails otherwise. If *i* is ``0``, ``ready()`` returns all available input. Not implemented for :ref:`window ` values. .. literalinclude:: examples/ready.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/ready.icn` Sample run: .. command-output:: unicon -s ready.icn -x :cwd: examples -------- .. index:: real, function; real .. _real-function: real ---- ``real(any)`` : *real?* ``real(x)`` converts *x* to a :ref:`real `, or fails if the conversion cannot be performed. .. literalinclude:: examples/real.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/real.icn` Sample run: .. command-output:: unicon -s real.icn -x :cwd: examples -------- .. index:: receive, function; receive .. _receive: receive ------- ``receive(f)`` : *record* ``receive(f)`` reads a datagram addressed to the port associated with *f*, waiting if necessary. The returned record is: ``record posix_message(addr, msg)`` containing the address of the sender and the contents of the message. .. literalinclude:: examples/receive.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/receive.icn` No sample run, document generator doesn't like to wait. .. skipped command-output:: unicon -s receive.icn -x :cwd: examples -------- .. index:: Refresh, function; Refresh .. _Refresh: Refresh ------- ``Refresh(w)`` : *window* [*3D Graphics*] ``Refresh(w)`` redraws the contents of window *w*. For use when objects have been moved in a 3D scene. Returns the window *w*. This is similar to the 2D graphic :ref:`WSync` function, but causes a redraw of cached 3D graphics, independent of any server side cache that may be in play. .. literalinclude:: examples/Refresh.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Refresh.icn` Sample run (not auto captured due to an issue with hidden canvas in 3D): .. skipped command-output:: unicon -s Refresh.icn -x :cwd: examples .. image:: images/Refresh.png .. only:: html .. rst-class:: leftalign :download:`images/Refresh.png` .. seealso:: :ref:`WSync` -------- .. index:: Rem, function; Rem .. _Rem: Rem --- ``Rem()`` : *string* A SNOBOL pattern match function. ``Rem()`` returns the remaining characters from the current position to the end of the subject string. This function won't ever fail. .. literalinclude:: examples/Rem.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Rem.icn` Sample run: .. command-output:: unicon -s Rem.icn -x :cwd: examples -------- .. index:: remove, function; remove .. _remove: remove ------ ``remove(s)`` : *?* ``remove(s)`` removes the file named *s*, or fails. .. literalinclude:: examples/remove.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/remove.icn` Sample run: .. command-output:: unicon -s remove.icn -x :cwd: examples -------- .. index:: rename, function; rename .. _rename: rename ------ ``rename(s, s)`` : *?* ``rename(s1, s2)`` renames file *s1* to the name *s2*. .. literalinclude:: examples/rename.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/rename.icn` Sample run: .. command-output:: unicon -s rename.icn -x :cwd: examples -------- .. index:: repl, function; repl .. _repl: repl ---- ``repl(x, i)`` : *x* ``repl(x, i)`` concatenates *i* copies of the string *x*. As of Unicon revision 4608, ``repl(L, n)`` can be used to replicate *n* copies of the :ref:`list ` *L*. .. literalinclude:: examples/repl.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/repl.icn` Sample run: .. command-output:: unicon -s repl.icn -x :cwd: examples -------- .. index:: reverse, function; reverse .. _reverse: reverse ------- ``reverse(x)`` : *x* ``reverse(x)`` returns the reverse of the string or list *x*. .. literalinclude:: examples/reverse.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/reverse.icn` Sample run: .. command-output:: unicon -s reverse.icn -x :cwd: examples -------- .. index:: right, function; right .. _right: right ----- ``right(s1, i:1, s2:" ")`` : *type* ``right(s1, i, s2)`` formats *s1* to be a string of length *i*. If *s1* has more than *i* characters, it is truncated (from the left). If *s1* has less than *i* characters then it is padded to the left with as many copies of *s2* needed to increase the length to *i*. Last copy of *s2* is right side truncated if necessary ("filler" will pad as "fill" for instance). .. literalinclude:: examples/right.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/right.icn` Sample run: .. command-output:: unicon -s right.icn -x :cwd: examples -------- .. index:: rmdir, function; rmdir .. _rmdir: rmdir ----- ``rmdir(s)`` : *?* ``rmdir(d)`` removes the directory named *d*. ``rmdir()`` fails if *d* is not empty, or does not exist. .. literalinclude:: examples/rmdir.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/rmdir.icn` Sample run: .. command-output:: unicon -s rmdir.icn -x :cwd: examples -------- .. index:: Rotate, function; Rotate .. _Rotate: Rotate ------ ``Rotate()`` : *type* .. todo:: entry for function Rotate ``Rotate()`` .. pending literalinclude:: examples/Rotate.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Rotate.icn` Sample run: .. pending command-output:: unicon -s Rotate.icn -x :cwd: examples -------- .. index:: Rpos, function; Rpos .. _Rpos: Rpos ---- ``Rpos(i)`` : *null* A SNOBOL pattern function. Like `Pos` counted back from the end. ``Rpos(i)`` will test if the current scanning position is equal to *i* position back from the end of the subject string. Fails if not. .. literalinclude:: examples/Rpos.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Rpos.icn` Sample run: .. command-output:: unicon -s Rpos.icn -x :cwd: examples -------- .. index:: Rtab, function; Rtab .. _Rtab: Rtab ---- ``Rtab(i)`` : *string* A SNOBOL inspired pattern matching function. ``Rtab(i)`` causes the cursor to be placed *i* positions back from the end of the subject, and returns the characters between the current position and this new position. .. literalinclude:: examples/Rtab.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Rtab.icn` Sample run: .. command-output:: unicon -s Rtab.icn -x :cwd: examples .. seealso:: `Tab` -------- .. index:: rtod, function; rtod .. _rtod: rtod ---- ``rtod()`` : *real* ``rtod(radians)`` given radians as a ``Real`` value, produces the conversion to degrees, as a ``Real`` number. :math:`d^{\circ} = r\frac{180^{\circ}}{\pi}` .. literalinclude:: examples/rtod.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/rtod.icn` Sample run: .. command-output:: unicon -s rtod.icn -x :cwd: examples -------- .. index:: runerr, function; runerr .. _runerr: runerr ------ ``runerr(i, any)`` ``runerr(i, x)`` produces a runtime error *i* with value *x*. Program execution is terminated. .. literalinclude:: examples/runerr.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/runerr.icn` Sample run: .. command-output:: unicon -s runerr.icn :cwd: examples .. command-output:: ./runerr :cwd: examples :returncode: 1 -------- .. index:: save, function; save .. _save: save ---- ``save(s)`` : *?* ``save(s)`` saves the run-time system in file *s*. .. literalinclude:: examples/save.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/save.icn` Sample run: .. command-output:: unicon -s save.icn -x :cwd: examples -------- .. index:: Scale, function; Scale .. _Scale: Scale ----- ``Scale()`` : *type* .. todo:: entry for function Scale ``Scale()`` .. pending literalinclude:: examples/Scale.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Scale.icn` Sample run: .. pending command-output:: unicon -s Scale.icn -x :cwd: examples -------- .. index:: seek, function; seek .. _seek: seek ---- ``seek(f, any)`` : *file?* ``seek(f, i)`` seeks to offset *i* in file *f*, if it is possible. If *f* is a regular file, *i* must be an :ref:`integer `. If *f* is a database, *i* seeks a position within the current set of selected rows. The position is selected numerically if *i* is convertible to an integer, otherwise *i* must be convertible to a string, and the position is selected associatively by the primary key. .. literalinclude:: examples/seek.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/seek.icn` Sample run: .. command-output:: unicon -s seek.icn -x :cwd: examples -------- .. index:: select, function; select .. _select: select ------ ``select(x1, x2, ?)`` : *list* ``select(files?, timeout)`` waits for input to become available on any of several file resources, typically network connections or windows. The arguments may be files, or lists of files, ending with an optional integer timeout in milliseconds. It returns a list of the files from the input list that have input waiting. If the final argument to ``select()`` is an integer, it acts as a timeout forcing a select return. A timeout of ``0`` causes ``select()`` to return immediately with a list of files (if any). If no files are given, ``select()`` will wait for the timeout. If no timeout is given ``select()`` waits forever for available input on one of the arguments. Directories and databases cannot be arguments for ``select()`` .. literalinclude:: examples/select.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/select.icn` Sample run: .. command-output:: unicon -s select.icn -x :cwd: examples -------- .. index:: send, function; send .. _send: send ---- ``send(s, s)`` : *?* ``send(s1, s2)`` sends a UDP datagram to the address *s1* (in host:port format) with message contents *s2*. .. literalinclude:: examples/send.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/send.icn` Sample run: .. command-output:: unicon -s send.icn -x :cwd: examples -------- .. index:: seq, function; seq .. _seq: seq --- ``seq(i:1, i:1)`` : *integer*\* ``seq(i, j)`` generates an infinite sequence *i*, *i+j*, *i+2j*, .... *j* may not be ``0``. .. literalinclude:: examples/seq.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/seq.icn` Sample run: .. command-output:: unicon -s seq.icn -x :cwd: examples -------- .. index:: serial, function; serial .. _serial: serial ------ ``serial(x)`` : *integer* ``serial(x)`` returns the serial number for structure *x*, if it has one. Serial numbers uniquely identify structure values. .. literalinclude:: examples/serial.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/serial.icn` Sample run: .. command-output:: unicon -s serial.icn -x :cwd: examples -------- .. index:: set, function; set .. _set-function: set --- ``set(x, ...)`` : *set* ``set()`` create a set. Arguments are inserted into the new set, with the exception of lists. ``set(L)`` creates a set with members taken from the elements of :ref:`list ` *L*. .. literalinclude:: examples/set.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/set.icn` Sample run: .. command-output:: unicon -s set.icn -x :cwd: examples -------- .. index:: setenv, function; setenv .. _setenv: setenv ------ ``setenv(s, s)`` : *?* ``setenv(s1, s2)`` sets environment variable *s1* to the value *s2*. .. literalinclude:: examples/setenv.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/setenv.icn` Sample run: .. command-output:: unicon -s setenv.icn -x :cwd: examples .. seealso:: :ref:`getenv` -------- .. index:: setgid, function; setgid .. _setgid: setgid ------ ``setgid(i)`` : *null* [*POSIX*] ``setgid(i)`` will attempt to set the current process group id. Usually requires permissions. .. literalinclude:: examples/setgid.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/setgid.icn` Sample run: .. command-output:: unicon -s setgid.icn -x :cwd: examples .. seealso:: :ref:`getgid`, :ref:`getgr` -------- .. index:: setgrent, function; setgrent .. _setgrent: setgrent -------- ``setgrent()`` : *null* [*POSIX*] ``setgrent()`` resets and rewinds the implicit context used by :ref:`getgr` to read through the operating system group entities when ``getgr()`` is given no explicit key value. .. literalinclude:: examples/setgrent.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/setgrent.icn` Sample run: .. command-output:: unicon -s setgrent.icn -x :cwd: examples .. seealso:: :ref:`getgr` -------- .. index:: sethostent, function; sethostent .. _sethostent: sethostent ---------- ``sethostent()`` : *type* .. todo:: entry for function sethostent ``sethostent()`` .. pending literalinclude:: examples/sethostent.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/sethostent.icn` Sample run: .. pending command-output:: unicon -s sethostent.icn -x :cwd: examples -------- .. index:: setpgrp, function; setpgrp .. _setpgrp: setpgrp ------- ``setpgrp()`` : *type* .. todo:: entry for function setpgrp ``setpgrp()`` .. pending literalinclude:: examples/setpgrp.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/setpgrp.icn` Sample run: .. pending command-output:: unicon -s setpgrp.icn -x :cwd: examples -------- .. index:: setpwent, function; setpwent .. _setpwent: setpwent -------- ``setpwent()`` : *type* .. todo:: entry for function setpwent ``setpwent()`` .. pending literalinclude:: examples/setpwent.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/setpwent.icn` Sample run: .. pending command-output:: unicon -s setpwent.icn -x :cwd: examples -------- .. index:: setservent, function; setservent .. _setservent: setservent ---------- ``setservent()`` : *type* .. todo:: entry for function setservent ``setservent()`` .. pending literalinclude:: examples/setservent.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/setservent.icn` Sample run: .. pending command-output:: unicon -s setservent.icn -x :cwd: examples -------- .. index:: setuid, function; setuid .. _setuid: setuid ------ ``setuid()`` : *type* .. todo:: entry for function setuid ``setuid()`` .. pending literalinclude:: examples/setuid.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/setuid.icn` Sample run: .. pending command-output:: unicon -s setuid.icn -x :cwd: examples -------- .. index:: signal, function; signal .. _signal: signal ------ ``signal(cv, i:1)`` : *?* ``signal(x, y)`` signals the condition variable *x*. If *y* is supplied, the condition variable is signalled *y* times. If *y* is 0, a **broadcast** signal is sent, waking up all threads waiting on *x*. .. literalinclude:: examples/signal.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/signal.icn` Sample run: .. command-output:: unicon -s signal.icn -x :cwd: examples .. seealso:: :ref:`condvar`, :ref:`wait` -------- .. index:: sin, function; sin, trig; sin .. _sin: sin --- ``sin(r)`` : *real* ``sin(r)`` returns the sine value of the given angle, *r* (in radians) .. literalinclude:: examples/sin.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/sin.icn` Sample run: .. command-output:: unicon -s sin.icn -x :cwd: examples Graphical plot: .. literalinclude:: examples/plot-function.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/plot-function.icn` .. command-output:: unicon -s plot-function.icn -x sin :cwd: examples .. image:: images/plot-sin.png .. only:: html .. rst-class:: leftalign :download:`images/plot-sin.png` .. seealso:: :ref:`acos`, :ref:`atan`, :ref:`asin`, :ref:`cos`, :ref:`tan` -------- .. index:: sort, function; sort .. _sort: sort ---- ``sort(x, i:1)`` : *list* ``sort(x)`` sorts the structure *x* in ascending order. If *x* is a table, ``sort(x, i)`` uses *i* as a sort method indicator. If *i* is ``1`` or ``2``, the table is sorted into a list of lists ``[[key, value], ...]``. If *i* is ``3`` or ``4`` then the table is sorted into a single list of alternating keys and values. Sorting is by keys for odd values of *i* and element values for even values of *i*. .. literalinclude:: examples/sort.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/sort.icn` Sample run: .. command-output:: unicon -s sort.icn -x :cwd: examples -------- .. index:: sortf, function; sortf .. _sortf: sortf ----- ``sortf(x, i:1)`` : *list* ``sortf(x, i)`` sorts a list, record or set *x* using field *i* of each elements that has one. Elements that don't have and *i*\ th field are sorted in standard order, coming before elements that do have an *i*\ th field. .. literalinclude:: examples/sortf.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/sortf.icn` Sample run: .. command-output:: unicon -s sortf.icn -x :cwd: examples -------- .. index:: Span, function; Span .. _Span: Span ---- ``Span()`` : *type* .. todo:: entry for function Span ``Span()`` .. pending literalinclude:: examples/Span.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Span.icn` Sample run: .. pending command-output:: unicon -s Span.icn -x :cwd: examples -------- .. index:: spawn, function; spawn .. _spawn: spawn ----- ``spawn(CE, i, i)`` : *thread* ``spawn(ce)`` launches co-expression *ce* as an asynchronous thread, executed concurrently with the current co-expression. The two optional integers specify the thread's block and string region allocations. The defaults are 10% of the main thread head size. .. literalinclude:: examples/spawn.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/spawn.icn` Sample run: .. command-output:: unicon -s spawn.icn -x :cwd: examples .. seealso:: :ref:`create`, :ref:`thread`, :ref:`wait` -------- .. index:: sql, function; sql .. _sql: sql --- ``sql(D, s)`` : *integer* ``sql(db, query)`` executes arbitrary SQL code on *db*. The *query* will be handled by vendor-specific features of the :ref:`ODBC ` engine in use. ``sql()`` is a power function that can leave a database in any state, as specified by the given SQL statement(s). Use care when feeding user entered *query* strings to the ``sql()`` function. .. literalinclude:: examples/sql.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/sql.icn` Sample run: .. command-output:: unicon -s sql.icn -x :cwd: examples -------- .. index:: sqrt, function; sqrt .. _sqrt: sqrt ---- ``sqrt(r)`` : *real* ``sqrt(r)`` produces the square root of *r*. Will raise a runtime error for negative values of *r*. .. literalinclude:: examples/sqrt.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/sqrt.icn` Sample run (ends with error demonstration): .. command-output:: unicon -s sqrt.icn -x :cwd: examples :returncode: 1 -------- .. index:: stat, function; stat .. _stat: stat ---- ``stat(s)`` : *record* ``stat(f)`` returns a record of filesystem information for file (or path) *f*. See :ref:`lstat`. Return record is:: record posix_stat(dev, ino, mode, nlink, gid, rdev, size, atime, mtime, ctime, blksize, blocks, symlink) The ``atime``, ``ctime``, and ``mtime`` fields may be formatted with the :ref:`ctime() ` and :ref:`gtime() ` functions. ``mode`` is a string form similar to the output of ``ls -l``. ``stat()`` will fail if the file or path *f* does not exist. .. literalinclude:: examples/stat.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/stat.icn` Sample run: .. command-output:: unicon -s stat.icn -x :cwd: examples -------- .. index:: staticnames, function; staticnames .. _staticnames: staticnames ----------- ``staticnames(CE, i)`` : *string*\* ``staticnames(ce, i)`` generates the names of local variables in co-expression *ce*, *i* levels up from the current procedure invocation. The default, level 0, generates names in the currently active procedure inside *ce*. .. literalinclude:: examples/staticnames.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/staticnames.icn` Sample run: .. command-output:: unicon -s staticnames.icn -x :cwd: examples .. seealso:: :ref:`globalnames`, :ref:`localnames` -------- .. index:: stop, function; stop .. _stop: stop ---- ``stop(s|f, ...)`` ``stop(args)`` halts execution after writing out string arguments, followed by a newline, to :ref:`&errout`. If any argument is a ``file``, subsequent string arguments are written to that file instead of ``&errout``. The program exit status indicates that an error occurred. .. literalinclude:: examples/stop.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/stop.icn` Sample run: .. command-output:: unicon -s stop.icn :cwd: examples .. command-output:: ./stop ; echo $? :cwd: examples :shell: -------- .. index:: StopAudio, function; StopAudio .. _StopAudio: StopAudio --------- ``StopAudio(i)`` : *integer* [*Audio*] ``StopAudio(i)`` stops the thread playing audio on channel *i*. Returns 1 or triggers an error if *i* is not an integer. Attempting to stop non running channel numbers will be gracefully ignored. .. literalinclude:: examples/StopAudio.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/StopAudio.icn` Sample run (skipped, you probably wouldn't hear it anyway): .. skipped command-output:: unicon -s StopAudio.icn -x :cwd: examples .. seealso:: :ref:`PlayAudio`, :ref:`VAttrib` -------- .. index:: string, function; string .. _string-function: string ------ ``string(x)`` : *string?* ``string(x)`` converts *x* to a :ref:`string ` and returns the result, or fails if the conversion is not possible. .. literalinclude:: examples/string.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/string.icn` Sample run: .. command-output:: unicon -s string.icn -x :cwd: examples -------- .. index:: structure, function; structure .. _structure: structure --------- ``structure(CE)`` : *any*\* ``structure(ce)`` generates the values in the block region of *ce*. This heap holds structure types such as lists and tables. .. literalinclude:: examples/structure.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/structure.icn` Sample run: .. command-output:: unicon -s structure.icn -x :cwd: examples .. seealso:: :ref:`cofail`, :ref:`fieldnames`, :ref:`globalnames`, :ref:`keyword`, :ref:`localnames`, :ref:`paramnames`, :ref:`staticnames`, :ref:`variable` -------- .. index:: Succeed, function; Succeed .. _Succeed: Succeed ------- ``Succeed()`` : *empty string* ``Succeed()`` places a fence on pattern matching, by matching the empty string when going left to right, and forcing the scanner to reverse direction forwards during backtracking. .. attention:: This function will almost always cause an endless loop and should NOT be used. Except for wasting CPU when the pattern is known to match on a first pass, or endlessly spinning when the pattern matcher needs to backtrack. Use :ref:`Fence` (or possibly :ref:`Fail`) instead. .. literalinclude:: examples/Succeed.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Succeed.icn` Sample run (skipped, as this pattern function is a no-win trap): .. skipped command-output:: unicon -s Succeed.icn -x :cwd: examples .. seealso:: :ref:`Fail`, :ref:`Fence` -------- .. index:: Swi, function; Swi .. _Swi: Swi --- ``Swi()`` : *type* An unsupported Archimedes specific feature. ``Swi()`` .. pending literalinclude:: examples/Swi.icn :language: unicon :start-after: ##+ .. pending only:: html .. rst-class:: rightalign :download:`examples/Swi.icn` Sample run: .. pending command-output:: unicon -s Swi.icn -x :cwd: examples -------- .. index:: symlink, function; symlink .. _symlink: symlink ------- ``symlink(s, s)`` : *?* [*POSIX*] ``symlink(src, dst)`` creates a symbolic (soft) file system link *dst* pointing to *src*. .. literalinclude:: examples/symlink.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/symlink.icn` Sample run: .. command-output:: unicon -s symlink.icn -x :cwd: examples -------- .. index:: sys_errstr, function; sys_errstr .. _sys_errstr: sys_errstr ---------- ``sys_errstr(i)`` : *string* ``sys_errstr(i)`` produces the error string corresponding to code *i*, or if not given, a code obtained from :ref:`&errno`. .. literalinclude:: examples/sys_errstr.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/sys_errstr.icn` Sample run: .. command-output:: unicon -s sys_errstr.icn -x :cwd: examples -------- .. index:: system, function; system .. _system: system ------ ``system(x, f:&input, f:&output, f:&errout, s)`` : *integer* ``system(x, f1, f2, f3, waitflag)`` executes a program in a separate process. *x* can be a string or a list of strings. For a single string, the command is processed by the platform's command interpreter. For a list, each member is a separate argument, the first is the program and all subsequent parameters are passed as arguments to the command. The ``file`` arguments are used for standard in, standard out and standard error for the new process. If the *waitflag* is ``"nowait"``, then ``system()`` returns immediately and the result is the new process id. Otherwise Unicon will wait for the new program to finish and the result is a status value. .. literalinclude:: examples/system.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/system.icn` Sample run: .. command-output:: unicon -s system.icn -x :cwd: examples -------- .. index:: syswrite, function; syswrite .. _syswrite: syswrite -------- ``syswrite(f, s)`` : *integer* ``syswrite(f, s)`` causes a low level unbuffered write of the string *s* to file *f*. .. literalinclude:: examples/syswrite.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/syswrite.icn` Sample run: .. command-output:: unicon -s syswrite.icn -x :cwd: examples -------- .. index:: Tab, function; Tab .. _Tab-pattern: Tab --- ``Tab(i)`` : *string* A SNOBOL inspired pattern matching function. ``Tab(i)`` places the cursor at position *i*, and returns the characters between the current position and the new position. .. literalinclude:: examples/Tab.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Tab.icn` Sample run: .. command-output:: unicon -s Tab.icn -x :cwd: examples .. seealso:: `Rtab` -------- .. index:: tab, function; tab .. _tab: tab --- ``tab(i:0)`` : *string?* ``tab(i)`` sets :ref:`&pos` to *i* and returns the substring of :ref:`&subject` between the old and new positions. ``tab(0)`` moves the position to the end of the string. This function reverts settings the position to its old value if it is resumed. .. literalinclude:: examples/tab.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/tab.icn` Sample run: .. command-output:: unicon -s tab.icn -x :cwd: examples -------- .. index:: table, function; table .. _table-function: table ----- ``table(k, v, ..., x)`` : *table* ``table(x)`` creates a table with default value *x*. If *x* is a structure, all references to the default value refers to the same same value, not a separate copy for each key. Given more than one argument, ``table(k,v,...,x)`` takes alternating keys and values to initialize the table. .. literalinclude:: examples/table.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/table.icn` Sample run: .. command-output:: unicon -s table.icn -x :cwd: examples -------- .. index:: tan, function; tan .. _tan: tan --- ``tan(r)`` : *real* ``tan(r)`` returns the Tangent of the given angle, *r* (in radians). Tangent is the ratio of the Opposite/Adjacent lines of a right angle triangle. ``tan(r)`` will cause a runtime error for *r* values that are multiples of :ref:`&pi` / 2 radians, the result being imaginary *infinity*. .. literalinclude:: examples/tan.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/tan.icn` Sample run: .. command-output:: unicon -s tan.icn -x :cwd: examples Graphical plot: .. literalinclude:: examples/plot-function.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/plot-function.icn` .. command-output:: unicon -s plot-function.icn -x tan :cwd: examples .. image:: images/plot-tan.png .. only:: html .. rst-class:: leftalign :download:`images/plot-tan.png` -------- .. index:: Texcoord, function; Texcoord .. _Texcoord: Texcoord -------- ``Texcoord()`` : *type* .. todo:: entry for function Texcoord ``Texcoord()`` .. pending literalinclude:: examples/Texcoord.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Texcoord.icn` Sample run: .. pending command-output:: unicon -s Texcoord.icn -x :cwd: examples -------- .. index:: Texture, function; Texture .. _Texture: Texture ------- ``Texture()`` : *type* .. todo:: entry for function Texture ``Texture()`` .. pending literalinclude:: examples/Texture.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Texture.icn` Sample run: .. pending command-output:: unicon -s Texture.icn -x :cwd: examples -------- .. index:: TextWidth, function; TextWidth .. _TextWidth: TextWidth --------- ``TextWidth()`` : *type* .. todo:: entry for function TextWidth ``TextWidth()`` .. pending literalinclude:: examples/TextWidth.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/TextWidth.icn` Sample run: .. pending command-output:: unicon -s TextWidth.icn -x :cwd: examples -------- .. index:: Translate, function; Translate .. _Translate: Translate --------- ``Translate()`` : *type* .. todo:: entry for function Translate ``Translate()`` .. pending literalinclude:: examples/Translate.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Translate.icn` Sample run: .. pending command-output:: unicon -s Translate.icn -x :cwd: examples -------- .. index:: trap, function; trap .. _trap: trap ---- ``trap(s, p)`` : *procedure* ``trap(s, proc)`` sets up a signal handler for the signal *s* (by name). The old handler, if any, is returned. If *proc* is null, then handler is reset to a default value. .. literalinclude:: examples/trap.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/trap.icn` Sample run: .. command-output:: unicon -s trap.icn -x :cwd: examples -------- .. index:: trim, function; trim .. _trim: trim ---- ``trim(s, c:' ', i:-1)`` : *string* ``trim(s, c, i)`` removes any of the characters in *c* from the ends of *s*. *i* specifies from where: - ``-1`` trailing - ``1`` leading - ``0`` both ends. .. literalinclude:: examples/trim.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/trim.icn` Sample run: .. command-output:: unicon -s trim.icn -x :cwd: examples -------- .. index:: truncate, function; truncate .. _truncate: truncate -------- ``truncate(f, i)`` : *?* ``truncate(f, len)`` changes the file *f* which may be a filename or an open file, to be no longer than length *len*. ``truncate()`` does not work on database, network connection, pipe, or window resources. Files already shorter than *i* will be filled with padding, usually zero bytes. .. literalinclude:: examples/truncate.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/truncate.icn` Sample run: .. command-output:: unicon -s truncate.icn -x :cwd: examples -------- .. index:: trylock, function; trylock .. _trylock: trylock ------- ``trylock(x)`` : *x?* ``trylock(m)`` locks the mutex *x* or the mutex associated with the thread-safe object *x*, if it is not already locked. .. literalinclude:: examples/trylock.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/trylock.icn` Sample run: .. command-output:: unicon -s trylock.icn -x :cwd: examples -------- .. index:: type, function; type .. _type: type ---- ``type(x)`` : *string* Returns the type of :math:`x`. ``type(x)`` returns a string representation of the type name of :math:`x`. .. literalinclude:: examples/type.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/type.icn` Sample run: .. command-output:: unicon -s type.icn -x :cwd: examples -------- .. index:: umask, function; umask .. _umask: umask ----- ``umask(integer)`` : *integer* [*POSIX*] ``umask(u)`` sets the ``umask`` for the current process to *u*, a nine bit encoding of read, write, execute permissions for user, group and world access. Each bit of ``umask`` turns off that access, by default, for newly created files. ``umask(u)`` returns the old value. .. literalinclude:: examples/umask.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/umask.icn` Sample run: .. command-output:: unicon -s umask.icn -x :cwd: examples -------- .. index:: Uncouple, function; Uncouple .. _Uncouple: Uncouple -------- ``Uncouple()`` : *type* .. todo:: entry for function Uncouple ``Uncouple()`` .. pending literalinclude:: examples/Uncouple.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/Uncouple.icn` Sample run: .. pending command-output:: unicon -s Uncouple.icn -x :cwd: examples -------- .. index:: unlock, function; unlock .. _unlock: unlock ------ ``unlock(x)`` : *x* ``unlock(m)`` unlocks the :ref:`mutex ` *m* or the mutex associated with the thread-safe object *x* .. literalinclude:: examples/unlock.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/unlock.icn` Sample run: .. command-output:: unicon -s unlock.icn -x :cwd: examples -------- .. index:: upto, function; upto .. _upto: upto ---- ``upto(c, s:&subject, i:1, i:0)`` : *integer*\* String scanning function ``upto(c, s, i1, i2)`` generates the sequence of integer positions in *s* scanning forward for characters in the cset *c* between indexes *i1* and *i2*. ``upto()`` fails if there is not such position. .. literalinclude:: examples/upto.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/upto.icn` Sample run: .. command-output:: unicon -s upto.icn -x :cwd: examples -------- .. index:: utime, function; utime .. _utime: utime ----- ``utime(s, i, i)`` : *null* ``utime(f, atime, mtime)`` sets the access and modification time of filename *f* to *atime* and *mtime* respectively. ``ctime`` is set to the current time. .. literalinclude:: examples/utime.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/utime.icn` Sample run: .. command-output:: unicon -s utime.icn -x :cwd: examples -------- .. index:: variable, function; variable .. _variable: variable -------- ``variable(s, CE:¤t, i:0)`` : *any?* ``variable(s, ce, i)`` returns a reference to the variable name *s* from the co-expression *ce*, *i* levels up from the current procedure frame. Name search is local to *ce* then global to the program that created *ce*. .. literalinclude:: examples/variable.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/variable.icn` Sample run: .. command-output:: unicon -s variable.icn -x :cwd: examples -------- .. index:: VAttrib, function; VAttrib .. _VAttrib: VAttrib ------- ``VAttrib()`` : *type* .. todo:: entry for function VAttrib ``VAttrib()`` .. pending literalinclude:: examples/VAttrib.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/VAttrib.icn` Sample run: .. pending command-output:: unicon -s VAttrib.icn -x :cwd: examples -------- .. index:: wait, function; wait .. _wait: wait ---- ``wait(x)`` : *?* ``wait(x)`` waits for *x*. If *x* is a thread, ``wait()`` waits for *x* to finish. If *x* is a condition variable, :ref:`condvar `, then ``wait()`` waits until that variable is signalled from another thread. .. literalinclude:: examples/wait.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/wait.icn` Sample run: .. command-output:: unicon -s wait.icn -x :cwd: examples -------- .. index:: WAttrib, function; WAttrib .. _WAttrib: WAttrib ------- .. function:: WAttrib(w, x,...) -> x **WAttrib(w, s, w2, s2)** will change the attribute of window *w* to the value specified in *s* and the attribute of window *w2* to the pair specified in *s2*. **WAttrib(w, s)** will retrieve the given attribute if no "set" operation is specified, "dy" versus "dy=yoffset" in the string *s*. .. todo:: this graphics section is woefully incomplete Attributes include: Canvas Attributes ................. - size=wid,hgt - pos=x,y - canvas=normal|hidden - windowlabel=string - inputmask=string - pointer=arrow,clock,etc - pointerx=x - pointery=y - display=device (X11) - depth=integer (# of bits) - displaywidth=x - displayheight=y - image=string Graphics contexts ................. - fg=colour - bg=colour - font=name - fheight=integer - fwidth=integer - leading=integer (vertical pixels between lines) - ascent=integer - descent=integer - drawop=operation (copy, reverse) - fillstyle=type (stippled, opaquestippled) - pattern=pattern (bits,#hex) - linestyle=style (onoff, doubledash) - linewidth=integer - clipx=integer - clipy=integer - clipw=integer - cliph=integer - dx=integer (coordinate translation) - dy=integer (coordinate translation) 3D attributes ............. - dim= - pick= - texmode= - slices= - rings= - normode= Example: .. literalinclude:: examples/WAttrib.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WAttrib.icn` Sample run: .. command-output:: unicon -s WAttrib.icn -x :cwd: examples Almost the same image as `WFlush`, but ``dx`` and ``dy`` are offset a bit on the blue half circle. .. image:: images/WAttrib.png .. only:: html .. rst-class:: leftalign :download:`images/WAttrib.png` .. seealso:: `WSync`, :doc:`graphics` -------- .. index:: WDefault, function; WDefault .. _WDefault: WDefault -------- ``WDefault()`` : *type* .. todo:: entry for function WDefault ``WDefault()`` .. pending literalinclude:: examples/WDefault.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WDefault.icn` Sample run: .. pending command-output:: unicon -s WDefault.icn -x :cwd: examples -------- .. index:: WFlush, function; WFlush .. _WFlush: WFlush ------ .. function:: WFlush(w) -> window **WFlush(w)** flushes window *w* output on window systems that buffer text and graphic output, without waiting for all pending events. Window data is automatically flushed during events that block. This function is a no-op on systems that do not buffer graphical output. .. literalinclude:: examples/WFlush.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WFlush.icn` Sample run: .. command-output:: unicon -s WFlush.icn -x :cwd: examples .. image:: images/WFlush.png .. only:: html .. rst-class:: leftalign :download:`images/WFlush.png` .. seealso:: `WSync` -------- .. index:: where, function; where .. _where: where ----- ``where(f)`` : *integer* ``where(f)`` returns the current offset position in file *f*. ``where()`` fails for window and network resources. The beginning of a file is offset ``1``. .. literalinclude:: examples/where.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/where.icn` Sample run: .. command-output:: unicon -s where.icn -x :cwd: examples -------- .. index:: WinAssociate, function; WinAssociate .. _WinAssociate: WinAssociate ------------ ``WinAssociate(s)`` : *string* [*Windows*] ``WinAssociate(s)`` returns the application name associated with the string file extension *s*. Requires Unicon for Windows, *non-portable*. .. literalinclude:: examples/WinAssociate.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WinAssociate.icn` Sample run: (not supported on the OS that builds this document) .. command-output:: unicon -s WinAssociate.icn -x :cwd: examples :returncode: 1 See Unicon Technical Report 7, http://unicon.org/utr/utr7.html The Windows only functions are no longer recommended for new Unicon developments. The :ref:`VIB ` and GUI class library should be used to create cross platform programs. -------- .. index:: WinButton, function; WinButton .. _WinButton: WinButton --------- ``WinButton(w, s, x,y, wd,ht)`` : *string* [*Windows*] ``WinButton(w, s, x, y, wd, ht)`` installs a pushbutton with label *s* at *x,y*, *wd* pixels wide and *ht* pixels high, on window *w*. When pressed the button label *s* is placed on the event queue. *Non-portable*. .. literalinclude:: examples/WinButton.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WinButton.icn` Sample run (not supported on the OS that builds this document): .. command-output:: unicon -s WinButton.icn -x :cwd: examples :returncode: 1 See Unicon Technical Report 7, http://unicon.org/utr/utr7.html. The Windows only functions are no longer recommended for new Unicon developments. The :ref:`VIB ` and GUI class library can and should be used to create cross platform programs. .. seealso:: :ref:`Event` -------- .. index:: WinColorDialog, function; WinColorDialog .. _WinColorDialog: WinColorDialog -------------- ``WinColorDialog()`` : *type* .. todo:: entry for function WinColorDialog ``WinColorDialog()`` .. pending literalinclude:: examples/WinColorDialog.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WinColorDialog.icn` Sample run: .. pending command-output:: unicon -s WinColorDialog.icn -x :cwd: examples -------- .. index:: WindowContents, function; WindowContents .. _WindowContents: WindowContents -------------- ``WindowContents(w)`` : *list* [*3D graphics*] ``WindowContents(w)`` returns a `list` of current 3D window *w* contents. .. literalinclude:: examples/WindowContents.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WindowContents.icn` Sample run: .. skipped command-output:: unicon -s WindowContents.icn -x :cwd: examples :: prompt$ unicon -s WindowContents.icn -x L2 := list(3) L2[1] := L3 := list(3) L3[1] := "dim" L3[2] := 336 L3[3] := 3 L2[2] := L4 := list(7,65535) L4[1] := "Fg" L4[2] := 160 L4[3] := "specular" L2[3] := R_gl_torus_1 := gl_torus() R_gl_torus_1.name := "DrawTorus" R_gl_torus_1.code := 149 R_gl_torus_1.x := 0.0 R_gl_torus_1.y := 0.19 R_gl_torus_1.z := -2.2 R_gl_torus_1.radius1 := 0.3 R_gl_torus_1.radius2 := 0.4 .. image:: images/WindowContents.png .. only:: html .. rst-class:: leftalign :download:`images/WindowContents.png` -------- .. index:: WinEditRegion, function; WinEditRegion .. _WinEditRegion: WinEditRegion ------------- ``WinEditRegion(s, s2, x,y, wd,ht)`` : *string* WinEditRegion(w, s, s2, x,y, wd,ht) manipulates a Windows edit region named s. This flexible editor is limited to text that is < 32Kbytes in length. The operation performed depends on argument s2. If argument s2 is omitted, WinEditRegion(s) returns a string containing the current contents of region s. If s2 is supplied and does not start with a !, it is a string to be edited; lines are separated by \r\n. s2 strings starting with ! are commands: - WinEditRegion(s, "!clear") clears the current selection. - WinEditRegion(s, "!copy") copies the current selection. - WinEditRegion(s, "!cut") cuts the current selection. - WinEditRegion(s, "!paste") pastes the current selection. - WinEditRegion(s, "!modified") succeeds if region s has been modified since last assigned. - WinEditRegion(s, "!setsel") sets the selection using parameters x and y as indices.. - WinEditRegion(s, "!undo") undoes the previous operation, if possible. .. pending literalinclude:: examples/WinEditRegion.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WinEditRegion.icn` Sample run: .. pending command-output:: unicon -s WinEditRegion.icn -x :cwd: examples -------- .. index:: WinFontDialog, function; WinFontDialog .. _WinFontDialog: WinFontDialog ------------- ``WinFontDialog()`` : *type* .. todo:: entry for function WinFontDialog ``WinFontDialog()`` .. pending literalinclude:: examples/WinFontDialog.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WinFontDialog.icn` Sample run: .. pending command-output:: unicon -s WinFontDialog.icn -x :cwd: examples -------- .. index:: WinMenuBar, function; WinMenuBar .. _WinMenuBar: WinMenuBar ---------- ``WinMenuBar()`` : *type* .. todo:: entry for function WinMenuBar ``WinMenuBar()`` .. pending literalinclude:: examples/WinMenuBar.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WinMenuBar.icn` Sample run: .. pending command-output:: unicon -s WinMenuBar.icn -x :cwd: examples -------- .. index:: WinOpenDialog, function; WinOpenDialog .. _WinOpenDialog: WinOpenDialog ------------- ``WinOpenDialog(w, s1, s2, i, s3,j, s4)`` : *string* ``WinOpenDialog(w, s1, s2, i, s3,j, s4)`` displays a typical open dialog to perform file selection for reading. *s1* is the caption, *s2* the default value and *i* is the text entry field size. *s3* and *j* specify the filter string and its index. *s3* is a string of alternating names and filters, separated and ending in \|, of the form ``"name1|filter1|name2|filter2|...|"``. *s3* defaults to ``"All Files(*.*)|*.*|"``. *j* supplies the default extension index within *s3*; it defaults to first pair in filter string. *s4* is the directory to show when the dialog is opened; it defaults to use Windows version-specific rules. Returns the file name chosen. Fails if the user selects Cancel. .. literalinclude:: examples/WinOpenDialog.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WinOpenDialog.icn` Sample run not available, code untested. .. skipped command-output:: unicon -s WinOpenDialog.icn -x :cwd: examples -------- .. index:: WinPlayMedia, function; WinPlayMedia .. _WinPlayMedia: WinPlayMedia ------------ ``WinPlayMedia(w, s1,...)`` : *null* ``WinPlayMedia(w, s1, s2)`` plays media file *s1* followed by *s2* for each argument. Media can be ``.wav``, ``.mdi``, ``.rmi`` or if unrecognized the string passed to MCI for supported media files. Fails on the first media file that cannot be played. .. literalinclude:: examples/WinPlayMedia.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WinPlayMedia.icn` Sample run not available, code untested. .. skipped command-output:: unicon -s WinPlayMedia.icn -x :cwd: examples **Deprecated**, see :ref:`PlayAudio` for the recommended cross-platform solution. -------- .. index:: WinSaveDialog, function; WinSaveDialog .. _WinSaveDialog: WinSaveDialog ------------- ``WinSaveDialog(w, s1, s2, i, s3,j, s4)`` : *string* ``WinSaveDialog(w, s1, s2, i, s3,j, s4)`` opens a typical save dialog to perform file selection for writing. *s1* is the caption, *s2* the default value and *i* is the text entry field size. *s3* and *j* specify the filter string and its index. *s3* is a string of alternating names and filters, separated and ending in \|, of the form ``"name1|filter1|name2|filter2|...|"``. *s3* defaults to ``"All Files(*.*)|*.*|"``. *j* supplies the default extension index within *s3*; it defaults to first pair in filter string. *s4* is the directory to show when the dialog is opened; it defaults to use Windows version-specific rules. Returns the file name chosen. Fails if the user selects Cancel. .. literalinclude:: examples/WinSaveDialog.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WinSaveDialog.icn` Sample run not available, code untested. .. skipped command-output:: unicon -s WinSaveDialog.icn -x :cwd: examples -------- .. index:: WinScrollBar, function; WinScrollBar .. _WinScrollBar: WinScrollBar ------------ ``WinScrollBar()`` : *type* .. todo:: entry for function WinScrollBar ``WinScrollBar()`` .. pending literalinclude:: examples/WinScrollBar.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WinScrollBar.icn` Sample run: .. pending command-output:: unicon -s WinScrollBar.icn -x :cwd: examples -------- .. index:: WinSelectDialog, function; WinSelectDialog .. _WinSelectDialog: WinSelectDialog --------------- ``WinSelectDialog(w, s1, buttons)`` : *string* [*Windows Unicon*] ``WinSelectDialog(w, title, L)`` displays a Windows native dialog box on window *w*, labelled *title*, offering a selection from a set of choices in the form of buttons, *["choice1", "choice2"]* (as list of strings). :ref:`Event() ` will return the choice as a string. .. literalinclude:: examples/WinSelectDialog.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WinSelectDialog.icn` Sample run not available. .. skipped command-output:: unicon -s WinSelectDialog.icn -x :cwd: examples **Deprecated**. The native Windows procedures are now deprecated in favour of the cross-platform Unicon :ref:`gui ` classes. -------- .. index:: write, function; write .. _write: write ----- ``write(s|f, ...)`` : *string|file* ``write(arglist)`` outputs strings, followed by a newline to a file or files. Strings are written to the closest preceding file argument, defaulting to :ref:`&output`. A newline is written whenever a non-initial file arguments directs output to a different file, or after the last argument. ``write()`` returns the last argument. .. literalinclude:: examples/write.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/write.icn` Sample run: .. command-output:: unicon -s write.icn -x :cwd: examples -------- .. index:: WriteImage, function; WriteImage .. _WriteImage: WriteImage ---------- ``WriteImage(w, s, x:0, y:0, wid:0, h:0)`` : *window* [*Graphics*] ``WriteImage(w, s, x, y, wid, h)`` saves an image of dimensions *wid, h* from window *w* (defaults to :ref:`&window`), at offset *x, y* to a file named *s*. The default is to save the entire window. The output format is written according the extension, GIF, JPG, BMP, PNG (depending on available library during Unicon build). Platform specific formats, such as XBM or XPM may also be supported. ``WriteImage()`` fails if *s* cannot be opened for writing. Almost all included graphics are generated during the builds of this documentation and saved with ``WriteImage()``, even the "no-image" image. Only the canvas image is included, window decorations (as provided by desktop window managers) are not part of images saved by ``WriteImage()``. .. literalinclude:: examples/WriteImage.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WriteImage.icn` Sample run: .. command-output:: unicon -s WriteImage.icn -x :cwd: examples .. image:: images/WriteImage.png .. only:: html .. rst-class:: leftalign :download:`images/WriteImage.png` -------- .. index:: writes, function; writes .. _writes: writes ------ ``writes(s|f, ...)`` : *string|file* ``writes(arglist)`` outputs strings to a file or files. Strings are written to the closest preceding file argument, defaulting to :ref:`&output`. ``write()`` returns the last argument. .. literalinclude:: examples/writes.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/writes.icn` Sample run: standard stream buffering might cause :ref:`&errout` to display separately from :ref:`&output`. .. command-output:: unicon -s writes.icn -x :cwd: examples -------- .. index:: WSection, function; WSection .. _WSection: WSection -------- ``WSection(w, s)`` : *record* ``WSection(w, s)`` starts a new window section named *s* on 3D window *w*. Returns a display list section marker record. During window :ref:`Refresh`, if the section marker's ``skip`` field is ``1``, the section is skipped. The section name *s* is produced by :ref:`&pick` is the graphic object in the block is clicked on when the attribute ``"pick=on"`` is set. ``WSection(w)`` marks the end of a named section. ``WSection`` blocks can be nested. .. literalinclude:: examples/WSection.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WSection.icn` Sample output, having clicked on the small sphere: .. skipped command-output:: unicon -s WSection.icn -x :cwd: examples :: prompt$ unicon -s WSection -x record gl_mark_1(7) -1 &x:43 &y:21 &row:2 &col:8 &pick:sphere .. image:: images/WSection.png .. only:: html .. rst-class:: leftalign :download:`images/WSection.png` -------- .. index:: WSync, function; WSync .. _WSync: WSync ----- ``WSync(w, s)`` : *w* ``WSync(w, s)`` synchronizes the program with the server attached to window *w* on systems that employ a client-server model. Output to the window is flushed, and ``WSync()`` waits for a reply from the server indicating that all output has been processed. If *s* is ``"yes"``, all pending events on *w* are discarded. ``WSync()`` is a no-op on windowing systems that do not use a client-server model. .. literalinclude:: examples/WSync.icn :language: unicon :start-after: ##+ .. only:: html .. rst-class:: rightalign :download:`examples/WSync.icn` Sample run: .. command-output:: unicon -s WSync.icn -x :cwd: examples .. image:: images/WSync.png .. only:: html .. rst-class:: leftalign :download:`images/WSync.png` .. seealso:: :ref:`Refresh`, :ref:`WFlush` .. only:: html .. -------- :ref:`genindex` | Previous: :doc:`reserved` | Next: :doc:`keywords` |