.\"	$Id: mchars_alloc.3,v 1.1 2014/08/05 05:48:56 schwarze Exp $
.\"
.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: August 5 2014 $
.Dt MCHARS_ALLOC 3
.Os
.Sh NAME
.Nm mchars_alloc ,
.Nm mchars_free ,
.Nm mchars_num2char ,
.Nm mchars_num2uc ,
.Nm mchars_spec2cp ,
.Nm mchars_spec2str
.Nd character table for mandoc
.Sh LIBRARY
.Lb libmandoc
.Sh SYNOPSIS
.In sys/types.h
.In mandoc.h
.Ft "struct mchars *"
.Fn mchars_alloc "void"
.Ft void
.Fo mchars_free
.Fa "struct mchars *table"
.Fc
.Ft char
.Fo mchars_num2char
.Fa "const char *decimal"
.Fa "size_t sz"
.Fc
.Ft int
.Fo mchars_num2uc
.Fa "const char *hexadecimal"
.Fa "size_t sz"
.Fc
.Ft int
.Fo mchars_spec2cp
.Fa "const struct mchars *table"
.Fa "const char *name"
.Fa "size_t sz"
.Fc
.Ft "const char *"
.Fo mchars_spec2str
.Fa "const struct mchars *table"
.Fa "const char *name"
.Fa "size_t sz"
.Fa "size_t *rsz"
.Fc
.Sh DESCRIPTION
These functions translate Unicode character numbers and
.Xr roff 7
character names into glyphs.
See
.Xr mandoc_char 7
for a list of
.Xr roff 7
special characters.
These functions are intended for external use by programs formatting
.Xr mdoc 7
and
.Xr man 7
pages for output, for example the
.Xr mandoc 1
output formatter modules and
.Xr makewhatis 8 .
The
.Fa decimal ,
.Fa hexadecimal ,
.Fa name ,
and
.Fa size
input arguments are usually obtained from the
.Xr mandoc_escape 3
parser function.
.Pp
The function
.Fn mchars_num2char
converts a
.Fa decimal
string representation of a character number consisting of
.Fa sz
digits into a printable ASCII character.
If the input string is non-numeric or does not represent a printable
ASCII character, the NUL character
.Pq Sq \e0
is returned.
For example, the
.Xr mandoc 1
.Fl Tascii ,
.Fl Tutf8 ,
and
.Fl Thtml
output modules use this function to render
.Xr roff 7
.Ic \eN
escape sequences.
.Pp
The function
.Fn mchars_num2uc
converts a
.Fa hexadecimal
string representation of a Unicode codepoint consisting of
.Fa sz
digits into an integer representation.
If the input string is non-numeric or represents an ASCII character,
the NUL character
.Pq Sq \e0
is returned.
For example, the
.Xr mandoc 1
.Fl Tutf8
and
.Fl Thtml
output modules use this function to render
.Xr roff 7
.Ic \e[u Ns Ar XXXX Ns Ic \&]
and
.Ic \eC\(aqu Ns Ar XXXX Ns Ic \(aq
escape sequences.
.Pp
The function
.Fn mchars_alloc
allocates an opaque
.Vt "struct mchars *"
table object for subsequent use by the following two lookup functions.
When no longer needed, this object can be destroyed with
.Fn mchars_free .
.Pp
The function
.Fn mchars_spec2cp
looks up a
.Xr roff 7
special character
.Fa name
consisting of
.Fa sz
characters in the
.Fa table
and returns the corresponding Unicode codepoint.
If the
.Ar name
is not recognized, \-1 is returned.
For example, the
.Xr mandoc 1
.Fl Tutf8
and
.Fl Thtml
output modules use this function to render
.Xr roff 7
.Ic \e[ Ns Ar name Ns Ic \&]
and
.Ic \eC\(aq Ns Ar name Ns Ic \(aq
escape sequences.
.Pp
The function
.Fn mchars_spec2str
looks up a
.Xr roff 7
special character
.Fa name
consisting of
.Fa sz
characters in the
.Fa table
and returns an ASCII string representation.
The length of the representation is returned in
.Fa rsz .
In many cases, the meaning of such ASCII representations
is not quite obvious, so using
.Xr roff 7
special characters in documents intended for ASCII rendering
is usually a bad idea.
If the
.Ar name
is not recognized,
.Dv NULL
is returned.
For example,
.Xr makewhatis 8
and the
.Xr mandoc 1
.Fl Tascii
output module use this function to render
.Xr roff 7
.Ic \e[ Ns Ar name Ns Ic \&]
and
.Ic \eC\(aq Ns Ar name Ns Ic \(aq
escape sequences.
.Sh FILES
These funtions are implemented in the file
.Pa chars.c .
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr mandoc_escape 3 ,
.Xr mandoc_char 7 ,
.Xr roff 7
.Sh HISTORY
These functions and their predecessors have been available since the
following mandoc versions:
.Bl -column "mchars_num2char()" "1.11.3" "chars_num2char()" "1.10.10"
.It Sy function Ta since Ta Sy predecessor Ta since
.It Fn mchars_alloc Ta 1.11.3 Ta Fn ascii2htab Ta 1.5.3
.It Fn mchars_free Ta 1.11.2 Ta Fn asciifree Ta 1.6.0
.It Fn mchars_num2char Ta 1.11.2 Ta Fn chars_num2char Ta 1.10.10
.It Fn mchars_num2uc Ta 1.11.3 Ta \(em Ta \(em
.It Fn mchars_spec2cp Ta 1.11.2 Ta Fn chars_spec2cp Ta 1.10.5
.It Fn mchars_spec2str Ta 1.11.2 Ta Fn a2ascii Ta 1.5.3
.El
.Sh AUTHORS
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
.An Ingo Schwarze Aq Mt schwarze@openbsd.org