Skip to content
Newer
Older
100644 101 lines (80 sloc) 5.06 KB
8dff99f @gagle v0.1.8
authored
1 Characters that cannot be directly represented in ISO 8859-1 encoding can be
2 written using Unicode escapes.
3
4 Properties are processed in terms of lines. There are two kinds of line,
5 natural lines and logical lines. A natural line is defined as a line of
6 characters that is terminated either by a set of line terminator characters
7 (\n or \r or \r\n) or by the end of the stream. A natural line may be either a
8 blank line, a comment line, or hold all or some of a key-element pair. A
9 logical line holds all the data of a key-element pair, which may be spread out
10 across several adjacent natural lines by escaping the line terminator sequence
11 with a backslash character \. Note that a comment line cannot be extended in
12 this manner; every natural line that is a comment must have its own comment
13 indicator, as described below. Lines are read from input until the end of the
14 stream is reached.
15
16 A natural line that contains only white space characters is considered blank
17 and is ignored. A comment line has an ASCII '#' or '!' as its first non-white
18 space character; comment lines are also ignored and do not encode key-element
19 information. In addition to line terminators, this format considers the
20 characters space (' ', '\u0020'), tab ('\t', '\u0009'), and form feed
21 ('\f', '\u000C') to be white space.
22
23 If a logical line is spread across several natural lines, the backslash
24 escaping the line terminator sequence, the line terminator sequence, and any
25 white space at the start of the following line have no affect on the key or
26 element values. The remainder of the discussion of key and element parsing
27 (when loading) will assume all the characters constituting the key and element
28 appear on a single natural line after line continuation characters have been
29 removed. Note that it is not sufficient to only examine the character preceding
30 a line terminator sequence to decide if the line terminator is escaped; there
31 must be an odd number of contiguous backslashes for the line terminator to be
32 escaped. Since the input is processed from left to right, a non-zero even
33 number of 2n contiguous backslashes before a line terminator (or elsewhere)
34 encodes n backslashes after escape processing.
35
36 The key contains all of the characters in the line starting with the first
37 non-white space character and up to, but not including, the first unescaped
38 '=', ':', or white space character other than a line terminator. All of these
39 key termination characters may be included in the key by escaping them with a
40 preceding backslash character; for example,
41
42 \:\=
43
44 would be the two-character key ":=". Line terminator characters can be included
45 using \r and \n escape sequences. Any white space after the key is skipped; if
46 the first non-white space character after the key is '=' or ':', then it is
47 ignored and any white space characters after it are also skipped. All remaining
48 characters on the line become part of the associated element string; if there
49 are no remaining characters, the element is the empty string "". Once the raw
50 character sequences constituting the key and element are identified, escape
51 processing is performed as described above.
52
53 As an example, each of the following three lines specifies the key "Truth" and
54 the associated element value "Beauty":
55
56 Truth = Beauty
57 Truth:Beauty
58 Truth :Beauty
59
60
61 As another example, the following three lines specify a single property:
62
63 fruits apple, banana, pear, \
64 cantaloupe, watermelon, \
65 kiwi, mango
66
67
68 The key is "fruits" and the associated element is:
69
70 "apple, banana, pear, cantaloupe, watermelon, kiwi, mango"
71
72 Note that a space appears before each \ so that a space will appear after each
73 comma in the final result; the \, line terminator, and leading white space on
74 the continuation line are merely discarded and are not replaced by one or more
75 other characters.
76
77 As a third example, the line:
78
79 cheeses
80
81
82 specifies that the key is "cheeses" and the associated element is the empty
83 string "".
84
85 Characters in keys and elements can be represented in escape sequences similar
86 to those used for character and string literals (see sections 3.3 and 3.10.6 of
87 The Java™ Language Specification). The differences from the character escape
88 sequences and Unicode escapes used for characters and strings are:
89
90 - Octal escapes are not recognized.
91 - The character sequence \b does not represent a backspace character.
92 - The method does not treat a backslash character, \, before a non-valid
93 escape character as an error; the backslash is silently dropped. For
94 example, in a Java string the sequence "\z" would cause a compile time
95 error. In contrast, this method silently drops the backslash. Therefore,
96 this method treats the two character sequence "\b" as equivalent to the
97 single character 'b'.
98 - Escapes are not necessary for single and double quotes; however, by the
99 rule above, single and double quote characters preceded by a backslash
100 still yield single and double quote characters, respectively.
101 - Only a single 'u' character is allowed in a Unicode escape sequence.
Something went wrong with that request. Please try again.