XEmacs 21.4.15
[chise/xemacs-chise.git.1] / info / lispref.info-8
1 This is ../info/lispref.info, produced by makeinfo version 4.6 from
2 lispref/lispref.texi.
3
4 INFO-DIR-SECTION XEmacs Editor
5 START-INFO-DIR-ENTRY
6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
7 END-INFO-DIR-ENTRY
8
9    Edition History:
10
11    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
20
21    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
24
25    Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
28
29    Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
33
34    Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
38
39    Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
45
46    Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
51
52 \1f
53 File: lispref.info,  Node: The LDAP Lisp Object,  Next: Opening and Closing a LDAP Connection,  Prev: The Low-Level LDAP API,  Up: The Low-Level LDAP API
54
55 The LDAP Lisp Object
56 ....................
57
58 An internal built-in `ldap' lisp object represents a LDAP connection.
59
60  - Function: ldapp object
61      This function returns non-`nil' if OBJECT is a `ldap' object.
62
63  - Function: ldap-host ldap
64      Return the server host of the connection represented by LDAP.
65
66  - Function: ldap-live-p ldap
67      Return non-`nil' if LDAP is an active LDAP connection.
68
69 \1f
70 File: lispref.info,  Node: Opening and Closing a LDAP Connection,  Next: Low-level Operations on a LDAP Server,  Prev: The LDAP Lisp Object,  Up: The Low-Level LDAP API
71
72 Opening and Closing a LDAP Connection
73 .....................................
74
75  - Function: ldap-open host &optional plist
76      Open a LDAP connection to HOST.  PLIST is a property list
77      containing additional parameters for the connection.  Valid keys
78      in that list are:
79     `port'
80           The TCP port to use for the connection if different from
81           `ldap-default-port' or the library builtin value
82
83     `auth'
84           The authentication method to use, possible values depend on
85           the LDAP library XEmacs was compiled with, they may include
86           `simple', `krbv41' and `krbv42'.
87
88     `binddn'
89           The distinguished name of the user to bind as.  This may look
90           like `c=com, o=Acme, cn=Babs Jensen', see RFC 1779 for
91           details.
92
93     `passwd'
94           The password to use for authentication.
95
96     `deref'
97           The dereference policy is one of the symbols `never',
98           `always', `search' or `find' and defines how aliases are
99           dereferenced.
100          `never'
101                Aliases are never dereferenced.
102
103          `always'
104                Aliases are always dereferenced.
105
106          `search'
107                Aliases are dereferenced when searching.
108
109          `find'
110                Aliases are dereferenced when locating the base object
111                for the search.
112           The default is `never'.
113
114     `timelimit'
115           The timeout limit for the connection in seconds.
116
117     `sizelimit'
118           The maximum number of matches to return for searches
119           performed on this connection.
120
121  - Function: ldap-close ldap
122      Close the connection represented by LDAP.
123
124 \1f
125 File: lispref.info,  Node: Low-level Operations on a LDAP Server,  Prev: Opening and Closing a LDAP Connection,  Up: The Low-Level LDAP API
126
127 Low-level Operations on a LDAP Server
128 .....................................
129
130 `ldap-search-basic' is the low-level primitive to perform a search on a
131 LDAP server.  It works directly on an open LDAP connection thus
132 requiring a preliminary call to `ldap-open'.  Multiple searches can be
133 made on the same connection, then the session must be closed with
134 `ldap-close'.
135
136  - Function: ldap-search-basic ldap filter &optional base scope attrs
137           attrsonly withdn verbose
138      Perform a search on an open connection LDAP created with
139      `ldap-open'.  FILTER is a filter string for the search *note
140      Syntax of Search Filters:: BASE is the distinguished name at which
141      to start the search.  SCOPE is one of the symbols `base',
142      `onelevel' or `subtree' indicating the scope of the search limited
143      to a base object, to a single level or to the whole subtree.  The
144      default is `subtree'.  ATTRS is a list of strings indicating which
145      attributes to retrieve for each matching entry. If `nil' all
146      available attributes are returned.  If ATTRSONLY is non-`nil' then
147      only the attributes are retrieved, not their associated values.
148      If WITHDN is non-`nil' then each entry in the result is prepended
149      with its distinguished name DN.  If VERBOSE is non-`nil' then
150      progress messages are echoed The function returns a list of
151      matching entries.  Each entry  is itself an alist of
152      attribute/value pairs optionally preceded by the DN of the entry
153      according to the value of WITHDN.
154
155  - Function: ldap-add ldap dn entry
156      Add ENTRY to a LDAP directory which a connection LDAP has been
157      opened to with `ldap-open'.  DN is the distinguished name of the
158      entry to add.  ENTRY is an entry specification, i.e., a list of
159      cons cells containing attribute/value string pairs.
160
161  - Function: ldap-modify ldap dn mods
162      Modify an entry in an LDAP directory.  LDAP is an LDAP connection
163      object created with `ldap-open'.  DN is the distinguished name of
164      the entry to modify.  MODS is a list of modifications to apply.  A
165      modification is a list of the form `(MOD-OP ATTR VALUE1 VALUE2
166      ...)'  MOD-OP and ATTR are mandatory, VALUES are optional
167      depending on MOD-OP.  MOD-OP is the type of modification, one of
168      the symbols `add', `delete' or `replace'. ATTR is the LDAP
169      attribute type to modify.
170
171  - Function: ldap-delete ldap dn
172      Delete an entry to an LDAP directory.  LDAP is an LDAP connection
173      object created with `ldap-open'.  DN is the distinguished name of
174      the entry to delete.
175
176 \1f
177 File: lispref.info,  Node: LDAP Internationalization,  Prev: The Low-Level LDAP API,  Up: XEmacs LDAP API
178
179 LDAP Internationalization
180 -------------------------
181
182 The XEmacs LDAP API provides basic internationalization features based
183 on the LDAP v3 specification (essentially RFC2252 on "LDAP v3 Attribute
184 Syntax Definitions").  Unfortunately since there is currently no free
185 LDAP v3 server software, this part has not received much testing and
186 should be considered experimental.  The framework is in place though.
187
188  - Function: ldap-decode-attribute attr
189      Decode the attribute/value pair ATTR according to LDAP rules.  The
190      attribute name is looked up in `ldap-attribute-syntaxes-alist' and
191      the corresponding decoder is then retrieved from
192      `ldap-attribute-syntax-decoders'' and applied on the value(s).
193
194 * Menu:
195
196 * LDAP Internationalization Variables::
197 * Encoder/Decoder Functions::
198
199 \1f
200 File: lispref.info,  Node: LDAP Internationalization Variables,  Next: Encoder/Decoder Functions,  Prev: LDAP Internationalization,  Up: LDAP Internationalization
201
202 LDAP Internationalization Variables
203 ...................................
204
205  - Variable: ldap-ignore-attribute-codings
206      If non-`nil', no encoding/decoding will be performed LDAP
207      attribute values
208
209  - Variable: ldap-coding-system
210      Coding system of LDAP string values.  LDAP v3 specifies the coding
211      system of strings to be UTF-8.  You need an XEmacs with Mule
212      support for this.
213
214  - Variable: ldap-default-attribute-decoder
215      Decoder function to use for attributes whose syntax is unknown.
216      Such a function receives an encoded attribute value as a string
217      and should return the decoded value as a string.
218
219  - Variable: ldap-attribute-syntax-encoders
220      A vector of functions used to encode LDAP attribute values.  The
221      sequence of functions corresponds to the sequence of LDAP
222      attribute syntax object identifiers of the form
223      1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2.
224      As of this writing, only a few encoder functions are available.
225
226  - Variable: ldap-attribute-syntax-decoders
227      A vector of functions used to decode LDAP attribute values.  The
228      sequence of functions corresponds to the sequence of LDAP
229      attribute syntax object identifiers of the form
230      1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2.
231      As of this writing, only a few decoder functions are available.
232
233  - Variable: ldap-attribute-syntaxes-alist
234      A map of LDAP attribute names to their type object id minor number.
235      This table is built from RFC2252 Section 5 and RFC2256 Section 5.
236
237 \1f
238 File: lispref.info,  Node: Encoder/Decoder Functions,  Prev: LDAP Internationalization Variables,  Up: LDAP Internationalization
239
240 Encoder/Decoder Functions
241 .........................
242
243  - Function: ldap-encode-boolean bool
244      A function that encodes an elisp boolean BOOL into a LDAP boolean
245      string representation.
246
247  - Function: ldap-decode-boolean str
248      A function that decodes a LDAP boolean string representation STR
249      into an elisp boolean.
250
251  - Function: ldap-decode-string str
252      Decode a string STR according to `ldap-coding-system'.
253
254  - Function: ldap-encode-string str
255      Encode a string STR according to `ldap-coding-system'.
256
257  - Function: ldap-decode-address str
258      Decode an address STR according to `ldap-coding-system' and
259      replacing $ signs with newlines as specified by LDAP encoding
260      rules for addresses.
261
262  - Function: ldap-encode-address str
263      Encode an address STR according to `ldap-coding-system' and
264      replacing newlines with $ signs as specified by LDAP encoding
265      rules for addresses.
266
267 \1f
268 File: lispref.info,  Node: Syntax of Search Filters,  Prev: XEmacs LDAP API,  Up: LDAP Support
269
270 Syntax of Search Filters
271 ========================
272
273 LDAP search functions use RFC1558 syntax to describe the search filter.
274 In that syntax simple filters have the form:
275
276      (<attr> <filtertype> <value>)
277
278    `<attr>' is an attribute name such as `cn' for Common Name, `o' for
279 Organization, etc...
280
281    `<value>' is the corresponding value.  This is generally an exact
282 string but may also contain `*' characters as wildcards
283
284    `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
285 equality, approximate equality, inferiority and superiority.
286
287    Thus `(cn=John Smith)' matches all records having a canonical name
288 equal to John Smith.
289
290    A special case is the presence filter `(<attr>=*' which matches
291 records containing a particular attribute.  For instance `(mail=*)'
292 matches all records containing a `mail' attribute.
293
294    Simple filters can be connected together with the logical operators
295 `&', `|' and `!' which stand for the usual and, or and not operators.
296
297    `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))'
298 matches records of class `Person' containing a `mail' attribute and
299 corresponding to people whose last name is `Smith' or whose first name
300 is `John'.
301
302 \1f
303 File: lispref.info,  Node: PostgreSQL Support,  Next: Internationalization,  Prev: LDAP Support,  Up: Top
304
305 PostgreSQL Support
306 ******************
307
308 XEmacs can be linked with PostgreSQL libpq run-time support to provide
309 relational database access from Emacs Lisp code.
310
311 * Menu:
312
313 * Building XEmacs with PostgreSQL support::
314 * XEmacs PostgreSQL libpq API::
315 * XEmacs PostgreSQL libpq Examples::
316
317 \1f
318 File: lispref.info,  Node: Building XEmacs with PostgreSQL support,  Next: XEmacs PostgreSQL libpq API,  Up: PostgreSQL Support
319
320 Building XEmacs with PostgreSQL support
321 =======================================
322
323 XEmacs PostgreSQL support requires linking to the PostgreSQL libpq
324 library.  Describing how to build and install PostgreSQL is beyond the
325 scope of this document.  See the PostgreSQL manual for details.
326
327    If you have installed XEmacs from one of the binary kits on
328 (<ftp://ftp.xemacs.org/>), or are using an XEmacs binary from a CD ROM,
329 you may have XEmacs PostgreSQL support by default.  `M-x
330 describe-installation' will tell you if you do.
331
332    If you are building XEmacs from source, you need to install
333 PostgreSQL first.  On some systems, PostgreSQL will come pre-installed
334 in /usr.  In this case, it should be autodetected when you run
335 configure.  If PostgreSQL is installed into its default location,
336 `/usr/local/pgsql', you must specify `--site-prefixes=/usr/local/pgsql'
337 when you run configure.  If PostgreSQL is installed into another
338 location, use that instead of `/usr/local/pgsql' when specifying
339 `--site-prefixes'.
340
341    As of XEmacs 21.2, PostgreSQL versions 6.5.3 and 7.0 are supported.
342 XEmacs Lisp support for V7.0 is somewhat more extensive than support for
343 V6.5.  In particular, asynchronous queries are supported.
344
345 \1f
346 File: lispref.info,  Node: XEmacs PostgreSQL libpq API,  Next: XEmacs PostgreSQL libpq Examples,  Prev: Building XEmacs with PostgreSQL support,  Up: PostgreSQL Support
347
348 XEmacs PostgreSQL libpq API
349 ===========================
350
351 The XEmacs PostgreSQL API is intended to be a policy-free, low-level
352 binding to libpq.  The intent is to provide all the basic functionality
353 and then let high level Lisp code decide its own policies.
354
355    This documentation assumes that the reader has knowledge of SQL, but
356 requires no prior knowledge of libpq.
357
358    There are many examples in this manual and some setup will be
359 required.  In order to run most of the following examples, the
360 following code needs to be executed.  In addition to the data is in
361 this table, nearly all of the examples will assume that the free
362 variable `P' refers to this database connection.  The examples in the
363 original edition of this manual were run against Postgres 7.0beta1.
364
365      (progn
366        (setq P (pq-connectdb ""))
367        ;; id is the primary key, shikona is a Japanese word that
368        ;; means `the professional name of a Sumo wrestler', and
369        ;; rank is the Sumo rank name.
370        (pq-exec P (concat "CREATE TABLE xemacs_test"
371                           " (id int, shikona text, rank text);"))
372        (pq-exec P "COPY xemacs_test FROM stdin;")
373        (pq-put-line P "1\tMusashimaru\tYokuzuna\n")
374        (pq-put-line P "2\tDejima\tOozeki\n")
375        (pq-put-line P "3\tMusoyama\tSekiwake\n")
376        (pq-put-line P "4\tMiyabiyama\tSekiwake\n")
377        (pq-put-line P "5\tWakanoyama\tMaegashira\n")
378        (pq-put-line P "\\.\n")
379        (pq-end-copy P))
380           => nil
381
382 * Menu:
383
384 * libpq Lisp Variables::
385 * libpq Lisp Symbols and DataTypes::
386 * Synchronous Interface Functions::
387 * Asynchronous Interface Functions::
388 * Large Object Support::
389 * Other libpq Functions::
390 * Unimplemented libpq Functions::
391
392 \1f
393 File: lispref.info,  Node: libpq Lisp Variables,  Next: libpq Lisp Symbols and DataTypes,  Prev: XEmacs PostgreSQL libpq API,  Up: XEmacs PostgreSQL libpq API
394
395 libpq Lisp Variables
396 --------------------
397
398 Various Unix environment variables are used by libpq to provide defaults
399 to the many different parameters.  In the XEmacs Lisp API, these
400 environment variables are bound to Lisp variables to provide more
401 convenient access to Lisp Code.  These variables are passed to the
402 backend database server during the establishment of a database
403 connection and when the `pq-setenv' call is made.
404
405  - Variable: pg:host
406      Initialized from the `PGHOST' environment variable.  The default
407      host to connect to.
408
409  - Variable: pg:user
410      Initialized from the `PGUSER' environment variable.  The default
411      database user name.
412
413  - Variable: pg:options
414      Initialized from the `PGOPTIONS' environment variable.  Default
415      additional server options.
416
417  - Variable: pg:port
418      Initialized from the `PGPORT' environment variable.  The default
419      TCP port to connect to.
420
421  - Variable: pg:tty
422      Initialized from the `PGTTY' environment variable.  The default
423      debugging TTY.
424
425      Compatibility note:  Debugging TTYs are turned off in the XEmacs
426      Lisp binding.
427
428  - Variable: pg:database
429      Initialized from the `PGDATABASE' environment variable.  The
430      default database to connect to.
431
432  - Variable: pg:realm
433      Initialized from the `PGREALM' environment variable.  The default
434      Kerberos realm.
435
436  - Variable: pg:client-encoding
437      Initialized from the `PGCLIENTENCODING' environment variable.  The
438      default client encoding.
439
440      Compatibility note:  This variable is not present in non-Mule
441      XEmacsen.  This variable is not present in versions of libpq prior
442      to 7.0.  In the current implementation, client encoding is
443      equivalent to the `file-name-coding-system' format.
444
445  - Variable: pg:authtype
446      Initialized from the `PGAUTHTYPE' environment variable.  The
447      default authentication scheme used.
448
449      Compatibility note:  This variable is unused in versions of libpq
450      after 6.5.  It is not implemented at all in the XEmacs Lisp
451      binding.
452
453  - Variable: pg:geqo
454      Initialized from the `PGGEQO' environment variable.  Genetic
455      optimizer options.
456
457  - Variable: pg:cost-index
458      Initialized from the `PGCOSTINDEX' environment variable.  Cost
459      index options.
460
461  - Variable: pg:cost-heap
462      Initialized from the `PGCOSTHEAP' environment variable.  Cost heap
463      options.
464
465  - Variable: pg:tz
466      Initialized from the `PGTZ' environment variable.  Default
467      timezone.
468
469  - Variable: pg:date-style
470      Initialized from the `PGDATESTYLE' environment variable.  Default
471      date style in returned date objects.
472
473  - Variable: pg-coding-system
474      This is a variable controlling which coding system is used to
475      encode non-ASCII strings sent to the database.
476
477      Compatibility Note: This variable is not present in InfoDock.
478
479 \1f
480 File: lispref.info,  Node: libpq Lisp Symbols and DataTypes,  Next: Synchronous Interface Functions,  Prev: libpq Lisp Variables,  Up: XEmacs PostgreSQL libpq API
481
482 libpq Lisp Symbols and Datatypes
483 --------------------------------
484
485 The following set of symbols are used to represent the intermediate
486 states involved in the asynchronous interface.
487
488  - Symbol: pgres::polling-failed
489      Undocumented.  A fatal error has occurred during processing of an
490      asynchronous operation.
491
492  - Symbol: pgres::polling-reading
493      An intermediate status return during an asynchronous operation.  It
494      indicates that one may use `select' before polling again.
495
496  - Symbol: pgres::polling-writing
497      An intermediate status return during an asynchronous operation.  It
498      indicates that one may use `select' before polling again.
499
500  - Symbol: pgres::polling-ok
501      An asynchronous operation has successfully completed.
502
503  - Symbol: pgres::polling-active
504      An intermediate status return during an asynchronous operation.
505      One can call the poll function again immediately.
506
507  - Function: pq-pgconn conn field
508      CONN A database connection object.  FIELD A symbol indicating
509      which field of PGconn to fetch.  Possible values are shown in the
510      following table.
511     `pq::db'
512           Database name
513
514     `pq::user'
515           Database user name
516
517     `pq::pass'
518           Database user's password
519
520     `pq::host'
521           Hostname database server is running on
522
523     `pq::port'
524           TCP port number used in the connection
525
526     `pq::tty'
527           Debugging TTY
528
529           Compatibility note:  Debugging TTYs are not used in the
530           XEmacs Lisp API.
531
532     `pq::options'
533           Additional server options
534
535     `pq::status'
536           Connection status.  Possible return values are shown in the
537           following table.
538          `pg::connection-ok'
539                The normal, connected status.
540
541          `pg::connection-bad'
542                The connection is not open and the PGconn object needs
543                to be deleted by `pq-finish'.
544
545          `pg::connection-started'
546                An asynchronous connection has been started, but is not
547                yet complete.
548
549          `pg::connection-made'
550                An asynchronous connect has been made, and there is data
551                waiting to be sent.
552
553          `pg::connection-awaiting-response'
554                Awaiting data from the backend during an asynchronous
555                connection.
556
557          `pg::connection-auth-ok'
558                Received authentication, waiting for the backend to
559                start up.
560
561          `pg::connection-setenv'
562                Negotiating environment during an asynchronous
563                connection.
564
565     `pq::error-message'
566           The last error message that was delivered to this connection.
567
568     `pq::backend-pid'
569           The process ID of the backend database server.
570
571    The `PGresult' object is used by libpq to encapsulate the results of
572 queries.  The printed representation takes on four forms.  When the
573 PGresult object contains tuples from an SQL `SELECT' it will look like:
574
575      (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
576           => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
577
578    The number in brackets indicates how many rows of data are available.
579 When the PGresult object is the result of a command query that doesn't
580 return anything, it will look like:
581
582      (pq-exec P "CREATE TABLE a_new_table (i int);")
583           => #<PGresult PGRES_COMMAND_OK - CREATE>
584
585    When either the query is a command-type query that can affect a
586 number of different rows, but doesn't return any of them it will look
587 like:
588
589      (progn
590        (pq-exec P "INSERT INTO a_new_table VALUES (1);")
591        (pq-exec P "INSERT INTO a_new_table VALUES (2);")
592        (pq-exec P "INSERT INTO a_new_table VALUES (3);")
593        (setq R (pq-exec P "DELETE FROM a_new_table;")))
594           => #<PGresult PGRES_COMMAND_OK[3] - DELETE 3>
595
596    Lastly, when the underlying PGresult object has been deallocated
597 directly by `pq-clear' the printed representation will look like:
598
599      (progn
600        (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
601        (pq-clear R)
602        R)
603           => #<PGresult DEAD>
604
605    The following set of functions are accessors to various data in the
606 PGresult object.
607
608  - Function: pq-result-status result
609      Return status of a query result.  RESULT is a PGresult object.
610      The return value is one of the symbols in the following table.
611     `pgres::empty-query'
612           A query contained no text.  This is usually the result of a
613           recoverable error, or a minor programming error.
614
615     `pgres::command-ok'
616           A query command that doesn't return anything was executed
617           properly by the backend.
618
619     `pgres::tuples-ok'
620           A query command that returns tuples was executed properly by
621           the backend.
622
623     `pgres::copy-out'
624           Copy Out data transfer is in progress.
625
626     `pgres::copy-in'
627           Copy In data transfer is in progress.
628
629     `pgres::bad-response'
630           An unexpected response was received from the backend.
631
632     `pgres::nonfatal-error'
633           Undocumented.  This value is returned when the libpq function
634           `PQresultStatus' is called with a `NULL' pointer.
635
636     `pgres::fatal-error'
637           Undocumented.  An error has occurred in processing the query
638           and the operation was not completed.
639
640  - Function: pq-res-status result
641      Return the query result status as a string, not a symbol.  RESULT
642      is a PGresult object.
643
644           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
645                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
646           (pq-res-status R)
647                => "PGRES_TUPLES_OK"
648
649  - Function: pq-result-error-message result
650      Return an error message generated by the query, if any.  RESULT is
651      a PGresult object.
652
653           (setq R (pq-exec P "SELECT * FROM xemacs-test;"))
654                => <A fatal error is signaled in the echo area>
655           (pq-result-error-message R)
656                => "ERROR:  parser: parse error at or near \"-\"
657           "
658
659  - Function: pq-ntuples result
660      Return the number of tuples in the query result.  RESULT is a
661      PGresult object.
662
663           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
664                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
665           (pq-ntuples R)
666                => 5
667
668  - Function: pq-nfields result
669      Return the number of fields in each tuple of the query result.
670      RESULT is a PGresult object.
671
672           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
673                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
674           (pq-nfields R)
675                => 3
676
677  - Function: pq-binary-tuples result
678      Returns t if binary tuples are present in the results, nil
679      otherwise.  RESULT is a PGresult object.
680
681           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
682                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
683           (pq-binary-tuples R)
684                => nil
685
686  - Function: pq-fname result field-index
687      Returns the name of a specific field.  RESULT is a PGresult object.
688      FIELD-INDEX is the number of the column to select from.  The first
689      column is number zero.
690
691           (let (i l)
692             (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
693             (setq i (pq-nfields R))
694             (while (>= (decf i) 0)
695               (push (pq-fname R i) l))
696             l)
697                => ("id" "shikona" "rank")
698
699  - Function: pq-fnumber result field-name
700      Return the field number corresponding to the given field name.  -1
701      is returned on a bad field name.  RESULT is a PGresult object.
702      FIELD-NAME is a string representing the field name to find.
703           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
704                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
705           (pq-fnumber R "id")
706                => 0
707           (pq-fnumber R "Not a field")
708                => -1
709
710  - Function: pq-ftype result field-num
711      Return an integer code representing the data type of the specified
712      column.  RESULT is a PGresult object.  FIELD-NUM is the field
713      number.
714
715      The return value of this function is the Object ID (Oid) in the
716      database of the type.  Further queries need to be made to various
717      system tables in order to convert this value into something useful.
718
719  - Function: pq-fmod result field-num
720      Return the type modifier code associated with a field.  Field
721      numbers start at zero.  RESULT is a PGresult object.  FIELD-INDEX
722      selects which field to use.
723
724  - Function: pq-fsize result field-index
725      Return size of the given field.  RESULT is a PGresult object.
726      FIELD-INDEX selects which field to use.
727
728           (let (i l)
729             (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
730             (setq i (pq-nfields R))
731             (while (>= (decf i) 0)
732               (push (list (pq-ftype R i) (pq-fsize R i)) l))
733             l)
734                => ((23 23) (25 25) (25 25))
735
736  - Function: pq-get-value result tup-num field-num
737      Retrieve a return value.  RESULT is a PGresult object.  TUP-NUM
738      selects which tuple to fetch from.  FIELD-NUM selects which field
739      to fetch from.
740
741      Both tuples and fields are numbered from zero.
742
743           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
744                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
745           (pq-get-value R 0 1)
746                => "Musashimaru"
747           (pq-get-value R 1 1)
748                => "Dejima"
749           (pq-get-value R 2 1)
750                => "Musoyama"
751
752  - Function: pq-get-length result tup-num field-num
753      Return the length of a specific value.  RESULT is a PGresult
754      object.  TUP-NUM selects which tuple to fetch from.  FIELD-NUM
755      selects which field to fetch from.
756
757           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
758                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
759           (pq-get-length R 0 1)
760                => 11
761           (pq-get-length R 1 1)
762                => 6
763           (pq-get-length R 2 1)
764                => 8
765
766  - Function: pq-get-is-null result tup-num field-num
767      Return t if the specific value is the SQL `NULL'.  RESULT is a
768      PGresult object.  TUP-NUM selects which tuple to fetch from.
769      FIELD-NUM selects which field to fetch from.
770
771  - Function: pq-cmd-status result
772      Return a summary string from the query.  RESULT is a PGresult
773      object.
774           (setq R (pq-exec P "INSERT INTO xemacs_test
775                              VALUES (6, 'Wakanohana', 'Yokozuna');"))
776                => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542086 1>
777           (pq-cmd-status R)
778                => "INSERT 542086 1"
779           (setq R (pq-exec P "UPDATE xemacs_test SET rank='retired'
780                               WHERE shikona='Wakanohana';"))
781                => #<PGresult PGRES_COMMAND_OK[1] - UPDATE 1>
782           (pq-cmd-status R)
783                => "UPDATE 1"
784
785      Note that the first number returned from an insertion, like in the
786      example, is an object ID number and will almost certainly vary from
787      system to system since object ID numbers in Postgres must be unique
788      across all databases.
789
790  - Function: pq-cmd-tuples result
791      Return the number of tuples if the last command was an
792      INSERT/UPDATE/DELETE.  If the last command was something else, the
793      empty string is returned.  RESULT is a PGresult object.
794
795           (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
796                               (7, 'Takanohana', 'Yokuzuna');"))
797                => #<PGresult PGRES_COMMAND_OK[1] - INSERT 38688 1>
798           (pq-cmd-tuples R)
799                => "1"
800           (setq R (pq-exec P "SELECT * from xemacs_test;"))
801                => #<PGresult PGRES_TUPLES_OK[7] - SELECT>
802           (pq-cmd-tuples R)
803                => ""
804           (setq R (pq-exec P "DELETE FROM xemacs_test
805                               WHERE shikona LIKE '%hana';"))
806                => #<PGresult PGRES_COMMAND_OK[2] - DELETE 2>
807           (pq-cmd-tuples R)
808                => "2"
809
810  - Function: pq-oid-value result
811      Return the object id of the insertion if the last command was an
812      INSERT.  0 is returned if the last command was not an insertion.
813      RESULT is a PGresult object.
814
815      In the first example, the numbers you will see on your local
816      system will almost certainly be different, however the second
817      number from the right in the unprintable PGresult object and the
818      number returned by `pq-oid-value' should match.
819           (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
820                               (8, 'Terao', 'Maegashira');"))
821                => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542089 1>
822           (pq-oid-value R)
823                => 542089
824           (setq R (pq-exec P "SELECT shikona FROM xemacs_test
825                               WHERE rank='Maegashira';"))
826                => #<PGresult PGRES_TUPLES_OK[2] - SELECT>
827           (pq-oid-value R)
828                => 0
829
830  - Function: pq-make-empty-pgresult conn status
831      Create an empty pgresult with the given status.  CONN a database
832      connection object STATUS a value that can be returned by
833      `pq-result-status'.
834
835      The caller is responsible for making sure the return value gets
836      properly freed.
837
838 \1f
839 File: lispref.info,  Node: Synchronous Interface Functions,  Next: Asynchronous Interface Functions,  Prev: libpq Lisp Symbols and DataTypes,  Up: XEmacs PostgreSQL libpq API
840
841 Synchronous Interface Functions
842 -------------------------------
843
844  - Function: pq-connectdb conninfo
845      Establish a (synchronous) database connection.  CONNINFO A string
846      of blank separated options.  Options are of the form "OPTION =
847      VALUE".  If VALUE contains blanks, it must be single quoted.
848      Blanks around the equal sign are optional.  Multiple option
849      assignments are blank separated.
850           (pq-connectdb "dbname=japanese port = 25432")
851                => #<PGconn localhost:25432 steve/japanese>
852      The printed representation of a database connection object has four
853      fields.  The first field is the hostname where the database server
854      is running (in this case localhost), the second field is the port
855      number, the third field is the database user name, and the fourth
856      field is the name of the database.
857
858      Database connection objects which have been disconnected and will
859      generate an immediate error if they are used look like:
860             #<PGconn BAD>
861      Bad connections can be reestablished with `pq-reset', or deleted
862      entirely with `pq-finish'.
863
864      A database connection object that has been deleted looks like:
865           (let ((P1 (pq-connectdb "")))
866             (pq-finish P1)
867             P1)
868                => #<PGconn DEAD>
869
870      Note that database connection objects are the most heavy weight
871      objects in XEmacs Lisp at this writing, usually representing as
872      much as several megabytes of virtual memory on the machine the
873      database server is running on.  It is wisest to explicitly delete
874      them when you are finished with them, rather than letting garbage
875      collection do it.  An example idiom is:
876
877           (let ((P (pq-connectiondb "")))
878             (unwind-protect
879                 (progn
880                 (...)) ; access database here
881               (pq-finish P)))
882
883      The following options are available in the options string:
884     `authtype'
885           Authentication type.  Same as `PGAUTHTYPE'.  This is no
886           longer used.
887
888     `user'
889           Database user name.  Same as `PGUSER'.
890
891     `password'
892           Database password.
893
894     `dbname'
895           Database name.  Same as `PGDATABASE'
896
897     `host'
898           Symbolic hostname.  Same as `PGHOST'.
899
900     `hostaddr'
901           Host address as four octets (eg. like 192.168.1.1).
902
903     `port'
904           TCP port to connect to.  Same as `PGPORT'.
905
906     `tty'
907           Debugging TTY.  Same as `PGTTY'.  This value is suppressed in
908           the XEmacs Lisp API.
909
910     `options'
911           Extra backend database options.  Same as `PGOPTIONS'.
912      A database connection object is returned regardless of whether a
913      connection was established or not.
914
915  - Function: pq-reset conn
916      Reestablish database connection.  CONN A database connection
917      object.
918
919      This function reestablishes a database connection using the
920      original connection parameters.  This is useful if something has
921      happened to the TCP link and it has become broken.
922
923  - Function: pq-exec conn query
924      Make a synchronous database query.  CONN A database connection
925      object.  QUERY A string containing an SQL query.  A PGresult
926      object is returned, which in turn may be queried by its many
927      accessor functions to retrieve state out of it.  If the query
928      string contains multiple SQL commands, only results from the final
929      command are returned.
930
931           (setq R (pq-exec P "SELECT * FROM xemacs_test;
932           DELETE FROM xemacs_test WHERE id=8;"))
933                => #<PGresult PGRES_COMMAND_OK[1] - DELETE 1>
934
935  - Function: pq-notifies conn
936      Return the latest async notification that has not yet been handled.
937      CONN A database connection object.  If there has been a
938      notification, then a list of two elements will be returned.  The
939      first element contains the relation name being notified, the second
940      element contains the backend process ID number.  nil is returned
941      if there aren't any notifications to process.
942
943  - Function: PQsetenv conn
944      Synchronous transfer of environment variables to a backend CONN A
945      database connection object.
946
947      Environment variable transfer is done as a normal part of database
948      connection.
949
950      Compatibility note: This function was present but not documented
951      in versions of libpq prior to 7.0.
952
953 \1f
954 File: lispref.info,  Node: Asynchronous Interface Functions,  Next: Large Object Support,  Prev: Synchronous Interface Functions,  Up: XEmacs PostgreSQL libpq API
955
956 Asynchronous Interface Functions
957 --------------------------------
958
959 Making command by command examples is too complex with the asynchronous
960 interface functions.  See the examples section for complete calling
961 sequences.
962
963  - Function: pq-connect-start conninfo
964      Begin establishing an asynchronous database connection.  CONNINFO
965      A string containing the connection options.  See the documentation
966      of `pq-connectdb' for a listing of all the available flags.
967
968  - Function: pq-connect-poll conn
969      An intermediate function to be called during an asynchronous
970      database connection.  CONN A database connection object.  The
971      result codes are documented in a previous section.
972
973  - Function: pq-is-busy conn
974      Returns t if `pq-get-result' would block waiting for input.  CONN
975      A database connection object.
976
977  - Function: pq-consume-input conn
978      Consume any available input from the backend.  CONN A database
979      connection object.
980
981      Nil is returned if anything bad happens.
982
983  - Function: pq-reset-start conn
984      Reset connection to the backend asynchronously.  CONN A database
985      connection object.
986
987  - Function: pq-reset-poll conn
988      Poll an asynchronous reset for completion CONN A database
989      connection object.
990
991  - Function: pq-reset-cancel conn
992      Attempt to request cancellation of the current operation.  CONN A
993      database connection object.
994
995      The return value is t if the cancel request was successfully
996      dispatched, nil if not (in which case conn->errorMessage is set).
997      Note: successful dispatch is no guarantee that there will be any
998      effect at the backend.  The application must read the operation
999      result as usual.
1000
1001  - Function: pq-send-query conn query
1002      Submit a query to Postgres and don't wait for the result.  CONN A
1003      database connection object.  Returns: t if successfully submitted
1004             nil if error (conn->errorMessage is set)
1005
1006  - Function: pq-get-result conn
1007      Retrieve an asynchronous result from a query.  CONN A database
1008      connection object.
1009
1010      `nil' is returned when no more query work remains.
1011
1012  - Function: pq-set-nonblocking conn arg
1013      Sets the PGconn's database connection non-blocking if the arg is
1014      TRUE or makes it non-blocking if the arg is FALSE, this will not
1015      protect you from PQexec(), you'll only be safe when using the
1016      non-blocking API.  CONN A database connection object.
1017
1018  - Function: pq-is-nonblocking conn
1019      Return the blocking status of the database connection CONN A
1020      database connection object.
1021
1022  - Function: pq-flush conn
1023      Force the write buffer to be written (or at least try) CONN A
1024      database connection object.
1025
1026  - Function: PQsetenvStart conn
1027      Start asynchronously passing environment variables to a backend.
1028      CONN A database connection object.
1029
1030      Compatibility note: this function is only available with libpq-7.0.
1031
1032  - Function: PQsetenvPoll conn
1033      Check an asynchronous environment variables transfer for
1034      completion.  CONN A database connection object.
1035
1036      Compatibility note: this function is only available with libpq-7.0.
1037
1038  - Function: PQsetenvAbort conn
1039      Attempt to terminate an asynchronous environment variables
1040      transfer.  CONN A database connection object.
1041
1042      Compatibility note: this function is only available with libpq-7.0.
1043
1044 \1f
1045 File: lispref.info,  Node: Large Object Support,  Next: Other libpq Functions,  Prev: Asynchronous Interface Functions,  Up: XEmacs PostgreSQL libpq API
1046
1047 Large Object Support
1048 --------------------
1049
1050  - Function: pq-lo-import conn filename
1051      Import a file as a large object into the database.  CONN a
1052      database connection object FILENAME filename to import
1053
1054      On success, the object id is returned.
1055
1056  - Function: pq-lo-export conn oid filename
1057      Copy a large object in the database into a file.  CONN a database
1058      connection object.  OID object id number of a large object.
1059      FILENAME filename to export to.
1060
1061 \1f
1062 File: lispref.info,  Node: Other libpq Functions,  Next: Unimplemented libpq Functions,  Prev: Large Object Support,  Up: XEmacs PostgreSQL libpq API
1063
1064 Other libpq Functions
1065 ---------------------
1066
1067  - Function: pq-finish conn
1068      Destroy a database connection object by calling free on it.  CONN
1069      a database connection object
1070
1071      It is possible to not call this routine because the usual XEmacs
1072      garbage collection mechanism will call the underlying libpq
1073      routine whenever it is releasing stale `PGconn' objects.  However,
1074      this routine is useful in `unwind-protect' clauses to make
1075      connections go away quickly when unrecoverable errors have
1076      occurred.
1077
1078      After calling this routine, the printed representation of the
1079      XEmacs wrapper object will contain the string "DEAD".
1080
1081  - Function: pq-client-encoding conn
1082      Return the client encoding as an integer code.  CONN a database
1083      connection object
1084
1085           (pq-client-encoding P)
1086                => 1
1087
1088      Compatibility note: This function did not exist prior to libpq-7.0
1089      and does not exist in a non-Mule XEmacs.
1090
1091  - Function: pq-set-client-encoding conn encoding
1092      Set client coding system.  CONN a database connection object
1093      ENCODING a string representing the desired coding system
1094
1095           (pq-set-client-encoding P "EUC_JP")
1096                => 0
1097
1098      The current idiom for ensuring proper coding system conversion is
1099      the following (illustrated for EUC Japanese encoding):
1100           (setq P (pq-connectdb "..."))
1101           (let ((file-name-coding-system 'euc-jp)
1102                 (pg-coding-system 'euc-jp))
1103             (pq-set-client-encoding "EUC_JP")
1104             ...)
1105           (pq-finish P)
1106      Compatibility note: This function did not exist prior to libpq-7.0
1107      and does not exist in a non-Mule XEmacs.
1108
1109  - Function: pq-env-2-encoding
1110      Return the integer code representing the coding system in
1111      `PGCLIENTENCODING'.
1112
1113           (pq-env-2-encoding)
1114                => 0
1115      Compatibility note: This function did not exist prior to libpq-7.0
1116      and does not exist in a non-Mule XEmacs.
1117
1118  - Function: pq-clear res
1119      Destroy a query result object by calling free() on it.  RES a
1120      query result object
1121
1122      Note:  The memory allocation systems of libpq and XEmacs are
1123      different.  The XEmacs representation of a query result object
1124      will have both the XEmacs version and the libpq version freed at
1125      the next garbage collection when the object is no longer being
1126      referenced.  Calling this function does not release the XEmacs
1127      object, it is still subject to the usual rules for Lisp objects.
1128      The printed representation of the XEmacs object will contain the
1129      string "DEAD" after this routine is called indicating that it is no
1130      longer useful for anything.
1131
1132  - Function: pq-conn-defaults
1133      Return a data structure that represents the connection defaults.
1134      The data is returned as a list of lists, where each sublist
1135      contains info regarding a single option.
1136
1137 \1f
1138 File: lispref.info,  Node: Unimplemented libpq Functions,  Prev: Other libpq Functions,  Up: XEmacs PostgreSQL libpq API
1139
1140 Unimplemented libpq Functions
1141 -----------------------------
1142
1143  - Unimplemented Function: PGconn *PQsetdbLogin (char *pghost, char
1144           *pgport, char *pgoptions, char *pgtty, char *dbName, char
1145           *login, char *pwd)
1146      Synchronous database connection.  PGHOST is the hostname of the
1147      PostgreSQL backend to connect to.  PGPORT is the TCP port number
1148      to use.  PGOPTIONS specifies other backend options.  PGTTY
1149      specifies the debugging tty to use.  DBNAME specifies the database
1150      name to use.  LOGIN specifies the database user name.  PWD
1151      specifies the database user's password.
1152
1153      This routine is deprecated as of libpq-7.0, and its functionality
1154      can be replaced by external Lisp code if needed.
1155
1156  - Unimplemented Function: PGconn *PQsetdb (char *pghost, char *pgport,
1157           char *pgoptions, char *pgtty, char *dbName)
1158      Synchronous database connection.  PGHOST is the hostname of the
1159      PostgreSQL backend to connect to.  PGPORT is the TCP port number
1160      to use.  PGOPTIONS specifies other backend options.  PGTTY
1161      specifies the debugging tty to use.  DBNAME specifies the database
1162      name to use.
1163
1164      This routine was deprecated in libpq-6.5.
1165
1166  - Unimplemented Function: int PQsocket (PGconn *conn)
1167      Return socket file descriptor to a backend database process.  CONN
1168      database connection object.
1169
1170  - Unimplemented Function: void PQprint (FILE *fout, PGresult *res,
1171           PGprintOpt *ps)
1172      Print out the results of a query to a designated C stream.  FOUT C
1173      stream to print to RES the query result object to print PS the
1174      print options structure.
1175
1176      This routine is deprecated as of libpq-7.0 and cannot be sensibly
1177      exported to XEmacs Lisp.
1178
1179  - Unimplemented Function: void PQdisplayTuples (PGresult *res, FILE
1180           *fp, int fillAlign, char *fieldSep, int printHeader, int
1181           quiet)
1182      RES query result object to print FP C stream to print to FILLALIGN
1183      pad the fields with spaces FIELDSEP field separator PRINTHEADER
1184      display headers?  QUIET
1185
1186      This routine was deprecated in libpq-6.5.
1187
1188  - Unimplemented Function: void PQprintTuples (PGresult *res, FILE
1189           *fout, int printAttName, int terseOutput, int width)
1190      RES query result object to print FOUT C stream to print to
1191      PRINTATTNAME print attribute names TERSEOUTPUT delimiter bars
1192      WIDTH width of column, if 0, use variable width
1193
1194      This routine was deprecated in libpq-6.5.
1195
1196  - Unimplemented Function: int PQmblen (char *s, int encoding)
1197      Determine length of a multibyte encoded char at `*s'.  S encoded
1198      string ENCODING type of encoding
1199
1200      Compatibility note:  This function was introduced in libpq-7.0.
1201
1202  - Unimplemented Function: void PQtrace (PGconn *conn, FILE *debug_port)
1203      Enable tracing on `debug_port'.  CONN database connection object.
1204      DEBUG_PORT C output stream to use.
1205
1206  - Unimplemented Function: void PQuntrace (PGconn *conn)
1207      Disable tracing.  CONN database connection object.
1208
1209  - Unimplemented Function: char *PQoidStatus (PGconn *conn)
1210      Return the object id as a string of the last tuple inserted.  CONN
1211      database connection object.
1212
1213      Compatibility note: This function is deprecated in libpq-7.0,
1214      however it is used internally by the XEmacs binding code when
1215      linked against versions prior to 7.0.
1216
1217  - Unimplemented Function: PGresult *PQfn (PGconn *conn, int fnid, int
1218           *result_buf, int *result_len, int result_is_int, PQArgBlock
1219           *args, int nargs)
1220      "Fast path" interface -- not really recommended for application use
1221      CONN A database connection object.  FNID RESULT_BUF RESULT_LEN
1222      RESULT_IS_INT ARGS NARGS
1223
1224    The following set of very low level large object functions aren't
1225 appropriate to be exported to Lisp.
1226
1227  - Unimplemented Function: int pq-lo-open (PGconn *conn, int lobjid,
1228           int mode)
1229      CONN a database connection object.  LOBJID a large object ID.
1230      MODE opening modes.
1231
1232  - Unimplemented Function: int pq-lo-close (PGconn *conn, int fd)
1233      CONN a database connection object.  FD a large object file
1234      descriptor
1235
1236  - Unimplemented Function: int pq-lo-read (PGconn *conn, int fd, char
1237           *buf, int len)
1238      CONN a database connection object.  FD a large object file
1239      descriptor.  BUF buffer to read into.  LEN size of buffer.
1240
1241  - Unimplemented Function: int pq-lo-write (PGconn *conn, int fd, char
1242           *buf, size_t len)
1243      CONN a database connection object.  FD a large object file
1244      descriptor.  BUF buffer to write from.  LEN size of buffer.
1245
1246  - Unimplemented Function: int pq-lo-lseek (PGconn *conn, int fd, int
1247           offset, int whence)
1248      CONN a database connection object.  FD a large object file
1249      descriptor.  OFFSET WHENCE
1250
1251  - Unimplemented Function: int pq-lo-creat (PGconn *conn, int mode)
1252      CONN a database connection object.  MODE opening modes.
1253
1254  - Unimplemented Function: int pq-lo-tell (PGconn *conn, int fd)
1255      CONN a database connection object.  FD a large object file
1256      descriptor.
1257
1258  - Unimplemented Function: int pq-lo-unlink (PGconn *conn, int lobjid)
1259      CONN a database connection object.  LBOJID a large object ID.
1260
1261 \1f
1262 File: lispref.info,  Node: XEmacs PostgreSQL libpq Examples,  Prev: XEmacs PostgreSQL libpq API,  Up: PostgreSQL Support
1263
1264 XEmacs PostgreSQL libpq Examples
1265 ================================
1266
1267 This is an example of one method of establishing an asynchronous
1268 connection.
1269
1270      (defun database-poller (P)
1271        (message "%S before poll" (pq-pgconn P 'pq::status))
1272        (pq-connect-poll P)
1273        (message "%S after poll" (pq-pgconn P 'pq::status))
1274        (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
1275            (message "Done!")
1276          (add-timeout .1 'database-poller P)))
1277           => database-poller
1278      (progn
1279        (setq P (pq-connect-start ""))
1280        (add-timeout .1 'database-poller P))
1281           => pg::connection-started before poll
1282           => pg::connection-made after poll
1283           => pg::connection-made before poll
1284           => pg::connection-awaiting-response after poll
1285           => pg::connection-awaiting-response before poll
1286           => pg::connection-auth-ok after poll
1287           => pg::connection-auth-ok before poll
1288           => pg::connection-setenv after poll
1289           => pg::connection-setenv before poll
1290           => pg::connection-ok after poll
1291           => Done!
1292      P
1293           => #<PGconn localhost:25432 steve/steve>
1294
1295    Here is an example of one method of doing an asynchronous reset.
1296
1297      (defun database-poller (P)
1298        (let (PS)
1299          (message "%S before poll" (pq-pgconn P 'pq::status))
1300          (setq PS (pq-reset-poll P))
1301          (message "%S after poll [%S]" (pq-pgconn P 'pq::status) PS)
1302          (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
1303         (message "Done!")
1304            (add-timeout .1 'database-poller P))))
1305           => database-poller
1306      (progn
1307        (pq-reset-start P)
1308        (add-timeout .1 'database-poller P))
1309           => pg::connection-started before poll
1310           => pg::connection-made after poll [pgres::polling-writing]
1311           => pg::connection-made before poll
1312           => pg::connection-awaiting-response after poll [pgres::polling-reading]
1313           => pg::connection-awaiting-response before poll
1314           => pg::connection-setenv after poll [pgres::polling-reading]
1315           => pg::connection-setenv before poll
1316           => pg::connection-ok after poll [pgres::polling-ok]
1317           => Done!
1318      P
1319           => #<PGconn localhost:25432 steve/steve>
1320
1321    And finally, an asynchronous query.
1322
1323      (defun database-poller (P)
1324        (let (R)
1325          (pq-consume-input P)
1326          (if (pq-is-busy P)
1327         (add-timeout .1 'database-poller P)
1328            (setq R (pq-get-result P))
1329            (if R
1330           (progn
1331             (push R result-list)
1332             (add-timeout .1 'database-poller P))))))
1333           => database-poller
1334      (when (pq-send-query P "SELECT * FROM xemacs_test;")
1335        (setq result-list nil)
1336        (add-timeout .1 'database-poller P))
1337           => 885
1338      ;; wait a moment
1339      result-list
1340           => (#<PGresult PGRES_TUPLES_OK - SELECT>)
1341
1342    Here is an example showing how multiple SQL statements in a single
1343 query can have all their results collected.
1344      ;; Using the same `database-poller' function from the previous example
1345      (when (pq-send-query P "SELECT * FROM xemacs_test;
1346      SELECT * FROM pg_database;
1347      SELECT * FROM pg_user;")
1348        (setq result-list nil)
1349        (add-timeout .1 'database-poller P))
1350           => 1782
1351      ;; wait a moment
1352      result-list
1353           => (#<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT>)
1354
1355    Here is an example which illustrates collecting all data from a
1356 query, including the field names.
1357
1358      (defun pg-util-query-results (results)
1359        "Retrieve results of last SQL query into a list structure."
1360        (let ((i (1- (pq-ntuples R)))
1361         j l1 l2)
1362          (while (>= i 0)
1363            (setq j (1- (pq-nfields R)))
1364            (setq l2 nil)
1365            (while (>= j 0)
1366         (push (pq-get-value R i j) l2)
1367         (decf j))
1368            (push l2 l1)
1369            (decf i))
1370          (setq j (1- (pq-nfields R)))
1371          (setq l2 nil)
1372          (while (>= j 0)
1373            (push (pq-fname R j) l2)
1374            (decf j))
1375          (push l2 l1)
1376          l1))
1377           => pg-util-query-results
1378      (setq R (pq-exec P "SELECT * FROM xemacs_test ORDER BY field2 DESC;"))
1379           => #<PGresult PGRES_TUPLES_OK - SELECT>
1380      (pg-util-query-results R)
1381           => (("f1" "field2") ("a" "97") ("b" "97") ("stuff" "42") ("a string" "12") ("foo" "10") ("string" "2") ("text" "1"))
1382
1383    Here is an example of a query that uses a database cursor.
1384
1385      (let (data R)
1386        (setq R (pq-exec P "BEGIN;"))
1387        (setq R (pq-exec P "DECLARE k_cursor CURSOR FOR SELECT * FROM xemacs_test ORDER BY f1 DESC;"))
1388      
1389        (setq R (pq-exec P "FETCH k_cursor;"))
1390        (while (eq (pq-ntuples R) 1)
1391          (push (list (pq-get-value R 0 0) (pq-get-value R 0 1)) data)
1392          (setq R (pq-exec P "FETCH k_cursor;")))
1393        (setq R (pq-exec P "END;"))
1394        data)
1395           => (("a" "97") ("a string" "12") ("b" "97") ("foo" "10") ("string" "2") ("stuff" "42") ("text" "1"))
1396
1397    Here's another example of cursors, this time with a Lisp macro to
1398 implement a mapping function over a table.
1399
1400      (defmacro map-db (P table condition callout)
1401        `(let (R)
1402           (pq-exec ,P "BEGIN;")
1403           (pq-exec ,P (concat "DECLARE k_cursor CURSOR FOR SELECT * FROM "
1404                          ,table
1405                          " "
1406                          ,condition
1407                          " ORDER BY f1 DESC;"))
1408           (setq R (pq-exec P "FETCH k_cursor;"))
1409           (while (eq (pq-ntuples R) 1)
1410             (,callout (pq-get-value R 0 0) (pq-get-value R 0 1))
1411             (setq R (pq-exec P "FETCH k_cursor;")))
1412           (pq-exec P "END;")))
1413           => map-db
1414      (defun callback (arg1 arg2)
1415        (message "arg1 = %s, arg2 = %s" arg1 arg2))
1416           => callback
1417      (map-db P "xemacs_test" "WHERE field2 > 10" callback)
1418           => arg1 = stuff, arg2 = 42
1419           => arg1 = b, arg2 = 97
1420           => arg1 = a string, arg2 = 12
1421           => arg1 = a, arg2 = 97
1422           => #<PGresult PGRES_COMMAND_OK - COMMIT>
1423
1424 \1f
1425 File: lispref.info,  Node: Internationalization,  Next: MULE,  Prev: PostgreSQL Support,  Up: Top
1426
1427 Internationalization
1428 ********************
1429
1430 * Menu:
1431
1432 * I18N Levels 1 and 2:: Support for different time, date, and currency formats.
1433 * I18N Level 3::        Support for localized messages.
1434 * I18N Level 4::        Support for Asian languages.
1435
1436 \1f
1437 File: lispref.info,  Node: I18N Levels 1 and 2,  Next: I18N Level 3,  Up: Internationalization
1438
1439 I18N Levels 1 and 2
1440 ===================
1441
1442 XEmacs is now compliant with I18N levels 1 and 2.  Specifically, this
1443 means that it is 8-bit clean and correctly handles time and date
1444 functions.  XEmacs will correctly display the entire ISO-Latin 1
1445 character set.
1446
1447    The compose key may now be used to create any character in the
1448 ISO-Latin 1 character set not directly available via the keyboard..  In
1449 order for the compose key to work it is necessary to load the file
1450 `x-compose.el'.  At any time while composing a character, `C-h' will
1451 display all valid completions and the character which would be produced.
1452
1453 \1f
1454 File: lispref.info,  Node: I18N Level 3,  Next: I18N Level 4,  Prev: I18N Levels 1 and 2,  Up: Internationalization
1455
1456 I18N Level 3
1457 ============
1458
1459 * Menu:
1460
1461 * Level 3 Basics::
1462 * Level 3 Primitives::
1463 * Dynamic Messaging::
1464 * Domain Specification::
1465 * Documentation String Extraction::
1466
1467 \1f
1468 File: lispref.info,  Node: Level 3 Basics,  Next: Level 3 Primitives,  Up: I18N Level 3
1469
1470 Level 3 Basics
1471 --------------
1472
1473 XEmacs now provides alpha-level functionality for I18N Level 3.  This
1474 means that everything necessary for full messaging is available, but
1475 not every file has been converted.
1476
1477    The two message files which have been created are `src/emacs.po' and
1478 `lisp/packages/mh-e.po'.  Both files need to be converted using
1479 `msgfmt', and the resulting `.mo' files placed in some locale's
1480 `LC_MESSAGES' directory.  The test "translations" in these files are
1481 the original messages prefixed by `TRNSLT_'.
1482
1483    The domain for a variable is stored on the variable's property list
1484 under the property name VARIABLE-DOMAIN.  The function
1485 `documentation-property' uses this information when translating a
1486 variable's documentation.
1487
1488 \1f
1489 File: lispref.info,  Node: Level 3 Primitives,  Next: Dynamic Messaging,  Prev: Level 3 Basics,  Up: I18N Level 3
1490
1491 Level 3 Primitives
1492 ------------------
1493
1494  - Function: gettext string
1495      This function looks up STRING in the default message domain and
1496      returns its translation.  If `I18N3' was not enabled when XEmacs
1497      was compiled, it just returns STRING.
1498
1499  - Function: dgettext domain string
1500      This function looks up STRING in the specified message domain and
1501      returns its translation.  If `I18N3' was not enabled when XEmacs
1502      was compiled, it just returns STRING.
1503
1504  - Function: bind-text-domain domain pathname
1505      This function associates a pathname with a message domain.  Here's
1506      how the path to message file is constructed under SunOS 5.x:
1507
1508           `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo'
1509
1510      If `I18N3' was not enabled when XEmacs was compiled, this function
1511      does nothing.
1512
1513  - Special Form: domain string
1514      This function specifies the text domain used for translating
1515      documentation strings and interactive prompts of a function.  For
1516      example, write:
1517
1518           (defun foo (arg) "Doc string" (domain "emacs-foo") ...)
1519
1520      to specify `emacs-foo' as the text domain of the function `foo'.
1521      The "call" to `domain' is actually a declaration rather than a
1522      function; when actually called, `domain' just returns `nil'.
1523
1524  - Function: domain-of function
1525      This function returns the text domain of FUNCTION; it returns
1526      `nil' if it is the default domain.  If `I18N3' was not enabled
1527      when XEmacs was compiled, it always returns `nil'.
1528
1529 \1f
1530 File: lispref.info,  Node: Dynamic Messaging,  Next: Domain Specification,  Prev: Level 3 Primitives,  Up: I18N Level 3
1531
1532 Dynamic Messaging
1533 -----------------
1534
1535 The `format' function has been extended to permit you to change the
1536 order of parameter insertion.  For example, the conversion format
1537 `%1$s' inserts parameter one as a string, while `%2$s' inserts
1538 parameter two.  This is useful when creating translations which require
1539 you to change the word order.
1540
1541 \1f
1542 File: lispref.info,  Node: Domain Specification,  Next: Documentation String Extraction,  Prev: Dynamic Messaging,  Up: I18N Level 3
1543
1544 Domain Specification
1545 --------------------
1546
1547 The default message domain of XEmacs is `emacs'.  For add-on packages,
1548 it is best to use a different domain.  For example, let us say we want
1549 to convert the "gorilla" package to use the domain `emacs-gorilla'.  To
1550 translate the message "What gorilla?", use `dgettext' as follows:
1551
1552      (dgettext "emacs-gorilla" "What gorilla?")
1553
1554    A function (or macro) which has a documentation string or an
1555 interactive prompt needs to be associated with the domain in order for
1556 the documentation or prompt to be translated.  This is done with the
1557 `domain' special form as follows:
1558
1559      (defun scratch (location)
1560        "Scratch the specified location."
1561        (domain "emacs-gorilla")
1562        (interactive "sScratch: ")
1563        ... )
1564
1565    It is most efficient to specify the domain in the first line of the
1566 function body, before the `interactive' form.
1567
1568    For variables and constants which have documentation strings,
1569 specify the domain after the documentation.
1570
1571  - Special Form: defvar symbol [value [doc-string [domain]]]
1572      Example:
1573           (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")
1574
1575  - Special Form: defconst symbol [value [doc-string [domain]]]
1576      Example:
1577           (defconst limbs 4 "Number of limbs" "emacs-gorilla")
1578
1579  - Function: autoload function filename &optional docstring interactive
1580           type
1581      This function defines FUNCTION to autoload from FILENAME Example:
1582           (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
1583
1584 \1f
1585 File: lispref.info,  Node: Documentation String Extraction,  Prev: Domain Specification,  Up: I18N Level 3
1586
1587 Documentation String Extraction
1588 -------------------------------
1589
1590 The utility `etc/make-po' scans the file `DOC' to extract documentation
1591 strings and creates a message file `doc.po'.  This file may then be
1592 inserted within `emacs.po'.
1593
1594    Currently, `make-po' is hard-coded to read from `DOC' and write to
1595 `doc.po'.  In order to extract documentation strings from an add-on
1596 package, first run `make-docfile' on the package to produce the `DOC'
1597 file.  Then run `make-po -p' with the `-p' argument to indicate that we
1598 are extracting documentation for an add-on package.
1599
1600    (The `-p' argument is a kludge to make up for a subtle difference
1601 between pre-loaded documentation and add-on documentation:  For add-on
1602 packages, the final carriage returns in the strings produced by
1603 `make-docfile' must be ignored.)
1604
1605 \1f
1606 File: lispref.info,  Node: I18N Level 4,  Prev: I18N Level 3,  Up: Internationalization
1607
1608 I18N Level 4
1609 ============
1610
1611 The Asian-language support in XEmacs is called "MULE".  *Note MULE::.
1612
1613 \1f
1614 File: lispref.info,  Node: MULE,  Next: Tips,  Prev: Internationalization,  Up: Top
1615
1616 MULE
1617 ****
1618
1619 "MULE" is the name originally given to the version of GNU Emacs
1620 extended for multi-lingual (and in particular Asian-language) support.
1621 "MULE" is short for "MUlti-Lingual Emacs".  It is an extension and
1622 complete rewrite of Nemacs ("Nihon Emacs" where "Nihon" is the Japanese
1623 word for "Japan"), which only provided support for Japanese.  XEmacs
1624 refers to its multi-lingual support as "MULE support" since it is based
1625 on "MULE".
1626
1627 * Menu:
1628
1629 * Internationalization Terminology::
1630                         Definition of various internationalization terms.
1631 * Charsets::            Sets of related characters.
1632 * MULE Characters::     Working with characters in XEmacs/MULE.
1633 * Composite Characters:: Making new characters by overstriking other ones.
1634 * Coding Systems::      Ways of representing a string of chars using integers.
1635 * CCL::                 A special language for writing fast converters.
1636 * Category Tables::     Subdividing charsets into groups.
1637
1638 \1f
1639 File: lispref.info,  Node: Internationalization Terminology,  Next: Charsets,  Up: MULE
1640
1641 Internationalization Terminology
1642 ================================
1643
1644 In internationalization terminology, a string of text is divided up
1645 into "characters", which are the printable units that make up the text.
1646 A single character is (for example) a capital `A', the number `2', a
1647 Katakana character, a Hangul character, a Kanji ideograph (an
1648 "ideograph" is a "picture" character, such as is used in Japanese
1649 Kanji, Chinese Hanzi, and Korean Hanja; typically there are thousands
1650 of such ideographs in each language), etc.  The basic property of a
1651 character is that it is the smallest unit of text with semantic
1652 significance in text processing.
1653
1654    Human beings normally process text visually, so to a first
1655 approximation a character may be identified with its shape.  Note that
1656 the same character may be drawn by two different people (or in two
1657 different fonts) in slightly different ways, although the "basic shape"
1658 will be the same.  But consider the works of Scott Kim; human beings
1659 can recognize hugely variant shapes as the "same" character.
1660 Sometimes, especially where characters are extremely complicated to
1661 write, completely different shapes may be defined as the "same"
1662 character in national standards.  The Taiwanese variant of Hanzi is
1663 generally the most complicated; over the centuries, the Japanese,
1664 Koreans, and the People's Republic of China have adopted
1665 simplifications of the shape, but the line of descent from the original
1666 shape is recorded, and the meanings and pronunciation of different
1667 forms of the same character are considered to be identical within each
1668 language.  (Of course, it may take a specialist to recognize the
1669 related form; the point is that the relations are standardized, despite
1670 the differing shapes.)
1671
1672    In some cases, the differences will be significant enough that it is
1673 actually possible to identify two or more distinct shapes that both
1674 represent the same character.  For example, the lowercase letters `a'
1675 and `g' each have two distinct possible shapes--the `a' can optionally
1676 have a curved tail projecting off the top, and the `g' can be formed
1677 either of two loops, or of one loop and a tail hanging off the bottom.
1678 Such distinct possible shapes of a character are called "glyphs".  The
1679 important characteristic of two glyphs making up the same character is
1680 that the choice between one or the other is purely stylistic and has no
1681 linguistic effect on a word (this is the reason why a capital `A' and
1682 lowercase `a' are different characters rather than different
1683 glyphs--e.g.  `Aspen' is a city while `aspen' is a kind of tree).
1684
1685    Note that "character" and "glyph" are used differently here than
1686 elsewhere in XEmacs.
1687
1688    A "character set" is essentially a set of related characters.  ASCII,
1689 for example, is a set of 94 characters (or 128, if you count
1690 non-printing characters).  Other character sets are ISO8859-1 (ASCII
1691 plus various accented characters and other international symbols), JIS
1692 X 0201 (ASCII, more or less, plus half-width Katakana), JIS X 0208
1693 (Japanese Kanji), JIS X 0212 (a second set of less-used Japanese Kanji),
1694 GB2312 (Mainland Chinese Hanzi), etc.
1695
1696    The definition of a character set will implicitly or explicitly give
1697 it an "ordering", a way of assigning a number to each character in the
1698 set.  For many character sets, there is a natural ordering, for example
1699 the "ABC" ordering of the Roman letters.  But it is not clear whether
1700 digits should come before or after the letters, and in fact different
1701 European languages treat the ordering of accented characters
1702 differently.  It is useful to use the natural order where available, of
1703 course.  The number assigned to any particular character is called the
1704 character's "code point".  (Within a given character set, each
1705 character has a unique code point.  Thus the word "set" is ill-chosen;
1706 different orderings of the same characters are different character sets.
1707 Identifying characters is simple enough for alphabetic character sets,
1708 but the difference in ordering can cause great headaches when the same
1709 thousands of characters are used by different cultures as in the Hanzi.)
1710
1711    A code point may be broken into a number of "position codes".  The
1712 number of position codes required to index a particular character in a
1713 character set is called the "dimension" of the character set.  For
1714 practical purposes, a position code may be thought of as a byte-sized
1715 index.  The printing characters of ASCII, being a relatively small
1716 character set, is of dimension one, and each character in the set is
1717 indexed using a single position code, in the range 1 through 94.  Use of
1718 this unusual range, rather than the familiar 33 through 126, is an
1719 intentional abstraction; to understand the programming issues you must
1720 break the equation between character sets and encodings.
1721
1722    JIS X 0208, i.e. Japanese Kanji, has thousands of characters, and is
1723 of dimension two - every character is indexed by two position codes,
1724 each in the range 1 through 94.  (This number "94" is not a
1725 coincidence; we shall see that the JIS position codes were chosen so
1726 that JIS kanji could be encoded without using codes that in ASCII are
1727 associated with device control functions.)  Note that the choice of the
1728 range here is somewhat arbitrary.  You could just as easily index the
1729 printing characters in ASCII using numbers in the range 0 through 93, 2
1730 through 95, 3 through 96, etc.  In fact, the standardized _encoding_
1731 for the ASCII _character set_ uses the range 33 through 126.
1732
1733    An "encoding" is a way of numerically representing characters from
1734 one or more character sets into a stream of like-sized numerical values
1735 called "words"; typically these are 8-bit, 16-bit, or 32-bit
1736 quantities.  If an encoding encompasses only one character set, then the
1737 position codes for the characters in that character set could be used
1738 directly.  (This is the case with the trivial cipher used by children,
1739 assigning 1 to `A', 2 to `B', and so on.)  However, even with ASCII,
1740 other considerations intrude.  For example, why are the upper- and
1741 lowercase alphabets separated by 8 characters?  Why do the digits start
1742 with `0' being assigned the code 48?  In both cases because semantically
1743 interesting operations (case conversion and numerical value extraction)
1744 become convenient masking operations.  Other artificial aspects (the
1745 control characters being assigned to codes 0-31 and 127) are historical
1746 accidents.  (The use of 127 for `DEL' is an artifact of the "punch
1747 once" nature of paper tape, for example.)
1748
1749    Naive use of the position code is not possible, however, if more than
1750 one character set is to be used in the encoding.  For example, printed
1751 Japanese text typically requires characters from multiple character sets
1752 - ASCII, JIS X 0208, and JIS X 0212, to be specific.  Each of these is
1753 indexed using one or more position codes in the range 1 through 94, so
1754 the position codes could not be used directly or there would be no way
1755 to tell which character was meant.  Different Japanese encodings handle
1756 this differently - JIS uses special escape characters to denote
1757 different character sets; EUC sets the high bit of the position codes
1758 for JIS X 0208 and JIS X 0212, and puts a special extra byte before each
1759 JIS X 0212 character; etc.  (JIS, EUC, and most of the other encodings
1760 you will encounter in files are 7-bit or 8-bit encodings.  There is one
1761 common 16-bit encoding, which is Unicode; this strives to represent all
1762 the world's characters in a single large character set.  32-bit
1763 encodings are often used internally in programs, such as XEmacs with
1764 MULE support, to simplify the code that manipulates them; however, they
1765 are not used externally because they are not very space-efficient.)
1766
1767    A general method of handling text using multiple character sets
1768 (whether for multilingual text, or simply text in an extremely
1769 complicated single language like Japanese) is defined in the
1770 international standard ISO 2022.  ISO 2022 will be discussed in more
1771 detail later (*note ISO 2022::), but for now suffice it to say that text
1772 needs control functions (at least spacing), and if escape sequences are
1773 to be used, an escape sequence introducer.  It was decided to make all
1774 text streams compatible with ASCII in the sense that the codes 0-31
1775 (and 128-159) would always be control codes, never graphic characters,
1776 and where defined by the character set the `SPC' character would be
1777 assigned code 32, and `DEL' would be assigned 127.  Thus there are 94
1778 code points remaining if 7 bits are used.  This is the reason that most
1779 character sets are defined using position codes in the range 1 through
1780 94.  Then ISO 2022 compatible encodings are produced by shifting the
1781 position codes 1 to 94 into character codes 33 to 126, or (if 8 bit
1782 codes are available) into character codes 161 to 254.
1783
1784    Encodings are classified as either "modal" or "non-modal".  In a
1785 "modal encoding", there are multiple states that the encoding can be
1786 in, and the interpretation of the values in the stream depends on the
1787 current global state of the encoding.  Special values in the encoding,
1788 called "escape sequences", are used to change the global state.  JIS,
1789 for example, is a modal encoding.  The bytes `ESC $ B' indicate that,
1790 from then on, bytes are to be interpreted as position codes for JIS X
1791 0208, rather than as ASCII.  This effect is cancelled using the bytes
1792 `ESC ( B', which mean "switch from whatever the current state is to
1793 ASCII".  To switch to JIS X 0212, the escape sequence `ESC $ ( D'.
1794 (Note that here, as is common, the escape sequences do in fact begin
1795 with `ESC'.  This is not necessarily the case, however.  Some encodings
1796 use control characters called "locking shifts" (effect persists until
1797 cancelled) to switch character sets.)
1798
1799    A "non-modal encoding" has no global state that extends past the
1800 character currently being interpreted.  EUC, for example, is a
1801 non-modal encoding.  Characters in JIS X 0208 are encoded by setting
1802 the high bit of the position codes, and characters in JIS X 0212 are
1803 encoded by doing the same but also prefixing the character with the
1804 byte 0x8F.
1805
1806    The advantage of a modal encoding is that it is generally more
1807 space-efficient, and is easily extendible because there are essentially
1808 an arbitrary number of escape sequences that can be created.  The
1809 disadvantage, however, is that it is much more difficult to work with
1810 if it is not being processed in a sequential manner.  In the non-modal
1811 EUC encoding, for example, the byte 0x41 always refers to the letter
1812 `A'; whereas in JIS, it could either be the letter `A', or one of the
1813 two position codes in a JIS X 0208 character, or one of the two
1814 position codes in a JIS X 0212 character.  Determining exactly which
1815 one is meant could be difficult and time-consuming if the previous
1816 bytes in the string have not already been processed, or impossible if
1817 they are drawn from an external stream that cannot be rewound.
1818
1819    Non-modal encodings are further divided into "fixed-width" and
1820 "variable-width" formats.  A fixed-width encoding always uses the same
1821 number of words per character, whereas a variable-width encoding does
1822 not.  EUC is a good example of a variable-width encoding: one to three
1823 bytes are used per character, depending on the character set.  16-bit
1824 and 32-bit encodings are nearly always fixed-width, and this is in fact
1825 one of the main reasons for using an encoding with a larger word size.
1826 The advantages of fixed-width encodings should be obvious.  The
1827 advantages of variable-width encodings are that they are generally more
1828 space-efficient and allow for compatibility with existing 8-bit
1829 encodings such as ASCII.  (For example, in Unicode ASCII characters are
1830 simply promoted to a 16-bit representation.  That means that every
1831 ASCII character contains a `NUL' byte; evidently all of the standard
1832 string manipulation functions will lose badly in a fixed-width Unicode
1833 environment.)
1834
1835    The bytes in an 8-bit encoding are often referred to as "octets"
1836 rather than simply as bytes.  This terminology dates back to the days
1837 before 8-bit bytes were universal, when some computers had 9-bit bytes,
1838 others had 10-bit bytes, etc.
1839
1840 \1f
1841 File: lispref.info,  Node: Charsets,  Next: MULE Characters,  Prev: Internationalization Terminology,  Up: MULE
1842
1843 Charsets
1844 ========
1845
1846 A "charset" in MULE is an object that encapsulates a particular
1847 character set as well as an ordering of those characters.  Charsets are
1848 permanent objects and are named using symbols, like faces.
1849
1850  - Function: charsetp object
1851      This function returns non-`nil' if OBJECT is a charset.
1852
1853 * Menu:
1854
1855 * Charset Properties::          Properties of a charset.
1856 * Basic Charset Functions::     Functions for working with charsets.
1857 * Charset Property Functions::  Functions for accessing charset properties.
1858 * Predefined Charsets::         Predefined charset objects.
1859
1860 \1f
1861 File: lispref.info,  Node: Charset Properties,  Next: Basic Charset Functions,  Up: Charsets
1862
1863 Charset Properties
1864 ------------------
1865
1866 Charsets have the following properties:
1867
1868 `name'
1869      A symbol naming the charset.  Every charset must have a different
1870      name; this allows a charset to be referred to using its name
1871      rather than the actual charset object.
1872
1873 `doc-string'
1874      A documentation string describing the charset.
1875
1876 `registry'
1877      A regular expression matching the font registry field for this
1878      character set.  For example, both the `ascii' and `latin-iso8859-1'
1879      charsets use the registry `"ISO8859-1"'.  This field is used to
1880      choose an appropriate font when the user gives a general font
1881      specification such as `-*-courier-medium-r-*-140-*', i.e. a
1882      14-point upright medium-weight Courier font.
1883
1884 `dimension'
1885      Number of position codes used to index a character in the
1886      character set.  XEmacs/MULE can only handle character sets of
1887      dimension 1 or 2.  This property defaults to 1.
1888
1889 `chars'
1890      Number of characters in each dimension.  In XEmacs/MULE, the only
1891      allowed values are 94 or 96. (There are a couple of pre-defined
1892      character sets, such as ASCII, that do not follow this, but you
1893      cannot define new ones like this.) Defaults to 94.  Note that if
1894      the dimension is 2, the character set thus described is 94x94 or
1895      96x96.
1896
1897 `columns'
1898      Number of columns used to display a character in this charset.
1899      Only used in TTY mode. (Under X, the actual width of a character
1900      can be derived from the font used to display the characters.)  If
1901      unspecified, defaults to the dimension. (This is almost always the
1902      correct value, because character sets with dimension 2 are usually
1903      ideograph character sets, which need two columns to display the
1904      intricate ideographs.)
1905
1906 `direction'
1907      A symbol, either `l2r' (left-to-right) or `r2l' (right-to-left).
1908      Defaults to `l2r'.  This specifies the direction that the text
1909      should be displayed in, and will be left-to-right for most
1910      charsets but right-to-left for Hebrew and Arabic. (Right-to-left
1911      display is not currently implemented.)
1912
1913 `final'
1914      Final byte of the standard ISO 2022 escape sequence designating
1915      this charset.  Must be supplied.  Each combination of (DIMENSION,
1916      CHARS) defines a separate namespace for final bytes, and each
1917      charset within a particular namespace must have a different final
1918      byte.  Note that ISO 2022 restricts the final byte to the range
1919      0x30 - 0x7E if dimension == 1, and 0x30 - 0x5F if dimension == 2.
1920      Note also that final bytes in the range 0x30 - 0x3F are reserved
1921      for user-defined (not official) character sets.  For more
1922      information on ISO 2022, see *Note Coding Systems::.
1923
1924 `graphic'
1925      0 (use left half of font on output) or 1 (use right half of font on
1926      output).  Defaults to 0.  This specifies how to convert the
1927      position codes that index a character in a character set into an
1928      index into the font used to display the character set.  With
1929      `graphic' set to 0, position codes 33 through 126 map to font
1930      indices 33 through 126; with it set to 1, position codes 33
1931      through 126 map to font indices 161 through 254 (i.e. the same
1932      number but with the high bit set).  For example, for a font whose
1933      registry is ISO8859-1, the left half of the font (octets 0x20 -
1934      0x7F) is the `ascii' charset, while the right half (octets 0xA0 -
1935      0xFF) is the `latin-iso8859-1' charset.
1936
1937 `ccl-program'
1938      A compiled CCL program used to convert a character in this charset
1939      into an index into the font.  This is in addition to the `graphic'
1940      property.  If a CCL program is defined, the position codes of a
1941      character will first be processed according to `graphic' and then
1942      passed through the CCL program, with the resulting values used to
1943      index the font.
1944
1945      This is used, for example, in the Big5 character set (used in
1946      Taiwan).  This character set is not ISO-2022-compliant, and its
1947      size (94x157) does not fit within the maximum 96x96 size of
1948      ISO-2022-compliant character sets.  As a result, XEmacs/MULE
1949      splits it (in a rather complex fashion, so as to group the most
1950      commonly used characters together) into two charset objects
1951      (`big5-1' and `big5-2'), each of size 94x94, and each charset
1952      object uses a CCL program to convert the modified position codes
1953      back into standard Big5 indices to retrieve a character from a
1954      Big5 font.
1955
1956    Most of the above properties can only be set when the charset is
1957 initialized, and cannot be changed later.  *Note Charset Property
1958 Functions::.
1959
1960 \1f
1961 File: lispref.info,  Node: Basic Charset Functions,  Next: Charset Property Functions,  Prev: Charset Properties,  Up: Charsets
1962
1963 Basic Charset Functions
1964 -----------------------
1965
1966  - Function: find-charset charset-or-name
1967      This function retrieves the charset of the given name.  If
1968      CHARSET-OR-NAME is a charset object, it is simply returned.
1969      Otherwise, CHARSET-OR-NAME should be a symbol.  If there is no
1970      such charset, `nil' is returned.  Otherwise the associated charset
1971      object is returned.
1972
1973  - Function: get-charset name
1974      This function retrieves the charset of the given name.  Same as
1975      `find-charset' except an error is signalled if there is no such
1976      charset instead of returning `nil'.
1977
1978  - Function: charset-list
1979      This function returns a list of the names of all defined charsets.
1980
1981  - Function: make-charset name doc-string props
1982      This function defines a new character set.  This function is for
1983      use with MULE support.  NAME is a symbol, the name by which the
1984      character set is normally referred.  DOC-STRING is a string
1985      describing the character set.  PROPS is a property list,
1986      describing the specific nature of the character set.  The
1987      recognized properties are `registry', `dimension', `columns',
1988      `chars', `final', `graphic', `direction', and `ccl-program', as
1989      previously described.
1990
1991  - Function: make-reverse-direction-charset charset new-name
1992      This function makes a charset equivalent to CHARSET but which goes
1993      in the opposite direction.  NEW-NAME is the name of the new
1994      charset.  The new charset is returned.
1995
1996  - Function: charset-from-attributes dimension chars final &optional
1997           direction
1998      This function returns a charset with the given DIMENSION, CHARS,
1999      FINAL, and DIRECTION.  If DIRECTION is omitted, both directions
2000      will be checked (left-to-right will be returned if character sets
2001      exist for both directions).
2002
2003  - Function: charset-reverse-direction-charset charset
2004      This function returns the charset (if any) with the same dimension,
2005      number of characters, and final byte as CHARSET, but which is
2006      displayed in the opposite direction.
2007
2008 \1f
2009 File: lispref.info,  Node: Charset Property Functions,  Next: Predefined Charsets,  Prev: Basic Charset Functions,  Up: Charsets
2010
2011 Charset Property Functions
2012 --------------------------
2013
2014 All of these functions accept either a charset name or charset object.
2015
2016  - Function: charset-property charset prop
2017      This function returns property PROP of CHARSET.  *Note Charset
2018      Properties::.
2019
2020    Convenience functions are also provided for retrieving individual
2021 properties of a charset.
2022
2023  - Function: charset-name charset
2024      This function returns the name of CHARSET.  This will be a symbol.
2025
2026  - Function: charset-description charset
2027      This function returns the documentation string of CHARSET.
2028
2029  - Function: charset-registry charset
2030      This function returns the registry of CHARSET.
2031
2032  - Function: charset-dimension charset
2033      This function returns the dimension of CHARSET.
2034
2035  - Function: charset-chars charset
2036      This function returns the number of characters per dimension of
2037      CHARSET.
2038
2039  - Function: charset-width charset
2040      This function returns the number of display columns per character
2041      (in TTY mode) of CHARSET.
2042
2043  - Function: charset-direction charset
2044      This function returns the display direction of CHARSET--either
2045      `l2r' or `r2l'.
2046
2047  - Function: charset-iso-final-char charset
2048      This function returns the final byte of the ISO 2022 escape
2049      sequence designating CHARSET.
2050
2051  - Function: charset-iso-graphic-plane charset
2052      This function returns either 0 or 1, depending on whether the
2053      position codes of characters in CHARSET map to the left or right
2054      half of their font, respectively.
2055
2056  - Function: charset-ccl-program charset
2057      This function returns the CCL program, if any, for converting
2058      position codes of characters in CHARSET into font indices.
2059
2060    The two properties of a charset that can currently be set after the
2061 charset has been created are the CCL program and the font registry.
2062
2063  - Function: set-charset-ccl-program charset ccl-program
2064      This function sets the `ccl-program' property of CHARSET to
2065      CCL-PROGRAM.
2066
2067  - Function: set-charset-registry charset registry
2068      This function sets the `registry' property of CHARSET to REGISTRY.
2069
2070 \1f
2071 File: lispref.info,  Node: Predefined Charsets,  Prev: Charset Property Functions,  Up: Charsets
2072
2073 Predefined Charsets
2074 -------------------
2075
2076 The following charsets are predefined in the C code.
2077
2078      Name                    Type  Fi Gr Dir Registry
2079      --------------------------------------------------------------
2080      ascii                    94    B  0  l2r ISO8859-1
2081      control-1                94       0  l2r ---
2082      latin-iso8859-1          94    A  1  l2r ISO8859-1
2083      latin-iso8859-2          96    B  1  l2r ISO8859-2
2084      latin-iso8859-3          96    C  1  l2r ISO8859-3
2085      latin-iso8859-4          96    D  1  l2r ISO8859-4
2086      cyrillic-iso8859-5       96    L  1  l2r ISO8859-5
2087      arabic-iso8859-6         96    G  1  r2l ISO8859-6
2088      greek-iso8859-7          96    F  1  l2r ISO8859-7
2089      hebrew-iso8859-8         96    H  1  r2l ISO8859-8
2090      latin-iso8859-9          96    M  1  l2r ISO8859-9
2091      thai-tis620              96    T  1  l2r TIS620
2092      katakana-jisx0201        94    I  1  l2r JISX0201.1976
2093      latin-jisx0201           94    J  0  l2r JISX0201.1976
2094      japanese-jisx0208-1978   94x94 @  0  l2r JISX0208.1978
2095      japanese-jisx0208        94x94 B  0  l2r JISX0208.19(83|90)
2096      japanese-jisx0212        94x94 D  0  l2r JISX0212
2097      chinese-gb2312           94x94 A  0  l2r GB2312
2098      chinese-cns11643-1       94x94 G  0  l2r CNS11643.1
2099      chinese-cns11643-2       94x94 H  0  l2r CNS11643.2
2100      chinese-big5-1           94x94 0  0  l2r Big5
2101      chinese-big5-2           94x94 1  0  l2r Big5
2102      korean-ksc5601           94x94 C  0  l2r KSC5601
2103      composite                96x96    0  l2r ---
2104
2105    The following charsets are predefined in the Lisp code.
2106
2107      Name                     Type  Fi Gr Dir Registry
2108      --------------------------------------------------------------
2109      arabic-digit             94    2  0  l2r MuleArabic-0
2110      arabic-1-column          94    3  0  r2l MuleArabic-1
2111      arabic-2-column          94    4  0  r2l MuleArabic-2
2112      sisheng                  94    0  0  l2r sisheng_cwnn\|OMRON_UDC_ZH
2113      chinese-cns11643-3       94x94 I  0  l2r CNS11643.1
2114      chinese-cns11643-4       94x94 J  0  l2r CNS11643.1
2115      chinese-cns11643-5       94x94 K  0  l2r CNS11643.1
2116      chinese-cns11643-6       94x94 L  0  l2r CNS11643.1
2117      chinese-cns11643-7       94x94 M  0  l2r CNS11643.1
2118      ethiopic                 94x94 2  0  l2r Ethio
2119      ascii-r2l                94    B  0  r2l ISO8859-1
2120      ipa                      96    0  1  l2r MuleIPA
2121      vietnamese-viscii-lower  96    1  1  l2r VISCII1.1
2122      vietnamese-viscii-upper  96    2  1  l2r VISCII1.1
2123
2124    For all of the above charsets, the dimension and number of columns
2125 are the same.
2126
2127    Note that ASCII, Control-1, and Composite are handled specially.
2128 This is why some of the fields are blank; and some of the filled-in
2129 fields (e.g. the type) are not really accurate.
2130
2131 \1f
2132 File: lispref.info,  Node: MULE Characters,  Next: Composite Characters,  Prev: Charsets,  Up: MULE
2133
2134 MULE Characters
2135 ===============
2136
2137  - Function: make-char charset arg1 &optional arg2
2138      This function makes a multi-byte character from CHARSET and octets
2139      ARG1 and ARG2.
2140
2141  - Function: char-charset character
2142      This function returns the character set of char CHARACTER.
2143
2144  - Function: char-octet character &optional n
2145      This function returns the octet (i.e. position code) numbered N
2146      (should be 0 or 1) of char CHARACTER.  N defaults to 0 if omitted.
2147
2148  - Function: find-charset-region start end &optional buffer
2149      This function returns a list of the charsets in the region between
2150      START and END.  BUFFER defaults to the current buffer if omitted.
2151
2152  - Function: find-charset-string string
2153      This function returns a list of the charsets in STRING.
2154
2155 \1f
2156 File: lispref.info,  Node: Composite Characters,  Next: Coding Systems,  Prev: MULE Characters,  Up: MULE
2157
2158 Composite Characters
2159 ====================
2160
2161 Composite characters are not yet completely implemented.
2162
2163  - Function: make-composite-char string
2164      This function converts a string into a single composite character.
2165      The character is the result of overstriking all the characters in
2166      the string.
2167
2168  - Function: composite-char-string character
2169      This function returns a string of the characters comprising a
2170      composite character.
2171
2172  - Function: compose-region start end &optional buffer
2173      This function composes the characters in the region from START to
2174      END in BUFFER into one composite character.  The composite
2175      character replaces the composed characters.  BUFFER defaults to
2176      the current buffer if omitted.
2177
2178  - Function: decompose-region start end &optional buffer
2179      This function decomposes any composite characters in the region
2180      from START to END in BUFFER.  This converts each composite
2181      character into one or more characters, the individual characters
2182      out of which the composite character was formed.  Non-composite
2183      characters are left as-is.  BUFFER defaults to the current buffer
2184      if omitted.
2185
2186 \1f
2187 File: lispref.info,  Node: Coding Systems,  Next: CCL,  Prev: Composite Characters,  Up: MULE
2188
2189 Coding Systems
2190 ==============
2191
2192 A coding system is an object that defines how text containing multiple
2193 character sets is encoded into a stream of (typically 8-bit) bytes.  The
2194 coding system is used to decode the stream into a series of characters
2195 (which may be from multiple charsets) when the text is read from a file
2196 or process, and is used to encode the text back into the same format
2197 when it is written out to a file or process.
2198
2199    For example, many ISO-2022-compliant coding systems (such as Compound
2200 Text, which is used for inter-client data under the X Window System) use
2201 escape sequences to switch between different charsets - Japanese Kanji,
2202 for example, is invoked with `ESC $ ( B'; ASCII is invoked with `ESC (
2203 B'; and Cyrillic is invoked with `ESC - L'.  See `make-coding-system'
2204 for more information.
2205
2206    Coding systems are normally identified using a symbol, and the
2207 symbol is accepted in place of the actual coding system object whenever
2208 a coding system is called for. (This is similar to how faces and
2209 charsets work.)
2210
2211  - Function: coding-system-p object
2212      This function returns non-`nil' if OBJECT is a coding system.
2213
2214 * Menu:
2215
2216 * Coding System Types::               Classifying coding systems.
2217 * ISO 2022::                          An international standard for
2218                                         charsets and encodings.
2219 * EOL Conversion::                    Dealing with different ways of denoting
2220                                         the end of a line.
2221 * Coding System Properties::          Properties of a coding system.
2222 * Basic Coding System Functions::     Working with coding systems.
2223 * Coding System Property Functions::  Retrieving a coding system's properties.
2224 * Encoding and Decoding Text::        Encoding and decoding text.
2225 * Detection of Textual Encoding::     Determining how text is encoded.
2226 * Big5 and Shift-JIS Functions::      Special functions for these non-standard
2227                                         encodings.
2228 * Predefined Coding Systems::         Coding systems implemented by MULE.
2229
2230 \1f
2231 File: lispref.info,  Node: Coding System Types,  Next: ISO 2022,  Up: Coding Systems
2232
2233 Coding System Types
2234 -------------------
2235
2236 The coding system type determines the basic algorithm XEmacs will use to
2237 decode or encode a data stream.  Character encodings will be converted
2238 to the MULE encoding, escape sequences processed, and newline sequences
2239 converted to XEmacs's internal representation.  There are three basic
2240 classes of coding system type: no-conversion, ISO-2022, and special.
2241
2242    No conversion allows you to look at the file's internal
2243 representation.  Since XEmacs is basically a text editor, "no
2244 conversion" does convert newline conventions by default.  (Use the
2245 'binary coding-system if this is not desired.)
2246
2247    ISO 2022 (*note ISO 2022::) is the basic international standard
2248 regulating use of "coded character sets for the exchange of data", ie,
2249 text streams.  ISO 2022 contains functions that make it possible to
2250 encode text streams to comply with restrictions of the Internet mail
2251 system and de facto restrictions of most file systems (eg, use of the
2252 separator character in file names).  Coding systems which are not ISO
2253 2022 conformant can be difficult to handle.  Perhaps more important,
2254 they are not adaptable to multilingual information interchange, with
2255 the obvious exception of ISO 10646 (Unicode).  (Unicode is partially
2256 supported by XEmacs with the addition of the Lisp package ucs-conv.)
2257
2258    The special class of coding systems includes automatic detection,
2259 CCL (a "little language" embedded as an interpreter, useful for
2260 translating between variants of a single character set),
2261 non-ISO-2022-conformant encodings like Unicode, Shift JIS, and Big5,
2262 and MULE internal coding.  (NB: this list is based on XEmacs 21.2.
2263 Terminology may vary slightly for other versions of XEmacs and for GNU
2264 Emacs 20.)
2265
2266 `no-conversion'
2267      No conversion, for binary files, and a few special cases of
2268      non-ISO-2022 coding systems where conversion is done by hook
2269      functions (usually implemented in CCL).  On output, graphic
2270      characters that are not in ASCII or Latin-1 will be replaced by a
2271      `?'. (For a no-conversion-encoded buffer, these characters will
2272      only be present if you explicitly insert them.)
2273
2274 `iso2022'
2275      Any ISO-2022-compliant encoding.  Among others, this includes JIS
2276      (the Japanese encoding commonly used for e-mail), national
2277      variants of EUC (the standard Unix encoding for Japanese and other
2278      languages), and Compound Text (an encoding used in X11).  You can
2279      specify more specific information about the conversion with the
2280      FLAGS argument.
2281
2282 `ucs-4'
2283      ISO 10646 UCS-4 encoding.  A 31-bit fixed-width superset of
2284      Unicode.
2285
2286 `utf-8'
2287      ISO 10646 UTF-8 encoding.  A "file system safe" transformation
2288      format that can be used with both UCS-4 and Unicode.
2289
2290 `undecided'
2291      Automatic conversion.  XEmacs attempts to detect the coding system
2292      used in the file.
2293
2294 `shift-jis'
2295      Shift-JIS (a Japanese encoding commonly used in PC operating
2296      systems).
2297
2298 `big5'
2299      Big5 (the encoding commonly used for Taiwanese).
2300
2301 `ccl'
2302      The conversion is performed using a user-written pseudo-code
2303      program.  CCL (Code Conversion Language) is the name of this
2304      pseudo-code.  For example, CCL is used to map KOI8-R characters
2305      (an encoding for Russian Cyrillic) to ISO8859-5 (the form used
2306      internally by MULE).
2307
2308 `internal'
2309      Write out or read in the raw contents of the memory representing
2310      the buffer's text.  This is primarily useful for debugging
2311      purposes, and is only enabled when XEmacs has been compiled with
2312      `DEBUG_XEMACS' set (the `--debug' configure option).  *Warning*:
2313      Reading in a file using `internal' conversion can result in an
2314      internal inconsistency in the memory representing a buffer's text,
2315      which will produce unpredictable results and may cause XEmacs to
2316      crash.  Under normal circumstances you should never use `internal'
2317      conversion.
2318
2319 \1f
2320 File: lispref.info,  Node: ISO 2022,  Next: EOL Conversion,  Prev: Coding System Types,  Up: Coding Systems
2321
2322 ISO 2022
2323 ========
2324
2325 This section briefly describes the ISO 2022 encoding standard.  A more
2326 thorough treatment is available in the original document of ISO 2022 as
2327 well as various national standards (such as JIS X 0202).
2328
2329    Character sets ("charsets") are classified into the following four
2330 categories, according to the number of characters in the charset:
2331 94-charset, 96-charset, 94x94-charset, and 96x96-charset.  This means
2332 that although an ISO 2022 coding system may have variable width
2333 characters, each charset used is fixed-width (in contrast to the MULE
2334 character set and UTF-8, for example).
2335
2336    ISO 2022 provides for switching between character sets via escape
2337 sequences.  This switching is somewhat complicated, because ISO 2022
2338 provides for both legacy applications like Internet mail that accept
2339 only 7 significant bits in some contexts (RFC 822 headers, for example),
2340 and more modern "8-bit clean" applications.  It also provides for
2341 compact and transparent representation of languages like Japanese which
2342 mix ASCII and a national script (even outside of computer programs).
2343
2344    First, ISO 2022 codified prevailing practice by dividing the code
2345 space into "control" and "graphic" regions.  The code points 0x00-0x1F
2346 and 0x80-0x9F are reserved for "control characters", while "graphic
2347 characters" must be assigned to code points in the regions 0x20-0x7F and
2348 0xA0-0xFF.  The positions 0x20 and 0x7F are special, and under some
2349 circumstances must be assigned the graphic character "ASCII SPACE" and
2350 the control character "ASCII DEL" respectively.
2351
2352    The various regions are given the name C0 (0x00-0x1F), GL
2353 (0x20-0x7F), C1 (0x80-0x9F), and GR (0xA0-0xFF).  GL and GR stand for
2354 "graphic left" and "graphic right", respectively, because of the
2355 standard method of displaying graphic character sets in tables with the
2356 high byte indexing columns and the low byte indexing rows.  I don't
2357 find it very intuitive, but these are called "registers".
2358
2359    An ISO 2022-conformant encoding for a graphic character set must use
2360 a fixed number of bytes per character, and the values must fit into a
2361 single register; that is, each byte must range over either 0x20-0x7F, or
2362 0xA0-0xFF.  It is not allowed to extend the range of the repertoire of a
2363 character set by using both ranges at the same.  This is why a standard
2364 character set such as ISO 8859-1 is actually considered by ISO 2022 to
2365 be an aggregation of two character sets, ASCII and LATIN-1, and why it
2366 is technically incorrect to refer to ISO 8859-1 as "Latin 1".  Also, a
2367 single character's bytes must all be drawn from the same register; this
2368 is why Shift JIS (for Japanese) and Big 5 (for Chinese) are not ISO
2369 2022-compatible encodings.
2370
2371    The reason for this restriction becomes clear when you attempt to
2372 define an efficient, robust encoding for a language like Japanese.
2373 Like ISO 8859, Japanese encodings are aggregations of several character
2374 sets.  In practice, the vast majority of characters are drawn from the
2375 "JIS Roman" character set (a derivative of ASCII; it won't hurt to
2376 think of it as ASCII) and the JIS X 0208 standard "basic Japanese"
2377 character set including not only ideographic characters ("kanji") but
2378 syllabic Japanese characters ("kana"), a wide variety of symbols, and
2379 many alphabetic characters (Roman, Greek, and Cyrillic) as well.
2380 Although JIS X 0208 includes the whole Roman alphabet, as a 2-byte code
2381 it is not suited to programming; thus the inclusion of ASCII in the
2382 standard Japanese encodings.
2383
2384    For normal Japanese text such as in newspapers, a broad repertoire of
2385 approximately 3000 characters is used.  Evidently this won't fit into
2386 one byte; two must be used.  But much of the text processed by Japanese
2387 computers is computer source code, nearly all of which is ASCII.  A not
2388 insignificant portion of ordinary text is English (as such or as
2389 borrowed Japanese vocabulary) or other languages which can represented
2390 at least approximately in ASCII, as well.  It seems reasonable then to
2391 represent ASCII in one byte, and JIS X 0208 in two.  And this is exactly
2392 what the Extended Unix Code for Japanese (EUC-JP) does.  ASCII is
2393 invoked to the GL register, and JIS X 0208 is invoked to the GR
2394 register.  Thus, each byte can be tested for its character set by
2395 looking at the high bit; if set, it is Japanese, if clear, it is ASCII.
2396 Furthermore, since control characters like newline can never be part of
2397 a graphic character, even in the case of corruption in transmission the
2398 stream will be resynchronized at every line break, on the order of 60-80
2399 bytes.  This coding system requires no escape sequences or special
2400 control codes to represent 99.9% of all Japanese text.
2401
2402    Note carefully the distinction between the character sets (ASCII and
2403 JIS X 0208), the encoding (EUC-JP), and the coding system (ISO 2022).
2404 The JIS X 0208 character set is used in three different encodings for
2405 Japanese, but in ISO-2022-JP it is invoked into GL (so the high bit is
2406 always clear), in EUC-JP it is invoked into GR (setting the high bit in
2407 the process), and in Shift JIS the high bit may be set or reset, and the
2408 significant bits are shifted within the 16-bit character so that the two
2409 main character sets can coexist with a third (the "halfwidth katakana"
2410 of JIS X 0201).  As the name implies, the ISO-2022-JP encoding is also a
2411 version of the ISO-2022 coding system.
2412
2413    In order to systematically treat subsidiary character sets (like the
2414 "halfwidth katakana" already mentioned, and the "supplementary kanji" of
2415 JIS X 0212), four further registers are defined: G0, G1, G2, and G3.
2416 Unlike GL and GR, they are not logically distinguished by internal
2417 format.  Instead, the process of "invocation" mentioned earlier is
2418 broken into two steps: first, a character set is "designated" to one of
2419 the registers G0-G3 by use of an "escape sequence" of the form:
2420
2421              ESC [I] I F
2422
2423    where I is an intermediate character or characters in the range 0x20
2424 - 0x3F, and F, from the range 0x30-0x7Fm is the final character
2425 identifying this charset.  (Final characters in the range 0x30-0x3F are
2426 reserved for private use and will never have a publicly registered
2427 meaning.)
2428
2429    Then that register is "invoked" to either GL or GR, either
2430 automatically (designations to G0 normally involve invocation to GL as
2431 well), or by use of shifting (affecting only the following character in
2432 the data stream) or locking (effective until the next designation or
2433 locking) control sequences.  An encoding conformant to ISO 2022 is
2434 typically defined by designating the initial contents of the G0-G3
2435 registers, specifying a 7 or 8 bit environment, and specifying whether
2436 further designations will be recognized.
2437
2438    Some examples of character sets and the registered final characters
2439 F used to designate them:
2440
2441 94-charset
2442      ASCII (B), left (J) and right (I) half of JIS X 0201, ...
2443
2444 96-charset
2445      Latin-1 (A), Latin-2 (B), Latin-3 (C), ...
2446
2447 94x94-charset
2448      GB2312 (A), JIS X 0208 (B), KSC5601 (C), ...
2449
2450 96x96-charset
2451      none for the moment
2452
2453    The meanings of the various characters in these sequences, where not
2454 specified by the ISO 2022 standard (such as the ESC character), are
2455 assigned by "ECMA", the European Computer Manufacturers Association.
2456
2457    The meaning of intermediate characters are:
2458
2459              $ [0x24]: indicate charset of dimension 2 (94x94 or 96x96).
2460              ( [0x28]: designate to G0 a 94-charset whose final byte is F.
2461              ) [0x29]: designate to G1 a 94-charset whose final byte is F.
2462              * [0x2A]: designate to G2 a 94-charset whose final byte is F.
2463              + [0x2B]: designate to G3 a 94-charset whose final byte is F.
2464              , [0x2C]: designate to G0 a 96-charset whose final byte is F.
2465              - [0x2D]: designate to G1 a 96-charset whose final byte is F.
2466              . [0x2E]: designate to G2 a 96-charset whose final byte is F.
2467              / [0x2F]: designate to G3 a 96-charset whose final byte is F.
2468
2469    The comma may be used in files read and written only by MULE, as a
2470 MULE extension, but this is illegal in ISO 2022.  (The reason is that
2471 in ISO 2022 G0 must be a 94-member character set, with 0x20 assigned
2472 the value SPACE, and 0x7F assigned the value DEL.)
2473
2474    Here are examples of designations:
2475
2476              ESC ( B :              designate to G0 ASCII
2477              ESC - A :              designate to G1 Latin-1
2478              ESC $ ( A or ESC $ A : designate to G0 GB2312
2479              ESC $ ( B or ESC $ B : designate to G0 JISX0208
2480              ESC $ ) C :            designate to G1 KSC5601
2481
2482    (The short forms used to designate GB2312 and JIS X 0208 are for
2483 backwards compatibility; the long forms are preferred.)
2484
2485    To use a charset designated to G2 or G3, and to use a charset
2486 designated to G1 in a 7-bit environment, you must explicitly invoke G1,
2487 G2, or G3 into GL.  There are two types of invocation, Locking Shift
2488 (forever) and Single Shift (one character only).
2489
2490    Locking Shift is done as follows:
2491
2492              LS0 or SI (0x0F): invoke G0 into GL
2493              LS1 or SO (0x0E): invoke G1 into GL
2494              LS2:  invoke G2 into GL
2495              LS3:  invoke G3 into GL
2496              LS1R: invoke G1 into GR
2497              LS2R: invoke G2 into GR
2498              LS3R: invoke G3 into GR
2499
2500    Single Shift is done as follows:
2501
2502              SS2 or ESC N: invoke G2 into GL
2503              SS3 or ESC O: invoke G3 into GL
2504
2505    The shift functions (such as LS1R and SS3) are represented by control
2506 characters (from C1) in 8 bit environments and by escape sequences in 7
2507 bit environments.
2508
2509    (#### Ben says: I think the above is slightly incorrect.  It appears
2510 that SS2 invokes G2 into GR and SS3 invokes G3 into GR, whereas ESC N
2511 and ESC O behave as indicated.  The above definitions will not parse
2512 EUC-encoded text correctly, and it looks like the code in mule-coding.c
2513 has similar problems.)
2514
2515    Evidently there are a lot of ISO-2022-compliant ways of encoding
2516 multilingual text.  Now, in the world, there exist many coding systems
2517 such as X11's Compound Text, Japanese JUNET code, and so-called EUC
2518 (Extended UNIX Code); all of these are variants of ISO 2022.
2519
2520    In MULE, we characterize a version of ISO 2022 by the following
2521 attributes:
2522
2523   1. The character sets initially designated to G0 thru G3.
2524
2525   2. Whether short form designations are allowed for Japanese and
2526      Chinese.
2527
2528   3. Whether ASCII should be designated to G0 before control characters.
2529
2530   4. Whether ASCII should be designated to G0 at the end of line.
2531
2532   5. 7-bit environment or 8-bit environment.
2533
2534   6. Whether Locking Shifts are used or not.
2535
2536   7. Whether to use ASCII or the variant JIS X 0201-1976-Roman.
2537
2538   8. Whether to use JIS X 0208-1983 or the older version JIS X
2539      0208-1976.
2540
2541    (The last two are only for Japanese.)
2542
2543    By specifying these attributes, you can create any variant of ISO
2544 2022.
2545
2546    Here are several examples:
2547
2548      ISO-2022-JP -- Coding system used in Japanese email (RFC 1463 #### check).
2549              1. G0 <- ASCII, G1..3 <- never used
2550              2. Yes.
2551              3. Yes.
2552              4. Yes.
2553              5. 7-bit environment
2554              6. No.
2555              7. Use ASCII
2556              8. Use JIS X 0208-1983
2557      
2558      ctext -- X11 Compound Text
2559              1. G0 <- ASCII, G1 <- Latin-1, G2,3 <- never used.
2560              2. No.
2561              3. No.
2562              4. Yes.
2563              5. 8-bit environment.
2564              6. No.
2565              7. Use ASCII.
2566              8. Use JIS X 0208-1983.
2567      
2568      euc-china -- Chinese EUC.  Often called the "GB encoding", but that is
2569      technically incorrect.
2570              1. G0 <- ASCII, G1 <- GB 2312, G2,3 <- never used.
2571              2. No.
2572              3. Yes.
2573              4. Yes.
2574              5. 8-bit environment.
2575              6. No.
2576              7. Use ASCII.
2577              8. Use JIS X 0208-1983.
2578      
2579      ISO-2022-KR -- Coding system used in Korean email.
2580              1. G0 <- ASCII, G1 <- KSC 5601, G2,3 <- never used.
2581              2. No.
2582              3. Yes.
2583              4. Yes.
2584              5. 7-bit environment.
2585              6. Yes.
2586              7. Use ASCII.
2587              8. Use JIS X 0208-1983.
2588
2589    MULE creates all of these coding systems by default.
2590
2591 \1f
2592 File: lispref.info,  Node: EOL Conversion,  Next: Coding System Properties,  Prev: ISO 2022,  Up: Coding Systems
2593
2594 EOL Conversion
2595 --------------
2596
2597 `nil'
2598      Automatically detect the end-of-line type (LF, CRLF, or CR).  Also
2599      generate subsidiary coding systems named `NAME-unix', `NAME-dos',
2600      and `NAME-mac', that are identical to this coding system but have
2601      an EOL-TYPE value of `lf', `crlf', and `cr', respectively.
2602
2603 `lf'
2604      The end of a line is marked externally using ASCII LF.  Since this
2605      is also the way that XEmacs represents an end-of-line internally,
2606      specifying this option results in no end-of-line conversion.  This
2607      is the standard format for Unix text files.
2608
2609 `crlf'
2610      The end of a line is marked externally using ASCII CRLF.  This is
2611      the standard format for MS-DOS text files.
2612
2613 `cr'
2614      The end of a line is marked externally using ASCII CR.  This is the
2615      standard format for Macintosh text files.
2616
2617 `t'
2618      Automatically detect the end-of-line type but do not generate
2619      subsidiary coding systems.  (This value is converted to `nil' when
2620      stored internally, and `coding-system-property' will return `nil'.)
2621
2622 \1f
2623 File: lispref.info,  Node: Coding System Properties,  Next: Basic Coding System Functions,  Prev: EOL Conversion,  Up: Coding Systems
2624
2625 Coding System Properties
2626 ------------------------
2627
2628 `mnemonic'
2629      String to be displayed in the modeline when this coding system is
2630      active.
2631
2632 `eol-type'
2633      End-of-line conversion to be used.  It should be one of the types
2634      listed in *Note EOL Conversion::.
2635
2636 `eol-lf'
2637      The coding system which is the same as this one, except that it
2638      uses the Unix line-breaking convention.
2639
2640 `eol-crlf'
2641      The coding system which is the same as this one, except that it
2642      uses the DOS line-breaking convention.
2643
2644 `eol-cr'
2645      The coding system which is the same as this one, except that it
2646      uses the Macintosh line-breaking convention.
2647
2648 `post-read-conversion'
2649      Function called after a file has been read in, to perform the
2650      decoding.  Called with two arguments, START and END, denoting a
2651      region of the current buffer to be decoded.
2652
2653 `pre-write-conversion'
2654      Function called before a file is written out, to perform the
2655      encoding.  Called with two arguments, START and END, denoting a
2656      region of the current buffer to be encoded.
2657
2658    The following additional properties are recognized if TYPE is
2659 `iso2022':
2660
2661 `charset-g0'
2662 `charset-g1'
2663 `charset-g2'
2664 `charset-g3'
2665      The character set initially designated to the G0 - G3 registers.
2666      The value should be one of
2667
2668         * A charset object (designate that character set)
2669
2670         * `nil' (do not ever use this register)
2671
2672         * `t' (no character set is initially designated to the
2673           register, but may be later on; this automatically sets the
2674           corresponding `force-g*-on-output' property)
2675
2676 `force-g0-on-output'
2677 `force-g1-on-output'
2678 `force-g2-on-output'
2679 `force-g3-on-output'
2680      If non-`nil', send an explicit designation sequence on output
2681      before using the specified register.
2682
2683 `short'
2684      If non-`nil', use the short forms `ESC $ @', `ESC $ A', and `ESC $
2685      B' on output in place of the full designation sequences `ESC $ (
2686      @', `ESC $ ( A', and `ESC $ ( B'.
2687
2688 `no-ascii-eol'
2689      If non-`nil', don't designate ASCII to G0 at each end of line on
2690      output.  Setting this to non-`nil' also suppresses other
2691      state-resetting that normally happens at the end of a line.
2692
2693 `no-ascii-cntl'
2694      If non-`nil', don't designate ASCII to G0 before control chars on
2695      output.
2696
2697 `seven'
2698      If non-`nil', use 7-bit environment on output.  Otherwise, use
2699      8-bit environment.
2700
2701 `lock-shift'
2702      If non-`nil', use locking-shift (SO/SI) instead of single-shift or
2703      designation by escape sequence.
2704
2705 `no-iso6429'
2706      If non-`nil', don't use ISO6429's direction specification.
2707
2708 `escape-quoted'
2709      If non-`nil', literal control characters that are the same as the
2710      beginning of a recognized ISO 2022 or ISO 6429 escape sequence (in
2711      particular, ESC (0x1B), SO (0x0E), SI (0x0F), SS2 (0x8E), SS3
2712      (0x8F), and CSI (0x9B)) are "quoted" with an escape character so
2713      that they can be properly distinguished from an escape sequence.
2714      (Note that doing this results in a non-portable encoding.) This
2715      encoding flag is used for byte-compiled files.  Note that ESC is a
2716      good choice for a quoting character because there are no escape
2717      sequences whose second byte is a character from the Control-0 or
2718      Control-1 character sets; this is explicitly disallowed by the ISO
2719      2022 standard.
2720
2721 `input-charset-conversion'
2722      A list of conversion specifications, specifying conversion of
2723      characters in one charset to another when decoding is performed.
2724      Each specification is a list of two elements: the source charset,
2725      and the destination charset.
2726
2727 `output-charset-conversion'
2728      A list of conversion specifications, specifying conversion of
2729      characters in one charset to another when encoding is performed.
2730      The form of each specification is the same as for
2731      `input-charset-conversion'.
2732
2733    The following additional properties are recognized (and required) if
2734 TYPE is `ccl':
2735
2736 `decode'
2737      CCL program used for decoding (converting to internal format).
2738
2739 `encode'
2740      CCL program used for encoding (converting to external format).
2741
2742    The following properties are used internally:  EOL-CR, EOL-CRLF,
2743 EOL-LF, and BASE.
2744
2745 \1f
2746 File: lispref.info,  Node: Basic Coding System Functions,  Next: Coding System Property Functions,  Prev: Coding System Properties,  Up: Coding Systems
2747
2748 Basic Coding System Functions
2749 -----------------------------
2750
2751  - Function: find-coding-system coding-system-or-name
2752      This function retrieves the coding system of the given name.
2753
2754      If CODING-SYSTEM-OR-NAME is a coding-system object, it is simply
2755      returned.  Otherwise, CODING-SYSTEM-OR-NAME should be a symbol.
2756      If there is no such coding system, `nil' is returned.  Otherwise
2757      the associated coding system object is returned.
2758
2759  - Function: get-coding-system name
2760      This function retrieves the coding system of the given name.  Same
2761      as `find-coding-system' except an error is signalled if there is no
2762      such coding system instead of returning `nil'.
2763
2764  - Function: coding-system-list
2765      This function returns a list of the names of all defined coding
2766      systems.
2767
2768  - Function: coding-system-name coding-system
2769      This function returns the name of the given coding system.
2770
2771  - Function: coding-system-base coding-system
2772      Returns the base coding system (undecided EOL convention) coding
2773      system.
2774
2775  - Function: make-coding-system name type &optional doc-string props
2776      This function registers symbol NAME as a coding system.
2777
2778      TYPE describes the conversion method used and should be one of the
2779      types listed in *Note Coding System Types::.
2780
2781      DOC-STRING is a string describing the coding system.
2782
2783      PROPS is a property list, describing the specific nature of the
2784      character set.  Recognized properties are as in *Note Coding
2785      System Properties::.
2786
2787  - Function: copy-coding-system old-coding-system new-name
2788      This function copies OLD-CODING-SYSTEM to NEW-NAME.  If NEW-NAME
2789      does not name an existing coding system, a new one will be created.
2790
2791  - Function: subsidiary-coding-system coding-system eol-type
2792      This function returns the subsidiary coding system of
2793      CODING-SYSTEM with eol type EOL-TYPE.
2794
2795 \1f
2796 File: lispref.info,  Node: Coding System Property Functions,  Next: Encoding and Decoding Text,  Prev: Basic Coding System Functions,  Up: Coding Systems
2797
2798 Coding System Property Functions
2799 --------------------------------
2800
2801  - Function: coding-system-doc-string coding-system
2802      This function returns the doc string for CODING-SYSTEM.
2803
2804  - Function: coding-system-type coding-system
2805      This function returns the type of CODING-SYSTEM.
2806
2807  - Function: coding-system-property coding-system prop
2808      This function returns the PROP property of CODING-SYSTEM.
2809
2810 \1f
2811 File: lispref.info,  Node: Encoding and Decoding Text,  Next: Detection of Textual Encoding,  Prev: Coding System Property Functions,  Up: Coding Systems
2812
2813 Encoding and Decoding Text
2814 --------------------------
2815
2816  - Function: decode-coding-region start end coding-system &optional
2817           buffer
2818      This function decodes the text between START and END which is
2819      encoded in CODING-SYSTEM.  This is useful if you've read in
2820      encoded text from a file without decoding it (e.g. you read in a
2821      JIS-formatted file but used the `binary' or `no-conversion' coding
2822      system, so that it shows up as `^[$B!<!+^[(B').  The length of the
2823      encoded text is returned.  BUFFER defaults to the current buffer
2824      if unspecified.
2825
2826  - Function: encode-coding-region start end coding-system &optional
2827           buffer
2828      This function encodes the text between START and END using
2829      CODING-SYSTEM.  This will, for example, convert Japanese
2830      characters into stuff such as `^[$B!<!+^[(B' if you use the JIS
2831      encoding.  The length of the encoded text is returned.  BUFFER
2832      defaults to the current buffer if unspecified.
2833
2834 \1f
2835 File: lispref.info,  Node: Detection of Textual Encoding,  Next: Big5 and Shift-JIS Functions,  Prev: Encoding and Decoding Text,  Up: Coding Systems
2836
2837 Detection of Textual Encoding
2838 -----------------------------
2839
2840  - Function: coding-category-list
2841      This function returns a list of all recognized coding categories.
2842
2843  - Function: set-coding-priority-list list
2844      This function changes the priority order of the coding categories.
2845      LIST should be a list of coding categories, in descending order of
2846      priority.  Unspecified coding categories will be lower in priority
2847      than all specified ones, in the same relative order they were in
2848      previously.
2849
2850  - Function: coding-priority-list
2851      This function returns a list of coding categories in descending
2852      order of priority.
2853
2854  - Function: set-coding-category-system coding-category coding-system
2855      This function changes the coding system associated with a coding
2856      category.
2857
2858  - Function: coding-category-system coding-category
2859      This function returns the coding system associated with a coding
2860      category.
2861
2862  - Function: detect-coding-region start end &optional buffer
2863      This function detects coding system of the text in the region
2864      between START and END.  Returned value is a list of possible coding
2865      systems ordered by priority.  If only ASCII characters are found,
2866      it returns `autodetect' or one of its subsidiary coding systems
2867      according to a detected end-of-line type.  Optional arg BUFFER
2868      defaults to the current buffer.
2869
2870 \1f
2871 File: lispref.info,  Node: Big5 and Shift-JIS Functions,  Next: Predefined Coding Systems,  Prev: Detection of Textual Encoding,  Up: Coding Systems
2872
2873 Big5 and Shift-JIS Functions
2874 ----------------------------
2875
2876 These are special functions for working with the non-standard Shift-JIS
2877 and Big5 encodings.
2878
2879  - Function: decode-shift-jis-char code
2880      This function decodes a JIS X 0208 character of Shift-JIS
2881      coding-system.  CODE is the character code in Shift-JIS as a cons
2882      of type bytes.  The corresponding character is returned.
2883
2884  - Function: encode-shift-jis-char character
2885      This function encodes a JIS X 0208 character CHARACTER to
2886      SHIFT-JIS coding-system.  The corresponding character code in
2887      SHIFT-JIS is returned as a cons of two bytes.
2888
2889  - Function: decode-big5-char code
2890      This function decodes a Big5 character CODE of BIG5 coding-system.
2891      CODE is the character code in BIG5.  The corresponding character
2892      is returned.
2893
2894  - Function: encode-big5-char character
2895      This function encodes the Big5 character CHARACTER to BIG5
2896      coding-system.  The corresponding character code in Big5 is
2897      returned.
2898
2899 \1f
2900 File: lispref.info,  Node: Predefined Coding Systems,  Prev: Big5 and Shift-JIS Functions,  Up: Coding Systems
2901
2902 Coding Systems Implemented
2903 --------------------------
2904
2905 MULE initializes most of the commonly used coding systems at XEmacs's
2906 startup.  A few others are initialized only when the relevant language
2907 environment is selected and support libraries are loaded.  (NB: The
2908 following list is based on XEmacs 21.2.19, the development branch at the
2909 time of writing.  The list may be somewhat different for other
2910 versions.  Recent versions of GNU Emacs 20 implement a few more rare
2911 coding systems; work is being done to port these to XEmacs.)
2912
2913    Unfortunately, there is not a consistent naming convention for
2914 character sets, and for practical purposes coding systems often take
2915 their name from their principal character sets (ASCII, KOI8-R, Shift
2916 JIS).  Others take their names from the coding system (ISO-2022-JP,
2917 EUC-KR), and a few from their non-text usages (internal, binary).  To
2918 provide for this, and for the fact that many coding systems have
2919 several common names, an aliasing system is provided.  Finally, some
2920 effort has been made to use names that are registered as MIME charsets
2921 (this is why the name 'shift_jis contains that un-Lisp-y underscore).
2922
2923    There is a systematic naming convention regarding end-of-line (EOL)
2924 conventions for different systems.  A coding system whose name ends in
2925 "-unix" forces the assumptions that lines are broken by newlines (0x0A).
2926 A coding system whose name ends in "-mac" forces the assumptions that
2927 lines are broken by ASCII CRs (0x0D).  A coding system whose name ends
2928 in "-dos" forces the assumptions that lines are broken by CRLF sequences
2929 (0x0D 0x0A).  These subsidiary coding systems are automatically derived
2930 from a base coding system.  Use of the base coding system implies
2931 autodetection of the text file convention.  (The fact that the -unix,
2932 -mac, and -dos are derived from a base system results in them showing up
2933 as "aliases" in `list-coding-systems'.)  These subsidiaries have a
2934 consistent modeline indicator as well.  "-dos" coding systems have ":T"
2935 appended to their modeline indicator, while "-mac" coding systems have
2936 ":t" appended (eg, "ISO8:t" for iso-2022-8-mac).
2937
2938    In the following table, each coding system is given with its mode
2939 line indicator in parentheses.  Non-textual coding systems are listed
2940 first, followed by textual coding systems and their aliases. (The
2941 coding system subsidiary modeline indicators ":T" and ":t" will be
2942 omitted from the table of coding systems.)
2943
2944    ### SJT 1999-08-23 Maybe should order these by language?  Definitely
2945 need language usage for the ISO-8859 family.
2946
2947    Note that although true coding system aliases have been implemented
2948 for XEmacs 21.2, the coding system initialization has not yet been
2949 converted as of 21.2.19.  So coding systems described as aliases have
2950 the same properties as the aliased coding system, but will not be equal
2951 as Lisp objects.
2952
2953 `automatic-conversion'
2954 `undecided'
2955 `undecided-dos'
2956 `undecided-mac'
2957 `undecided-unix'
2958      Modeline indicator: `Auto'.  A type `undecided' coding system.
2959      Attempts to determine an appropriate coding system from file
2960      contents or the environment.
2961
2962 `raw-text'
2963 `no-conversion'
2964 `raw-text-dos'
2965 `raw-text-mac'
2966 `raw-text-unix'
2967 `no-conversion-dos'
2968 `no-conversion-mac'
2969 `no-conversion-unix'
2970      Modeline indicator: `Raw'.  A type `no-conversion' coding system,
2971      which converts only line-break-codes.  An implementation quirk
2972      means that this coding system is also used for ISO8859-1.
2973
2974 `binary'
2975      Modeline indicator: `Binary'.  A type `no-conversion' coding
2976      system which does no character coding or EOL conversions.  An
2977      alias for `raw-text-unix'.
2978
2979 `alternativnyj'
2980 `alternativnyj-dos'
2981 `alternativnyj-mac'
2982 `alternativnyj-unix'
2983      Modeline indicator: `Cy.Alt'.  A type `ccl' coding system used for
2984      Alternativnyj, an encoding of the Cyrillic alphabet.
2985
2986 `big5'
2987 `big5-dos'
2988 `big5-mac'
2989 `big5-unix'
2990      Modeline indicator: `Zh/Big5'.  A type `big5' coding system used
2991      for BIG5, the most common encoding of traditional Chinese as used
2992      in Taiwan.
2993
2994 `cn-gb-2312'
2995 `cn-gb-2312-dos'
2996 `cn-gb-2312-mac'
2997 `cn-gb-2312-unix'
2998      Modeline indicator: `Zh-GB/EUC'.  A type `iso2022' coding system
2999      used for simplified Chinese (as used in the People's Republic of
3000      China), with the `ascii' (G0), `chinese-gb2312' (G1), and `sisheng'
3001      (G2) character sets initially designated.  Chinese EUC (Extended
3002      Unix Code).
3003
3004 `ctext-hebrew'
3005 `ctext-hebrew-dos'
3006 `ctext-hebrew-mac'
3007 `ctext-hebrew-unix'
3008      Modeline indicator: `CText/Hbrw'.  A type `iso2022' coding system
3009      with the `ascii' (G0) and `hebrew-iso8859-8' (G1) character sets
3010      initially designated for Hebrew.
3011
3012 `ctext'
3013 `ctext-dos'
3014 `ctext-mac'
3015 `ctext-unix'
3016      Modeline indicator: `CText'.  A type `iso2022' 8-bit coding system
3017      with the `ascii' (G0) and `latin-iso8859-1' (G1) character sets
3018      initially designated.  X11 Compound Text Encoding.  Often
3019      mistakenly recognized instead of EUC encodings; usual cause is
3020      inappropriate setting of `coding-priority-list'.
3021
3022 `escape-quoted'
3023      Modeline indicator: `ESC/Quot'.  A type `iso2022' 8-bit coding
3024      system with the `ascii' (G0) and `latin-iso8859-1' (G1) character
3025      sets initially designated and escape quoting.  Unix EOL conversion
3026      (ie, no conversion).  It is used for .ELC files.
3027
3028 `euc-jp'
3029 `euc-jp-dos'
3030 `euc-jp-mac'
3031 `euc-jp-unix'
3032      Modeline indicator: `Ja/EUC'.  A type `iso2022' 8-bit coding system
3033      with `ascii' (G0), `japanese-jisx0208' (G1), `katakana-jisx0201'
3034      (G2), and `japanese-jisx0212' (G3) initially designated.  Japanese
3035      EUC (Extended Unix Code).
3036
3037 `euc-kr'
3038 `euc-kr-dos'
3039 `euc-kr-mac'
3040 `euc-kr-unix'
3041      Modeline indicator: `ko/EUC'.  A type `iso2022' 8-bit coding system
3042      with `ascii' (G0) and `korean-ksc5601' (G1) initially designated.
3043      Korean EUC (Extended Unix Code).
3044
3045 `hz-gb-2312'
3046      Modeline indicator: `Zh-GB/Hz'.  A type `no-conversion' coding
3047      system with Unix EOL convention (ie, no conversion) using
3048      post-read-decode and pre-write-encode functions to translate the
3049      Hz/ZW coding system used for Chinese.
3050
3051 `iso-2022-7bit'
3052 `iso-2022-7bit-unix'
3053 `iso-2022-7bit-dos'
3054 `iso-2022-7bit-mac'
3055 `iso-2022-7'
3056      Modeline indicator: `ISO7'.  A type `iso2022' 7-bit coding system
3057      with `ascii' (G0) initially designated.  Other character sets must
3058      be explicitly designated to be used.
3059
3060 `iso-2022-7bit-ss2'
3061 `iso-2022-7bit-ss2-dos'
3062 `iso-2022-7bit-ss2-mac'
3063 `iso-2022-7bit-ss2-unix'
3064      Modeline indicator: `ISO7/SS'.  A type `iso2022' 7-bit coding
3065      system with `ascii' (G0) initially designated.  Other character
3066      sets must be explicitly designated to be used.  SS2 is used to
3067      invoke a 96-charset, one character at a time.
3068
3069 `iso-2022-8'
3070 `iso-2022-8-dos'
3071 `iso-2022-8-mac'
3072 `iso-2022-8-unix'
3073      Modeline indicator: `ISO8'.  A type `iso2022' 8-bit coding system
3074      with `ascii' (G0) and `latin-iso8859-1' (G1) initially designated.
3075      Other character sets must be explicitly designated to be used.
3076      No single-shift or locking-shift.
3077
3078 `iso-2022-8bit-ss2'
3079 `iso-2022-8bit-ss2-dos'
3080 `iso-2022-8bit-ss2-mac'
3081 `iso-2022-8bit-ss2-unix'
3082      Modeline indicator: `ISO8/SS'.  A type `iso2022' 8-bit coding
3083      system with `ascii' (G0) and `latin-iso8859-1' (G1) initially
3084      designated.  Other character sets must be explicitly designated to
3085      be used.  SS2 is used to invoke a 96-charset, one character at a
3086      time.
3087
3088 `iso-2022-int-1'
3089 `iso-2022-int-1-dos'
3090 `iso-2022-int-1-mac'
3091 `iso-2022-int-1-unix'
3092      Modeline indicator: `INT-1'.  A type `iso2022' 7-bit coding system
3093      with `ascii' (G0) and `korean-ksc5601' (G1) initially designated.
3094      ISO-2022-INT-1.
3095
3096 `iso-2022-jp-1978-irv'
3097 `iso-2022-jp-1978-irv-dos'
3098 `iso-2022-jp-1978-irv-mac'
3099 `iso-2022-jp-1978-irv-unix'
3100      Modeline indicator: `Ja-78/7bit'.  A type `iso2022' 7-bit coding
3101      system.  For compatibility with old Japanese terminals; if you
3102      need to know, look at the source.
3103
3104 `iso-2022-jp'
3105 `iso-2022-jp-2 (ISO7/SS)'
3106 `iso-2022-jp-dos'
3107 `iso-2022-jp-mac'
3108 `iso-2022-jp-unix'
3109 `iso-2022-jp-2-dos'
3110 `iso-2022-jp-2-mac'
3111 `iso-2022-jp-2-unix'
3112      Modeline indicator: `MULE/7bit'.  A type `iso2022' 7-bit coding
3113      system with `ascii' (G0) initially designated, and complex
3114      specifications to insure backward compatibility with old Japanese
3115      systems.  Used for communication with mail and news in Japan.  The
3116      "-2" versions also use SS2 to invoke a 96-charset one character at
3117      a time.
3118
3119 `iso-2022-kr'
3120      Modeline indicator: `Ko/7bit'  A type `iso2022' 7-bit coding
3121      system with `ascii' (G0) and `korean-ksc5601' (G1) initially
3122      designated.  Used for e-mail in Korea.
3123
3124 `iso-2022-lock'
3125 `iso-2022-lock-dos'
3126 `iso-2022-lock-mac'
3127 `iso-2022-lock-unix'
3128      Modeline indicator: `ISO7/Lock'.  A type `iso2022' 7-bit coding
3129      system with `ascii' (G0) initially designated, using Locking-Shift
3130      to invoke a 96-charset.
3131
3132 `iso-8859-1'
3133 `iso-8859-1-dos'
3134 `iso-8859-1-mac'
3135 `iso-8859-1-unix'
3136      Due to implementation, this is not a type `iso2022' coding system,
3137      but rather an alias for the `raw-text' coding system.
3138
3139 `iso-8859-2'
3140 `iso-8859-2-dos'
3141 `iso-8859-2-mac'
3142 `iso-8859-2-unix'
3143      Modeline indicator: `MIME/Ltn-2'.  A type `iso2022' coding system
3144      with `ascii' (G0) and `latin-iso8859-2' (G1) initially invoked.
3145
3146 `iso-8859-3'
3147 `iso-8859-3-dos'
3148 `iso-8859-3-mac'
3149 `iso-8859-3-unix'
3150      Modeline indicator: `MIME/Ltn-3'.  A type `iso2022' coding system
3151      with `ascii' (G0) and `latin-iso8859-3' (G1) initially invoked.
3152
3153 `iso-8859-4'
3154 `iso-8859-4-dos'
3155 `iso-8859-4-mac'
3156 `iso-8859-4-unix'
3157      Modeline indicator: `MIME/Ltn-4'.  A type `iso2022' coding system
3158      with `ascii' (G0) and `latin-iso8859-4' (G1) initially invoked.
3159
3160 `iso-8859-5'
3161 `iso-8859-5-dos'
3162 `iso-8859-5-mac'
3163 `iso-8859-5-unix'
3164      Modeline indicator: `ISO8/Cyr'.  A type `iso2022' coding system
3165      with `ascii' (G0) and `cyrillic-iso8859-5' (G1) initially invoked.
3166
3167 `iso-8859-7'
3168 `iso-8859-7-dos'
3169 `iso-8859-7-mac'
3170 `iso-8859-7-unix'
3171      Modeline indicator: `Grk'.  A type `iso2022' coding system with
3172      `ascii' (G0) and `greek-iso8859-7' (G1) initially invoked.
3173
3174 `iso-8859-8'
3175 `iso-8859-8-dos'
3176 `iso-8859-8-mac'
3177 `iso-8859-8-unix'
3178      Modeline indicator: `MIME/Hbrw'.  A type `iso2022' coding system
3179      with `ascii' (G0) and `hebrew-iso8859-8' (G1) initially invoked.
3180
3181 `iso-8859-9'
3182 `iso-8859-9-dos'
3183 `iso-8859-9-mac'
3184 `iso-8859-9-unix'
3185      Modeline indicator: `MIME/Ltn-5'.  A type `iso2022' coding system
3186      with `ascii' (G0) and `latin-iso8859-9' (G1) initially invoked.
3187
3188 `koi8-r'
3189 `koi8-r-dos'
3190 `koi8-r-mac'
3191 `koi8-r-unix'
3192      Modeline indicator: `KOI8'.  A type `ccl' coding-system used for
3193      KOI8-R, an encoding of the Cyrillic alphabet.
3194
3195 `shift_jis'
3196 `shift_jis-dos'
3197 `shift_jis-mac'
3198 `shift_jis-unix'
3199      Modeline indicator: `Ja/SJIS'.  A type `shift-jis' coding-system
3200      implementing the Shift-JIS encoding for Japanese.  The underscore
3201      is to conform to the MIME charset implementing this encoding.
3202
3203 `tis-620'
3204 `tis-620-dos'
3205 `tis-620-mac'
3206 `tis-620-unix'
3207      Modeline indicator: `TIS620'.  A type `ccl' encoding for Thai.  The
3208      external encoding is defined by TIS620, the internal encoding is
3209      peculiar to MULE, and called `thai-xtis'.
3210
3211 `viqr'
3212      Modeline indicator: `VIQR'.  A type `no-conversion' coding system
3213      with Unix EOL convention (ie, no conversion) using
3214      post-read-decode and pre-write-encode functions to translate the
3215      VIQR coding system for Vietnamese.
3216
3217 `viscii'
3218 `viscii-dos'
3219 `viscii-mac'
3220 `viscii-unix'
3221      Modeline indicator: `VISCII'.  A type `ccl' coding-system used for
3222      VISCII 1.1 for Vietnamese.  Differs slightly from VSCII; VISCII is
3223      given priority by XEmacs.
3224
3225 `vscii'
3226 `vscii-dos'
3227 `vscii-mac'
3228 `vscii-unix'
3229      Modeline indicator: `VSCII'.  A type `ccl' coding-system used for
3230      VSCII 1.1 for Vietnamese.  Differs slightly from VISCII, which is
3231      given priority by XEmacs.  Use `(prefer-coding-system
3232      'vietnamese-vscii)' to give priority to VSCII.
3233
3234
3235 \1f
3236 File: lispref.info,  Node: CCL,  Next: Category Tables,  Prev: Coding Systems,  Up: MULE
3237
3238 CCL
3239 ===
3240
3241 CCL (Code Conversion Language) is a simple structured programming
3242 language designed for character coding conversions.  A CCL program is
3243 compiled to CCL code (represented by a vector of integers) and executed
3244 by the CCL interpreter embedded in Emacs.  The CCL interpreter
3245 implements a virtual machine with 8 registers called `r0', ..., `r7', a
3246 number of control structures, and some I/O operators.  Take care when
3247 using registers `r0' (used in implicit "set" statements) and especially
3248 `r7' (used internally by several statements and operations, especially
3249 for multiple return values and I/O operations).
3250
3251    CCL is used for code conversion during process I/O and file I/O for
3252 non-ISO2022 coding systems.  (It is the only way for a user to specify a
3253 code conversion function.)  It is also used for calculating the code
3254 point of an X11 font from a character code.  However, since CCL is
3255 designed as a powerful programming language, it can be used for more
3256 generic calculation where efficiency is demanded.  A combination of
3257 three or more arithmetic operations can be calculated faster by CCL than
3258 by Emacs Lisp.
3259
3260    *Warning:*  The code in `src/mule-ccl.c' and
3261 `$packages/lisp/mule-base/mule-ccl.el' is the definitive description of
3262 CCL's semantics.  The previous version of this section contained
3263 several typos and obsolete names left from earlier versions of MULE,
3264 and many may remain.  (I am not an experienced CCL programmer; the few
3265 who know CCL well find writing English painful.)
3266
3267    A CCL program transforms an input data stream into an output data
3268 stream.  The input stream, held in a buffer of constant bytes, is left
3269 unchanged.  The buffer may be filled by an external input operation,
3270 taken from an Emacs buffer, or taken from a Lisp string.  The output
3271 buffer is a dynamic array of bytes, which can be written by an external
3272 output operation, inserted into an Emacs buffer, or returned as a Lisp
3273 string.
3274
3275    A CCL program is a (Lisp) list containing two or three members.  The
3276 first member is the "buffer magnification", which indicates the
3277 required minimum size of the output buffer as a multiple of the input
3278 buffer.  It is followed by the "main block" which executes while there
3279 is input remaining, and an optional "EOF block" which is executed when
3280 the input is exhausted.  Both the main block and the EOF block are CCL
3281 blocks.
3282
3283    A "CCL block" is either a CCL statement or list of CCL statements.
3284 A "CCL statement" is either a "set statement" (either an integer or an
3285 "assignment", which is a list of a register to receive the assignment,
3286 an assignment operator, and an expression) or a "control statement" (a
3287 list starting with a keyword, whose allowable syntax depends on the
3288 keyword).
3289
3290 * Menu:
3291
3292 * CCL Syntax::          CCL program syntax in BNF notation.
3293 * CCL Statements::      Semantics of CCL statements.
3294 * CCL Expressions::     Operators and expressions in CCL.
3295 * Calling CCL::         Running CCL programs.
3296 * CCL Examples::        The encoding functions for Big5 and KOI-8.
3297
3298 \1f
3299 File: lispref.info,  Node: CCL Syntax,  Next: CCL Statements,  Up: CCL
3300
3301 CCL Syntax
3302 ----------
3303
3304 The full syntax of a CCL program in BNF notation:
3305
3306 CCL_PROGRAM :=
3307         (BUFFER_MAGNIFICATION
3308          CCL_MAIN_BLOCK
3309          [ CCL_EOF_BLOCK ])
3310
3311 BUFFER_MAGNIFICATION := integer
3312 CCL_MAIN_BLOCK := CCL_BLOCK
3313 CCL_EOF_BLOCK := CCL_BLOCK
3314
3315 CCL_BLOCK :=
3316         STATEMENT | (STATEMENT [STATEMENT ...])
3317 STATEMENT :=
3318         SET | IF | BRANCH | LOOP | REPEAT | BREAK | READ | WRITE
3319         | CALL | END
3320
3321 SET :=
3322         (REG = EXPRESSION)
3323         | (REG ASSIGNMENT_OPERATOR EXPRESSION)
3324         | integer
3325
3326 EXPRESSION := ARG | (EXPRESSION OPERATOR ARG)
3327
3328 IF := (if EXPRESSION CCL_BLOCK [CCL_BLOCK])
3329 BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...])
3330 LOOP := (loop STATEMENT [STATEMENT ...])
3331 BREAK := (break)
3332 REPEAT :=
3333         (repeat)
3334         | (write-repeat [REG | integer | string])
3335         | (write-read-repeat REG [integer | ARRAY])
3336 READ :=
3337         (read REG ...)
3338         | (read-if (REG OPERATOR ARG) CCL_BLOCK CCL_BLOCK)
3339         | (read-branch REG CCL_BLOCK [CCL_BLOCK ...])
3340 WRITE :=
3341         (write REG ...)
3342         | (write EXPRESSION)
3343         | (write integer) | (write string) | (write REG ARRAY)
3344         | string
3345 CALL := (call ccl-program-name)
3346 END := (end)
3347
3348 REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7
3349 ARG := REG | integer
3350 OPERATOR :=
3351         + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | //
3352         | < | > | == | <= | >= | != | de-sjis | en-sjis
3353 ASSIGNMENT_OPERATOR :=
3354         += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>=
3355 ARRAY := '[' integer ... ']'
3356
3357 \1f
3358 File: lispref.info,  Node: CCL Statements,  Next: CCL Expressions,  Prev: CCL Syntax,  Up: CCL
3359
3360 CCL Statements
3361 --------------
3362
3363 The Emacs Code Conversion Language provides the following statement
3364 types: "set", "if", "branch", "loop", "repeat", "break", "read",
3365 "write", "call", and "end".
3366
3367 Set statement:
3368 ==============
3369
3370 The "set" statement has three variants with the syntaxes `(REG =
3371 EXPRESSION)', `(REG ASSIGNMENT_OPERATOR EXPRESSION)', and `INTEGER'.
3372 The assignment operator variation of the "set" statement works the same
3373 way as the corresponding C expression statement does.  The assignment
3374 operators are `+=', `-=', `*=', `/=', `%=', `&=', `|=', `^=', `<<=',
3375 and `>>=', and they have the same meanings as in C.  A "naked integer"
3376 INTEGER is equivalent to a SET statement of the form `(r0 = INTEGER)'.</