1.\" $Id: mchars_alloc.3,v 1.1.1.1 2015/12/17 21:58:48 christos Exp $ 2.\" 3.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: October 26 2014 $ 18.Dt MCHARS_ALLOC 3 19.Os 20.Sh NAME 21.Nm mchars_alloc , 22.Nm mchars_free , 23.Nm mchars_num2char , 24.Nm mchars_num2uc , 25.Nm mchars_spec2cp , 26.Nm mchars_spec2str 27.Nd character table for mandoc 28.Sh LIBRARY 29.Lb libmandoc 30.Sh SYNOPSIS 31.In sys/types.h 32.In mandoc.h 33.Ft "struct mchars *" 34.Fn mchars_alloc "void" 35.Ft void 36.Fo mchars_free 37.Fa "struct mchars *table" 38.Fc 39.Ft char 40.Fo mchars_num2char 41.Fa "const char *decimal" 42.Fa "size_t sz" 43.Fc 44.Ft int 45.Fo mchars_num2uc 46.Fa "const char *hexadecimal" 47.Fa "size_t sz" 48.Fc 49.Ft int 50.Fo mchars_spec2cp 51.Fa "const struct mchars *table" 52.Fa "const char *name" 53.Fa "size_t sz" 54.Fc 55.Ft "const char *" 56.Fo mchars_spec2str 57.Fa "const struct mchars *table" 58.Fa "const char *name" 59.Fa "size_t sz" 60.Fa "size_t *rsz" 61.Fc 62.Ft "const char *" 63.Fn mchars_uc2str "int codepoint" 64.Sh DESCRIPTION 65These functions translate Unicode character numbers and 66.Xr roff 7 67character names into glyphs. 68See 69.Xr mandoc_char 7 70for a list of 71.Xr roff 7 72special characters. 73These functions are intended for external use by programs formatting 74.Xr mdoc 7 75and 76.Xr man 7 77pages for output, for example the 78.Xr mandoc 1 79output formatter modules and 80.Xr makewhatis 8 . 81The 82.Fa decimal , 83.Fa hexadecimal , 84.Fa name , 85and 86.Fa size 87input arguments are usually obtained from the 88.Xr mandoc_escape 3 89parser function. 90.Pp 91The function 92.Fn mchars_num2char 93converts a 94.Fa decimal 95string representation of a character number consisting of 96.Fa sz 97digits into a printable ASCII character. 98If the input string is non-numeric or does not represent a printable 99ASCII character, the NUL character 100.Pq Sq \e0 101is returned. 102For example, the 103.Xr mandoc 1 104.Fl Tascii , 105.Fl Tutf8 , 106and 107.Fl Thtml 108output modules use this function to render 109.Xr roff 7 110.Ic \eN 111escape sequences. 112.Pp 113The function 114.Fn mchars_num2uc 115converts a 116.Fa hexadecimal 117string representation of a Unicode codepoint consisting of 118.Fa sz 119digits into an integer representation. 120If the input string is non-numeric or represents an ASCII character, 121the NUL character 122.Pq Sq \e0 123is returned. 124For example, the 125.Xr mandoc 1 126.Fl Tutf8 127and 128.Fl Thtml 129output modules use this function to render 130.Xr roff 7 131.Ic \e[u Ns Ar XXXX Ns Ic \&] 132and 133.Ic \eC\(aqu Ns Ar XXXX Ns Ic \(aq 134escape sequences. 135.Pp 136The function 137.Fn mchars_alloc 138allocates an opaque 139.Vt "struct mchars *" 140table object for subsequent use by the following two lookup functions. 141When no longer needed, this object can be destroyed with 142.Fn mchars_free . 143.Pp 144The function 145.Fn mchars_spec2cp 146looks up a 147.Xr roff 7 148special character 149.Fa name 150consisting of 151.Fa sz 152characters in the 153.Fa table 154and returns the corresponding Unicode codepoint. 155If the 156.Ar name 157is not recognized, \-1 is returned. 158For example, the 159.Xr mandoc 1 160.Fl Tutf8 161and 162.Fl Thtml 163output modules use this function to render 164.Xr roff 7 165.Ic \e[ Ns Ar name Ns Ic \&] 166and 167.Ic \eC\(aq Ns Ar name Ns Ic \(aq 168escape sequences. 169.Pp 170The function 171.Fn mchars_spec2str 172looks up a 173.Xr roff 7 174special character 175.Fa name 176consisting of 177.Fa sz 178characters in the 179.Fa table 180and returns an ASCII string representation. 181The length of the representation is returned in 182.Fa rsz . 183In many cases, the meaning of such ASCII representations 184is not quite obvious, so using 185.Xr roff 7 186special characters in documents intended for ASCII rendering 187is usually a bad idea. 188If the 189.Ar name 190is not recognized, 191.Dv NULL 192is returned. 193For example, 194.Xr makewhatis 8 195and the 196.Xr mandoc 1 197.Fl Tascii 198output module use this function to render 199.Xr roff 7 200.Ic \e[ Ns Ar name Ns Ic \&] 201and 202.Ic \eC\(aq Ns Ar name Ns Ic \(aq 203escape sequences. 204.Pp 205The function 206.Fn mchars_uc2str 207performs a reverse lookup of the Unicode 208.Fa codepoint 209and returns an ASCII string representation, or the string 210.Qq <?> 211if none is available. 212.Sh FILES 213These funtions are implemented in the file 214.Pa chars.c . 215.Sh SEE ALSO 216.Xr mandoc 1 , 217.Xr mandoc_escape 3 , 218.Xr mandoc_char 7 , 219.Xr roff 7 220.Sh HISTORY 221These functions and their predecessors have been available since the 222following mandoc versions: 223.Bl -column "mchars_num2char()" "1.11.3" "chars_num2char()" "1.10.10" 224.It Sy function Ta since Ta Sy predecessor Ta since 225.It Fn mchars_alloc Ta 1.11.3 Ta Fn ascii2htab Ta 1.5.3 226.It Fn mchars_free Ta 1.11.2 Ta Fn asciifree Ta 1.6.0 227.It Fn mchars_num2char Ta 1.11.2 Ta Fn chars_num2char Ta 1.10.10 228.It Fn mchars_num2uc Ta 1.11.3 Ta \(em Ta \(em 229.It Fn mchars_spec2cp Ta 1.11.2 Ta Fn chars_spec2cp Ta 1.10.5 230.It Fn mchars_spec2str Ta 1.11.2 Ta Fn a2ascii Ta 1.5.3 231.It Fn mchars_uc2str Ta 1.13.2 Ta \(em Ta \(em 232.El 233.Sh AUTHORS 234.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 235.An Ingo Schwarze Aq Mt schwarze@openbsd.org 236