.. include:: ../global.rst .. _`printing values`: Printing Values ^^^^^^^^^^^^^^^ All :lname:`Idio` values can be printed although not all have a valid reader input form. Those without valid reader forms are subject to change. The output generally takes the form :samp:`#<{TYPE} ...>`. If you are unsure, use ``%s`` ("as a string") as a generic catch-all format specifier. This "as a string" is used as default behaviour for unexpected format specifiers (and which may result in a warning). See below. There is a subtle distinction between a value being *printed* -- commonly at the REPL as generally suitable to be read back in -- and being *displayed* as general output of the program. This only affects unicode and string types where any escaping is removed and full UTF-8 encoding is used when displayed. .. warning:: Very deep data structures are truncated. Fixnums """"""" :ref:`Fixnums ` support the usual integer formats ``%[Xbdox]`` where ``%b`` is a binary format. Any other format specifier is treated as ``%d``. Bignums """"""" :ref:`Bignums ` have limited printing support. Integer bignums are printed as, effectively, ``%d``. Floating point bignums are printed as one of: * ``%s`` a normalized form * ``%e`` or ``%f`` in the style of :manpage:`printf(3)` Any other format specifier is treated as ``%e``. The output may be preceded by ``#i`` (or ``#e``) indicating the underlying bignum is *inexact* (or *exact*). Unicode """"""" In general, :ref:`unicode ` is *printed* as ``#U+HHHH`` although if the code point is below 128 and satisfies :manpage:`isgraph(3)` it will be printed as :samp:`#\\c`. If unicode is being *displayed* :lname:`Idio` generates the UTF-8 encoding for the value. Strings """"""" :ref:`Strings ` are *printed* double-quoted and with the usual :lname:`C` escape sequences escaped: a newline will be represented by ``\n``, for example. Otherwise Unicode code points are encoded as UTF-8. String are *displayed* unquoted and with all Unicode code points UTF-8 encoded. Symbols """"""" :ref:`Symbols ` are displayed as just their name, without a leading ``'``. This creates some anomalies. Pairs """"" :ref:`Pairs ` are printed as expected. If the list represents a template any original change to interpolation characters is lost and standard :lname:`Idio` symbols are used. Arrays """""" :ref:`Arrays ` are printed in the nominal reader form: ``#[ ... ]``. If the array is less than 40 elements long it is printed in full. .. warning:: If it is more than 40 elements long then the first 20 and the last 20 are printed with in ellipsis and missing index marker displayed. Hash Tables """"""""""" :ref:`Hash tables ` are printed in the nominal reader form: ``#{ ... }``. Bitsets """"""" :ref:`Bitsets ` are printed in the nominal reader form: ``#B{ ... }``. C Types """"""" :ref:`C types ` are printed as: * ``%c`` for ``char`` * ``%d`` for signed integral types Any other format specifier is treated as ``%d``. Any format specifier other than ``%s`` may elicit a warning. * ``%[Xboux]`` for unsigned integral types including the ``%b`` binary format Any other format specifier is treated as ``%u``. Any other format specifier other than ``%s`` may elicit a warning. * ``%[efg]`` for floating point types Any other format specifier is treated as ``%g``. Any other format specifier other than ``%s`` may elicit a warning. ``C/pointer`` types have the option to be printed by a bespoke printer. See :ref:`add-as-string `. Struct Instances """""""""""""""" :ref:`Struct instances ` have the option to be printed by a bespoke printer. See :ref:`add-as-string `. Printing Functions ^^^^^^^^^^^^^^^^^^ The printing functions revolve around :ref:`%format <%format>` which takes a :manpage:`printf(3)`-style format string and constructs a formatted string from the arguments. .. _`printf`: .. idio:function:: printf fmt [args] Invoke the :ref:`hprintf ` function on the current output handle with `fmt` and `args` :param fmt: the format string for printf :type fmt: string :param args: any args for the format string :type args: list, optional :return: ``#`` .. _`eprintf`: .. idio:function:: eprintf fmt [args] Invoke the :ref:`hprintf ` function on the current error handle with `fmt` and `args` :param fmt: the format string for printf :type fmt: string :param args: any args for the format string :type args: list, optional :return: ``#`` .. _`sprintf`: .. idio:function:: sprintf fmt [args] Invoke the :ref:`hprintf ` function on an output string handle with `fmt` and `args` and return the resultant string :param fmt: the format string for printf :type fmt: string :param args: any args for the format string :type args: list, optional :return: string .. _`hprintf`: .. idio:function:: hprintf handle fmt [args] Invoke the :ref:`display ` function on `handle` with the result of applying :ref:`format ` to `fmt` and `args`. :param handle: the handle to load from :type handle: handle :param fmt: the format string for printf :type fmt: string :param args: any args for the format string :type args: list, optional :return: ``#`` .. _`format`: .. idio:function:: format fmt [args] Call :ref:`%format <%format>`: :samp:`%format 'args {fmt} {args}` .. _`%format`: .. idio:function:: %format type fmt [args] Return a string from the format string `fmt` expanded by any *escape sequences*. If `type` is ``'args`` then a ``%`` character in the format string starts an escape sequence which has the general form :samp:`%[{flags}][{width}][.{prec}]{K}` where :samp:`{K}` is a :manpage:`printf(3)`-ish conversion specifier character with arguments in `args`. If :samp:`{K}` is an ``@`` character then the list argument is spliced into the string converting all elements of the list to string form separated by a U+0022 (SPACE) character. If `type` is ``'keyed`` then a ``%`` character in the format string starts an escape sequence which has the general form :samp:`%[{flags}][{width}][.{prec}]{K}` where :samp:`{K}` is a single Unicode code point (satisfying ``Alphabetic?``) which is expected to be a key in the optional hash table -- unless it is another ``%`` character. The value associated with the key will be printed according to the specification. In both cases if :samp:`{K}` is a ``%`` character then a ``%`` is printed according to the specification If `type` is ``'timeformat`` then it works similarly to ``'keyed`` except we avoid a double application of any precision. :var:`TIMEFORMAT` describes a ``%f``-like precision to the :ref:`struct-timeval ` strings. The :samp:`{flags}` are: .. csv-table:: :header: `flag`, effect, code point :widths: auto :align: left ``-``, left align the output within :samp:`{width}`, U+002D (HYPHEN-MINUS) :literal:`\ `, use ``#\{space}`` as the left padding character, U+0020 (SPACE) ``0``, use ``#\0`` (zero) as the left padding character, U+0030 (DIGIT ZERO) The default padding character is ``#\{space}`` .. seealso:: :ref:`printing values ` for some type-specific conversion specifiers. .. _`display`: .. idio:function:: display o [handle] display `o` to `handle` :param o: object :param handle: handle to write to, defaults to the current output handle :type handle: handle, optional :return: ``#`` .. _`display*`: .. idio:function:: display* [x*] display ``#\{space}`` -separated `x*` to the current output handle :param x*: values to print :return: ``#`` .. _`edisplay`: .. idio:function:: edisplay x :ref:`display ` `x` to the current error handle :param x*: values to print :return: ``#`` .. _`edisplay*`: .. idio:function:: edisplay* [x*] display ``#\{space}`` -separated `x*` to the current error handle :param x*: values to print :return: ``#`` .. _`newline`: .. idio:function:: newline [handle] write a UTF-8 encoded U+000A character to `handle` :param handle: handle to write to, defaults to the current output handle :type handle: handle, optional :return: ``#`` .. _`display-string`: .. idio:function:: display-string o convert `o` to a display string :param o: object to convert :return: a string representation of `o` .. _`add-as-string`: .. idio:function:: add-as-string o f Associate a printer function `f` with `o`. `f` will be invoked with the value to be printed and #n. The second argument can be used for any subsequent purpose but might normally be used to maintain a set of previously seen values to handle circular data structures. This is currently only used for: - struct instances where a struct type was associated with a printer. When we come to print a struct instance we check to see if a printer exists for its type. - C/pointer types where an IDIO_C_STRUCT_IDENT has been set up and assigned to the C/pointer .. include:: ../commit.rst