.\" Copyright (C) 2001 Information-technology Promotion Agency (IPA)
.\" Copyright (C) 2001-2011
.\"   National Institute of Advanced Industrial Science and Technology (AIST)
.\" This file is part of the m17n library documentation.
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Section, no Front-Cover Texts,
.\" and no Back-Cover Texts.  A copy of the license is included in the
.\" appendix entitled "GNU Free Documentation License".
.TH "mconv_define_coding" 3m17n "12 Jan 2011" "Version 1.6.2" "The m17n Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
mconv_define_coding \- Define a coding system. 


.SH SYNOPSIS
\fBMSymbol\fP
\fBmconv_define_coding\fP (const char *
\fIname\fP, \fBMPlist\fP *
\fIplist\fP, int(*)(\fBMConverter\fP *)
\fIresetter\fP, int(*)(const unsigned char *,
\fIint\fP, \fBMText\fP *, \fBMConverter\fP *)
\fIdecoder\fP, int(*)(\fBMText\fP *,
\fIint\fP,
\fIint\fP, unsigned char *,
\fIint\fP, \fBMConverter\fP *)
\fIencoder\fP, void *
\fIextra_info\fP)


.SH DESCRIPTION
Define a coding system. The
.ft B
mconv_define_coding()
.ft R
function defines a new coding system and makes it accessible via a symbol whose name is
.ft B
name\fP.
.ft R
.ft B
plist
.ft R
specifies parameters of the coding system as below:
.PP
.PD 0
.IP "\(bu" 2
Key is
.ft C
Mtype\fP,
.ft R
value is a symbol
.PP
The value specifies the type of the coding system. It must be
.ft B
Mcharset\fP,
.ft R
.ft B
Mutf\fP,
.ft R
.ft B
Miso_2022\fP,
.ft R
or
.ft B
Mnil\fP.
.ft R
.PP
If the type is
.ft B
Mcharset\fP,
.ft R
.ft B
extra_info
.ft R
is ignored.
.PP
If the type is
.ft B
Mutf\fP,
.ft R
.ft B
extra_info
.ft R
must be a pointer to
.ft B
MCodingInfoUTF\fP.
.ft R
.PP
If the type is
.ft B
Miso_2022\fP,
.ft R
.ft B
extra_info
.ft R
must be a pointer to
.ft B
MCodingInfoISO2022\fP.
.ft R
.PP
If the type is
.ft B
Mnil\fP,
.ft R
the argument
.ft B
resetter\fP,
.ft R
.ft B
decoder\fP,
.ft R
and
.ft B
encoder
.ft R
must be supplied.
.ft B
extra_info
.ft R
is ignored. Otherwise, they can be
.ft C
NULL
.ft R
and the m17n library provides proper defaults.
.PP

.IP "\(bu" 2
Key is
.ft B
Mcharsets\fP,
.ft R
value is a plist
.PP
The value specifies a list charsets supported by the coding system. The keys of the plist must be
.ft B
Msymbol\fP,
.ft R
and the values must be symbols representing charsets.
.PP

.IP "\(bu" 2
Key is
.ft B
Mflags\fP,
.ft R
value is a plist
.PP
If the type is
.ft B
Miso_2022\fP,
.ft R
the values specifies flags to control the ISO 2022 interpreter. The keys of the plist must e
.ft B
Msymbol\fP,
.ft R
and values must be one of the following.
.PP
.PD 0
.IP "  \(bu" 4
\fBMreset_at_eol
.ft R
.PP
If this flag exists, designation and invocation status is reset to the initial state at the end of line.
.PP

.IP "  \(bu" 4
\fBMreset_at_cntl
.ft R
.PP
If this flag exists, designation and invocation status is reset to the initial state at a control character.
.PP

.IP "  \(bu" 4
\fBMeight_bit
.ft R
.PP
If this flag exists, the graphic plane right is used.
.PP

.IP "  \(bu" 4
\fBMlong_form
.ft R
.PP
If this flag exists, the over\-long escape sequences (ESC '$' '(' <final_byte>) are used for designating the CCS JISX0208.1978, GB2312, and JISX0208.
.PP

.IP "  \(bu" 4
\fBMdesignation_g0
.ft R
.PP
If this flag and
.ft B
Mfull_support
.ft R
exists, designates charsets not listed in the charset list to the graphic register G0.
.PP

.IP "  \(bu" 4
\fBMdesignation_g1
.ft R
.PP
If this flag and
.ft B
Mfull_support
.ft R
exists, designates charsets not listed in the charset list to the graphic register G1.
.PP

.IP "  \(bu" 4
\fBMdesignation_ctext
.ft R
.PP
If this flag and
.ft B
Mfull_support
.ft R
exists, designates charsets not listed in the charset list to a graphic register G0 or G1 based on the criteria of the Compound Text.
.PP

.IP "  \(bu" 4
\fBMdesignation_ctext_ext
.ft R
.PP
If this flag and
.ft B
Mfull_support
.ft R
exists, designates charsets not listed in the charset list to a graphic register G0 or G1, or use extended segment for such charsets based on the criteria of the Compound Text.
.PP

.IP "  \(bu" 4
\fBMlocking_shift
.ft R
.PP
If this flag exists, use locking shift.
.PP

.IP "  \(bu" 4
\fBMsingle_shift
.ft R
.PP
If this flag exists, use single shift.
.PP

.IP "  \(bu" 4
\fBMsingle_shift_7
.ft R
.PP
If this flag exists, use 7\-bit single shift code (0x19).
.PP

.IP "  \(bu" 4
\fBMeuc_tw_shift
.ft R
.PP
If this flag exists, use a special shifting according to EUC\-TW.
.PP

.IP "  \(bu" 4
\fBMiso_6429
.ft R
.PP
This flag is currently ignored.
.PP

.IP "  \(bu" 4
\fBMrevision_number
.ft R
.PP
If this flag exists, use a revision number escape sequence to designate a charset that has a revision number.
.PP

.IP "  \(bu" 4
\fBMfull_support
.ft R
.PP
If this flag exists, support all charsets registered in the International Registry.
.PP

.PP
.PP

.IP "\(bu" 2
Key is
.ft B
Mdesignation\fP,
.ft R
value is a plist
.PP
If the type is
.ft B
Miso_2022\fP,
.ft R
the value specifies how to designate each supported characters. The keys of the plist must be
.ft B
Minteger\fP,
.ft R
and the values must be numbers indicating a graphic registers. The Nth element value is for the Nth charset of the charset list. The value 0..3 means that it is assumed that a charset is already designated to the graphic register 0..3. The negative value G (\-4..\-1) means that a charset is not designated to any register at first, and if necessary, is designated to the (G+4) graphic register.
.PP

.IP "\(bu" 2
Key is
.ft B
Minvocation\fP,
.ft R
value is a plist
.PP
If the type is
.ft B
Miso_2022\fP,
.ft R
the value specifies how to invocate each graphic registers. The plist length must be one or two. The keys of the plist must be
.ft B
Minteger\fP,
.ft R
and the values must be numbers indicating a graphic register. The value of the first element specifies which graphic register is invocated to the graphic plane left. If the length is one, no graphic register is invocated to the graphic plane right. Otherwise, the value of the second element specifies which graphic register is invocated to the graphic plane right.
.PP

.IP "\(bu" 2
Key is
.ft B
Mcode_unit\fP,
.ft R
value is an integer
.PP
If the type is
.ft B
Mutf\fP,
.ft R
the value specifies the bit length of a code\-unit. It must be 8, 16, or 32.
.PP

.IP "\(bu" 2
Key is
.ft B
Mbom\fP,
.ft R
value is a symbol
.PP
If the type is
.ft B
Mutf
.ft R
and the code\-unit bit length is 16 or 32, it specifies whether or not to use BOM (Byte Order Mark). If the value is
.ft B
Mnil
.ft R
(default), BOM is not used, else if the value is
.ft B
Mmaybe\fP,
.ft R
the existence of BOM is detected at decoding time, else BOM is used.
.PP

.IP "\(bu" 2
Key is
.ft B
Mlittle_endian\fP,
.ft R
value is a symbol
.PP
If the type is
.ft B
Mutf
.ft R
and the code\-unit bit length is 16 or 32, it specifies whether or not the encoding is little endian. If the value is
.ft B
Mnil
.ft R
(default), it is big endian, else it is little endian.
.PP

.PP
.PP
\fBresetter
.ft R
is a pointer to a function that resets a converter for the coding system to the initial status. The pointed function is called with one argument, a pointer to a converter object.
.PP
\fBdecoder
.ft R
is a pointer to a function that decodes a byte sequence according to the coding system. The pointed function is called with four arguments:
.PP
.PD 0
.IP "\(bu" 2
A pointer to the byte sequence to decode. 
.IP "\(bu" 2
The number of bytes to decode. 
.IP "\(bu" 2
A pointer to an M\-text to which the decoded characters are appended. 
.IP "\(bu" 2
A pointer to a converter object.
.PP
\fBdecoder
.ft R
must return 0 if it succeeds. Otherwise it must return \-1.
.PP
\fBencoder
.ft R
is a pointer to a function that encodes an M\-text according to the coding system. The pointed function is called with six arguments:
.PP
.PD 0
.IP "\(bu" 2
A pointer to the M\-text to encode. 
.IP "\(bu" 2
The starting position of the encoding. 
.IP "\(bu" 2
The ending position of the encoding. 
.IP "\(bu" 2
A pointer to a memory area where the produced bytes are stored. 
.IP "\(bu" 2
The size of the memory area. 
.IP "\(bu" 2
A pointer to a converter object.
.PP
\fBencoder
.ft R
must return 0 if it succeeds. Otherwise it must return \-1.
.PP
\fBextra_info
.ft R
is a pointer to a data structure that contains extra information about the coding system. The type of the data structure depends on
.ft B
type\fP.
.ft R
.PP
.SH RETURN VALUE
.PP
.RS 4

.RE
.PP
If the operation was successful,
.ft B
mconv_define_coding()
.ft R
returns a symbol whose name is
.ft B
name\fP.
.ft R
If an error is detected, it returns
.ft B
Mnil
.ft R
and assigns an error code to the external variable
.ft B
merror_code\fP.
.ft R
.PP
.SH ERRORS
.PP
.RS 4
\fCMERROR_CODING
.ft R
.RE
.PP

.SH COPYRIGHT
Copyright (C) 2001 Information\-technology Promotion Agency (IPA)
.br
Copyright (C) 2001\-2011 National Institute of Advanced Industrial Science and Technology (AIST)
.br
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License 
<http://www.gnu.org/licenses/fdl.html>.