| [ << ] | jpayne@68:[ >> ] | jpayne@68:jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | [Top] | jpayne@68:[Contents] | jpayne@68:[Index] | jpayne@68:[ ? ] | jpayne@68:
As a programmer, enabling styling consists of the following tasks: jpayne@68:
styled_ostream_begin_css_class,
jpayne@68: styled_ostream_end_css_class around each run of text with a
jpayne@68: specific text role.
jpayne@68: libtextstyle. If your package is using GNU autoconf,
jpayne@68: you can use the libtextstyle.m4 macro from Gnulib.
jpayne@68: The following sections go into more detail. jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:Source code that makes use of GNU libtextstyle needs an include statement: jpayne@68:
jpayne@68:#include <textstyle.h> jpayne@68: |
Basic use of GNU libtextstyle consists of statements like these: jpayne@68:
jpayne@68:styled_ostream_t stream = jpayne@68: styled_ostream_create (STDOUT_FILENO, "(stdout)", TTYCTL_AUTO, jpayne@68: style_file_name); jpayne@68: ... jpayne@68: styled_ostream_begin_use_class (stream, css_class); jpayne@68: ... jpayne@68: ostream_write_str (stream, string); jpayne@68: ... jpayne@68: styled_ostream_end_use_class (stream, css_class); jpayne@68: ... jpayne@68: styled_ostream_free (stream); jpayne@68: |
Before this snippet, your code needs to determine the name of the style
jpayne@68: file to use (style_file_name). If no styling is desired – the
jpayne@68: precise condition depends on the value of color_mode but also on
jpayne@68: your application logic –, you should set style_file_name to
jpayne@68: NULL.
jpayne@68:
An object of type styled_ostream_t is allocated. The function
jpayne@68: styled_ostream_create allocates it; the function
jpayne@68: styled_ostream_free deallocates it.
jpayne@68:
Such styled_ostream_t supports output operations
jpayne@68: (ostream_write_str), interleaved with adding and removing CSS
jpayne@68: classes. The CSS class in effect when an output operation is performed
jpayne@68: determines, through the style file, the text attributes associated with
jpayne@68: that piece of text.
jpayne@68:
Text output may contain hyperlinks. These hyperlinks are encoded through
jpayne@68: an escape sequence, specified at
jpayne@68: Hyperlinks in terminal emulators. Currently (as of 2019), they are
jpayne@68: displayed only in gnome-terminal version 3.26 or above. More
jpayne@68: terminal emulators will support hyperlinks in the future. Terminal
jpayne@68: emulators which don't support hyperlinks ignore it, except for a few
jpayne@68: terminal emulators, for which users may need to disable the hyperlinks
jpayne@68: (see The environment variable NO_TERM_HYPERLINKS) if the heuristic built into
jpayne@68: libtextstyle does not already disable them.
jpayne@68:
To emit a hyperlink, use code like this: jpayne@68:
jpayne@68:styled_ostream_t stream = ... jpayne@68: ... jpayne@68: /* Start a hyperlink. */ jpayne@68: styled_ostream_set_hyperlink (stream, url, NULL); jpayne@68: ... jpayne@68: /* Emit the anchor text. This can be styled text. */ jpayne@68: ostream_write_str (stream, "Click here!"); jpayne@68: ... jpayne@68: /* End the current hyperlink. */ jpayne@68: styled_ostream_set_hyperlink (stream, NULL, NULL); jpayne@68: |
The anchor text can be styled. But the hyperlinks themselves cannot be jpayne@68: styled; they behave as implemented by the terminal emulator. jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68:The include file <textstyle.h> declares all facilities defined by
jpayne@68: the library.
jpayne@68:
The library to link with is called libtextstyle, with a
jpayne@68: system-dependent suffix. You link with it though link options of the
jpayne@68: form -ltextstyle for a library installed in system locations, or
jpayne@68: -Llibdir -ltextstyle for a static library installed in other
jpayne@68: locations, or -Llibdir -ltextstyle -Wl,-rpath,libdir
jpayne@68: for a shared library installed in other locations (assuming a GCC
jpayne@68: compatible compiler and linker and no libtool), or
jpayne@68: -Llibdir -ltextstyle -Rlibdir for a shared library
jpayne@68: installed in other locations (with libtool). Additionally, the
jpayne@68: link options may need to include the dependencies: -lm, and
jpayne@68: -lncurses or (on NetBSD) -ltermcap or (on AIX)
jpayne@68: -lxcurses or (on HP-UX) -lcurses, and on some systems also
jpayne@68: -liconv.
jpayne@68:
It is a bit complicated to determine the right link options in a portable
jpayne@68: way. Therefore an Autoconf macro is provided in the file
jpayne@68: libtextstyle.m4 in Gnulib, that makes this task easier. Assuming
jpayne@68: the build system of your package is based on GNU Autoconf, you invoke it
jpayne@68: through gl_LIBTEXTSTYLE. It searches for an installed
jpayne@68: libtextstyle. If found, it sets and AC_SUBSTs
jpayne@68: HAVE_LIBTEXTSTYLE=yes and the LIBTEXTSTYLE and
jpayne@68: LTLIBTEXTSTYLE variables, and augments the CPPFLAGS
jpayne@68: variable, and #defines HAVE_LIBTEXTSTYLE to 1. Otherwise, it sets
jpayne@68: and AC_SUBSTs HAVE_LIBTEXTSTYLE=no and LIBTEXTSTYLE and
jpayne@68: LTLIBTEXTSTYLE to empty. In link commands that use libtool,
jpayne@68: use LTLIBTEXTSTYLE; in link commands that don't use libtool,
jpayne@68: use LIBTEXTSTYLE.
jpayne@68:
If you use GNU Automake, the proper place to use the link options is
jpayne@68: program_LDADD for programs and library_LIBADD
jpayne@68: for libraries.
jpayne@68:
While you are free to provide any command-line option to enable the
jpayne@68: styling of the output, it is good if different GNU programs use the same
jpayne@68: command-line options for this purpose. These options are described in
jpayne@68: the sections The --color option and The --style option. To
jpayne@68: achieve this, use the following API (declared in <textstyle.h>):
jpayne@68:
True if a --color option with value test has been seen.
jpayne@68:
Stores the value of the --color option.
jpayne@68:
Stores the value of the --style option.
jpayne@68:
Note: These variables, like any variables exported from shared libraries, jpayne@68: can only be used in executable code. You cannot portably use jpayne@68: their address in initializers of global or static variables. This is a jpayne@68: restriction that is imposed by the Windows, Cygwin, and Android platforms. jpayne@68:
jpayne@68:You invoke this function when, during argument parsing, you have
jpayne@68: encountered a --color or --color=... option. The return
jpayne@68: value is an error indicator: true means an invalid option.
jpayne@68:
You invoke this function when, during argument parsing, you have
jpayne@68: encountered a --style or --style=... option.
jpayne@68:
Prints a color test page. You invoke this function after argument
jpayne@68: parsing, when the color_test_mode variable is true.
jpayne@68:
Assigns a default value to style_file_name if necessary. You
jpayne@68: invoke this function after argument parsing, when color_test_mode
jpayne@68: is false.
jpayne@68:
style_file_envvar is an environment variable that, when set
jpayne@68: to a non-empty value, specifies the style file to use. This environment
jpayne@68: variable is meant to be set by the user.
jpayne@68:
stylesdir_envvar is an environment variable that, when set
jpayne@68: to a non-empty value, specifies the directory with the style files, or
jpayne@68: NULL. This is necessary for running the testsuite before
jpayne@68: ‘make install’.
jpayne@68:
stylesdir_after_install is the directory with the style
jpayne@68: files after ‘make install’.
jpayne@68:
default_style_file is the file name of the default style
jpayne@68: file, relative to stylesdir.
jpayne@68:
There are various classes of output streams, some of them with styling jpayne@68: support. These “classes” are defined in an object-oriented programming jpayne@68: style that resembles C++ or Java, but are actually implemented in C with jpayne@68: a little bit of object orientation syntax. These definitions are jpayne@68: preprocessed down to C. As a consequence, GNU libtextstyle is a C jpayne@68: library and does not need to link with the C++ standard library. jpayne@68:
jpayne@68:All these classes are declared in <textstyle.h>.
jpayne@68:
The base output stream type is ‘ostream_t’. It is a pointer type to jpayne@68: a (hidden) implementation type. Similarly for the subclasses. jpayne@68:
jpayne@68:When we say that ‘some_ostream_t’ is a subclass of ‘ostream_t’, jpayne@68: what we mean is: jpayne@68:
ostream class The base output stream type is ‘ostream_t’. jpayne@68:
jpayne@68:It has the following methods: jpayne@68:
jpayne@68:Writes a sequence of bytes to a stream. jpayne@68:
Writes a string's contents to a stream. jpayne@68:
Writes formatted output to a stream. jpayne@68:
jpayne@68:These functions return the size of formatted output, or a negative value jpayne@68: in case of an error. jpayne@68:
Brings buffered data to its destination. jpayne@68:
Closes and frees a stream. jpayne@68:
styled_ostream class The type for a styled output stream is ‘styled_ostream_t’. It is a jpayne@68: subclass of ‘ostream_t’ that adds the following methods: jpayne@68:
jpayne@68:Starts a run of text belonging to classname. The
jpayne@68: classname is the name of a CSS class. It can be chosen
jpayne@68: arbitrarily and customized through the CSS file.
jpayne@68:
Ends a run of text belonging to classname. The
jpayne@68: styled_ostream_begin_use_class /
jpayne@68: styled_ostream_end_use_class calls must match properly.
jpayne@68:
Returns the referred URL of the currently set hyperlink, or NULL
jpayne@68: if no hyperlink attribute is currently set.
jpayne@68:
Note: The returned string is only valid up to the next invocation of
jpayne@68: styled_ostream_set_hyperlink.
jpayne@68:
Returns the id of the currently set hyperlink, or NULL if no
jpayne@68: hyperlink attribute is currently set.
jpayne@68:
Note: The returned string is only valid up to the next invocation of
jpayne@68: styled_ostream_set_hyperlink.
jpayne@68:
Sets or removes a hyperlink attribute. jpayne@68:
jpayne@68:To set a hyperlink attribute, pass a non-NULL ref.
jpayne@68: ref is an URL; it should be at most 2083 bytes long. Non-ASCII
jpayne@68: characters should be URI-escaped (using the %nn syntax). id is
jpayne@68: an optional identifier. On terminal output, multiple hyperlinks with
jpayne@68: the same id will be highlighted together. If specified, id
jpayne@68: should be at most 250 bytes long.
jpayne@68:
To remove a hyperlink attribute, pass NULL for ref and id.
jpayne@68:
Hyperlinks don't nest. That is, a hyperlink attribute is enabled only
jpayne@68: up to the next invocation of styled_ostream_set_hyperlink.
jpayne@68:
This function acts like ostream_flush (stream, FLUSH_THIS_STREAM),
jpayne@68: except that it leaves the destination with the current text style enabled,
jpayne@68: instead of with the default text style.
jpayne@68:
After calling this function, you can output strings without newlines(!) to the
jpayne@68: underlying stream, and they will be rendered like strings passed to
jpayne@68: ostream_write_mem, ostream_write_str, or ostream_printf.
jpayne@68:
file_ostream class The file_ostream class supports output to an <stdio.h>
jpayne@68: FILE stream. Its type is ‘file_ostream_t’. It is a subclass
jpayne@68: of ‘ostream_t’ that adds no methods.
jpayne@68:
It can be instantiated through this function: jpayne@68:
jpayne@68:Creates an output stream referring to fp.
jpayne@68:
Note: The resulting stream must be closed before fp can be
jpayne@68: closed.
jpayne@68:
fd_ostream class The file_ostream class supports output to a file descriptor. Its
jpayne@68: type is ‘fd_ostream_t’. It is a subclass of ‘ostream_t’ that
jpayne@68: adds no methods.
jpayne@68:
It can be instantiated through this function: jpayne@68:
jpayne@68:Creates an output stream referring to the file descriptor fd.
jpayne@68:
filename is used only for error messages.
jpayne@68:
Note: The resulting stream must be closed before fd can be
jpayne@68: closed.
jpayne@68:
term_ostream class The term_ostream class supports output to a file descriptor that
jpayne@68: is connected to a terminal emulator or console. Its type is
jpayne@68: ‘term_ostream_t’. It is a subclass of ‘ostream_t’.
jpayne@68:
It can be instantiated through this function: jpayne@68:
jpayne@68:Creates an output stream referring to the file descriptor fd.
jpayne@68:
filename is used only for error messages.
jpayne@68:
tty_control specifies the amount of control to take over the
jpayne@68: underlying tty.
jpayne@68:
The resulting stream will be line-buffered. jpayne@68:
jpayne@68:Note: The resulting stream must be closed before fd can be
jpayne@68: closed.
jpayne@68:
The class adds the following methods: jpayne@68:
jpayne@68:Converts an RGB value
jpayne@68: (red, green, blue in [0..255]) to
jpayne@68: a color, valid for this stream only.
jpayne@68:
Gets/sets the text color. jpayne@68:
Gets/sets the background color. jpayne@68:
Gets/sets the font weight. jpayne@68:
Gets/sets the font posture. jpayne@68:
Gets/sets the text underline decoration. jpayne@68:
Returns the referred URL of the currently set hyperlink, or NULL
jpayne@68: if no hyperlink attribute is currently set.
jpayne@68:
Note: The returned string is only valid up to the next invocation of
jpayne@68: term_ostream_set_hyperlink.
jpayne@68:
Returns the id of the currently set hyperlink, or NULL if no
jpayne@68: hyperlink attribute is currently set.
jpayne@68:
Note: The returned string is only valid up to the next invocation of
jpayne@68: term_ostream_set_hyperlink.
jpayne@68:
Sets or removes a hyperlink attribute. jpayne@68:
jpayne@68:To set a hyperlink attribute, pass a non-NULL ref.
jpayne@68: ref is an URL; it should be at most 2083 bytes long. Non-ASCII
jpayne@68: characters should be URI-escaped (using the %nn syntax). id is
jpayne@68: an optional identifier. Multiple hyperlinks with the same id
jpayne@68: will be highlighted together. If specified, id should be at most
jpayne@68: 250 bytes long.
jpayne@68:
To remove a hyperlink attribute, pass NULL for ref and id.
jpayne@68:
Hyperlinks don't nest. That is, a hyperlink attribute is enabled only
jpayne@68: up to the next invocation of styled_ostream_set_hyperlink.
jpayne@68:
This function acts like ostream_flush (stream, FLUSH_THIS_STREAM),
jpayne@68: except that it leaves the terminal with the current text attributes enabled,
jpayne@68: instead of with the default text attributes.
jpayne@68:
After calling this function, you can output strings without newlines(!) to the
jpayne@68: underlying file descriptor, and they will be rendered like strings passed to
jpayne@68: ostream_write_mem, ostream_write_str, or ostream_printf.
jpayne@68:
html_ostream class The html_ostream class supports output to any destination, in HTML
jpayne@68: syntax. Its type is ‘html_ostream_t’. It is a subclass of
jpayne@68: ‘ostream_t’.
jpayne@68:
It can be instantiated through this function: jpayne@68:
jpayne@68:Creates an output stream that takes input in the UTF-8 encoding and
jpayne@68: writes it in HTML form on destination.
jpayne@68:
This stream produces a sequence of lines. The caller is responsible for
jpayne@68: opening the <body><html> elements before and for closing them
jpayne@68: after the use of this stream.
jpayne@68:
Note: The resulting stream must be closed before destination
jpayne@68: can be closed.
jpayne@68:
The class adds the following methods: jpayne@68:
jpayne@68:Starts a <span class="classname"> element. The
jpayne@68: classname is the name of a CSS class. It can be chosen
jpayne@68: arbitrarily and customized through the CSS file.
jpayne@68:
Ends a <span class="classname"> element.
jpayne@68:
The html_ostream_begin_span / html_ostream_end_span calls
jpayne@68: must match properly.
jpayne@68:
Returns the referred URL of the currently set hyperlink, or NULL
jpayne@68: if no hyperlink attribute is currently set.
jpayne@68:
Note: The returned string is only valid up to the next invocation of
jpayne@68: html_ostream_set_hyperlink_ref.
jpayne@68:
Sets or removes a hyperlink attribute. jpayne@68:
jpayne@68:To set a hyperlink attribute, pass a non-NULL ref.
jpayne@68: ref is an URL; it should be at most 2083 bytes long. Non-ASCII
jpayne@68: characters should be URI-escaped (using the %nn syntax).
jpayne@68:
To remove a hyperlink attribute, pass NULL for ref.
jpayne@68:
Hyperlinks don't nest. That is, a hyperlink attribute is enabled only
jpayne@68: up to the next invocation of html_ostream_set_hyperlink_ref.
jpayne@68:
This function acts like ostream_flush (stream, FLUSH_THIS_STREAM),
jpayne@68: except that it leaves the destination with the current text style enabled,
jpayne@68: instead of with the default text style.
jpayne@68:
After calling this function, you can output strings without newlines(!) to the
jpayne@68: underlying stream, and they will be rendered like strings passed to
jpayne@68: ostream_write_mem, ostream_write_str, or ostream_printf.
jpayne@68:
memory_ostream class The memory_ostream class supports output to an in-memory buffer.
jpayne@68: Its type is ‘memory_ostream_t’. It is a subclass of
jpayne@68: ‘ostream_t’.
jpayne@68:
It can be instantiated through this function: jpayne@68:
jpayne@68:Creates an output stream that accumulates the output in a memory buffer. jpayne@68:
The class adds the following method: jpayne@68:
jpayne@68:Returns a pointer to the output accumulated so far and its size. It
jpayne@68: stores them in *bufp and *buflenp, respectively.
jpayne@68:
Note: These two return values become invalid when more output is done to jpayne@68: the stream or when the stream is freed. jpayne@68:
iconv_ostream class The iconv_ostream class supports output to any destination. Its
jpayne@68: type is ‘iconv_ostream_t’. It is a subclass of ‘ostream_t’
jpayne@68: that adds no methods.
jpayne@68:
It can be instantiated through this function: jpayne@68:
jpayne@68:Creates an output stream that converts from from_encoding to
jpayne@68: to_encoding, writing the result to destination.
jpayne@68:
Note: The resulting stream must be closed before destination
jpayne@68: can be closed.
jpayne@68:
styled_ostream subclasses term_styled_ostream class The term_styled_ostream class supports styled output to a file
jpayne@68: descriptor that is connected to a terminal emulator or console. Its type
jpayne@68: is ‘term_styled_ostream_t’. It is a subclass of
jpayne@68: ‘styled_ostream_t’.
jpayne@68:
It can be instantiated through this function: jpayne@68:
jpayne@68:Creates an output stream referring to the file descriptor fd,
jpayne@68: styled with the file css_filename.
jpayne@68:
filename is used only for error messages.
jpayne@68:
tty_control specifies the amount of control to take over the
jpayne@68: underlying tty.
jpayne@68:
Note: The resulting stream must be closed before fd can be
jpayne@68: closed.
jpayne@68:
Returns NULL upon failure.
jpayne@68:
The following is a variant of this function. Upon failure, it does not
jpayne@68: return NULL; instead, it returns a styled fd_stream on
jpayne@68: which the styling operations exist but are no-ops.
jpayne@68:
Creates an output stream referring to the file descriptor fd,
jpayne@68: styled with the file css_filename if possible.
jpayne@68:
filename is used only for error messages.
jpayne@68:
tty_control specifies the amount of control to take over the
jpayne@68: underlying tty.
jpayne@68:
Note: The resulting stream must be closed before fd can be
jpayne@68: closed.
jpayne@68:
html_styled_ostream class The html_styled_ostream class supports styled output to any
jpayne@68: destination, in HTML syntax. Its type is ‘html_styled_ostream_t’.
jpayne@68: It is a subclass of ‘styled_ostream_t’.
jpayne@68:
It can be instantiated through this function: jpayne@68:
jpayne@68:Creates an output stream that takes input in the UTF-8 encoding and
jpayne@68: writes it in HTML form on destination, styled with the file
jpayne@68: css_filename.
jpayne@68:
Note: The resulting stream must be closed before destination
jpayne@68: can be closed.
jpayne@68:
noop_styled_ostream class The noop_styled_ostream class supports the styled output operations
jpayne@68: to any destination. The text is output to the given destination; the
jpayne@68: styling operations, however, do nothing. Its type is
jpayne@68: ‘noop_styled_ostream_t’. It is a subclass of ‘styled_ostream_t’.
jpayne@68:
It can be instantiated through this function: jpayne@68:
jpayne@68:Creates an output stream that delegates to destination and
jpayne@68: that supports the styling operations as no-ops.
jpayne@68:
If pass_ownership is true, closing the resulting
jpayne@68: stream will automatically close the destination.
jpayne@68:
Note: If pass_ownership is false, the resulting stream
jpayne@68: must be closed before destination can be closed.
jpayne@68:
The various concrete stream classes have methods that allow you to retrieve jpayne@68: the arguments passed to the respective constructor function. jpayne@68:
jpayne@68:Note: While these methods allow you to retrieve the underlying destination jpayne@68: stream of various kinds of stream, it is not recommended to operate on both jpayne@68: the stream and its underlying destination stream at the same time. Doing jpayne@68: so can lead to undesired interactions between the two streams. jpayne@68:
jpayne@68:The file_ostream class has this accessor method:
jpayne@68:
The fd_ostream class has these accessor methods:
jpayne@68:
The term_ostream class has these accessor methods:
jpayne@68:
Returns the effective tty control of the stream (not TTYCTL_AUTO).
jpayne@68:
The iconv_ostream class has these accessor methods:
jpayne@68:
The html_ostream class has this accessor method:
jpayne@68:
The term_styled_ostream class has these accessor methods:
jpayne@68:
The html_styled_ostream class has these accessor methods:
jpayne@68:
The noop_styled_ostream class has these accessor methods:
jpayne@68:
If you want to understand which output of your program is associated with jpayne@68: which CSS classes, the simplest way is as follows: jpayne@68:
jpayne@68:--color=html,
jpayne@68: redirecting the output to a file.
jpayne@68: <span class="css-class">...</span>.
jpayne@68: To make the text styling support available to the end user of your jpayne@68: package, the following need to be documented: jpayne@68:
man pages (if present),
jpayne@68: and in the documentation.
jpayne@68: style_file_envvar above,
jpayne@68: that, when set to a non-empty value, specifies the style file to use.
jpayne@68: | [ << ] | jpayne@68:[ >> ] | jpayne@68:jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | jpayne@68: | [Top] | jpayne@68:[Contents] | jpayne@68:[Index] | jpayne@68:[ ? ] | jpayne@68:
jpayne@68:
jpayne@68: This document was generated by Bruno Haible on February, 21 2024 using texi2html 1.78a.
jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68: