NAME¶
textwrap - line-folding (text-wrapping) library with i18n support
SYNOPSIS¶
#include <textwrap.h>
void textwrap_init(textwrap_t *prop);
void textwrap_columns(textwrap_t *prop, int columns);
void textwrap_tab(textwrap_t *prop, int tab);
void textwrap_head(textwrap_t *prop, const char *head1, const char
*head2);
char *textwrap(const textwrap_t *prop, const char *text);
DESCRIPTION¶
textwrap is a library to wrap given text to fit the terminal with a
certain width. This is like
Text::Wrap(3pm).
Unlike other libraries or functions, this supports internationalization.
At first, this automatically detects the
current LC_CTYPE locale and
follows it. To enable this, your application must call
setlocale(3) in
advance.
Next, this supports
multibyte encodings such as UTF-8 and EUC-JP. In
multibyte encodings, one character consists from one or more bytes.
Third, this supports
fullwidth characters such as CJK Ideogram, Katakana,
Hiragana, and Hangul. These characters occupy two columns per one character on
the terminal.
Forth, this supports
combining characters such as Thai and accents for
Latin scripts. These characters occupy zero columns per one character on the
terminal.
Fifth, this supports languages which do not use whitespaces between words. In
these languages, lines can be folded at any places with small amount of
exception (such as before commas).
USAGE¶
At first, you will have to prepare a set of parameters as
textwrap_t.
Prepare a variable of
textwrap_t and then call
textwrap_init()
with the pointer to the variable.
Members of
textwrap_t may change in future. Thus, please use API
functions to modify values of these members.
- textwrap_columns()
- Specifies the number of columns or width of your terminal. The result
string will not have longer line than this value. The default value is
76.
- textwrap_tab()
- Specifies the number of columns for TAB code. The default is 8.
- textwrap_head()
- Specifies strings which will be added at the top of the top line and
following lines. The defaults are NULL for head1 and NULL for
head2.
The real text-wrapping is performed by
textwrap(). The text to be folded
is given as
text. The text must be encoded in the current LC_CTYPE
locale, i.e., ISO-8859-1 in ISO-8859-1 locales, KOI8-R in KOI8-R locales,
EUC-JP in EUC-JP locales, UTF-8 in UTF-8 locales, and so on. Though you might
not be very familiar with the term LC_CTYPE locale, this behavior is under
what most of users use UNIX-like systems. Thus, you do not have to convert the
encoding of the string.
The
text can contain tab code (0x09). The tab is converted into proper
number of space code (0x20) by
textwrap.
RETURN VALUE¶
textwrap() returns the line-folded text. You can
free(3) the given value.
In case of any error while processing the string, the text <ERR> will be
appended to the output and processing will be aborted.
EXAMPLE¶
#include <stdio.h>
#include <textwrap.h>
main()
{
textwrap_t property;
char *text = "This is a sample.\n";
char *outtext;
textwrap_init(&property);
textwrap_columns(&property, 70);
outtext = textwrap(&property, text);
printf("%s\n",outtext);
free(outtext);
}
SEE ALSO¶
Manual pages of
dotextwrap(1),
setlocale(3),
locale(7),
charsets(7), and
UTF-8(7).
AUTHOR¶
Tomohiro KUBOTA <kubota@debian.org>.