NAME

       mconv_define_coding - Define a coding system.

SYNOPSIS

       MSymbol mconv_define_coding (const char * name, MPlist * plist, int(*)(MConverter *)
       resetter, int(*)(const unsigned char *, int, MText *, MConverter *) decoder, int(*)(MText
       *, int, int, unsigned char *, int, MConverter *) encoder, void * extra_info)

DESCRIPTION

       Define a coding system. The mconv_define_coding() function defines a new coding system and
       makes it accessible via a symbol whose name is name.  plist specifies parameters of the
       coding system as below:

       • Key is Mtype, value is a symbol
       The value specifies the type of the coding system. It must be Mcharset, Mutf, Miso_2022,
       or Mnil.
       If the type is Mcharset, extra_info is ignored.
       If the type is Mutf, extra_info must be a pointer to MCodingInfoUTF.
       If the type is Miso_2022, extra_info must be a pointer to MCodingInfoISO2022.
       If the type is Mnil, the argument resetter, decoder, and encoder must be supplied.
       extra_info is ignored. Otherwise, they can be NULL and the m17n library provides proper
       defaults.
       • Key is Mcharsets, value is a plist
       The value specifies a list charsets supported by the coding system. The keys of the plist
       must be Msymbol, and the values must be symbols representing charsets.
       • Key is Mflags, value is a plist
       If the type is Miso_2022, the values specifies flags to control the ISO 2022 interpreter.
       The keys of the plist must e Msymbol, and values must be one of the following.
         • Mreset_at_eol
       If this flag exists, designation and invocation status is reset to the initial state at
       the end of line.
         • Mreset_at_cntl
       If this flag exists, designation and invocation status is reset to the initial state at a
       control character.
         • Meight_bit
       If this flag exists, the graphic plane right is used.
         • Mlong_form
       If this flag exists, the over-long escape sequences (ESC '$' '(' <final_byte>) are used
       for designating the CCS JISX0208.1978, GB2312, and JISX0208.
         • Mdesignation_g0
       If this flag and Mfull_support exists, designates charsets not listed in the charset list
       to the graphic register G0.
         • Mdesignation_g1
       If this flag and Mfull_support exists, designates charsets not listed in the charset list
       to the graphic register G1.
         • Mdesignation_ctext
       If this flag and Mfull_support exists, designates charsets not listed in the charset list
       to a graphic register G0 or G1 based on the criteria of the Compound Text.
         • Mdesignation_ctext_ext
       If this flag and Mfull_support 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.
         • Mlocking_shift
       If this flag exists, use locking shift.
         • Msingle_shift
       If this flag exists, use single shift.
         • Msingle_shift_7
       If this flag exists, use 7-bit single shift code (0x19).
         • Meuc_tw_shift
       If this flag exists, use a special shifting according to EUC-TW.
         • Miso_6429
       This flag is currently ignored.
         • Mrevision_number
       If this flag exists, use a revision number escape sequence to designate a charset that has
       a revision number.
         • Mfull_support
       If this flag exists, support all charsets registered in the International Registry.
       • Key is Mdesignation, value is a plist
       If the type is Miso_2022, the value specifies how to designate each supported characters.
       The keys of the plist must be Minteger, 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.
       • Key is Minvocation, value is a plist
       If the type is Miso_2022, the value specifies how to invocate each graphic registers. The
       plist length must be one or two. The keys of the plist must be Minteger, 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.
       • Key is Mcode_unit, value is an integer
       If the type is Mutf, the value specifies the bit length of a code-unit. It must be 8, 16,
       or 32.
       • Key is Mbom, value is a symbol
       If the type is Mutf 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 Mnil (default), BOM is not used, else if the
       value is Mmaybe, the existence of BOM is detected at decoding time, else BOM is used.
       • Key is Mlittle_endian, value is a symbol
       If the type is Mutf and the code-unit bit length is 16 or 32, it specifies whether or not
       the encoding is little endian. If the value is Mnil (default), it is big endian, else it
       is little endian.
       resetter 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.
       decoder is a pointer to a function that decodes a byte sequence according to the coding
       system. The pointed function is called with four arguments:
       • A pointer to the byte sequence to decode.
       • The number of bytes to decode.
       • A pointer to an M-text to which the decoded characters are appended.
       • A pointer to a converter object.
       decoder must return 0 if it succeeds. Otherwise it must return -1.
       encoder is a pointer to a function that encodes an M-text according to the coding system.
       The pointed function is called with six arguments:
       • A pointer to the M-text to encode.
       • The starting position of the encoding.
       • The ending position of the encoding.
       • A pointer to a memory area where the produced bytes are stored.
       • The size of the memory area.
       • A pointer to a converter object.
       encoder must return 0 if it succeeds. Otherwise it must return -1.
       extra_info is a pointer to a data structure that contains extra information about the
       coding system. The type of the data structure depends on type.

RETURN VALUE

       If the operation was successful, mconv_define_coding() returns a symbol whose name is
       name.  If an error is detected, it returns Mnil and assigns an error code to the external
       variable merror_code.

ERRORS

           MERROR_CODING

COPYRIGHT

       Copyright (C) 2001 Information-technology Promotion Agency (IPA)
       Copyright (C) 2001-2011 National Institute of Advanced Industrial Science and Technology
       (AIST)
       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>.