gui: Allow File|Open to select an encoding for system files.
[pspp] / src / libpspp / encoding-guesser.h
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 2011, 2012, 2013 Free Software Foundation, Inc.
3
4    This program is free software: you can redistribute it and/or modify
5    it under the terms of the GNU General Public License as published by
6    the Free Software Foundation, either version 3 of the License, or
7    (at your option) any later version.
8
9    This program is distributed in the hope that it will be useful,
10    but WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12    GNU General Public License for more details.
13
14    You should have received a copy of the GNU General Public License
15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
16
17 #ifndef LIBPSPP_ENCODING_GUESSER_H
18 #define LIBPSPP_ENCODING_GUESSER_H 1
19
20 #include <stdbool.h>
21 #include <stddef.h>
22 #include <stdint.h>
23
24 /* A library for autodetecting the encoding of a text file.
25
26    Naming Encodings
27    ----------------
28
29    The encoding guesser starts with an encoding name in one of various
30    different forms.  Some of the forms do not actually do any autodetection.
31    The encoding guesser will return the specified encoding without looking at
32    any file data:
33
34      - A valid IANA or system encoding name: These are returned as-is.
35
36      - "Locale": Translated to the encoding used by the system locale, as
37        returned by locale_charset().
38
39    The remaining forms that do perform autodetection are:
40
41      - "Auto," followed by a valid IANA or system encoding name (the "fallback
42        encoding"): Requests detection whether the input is encoded in UTF-8,
43        UTF-16, UTF-32, or a few other easily identifiable charsets.  When a
44        particular character set cannot be recognized, the guesser falls back to
45        the encoding following the comma.  When the fallback encoding is UTF-8,
46        but the input is invalid UTF-8, then the windows-1252 encoding (closely
47        related to ISO 8859-1) is used instead.  UTF-8 detection works only for
48        ASCII-compatible character sets.
49
50      - NULL or "Auto": As above, with the encoding used by the system locale as
51        the fallback encoding.
52
53    The above are suggested capitalizations but encoding names are not
54    case-sensitive.
55
56    The encoding_guess_parse_encoding() and encoding_guess_encoding_is_auto()
57    functions work with encoding names in these forms.
58
59    Usage
60    -----
61
62    1. Call encoding_guess_head_encoding() with several bytes from the start of
63       the text file.  Feed in at least ENCODING_GUESS_MIN bytes, unless the
64       file is shorter than that, but as many more as are conveniently
65       available.  ENCODING_GUESS_SUGGESTED is a reasonable amount.
66
67       encoding_guess_head_encoding() returns its best guess at the file's
68       encoding.  Ordinarily it returns a final guess that the client can use to
69       interpret the file, and you're all done.  However, if it returns "ASCII"
70       and the original encoding name requests autodetection (which you can find
71       out by calling encoding_guess_encoding_is_auto()), then proceed to the
72       next step.
73
74    2. The encoding guesser is confident that the stream uses an ASCII
75       compatible encoding, either UTF-8 or the fallback encoding.  The client
76       may safely read and process the stream up to the first non-ASCII
77       character.  If the stream continues to be ASCII all the way to its end,
78       then we're done.
79
80       The encoding guesser provides a pair of functions to detect non-ASCII
81       characters: encoding_guess_is_ascii_text() for single characters and
82       encoding_guess_count_ascii() as a convenient wrapper for whole buffers.
83
84    3. Otherwise, the stream contains some non-ASCII data at some point.  Now
85       the client should gather several bytes starting at this point, at least
86       ENCODING_GUESS_MIN, unless the file ends before that, but as many more as
87       are conveniently available.  ENCODING_GUESS_SUGGESTED is a reasonable
88       amount.
89
90       The client should pass these bytes to encoding_guess_tail_encoding(),
91       which returns a best and final guess at the file's encoding, which is
92       either UTF-8 or the fallback encoding.  Another alternative is
93       encoding_guess_tail_is_utf8(), which guesses the same way but has a
94       different form of return value.
95 */
96
97 /* Minimum number of bytes for use in autodetection.
98    You should only pass fewer bytes to the autodetection routines if the file
99    is actually shorter than this. */
100 #define ENCODING_GUESS_MIN              16
101
102 /* Suggested minimum buffer size to use for autodetection. */
103 #define ENCODING_GUESS_SUGGESTED        1024
104
105 /* Parsing encoding names. */
106 const char *encoding_guess_parse_encoding (const char *encoding);
107 bool encoding_guess_encoding_is_auto (const char *encoding);
108
109 /* Making an initial coding guess based on the start of a file. */
110 const char *encoding_guess_head_encoding (const char *encoding,
111                                           const void *, size_t);
112 size_t encoding_guess_bom_length (const char *encoding,
113                                   const void *, size_t n);
114
115 /* Refining an initial ASCII coding guess using later non-ASCII bytes. */
116 static inline bool encoding_guess_is_ascii_text (uint8_t c);
117 size_t encoding_guess_count_ascii (const void *, size_t);
118 int encoding_guess_tail_is_utf8 (const void *, size_t);
119 const char *encoding_guess_tail_encoding (const char *encoding,
120                                           const void *, size_t);
121
122 /* Guessing from entire file contents. */
123 const char *encoding_guess_whole_file (const char *encoding,
124                                        const void *, size_t);
125
126 /* Returns true if C is a byte that might appear in an ASCII text file,
127    false otherwise. */
128 static inline bool
129 encoding_guess_is_ascii_text (uint8_t c)
130 {
131   return (c >= 0x20 && c < 0x7f) || (c >= 0x09 && c < 0x0e);
132 }
133
134 #endif /* libpspp/encoding-guesser.h */