diff options
Diffstat (limited to 'lib/stdlib/doc/src')
79 files changed, 5613 insertions, 4325 deletions
diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile index 50f6427eaa..ff77c3eea0 100644 --- a/lib/stdlib/doc/src/Makefile +++ b/lib/stdlib/doc/src/Makefile @@ -71,6 +71,7 @@ XML_REF3_FILES = \ lib.xml \ lists.xml \ log_mf_h.xml \ + maps.xml \ math.xml \ ms_transform.xml \ orddict.xml \ @@ -101,7 +102,6 @@ XML_REF6_FILES = stdlib_app.xml XML_PART_FILES = part.xml part_notes.xml part_notes_history.xml XML_CHAPTER_FILES = io_protocol.xml unicode_usage.xml notes.xml notes_history.xml -GIF_FILES = ushell1.gif ushell2.gif ushell3.gif BOOK_FILES = book.xml @@ -112,8 +112,7 @@ XML_FILES = \ # ---------------------------------------------------- HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ - $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) \ - $(GIF_FILES:%.gif=$(HTMLDIR)/%.gif) + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) INFO_FILE = ../../info @@ -138,21 +137,16 @@ SPECS_FLAGS = -I../../include -I../../../kernel/include # ---------------------------------------------------- # Targets # ---------------------------------------------------- -$(HTMLDIR)/%.gif: %.gif - $(INSTALL_DATA) $< $@ - docs: man pdf html $(TOP_PDF_FILE): $(XML_FILES) pdf: $(TOP_PDF_FILE) -html: gifs $(HTML_REF_MAN_FILE) +html: $(HTML_REF_MAN_FILE) man: $(MAN3_FILES) $(MAN6_FILES) -gifs: $(GIF_FILES:%=$(HTMLDIR)/%) - debug opt: clean clean_docs: diff --git a/lib/stdlib/doc/src/array.xml b/lib/stdlib/doc/src/array.xml index a79fcd487e..b03a2fa0cc 100644 --- a/lib/stdlib/doc/src/array.xml +++ b/lib/stdlib/doc/src/array.xml @@ -1,9 +1,9 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2007</year><year>2011</year> + <year>2007</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -84,7 +84,7 @@ the default value cannot be confused with the values of set entries.</p> {'EXIT',{badarg,_}} = (catch array:get(18, A3)).</pre></description> <datatypes> <datatype> - <name><marker id="type-array">array()</marker></name> + <name name="array" n_vars="1"/> <desc> <p>A functional, extendible array. The representation is not documented and is subject to change without notice. Note that @@ -92,6 +92,12 @@ the default value cannot be confused with the values of set entries.</p> </desc> </datatype> <datatype> + <name name="array" n_vars="0"/> + <desc> + <p><c>array()</c> is equivalent to <c>array(term())</c>.</p> + </desc> + </datatype> + <datatype> <name name="array_indx"/> </datatype> <datatype> @@ -189,7 +195,7 @@ the default value cannot be confused with the values of set entries.</p> <desc><marker id="from_orddict-2"/> -<p>Convert an ordered list of pairs <c>{Index, Value}</c> to a +<p>Convert an ordered list of pairs <c>{Index, <anno>Value</anno>}</c> to a corresponding extendible array. <c><anno>Default</anno></c> is used as the value for uninitialized entries of the array. If <c><anno>Orddict</anno></c> is not a proper, ordered list of pairs whose first elements are nonnegative @@ -455,7 +461,7 @@ cannot be changed once the array has been created.</p> <desc><marker id="sparse_to_orddict-1"/> -<p>Convert the array to an ordered list of pairs <c>{Index, Value}</c>, +<p>Convert the array to an ordered list of pairs <c>{Index, <anno>Value</anno>}</c>, skipping default-valued entries. </p> <p><em>See also:</em> <seealso marker="#to_orddict-1">to_orddict/1</seealso>.</p> @@ -476,7 +482,7 @@ cannot be changed once the array has been created.</p> <desc><marker id="to_orddict-1"/> -<p>Convert the array to an ordered list of pairs <c>{Index, Value}</c>. +<p>Convert the array to an ordered list of pairs <c>{Index, <anno>Value</anno>}</c>. </p> <p><em>See also:</em> <seealso marker="#from_orddict-2">from_orddict/2</seealso>, <seealso marker="#sparse_to_orddict-1">sparse_to_orddict/1</seealso>.</p> </desc></func></funcs> diff --git a/lib/stdlib/doc/src/base64.xml b/lib/stdlib/doc/src/base64.xml index bfe8494a73..c4982f4eaa 100644 --- a/lib/stdlib/doc/src/base64.xml +++ b/lib/stdlib/doc/src/base64.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2007</year><year>2011</year> + <year>2007</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -37,6 +37,11 @@ <datatype> <name name="ascii_string"/> </datatype> + <datatype> + <name name="ascii_binary"/> + <desc><p>A <c>binary()</c> with ASCII characters in the range 1 to 255.</p> + </desc> + </datatype> </datatypes> <funcs> <func> diff --git a/lib/stdlib/doc/src/beam_lib.xml b/lib/stdlib/doc/src/beam_lib.xml index db65eb3848..eb4974a79f 100644 --- a/lib/stdlib/doc/src/beam_lib.xml +++ b/lib/stdlib/doc/src/beam_lib.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2000</year><year>2011</year> + <year>2000</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/binary.xml b/lib/stdlib/doc/src/binary.xml index 7b8e279788..2410f1f9b8 100644 --- a/lib/stdlib/doc/src/binary.xml +++ b/lib/stdlib/doc/src/binary.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>2009</year> - <year>2012</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -77,41 +77,30 @@ </datatypes> <funcs> <func> - <name>at(Subject, Pos) -> byte()</name> + <name name="at" arity="2"/> <fsummary>Returns the byte at a specific position in a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pos = integer() >= 0</v> - </type> <desc> - <p>Returns the byte at position <c>Pos</c> (zero-based) in the binary - <c>Subject</c> as an integer. If <c>Pos</c> >= <c>byte_size(Subject)</c>, + <p>Returns the byte at position <c><anno>Pos</anno></c> (zero-based) in the binary + <c><anno>Subject</anno></c> as an integer. If <c><anno>Pos</anno></c> >= <c>byte_size(<anno>Subject</anno>)</c>, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>bin_to_list(Subject) -> [byte()]</name> + <name name="bin_to_list" arity="1"/> <fsummary>Convert a binary to a list of integers</fsummary> - <type> - <v>Subject = binary()</v> - </type> <desc> - <p>The same as <c>bin_to_list(Subject,{0,byte_size(Subject)})</c>.</p> + <p>The same as <c>bin_to_list(<anno>Subject</anno>,{0,byte_size(<anno>Subject</anno>)})</c>.</p> </desc> </func> <func> - <name>bin_to_list(Subject, PosLen) -> [byte()]</name> + <name name="bin_to_list" arity="2"/> <fsummary>Convert a binary to a list of integers</fsummary> - <type> - <v>Subject = binary()</v> - <v>PosLen = part()</v> - </type> <desc> - <p>Converts <c>Subject</c> to a list of <c>byte()</c>s, each representing + <p>Converts <c><anno>Subject</anno></c> to a list of <c>byte()</c>s, each representing the value of one byte. The <c>part()</c> denotes which part of the <c>binary()</c> to convert. Example:</p> @@ -120,27 +109,19 @@ "rla" %% or [114,108,97] in list notation. </code> - <p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> + <p>If <c><anno>PosLen</anno></c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>bin_to_list(Subject, Pos, Len) -> [byte()]</name> + <name name="bin_to_list" arity="3"/> <fsummary>Convert a binary to a list of integers</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pos = integer() >= 0</v> - <v>Len = integer() >= 0</v> - </type> <desc> - <p>The same as<c> bin_to_list(Subject,{Pos,Len})</c>.</p> + <p>The same as<c> bin_to_list(<anno>Subject</anno>,{<anno>Pos</anno>,<anno>Len</anno>})</c>.</p> </desc> </func> <func> - <name>compile_pattern(Pattern) -> cp()</name> + <name name="compile_pattern" arity="1"/> <fsummary>Pre-compiles a binary search pattern</fsummary> - <type> - <v>Pattern = binary() | [ binary() ]</v> - </type> <desc> <p>Builds an internal structure representing a compilation of a @@ -155,7 +136,7 @@ <p>When a list of binaries is given, it denotes a set of alternative binaries to search for. I.e if <c>[<<"functional">>,<<"programming">>]</c> - is given as <c>Pattern</c>, this + is given as <c><anno>Pattern</anno></c>, this means "either <c><<"functional">></c> or <c><<"programming">></c>". The pattern is a set of alternatives; when only a single binary is given, the set has @@ -163,32 +144,25 @@ <p>The list of binaries used for search alternatives shall be flat and proper.</p> - <p>If <c>Pattern</c> is not a binary or a flat proper list of binaries with length > 0, + <p>If <c><anno>Pattern</anno></c> is not a binary or a flat proper list of binaries with length > 0, a <c>badarg</c> exception will be raised.</p> </desc> </func> <func> - <name>copy(Subject) -> binary()</name> + <name name="copy" arity="1"/> <fsummary>Creates a duplicate of a binary</fsummary> - <type> - <v>Subject = binary()</v> - </type> <desc> - <p>The same as <c>copy(Subject, 1)</c>.</p> + <p>The same as <c>copy(<anno>Subject</anno>, 1)</c>.</p> </desc> </func> <func> - <name>copy(Subject,N) -> binary()</name> + <name name="copy" arity="2"/> <fsummary>Duplicates a binary N times and creates a new</fsummary> - <type> - <v>Subject = binary()</v> - <v>N = integer() >= 0</v> - </type> <desc> - <p>Creates a binary with the content of <c>Subject</c> duplicated <c>N</c> times.</p> + <p>Creates a binary with the content of <c><anno>Subject</anno></c> duplicated <c><anno>N</anno></c> times.</p> - <p>This function will always create a new binary, even if <c>N = + <p>This function will always create a new binary, even if <c><anno>N</anno> = 1</c>. By using <c>copy/1</c> on a binary referencing a larger binary, one might free up the larger binary for garbage collection.</p> @@ -201,32 +175,23 @@ large binaries are no longer used in any process, deliberate copying might be a good idea.</p> </note> - <p>If <c>N</c> < <c>0</c>, a <c>badarg</c> exception is raised.</p> + <p>If <c><anno>N</anno></c> < <c>0</c>, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>decode_unsigned(Subject) -> Unsigned</name> + <name name="decode_unsigned" arity="1"/> <fsummary>Decode a whole binary into an integer of arbitrary size</fsummary> - <type> - <v>Subject = binary()</v> - <v>Unsigned = integer() >= 0</v> - </type> <desc> - <p>The same as <c>decode_unsigned(Subject,big)</c>.</p> + <p>The same as <c>decode_unsigned(<anno>Subject</anno>, big)</c>.</p> </desc> </func> <func> - <name>decode_unsigned(Subject, Endianess) -> Unsigned</name> + <name name="decode_unsigned" arity="2"/> <fsummary>Decode a whole binary into an integer of arbitrary size</fsummary> - <type> - <v>Subject = binary()</v> - <v>Endianess = big | little</v> - <v>Unsigned = integer() >= 0</v> - </type> <desc> <p>Converts the binary digit representation, in big or little - endian, of a positive integer in <c>Subject</c> to an Erlang <c>integer()</c>.</p> + endian, of a positive integer in <c><anno>Subject</anno></c> to an Erlang <c>integer()</c>.</p> <p>Example:</p> @@ -237,22 +202,15 @@ </desc> </func> <func> - <name>encode_unsigned(Unsigned) -> binary()</name> + <name name="encode_unsigned" arity="1"/> <fsummary>Encodes an unsigned integer into the minimal binary</fsummary> - <type> - <v>Unsigned = integer() >= 0</v> - </type> <desc> - <p>The same as <c>encode_unsigned(Unsigned,big)</c>.</p> + <p>The same as <c>encode_unsigned(<anno>Unsigned</anno>, big)</c>.</p> </desc> </func> <func> - <name>encode_unsigned(Unsigned,Endianess) -> binary()</name> + <name name="encode_unsigned" arity="2"/> <fsummary>Encodes an unsigned integer into the minimal binary</fsummary> - <type> - <v>Unsigned = integer() >= 0</v> - <v>Endianess = big | little</v> - </type> <desc> <p>Converts a positive integer to the smallest possible @@ -268,51 +226,39 @@ </desc> </func> <func> - <name>first(Subject) -> byte()</name> + <name name="first" arity="1"/> <fsummary>Returns the first byte of a binary</fsummary> - <type> - <v>Subject = binary()</v> - </type> <desc> - <p>Returns the first byte of the binary <c>Subject</c> as an integer. If the - size of <c>Subject</c> is zero, a <c>badarg</c> exception is raised.</p> + <p>Returns the first byte of the binary <c><anno>Subject</anno></c> as an integer. If the + size of <c><anno>Subject</anno></c> is zero, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>last(Subject) -> byte()</name> + <name name="last" arity="1"/> <fsummary>Returns the last byte of a binary</fsummary> - <type> - <v>Subject = binary()</v> - </type> <desc> - <p>Returns the last byte of the binary <c>Subject</c> as an integer. If the - size of <c>Subject</c> is zero, a <c>badarg</c> exception is raised.</p> + <p>Returns the last byte of the binary <c><anno>Subject</anno></c> as an integer. If the + size of <c><anno>Subject</anno></c> is zero, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>list_to_bin(ByteList) -> binary()</name> + <name name="list_to_bin" arity="1"/> <fsummary>Convert a list of integers and binaries to a binary</fsummary> - <type> - <v>ByteList = iodata() (see module erlang)</v> - </type> <desc> <p>Works exactly as <c>erlang:list_to_binary/1</c>, added for completeness.</p> </desc> </func> <func> - <name>longest_common_prefix(Binaries) -> integer() >= 0</name> + <name name="longest_common_prefix" arity="1"/> <fsummary>Returns length of longest common prefix for a set of binaries</fsummary> - <type> - <v>Binaries = [ binary() ]</v> - </type> <desc> <p>Returns the length of the longest common prefix of the - binaries in the list <c>Binaries</c>. Example:</p> + binaries in the list <c><anno>Binaries</anno></c>. Example:</p> <code> 1> binary:longest_common_prefix([<<"erlang">>,<<"ergonomy">>]). @@ -321,19 +267,16 @@ 0 </code> - <p>If <c>Binaries</c> is not a flat list of binaries, a <c>badarg</c> exception is raised.</p> + <p>If <c><anno>Binaries</anno></c> is not a flat list of binaries, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>longest_common_suffix(Binaries) -> integer() >= 0</name> + <name name="longest_common_suffix" arity="1"/> <fsummary>Returns length of longest common suffix for a set of binaries</fsummary> - <type> - <v>Binaries = [ binary() ]</v> - </type> <desc> <p>Returns the length of the longest common suffix of the - binaries in the list <c>Binaries</c>. Example:</p> + binaries in the list <c><anno>Binaries</anno></c>. Example:</p> <code> 1> binary:longest_common_suffix([<<"erlang">>,<<"fang">>]). @@ -347,35 +290,24 @@ </desc> </func> <func> - <name>match(Subject, Pattern) -> Found | <c>nomatch</c></name> + <name name="match" arity="2"/> <fsummary>Searches for the first match of a pattern in a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pattern = binary() | [ binary() ] | cp()</v> - <v>Found = part()</v> - </type> <desc> - <p>The same as <c>match(Subject, Pattern, [])</c>.</p> + <p>The same as <c>match(<anno>Subject</anno>, <anno>Pattern</anno>, [])</c>.</p> </desc> </func> <func> - <name>match(Subject,Pattern,Options) -> Found | <c>nomatch</c></name> + <name name="match" arity="3"/> + <type name="part"/> <fsummary>Searches for the first match of a pattern in a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pattern = binary() | [ binary() ] | cp()</v> - <v>Found = part()</v> - <v>Options = [ Option ]</v> - <v>Option = {scope, part()}</v> - </type> <desc> - <p>Searches for the first occurrence of <c>Pattern</c> in <c>Subject</c> and + <p>Searches for the first occurrence of <c><anno>Pattern</anno></c> in <c><anno>Subject</anno></c> and returns the position and length.</p> - <p>The function will return <c>{Pos,Length}</c> for the binary - in <c>Pattern</c> starting at the lowest position in - <c>Subject</c>, Example:</p> + <p>The function will return <c>{Pos, Length}</c> for the binary + in <c><anno>Pattern</anno></c> starting at the lowest position in + <c><anno>Subject</anno></c>, Example:</p> <code> 1> binary:match(<<"abcde">>, [<<"bcde">>,<<"cd">>],[]). @@ -391,16 +323,16 @@ <p>Summary of the options:</p> <taglist> - <tag>{scope, {Start, Length}}</tag> + <tag>{scope, {<anno>Start</anno>, <anno>Length</anno>}}</tag> <item><p>Only the given part is searched. Return values still have - offsets from the beginning of <c>Subject</c>. A negative <c>Length</c> is - allowed as described in the <c>TYPES</c> section of this manual.</p></item> + offsets from the beginning of <c><anno>Subject</anno></c>. A negative <c>Length</c> is + allowed as described in the <c>DATA TYPES</c> section of this manual.</p></item> </taglist> <p>If none of the strings in - <c>Pattern</c> is found, the atom <c>nomatch</c> is returned.</p> + <c><anno>Pattern</anno></c> is found, the atom <c>nomatch</c> is returned.</p> - <p>For a description of <c>Pattern</c>, see + <p>For a description of <c><anno>Pattern</anno></c>, see <seealso marker="#compile_pattern-1">compile_pattern/1</seealso>.</p> <p>If <c>{scope, {Start,Length}}</c> is given in the options @@ -412,32 +344,21 @@ </desc> </func> <func> - <name>matches(Subject, Pattern) -> Found</name> + <name name="matches" arity="2"/> <fsummary>Searches for all matches of a pattern in a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pattern = binary() | [ binary() ] | cp()</v> - <v>Found = [ part() ] | []</v> - </type> <desc> - <p>The same as <c>matches(Subject, Pattern, [])</c>.</p> + <p>The same as <c>matches(<anno>Subject</anno>, <anno>Pattern</anno>, [])</c>.</p> </desc> </func> <func> - <name>matches(Subject,Pattern,Options) -> Found</name> + <name name="matches" arity="3"/> + <type name="part"/> <fsummary>Searches for all matches of a pattern in a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pattern = binary() | [ binary() ] | cp()</v> - <v>Found = [ part() ] | []</v> - <v>Options = [ Option ]</v> - <v>Option = {scope, part()}</v> - </type> <desc> - <p>Works like match, but the <c>Subject</c> is searched until + <p>Works like <c>match/2</c>, but the <c><anno>Subject</anno></c> is searched until exhausted and a list of all non-overlapping parts matching - <c>Pattern</c> is returned (in order). </p> + <c><anno>Pattern</anno></c> is returned (in order). </p> <p>The first and longest match is preferred to a shorter, which is illustrated by the following example:</p> @@ -458,26 +379,22 @@ <p>If none of the strings in pattern is found, an empty list is returned.</p> - <p>For a description of <c>Pattern</c>, see <seealso marker="#compile_pattern-1">compile_pattern/1</seealso> and for a + <p>For a description of <c><anno>Pattern</anno></c>, see <seealso marker="#compile_pattern-1">compile_pattern/1</seealso> and for a description of available options, see <seealso marker="#match-3">match/3</seealso>.</p> - <p>If <c>{scope, {Start,Length}}</c> is given in the options such that - <c>Start</c> is larger than the size of <c>Subject</c>, <c>Start + Length</c> is - less than zero or <c>Start + Length</c> is larger than the size of - <c>Subject</c>, a <c>badarg</c> exception is raised.</p> + <p>If <c>{scope, {<anno>Start</anno>,<anno>Length</anno>}}</c> is given in the options such that + <c><anno>Start</anno></c> is larger than the size of <c><anno>Subject</anno></c>, <c><anno>Start</anno> + <anno>Length</anno></c> is + less than zero or <c><anno>Start</anno> + <anno>Length</anno></c> is larger than the size of + <c><anno>Subject</anno></c>, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>part(Subject, PosLen) -> binary()</name> + <name name="part" arity="2"/> <fsummary>Extracts a part of a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>PosLen = part()</v> - </type> <desc> - <p>Extracts the part of the binary <c>Subject</c> described by <c>PosLen</c>.</p> + <p>Extracts the part of the binary <c><anno>Subject</anno></c> described by <c><anno>PosLen</anno></c>.</p> <p>Negative length can be used to extract bytes at the end of a binary:</p> @@ -494,25 +411,20 @@ <c>binary_part/3</c>. Those BIFs are allowed in guard tests.</p> </note> - <p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception + <p>If <c><anno>PosLen</anno></c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>part(Subject, Pos, Len) -> binary()</name> + <name name="part" arity="3"/> <fsummary>Extracts a part of a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pos = integer() >= 0</v> - <v>Len = integer()</v> - </type> <desc> - <p>The same as <c>part(Subject, {Pos, Len})</c>.</p> + <p>The same as <c>part(<anno>Subject</anno>, {<anno>Pos</anno>, <anno>Len</anno>})</c>.</p> </desc> </func> <func> - <name>referenced_byte_size(binary()) -> integer() >= 0</name> + <name name="referenced_byte_size" arity="1"/> <fsummary>Determines the size of the actual binary pointed out by a sub-binary</fsummary> <desc> diff --git a/lib/stdlib/doc/src/book.xml b/lib/stdlib/doc/src/book.xml index 10ee6f3855..b1b67d661c 100644 --- a/lib/stdlib/doc/src/book.xml +++ b/lib/stdlib/doc/src/book.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE book SYSTEM "book.dtd"> <book xmlns:xi="http://www.w3.org/2001/XInclude"> <header titlestyle="normal"> <copyright> - <year>1997</year><year>2009</year> + <year>1997</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/c.xml b/lib/stdlib/doc/src/c.xml index ddae388a1b..b49fa6ad67 100644 --- a/lib/stdlib/doc/src/c.xml +++ b/lib/stdlib/doc/src/c.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -140,9 +140,9 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> <name name="ls" arity="1"/> - <fsummary>List files in a directory</fsummary> + <fsummary>List files in a directory or a single file</fsummary> <desc> - <p>Lists files in directory <c><anno>Dir</anno></c>.</p> + <p>Lists files in directory <c><anno>Dir</anno></c> or, if Dir is a file, only list it.</p> </desc> </func> <func> diff --git a/lib/stdlib/doc/src/calendar.xml b/lib/stdlib/doc/src/calendar.xml index f8db48e00c..e32a639b81 100644 --- a/lib/stdlib/doc/src/calendar.xml +++ b/lib/stdlib/doc/src/calendar.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/dets.xml b/lib/stdlib/doc/src/dets.xml index 215ec154ed..6bbedb0662 100644 --- a/lib/stdlib/doc/src/dets.xml +++ b/lib/stdlib/doc/src/dets.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml index b01acd02bf..942fd1f45e 100644 --- a/lib/stdlib/doc/src/dict.xml +++ b/lib/stdlib/doc/src/dict.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -41,9 +41,15 @@ <datatypes> <datatype> - <name><marker id="type-dict">dict()</marker></name> + <name name="dict" n_vars="2"/> <desc><p>Dictionary as returned by <c>new/0</c>.</p></desc> </datatype> + <datatype> + <name name="dict" n_vars="0"/> + <desc> + <p><c>dict()</c> is equivalent to <c>dict(term(), term())</c>.</p> + </desc> + </datatype> </datatypes> <funcs> <func> @@ -177,6 +183,13 @@ merge(Fun, D1, D2) -> </desc> </func> <func> + <name name="is_empty" arity="1"/> + <fsummary>Return true if the dictionary is empty</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>Dict</anno></c> has no elements, <c>false</c> otherwise.</p> + </desc> + </func> + <func> <name name="store" arity="3"/> <fsummary>Store a value in a dictionary</fsummary> <desc> diff --git a/lib/stdlib/doc/src/digraph.xml b/lib/stdlib/doc/src/digraph.xml index 0afc70ebe0..9b9b48584b 100644 --- a/lib/stdlib/doc/src/digraph.xml +++ b/lib/stdlib/doc/src/digraph.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -98,7 +98,7 @@ <name name="d_protection"/> </datatype> <datatype> - <name><marker id="type-digraph">digraph()</marker></name> + <name name="graph"/> <desc><p>A digraph as returned by <c>new/0,1</c>.</p></desc> </datatype> <datatype> diff --git a/lib/stdlib/doc/src/digraph_utils.xml b/lib/stdlib/doc/src/digraph_utils.xml index ef6e1cb46f..ef6f9d8611 100644 --- a/lib/stdlib/doc/src/digraph_utils.xml +++ b/lib/stdlib/doc/src/digraph_utils.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2000</year><year>2012</year> + <year>2000</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/epp.xml b/lib/stdlib/doc/src/epp.xml index 386ed89fe1..452341f7d2 100644 --- a/lib/stdlib/doc/src/epp.xml +++ b/lib/stdlib/doc/src/epp.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2012</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -37,6 +37,20 @@ <p>The Erlang code preprocessor includes functions which are used by <c>compile</c> to preprocess macros and include files before the actual parsing takes place.</p> + <p>The Erlang source file <marker + id="encoding"><em>encoding</em></marker> is selected by a + comment in one of the first two lines of the source file. The + first string that matches the regular expression + <c>coding\s*[:=]\s*([-a-zA-Z0-9])+</c> selects the encoding. If + the matching string is not a valid encoding it is ignored. The + valid encodings are <c>Latin-1</c> and <c>UTF-8</c> where the + case of the characters can be chosen freely. Examples:</p> + <pre> +%% coding: utf-8</pre> + <pre> +%% For this file we have chosen encoding = Latin-1</pre> + <pre> +%% -*- coding: latin-1 -*-</pre> </description> <datatypes> <datatype> @@ -46,14 +60,35 @@ <name name="epp_handle"></name> <desc><p>Handle to the epp server.</p></desc> </datatype> + <datatype> + <name name="source_encoding"></name> + </datatype> </datatypes> <funcs> <func> + <name name="open" arity="1"/> + <fsummary>Open a file for preprocessing</fsummary> + <desc> + <p>Opens a file for preprocessing.</p> + <p>If <c>extra</c> is given in + <c><anno>Options</anno></c>, the return value will be + <c>{ok, <anno>Epp</anno>, <anno>Extra</anno>}</c> instead + of <c>{ok, <anno>Epp</anno>}</c>.</p> + </desc> + </func> + <func> <name name="open" arity="2"/> + <fsummary>Open a file for preprocessing</fsummary> + <desc> + <p>Equivalent to <c>epp:open([{name, FileName}, {includes, IncludePath}])</c>.</p> + </desc> + </func> + <func> <name name="open" arity="3"/> <fsummary>Open a file for preprocessing</fsummary> <desc> - <p>Opens a file for preprocessing.</p> + <p>Equivalent to <c>epp:open([{name, FileName}, {includes, IncludePath}, + {macros, PredefMacros}])</c>.</p> </desc> </func> <func> @@ -74,12 +109,99 @@ </desc> </func> <func> - <name name="parse_file" arity="3"/> + <name name="parse_file" arity="2"/> <fsummary>Preprocess and parse an Erlang source file</fsummary> <desc> <p>Preprocesses and parses an Erlang source file. - Note that the tuple <c>{eof, <anno>Line</anno>}</c> returned at end-of-file is - included as a "form".</p> + Note that the tuple <c>{eof, <anno>Line</anno>}</c> returned + at end-of-file is included as a "form".</p> + <p>If <c>extra</c> is given in + <c><anno>Options</anno></c>, the return value will be + <c>{ok, [<anno>Form</anno>], <anno>Extra</anno>}</c> instead + of <c>{ok, [<anno>Form</anno>]}</c>.</p> + </desc> + </func> + <func> + <name name="parse_file" arity="3"/> + <fsummary>Preprocess and parse an Erlang source file</fsummary> + <desc> + <p>Equivalent to <c>epp:parse_file(FileName, [{includes, IncludePath}, + {macros, PredefMacros}])</c>.</p> + </desc> + </func> + <func> + <name name="default_encoding" arity="0"/> + <fsummary>Return the default encoding of Erlang source files</fsummary> + <desc> + <p>Returns the default encoding of Erlang source files.</p> + </desc> + </func> + <func> + <name name="encoding_to_string" arity="1"/> + <fsummary>Return a string representation of an encoding</fsummary> + <desc> + <p>Returns a string representation of an encoding. The string + is recognized by <c>read_encoding/1,2</c>, + <c>read_encoding_from_binary/1,2</c>, and + <c>set_encoding/1,2</c> as a valid encoding.</p> + </desc> + </func> + <func> + <name name="read_encoding" arity="1"/> + <name name="read_encoding" arity="2"/> + <fsummary>Read the encoding from a file</fsummary> + <desc> + <p>Read the <seealso marker="#encoding">encoding</seealso> from + a file. Returns the read encoding, or <c>none</c> if no + valid encoding was found.</p> + <p>The option <c>in_comment_only</c> is <c>true</c> by + default, which is correct for Erlang source files. If set to + <c>false</c> the encoding string does not necessarily have to + occur in a comment.</p> + </desc> + </func> + <func> + <name name="read_encoding_from_binary" arity="1"/> + <name name="read_encoding_from_binary" arity="2"/> + <fsummary>Read the encoding from a binary</fsummary> + <desc> + <p>Read the <seealso marker="#encoding">encoding</seealso> from + a binary. Returns the read encoding, or <c>none</c> if no + valid encoding was found.</p> + <p>The option <c>in_comment_only</c> is <c>true</c> by + default, which is correct for Erlang source files. If set to + <c>false</c> the encoding string does not necessarily have to + occur in a comment.</p> + </desc> + </func> + <func> + <name name="set_encoding" arity="1"/> + <fsummary>Read and set the encoding of an IO device</fsummary> + <desc> + <p>Reads the <seealso marker="#encoding">encoding</seealso> from + an IO device and sets the encoding of the device + accordingly. The position of the IO device referenced by + <c><anno>File</anno></c> is not affected. If no valid + encoding can be read from the IO device the encoding of the + IO device is set to the default encoding.</p> + <p>Returns the read encoding, or <c>none</c> if no valid + encoding was found.</p> + </desc> + </func> + <func> + <name name="set_encoding" arity="2"/> + <fsummary>Read and set the encoding of an IO device</fsummary> + <desc> + <p>Reads the <seealso marker="#encoding">encoding</seealso> from + an IO device and sets the encoding of the device + accordingly. The position of the IO device referenced by + <c><anno>File</anno></c> is not affected. If no valid + encoding can be read from the IO device the encoding of the + IO device is set to the + <seealso marker="#encoding">encoding</seealso> given by + <c><anno>Default</anno></c>.</p> + <p>Returns the read encoding, or <c>none</c> if no valid + encoding was found.</p> </desc> </func> <func> diff --git a/lib/stdlib/doc/src/erl_eval.xml b/lib/stdlib/doc/src/erl_eval.xml index d0622594d9..b707dbcc02 100644 --- a/lib/stdlib/doc/src/erl_eval.xml +++ b/lib/stdlib/doc/src/erl_eval.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -288,10 +288,7 @@ Func(FuncSpec, Arguments) </code> <section> <title>Bugs</title> - <p>The evaluator is not complete. <c>receive</c> cannot be - handled properly. - </p> - <p>Any undocumented functions in <c>erl_eval</c> should not be used.</p> + <p>Undocumented functions in <c>erl_eval</c> should not be used.</p> </section> </erlref> diff --git a/lib/stdlib/doc/src/erl_expand_records.xml b/lib/stdlib/doc/src/erl_expand_records.xml index 8ead438b31..1b5ee5de36 100644 --- a/lib/stdlib/doc/src/erl_expand_records.xml +++ b/lib/stdlib/doc/src/erl_expand_records.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>2005</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/erl_id_trans.xml b/lib/stdlib/doc/src/erl_id_trans.xml index 18cc2460f9..0f7042f0c6 100644 --- a/lib/stdlib/doc/src/erl_id_trans.xml +++ b/lib/stdlib/doc/src/erl_id_trans.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/erl_internal.xml b/lib/stdlib/doc/src/erl_internal.xml index b8d5ad73b3..54e560f8b9 100644 --- a/lib/stdlib/doc/src/erl_internal.xml +++ b/lib/stdlib/doc/src/erl_internal.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/erl_lint.xml b/lib/stdlib/doc/src/erl_lint.xml index b7fbdd8799..1ca58baf9a 100644 --- a/lib/stdlib/doc/src/erl_lint.xml +++ b/lib/stdlib/doc/src/erl_lint.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/erl_parse.xml b/lib/stdlib/doc/src/erl_parse.xml index bafc2e0746..cf0bff48cd 100644 --- a/lib/stdlib/doc/src/erl_parse.xml +++ b/lib/stdlib/doc/src/erl_parse.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -167,6 +167,29 @@ <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an abstract form of type <c><anno>AbsTerm</anno></c>. This is the inverse of <c>normalise/1</c>.</p> + <p><c>erl_parse:abstract(T)</c> is equivalent to + <c>erl_parse:abstract(T, 0)</c>.</p> + </desc> + </func> + <func> + <name name="abstract" arity="2"/> + <type name="encoding_func"/> + <fsummary>Convert an Erlang term into an abstract form</fsummary> + <desc> + <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an + abstract form of type <c><anno>AbsTerm</anno></c>.</p> + <p>The <c><anno>Line</anno></c> option is the line that will + be assigned to each node of the abstract form.</p> + <p>The <c><anno>Encoding</anno></c> option is used for + selecting which integer lists will be considered + as strings. The default is to use the encoding returned by + <seealso marker="epp#default_encoding/0"> + <c>epp:default_encoding/0</c></seealso>. + The value <c>none</c> means that no integer lists will be + considered as strings. The <c>encoding_func()</c> will be + called with one integer of a list at a time, and if it + returns <c>true</c> for every integer the list will be + considered a string.</p> </desc> </func> </funcs> diff --git a/lib/stdlib/doc/src/erl_pp.xml b/lib/stdlib/doc/src/erl_pp.xml index 57b5828bcd..005c101973 100644 --- a/lib/stdlib/doc/src/erl_pp.xml +++ b/lib/stdlib/doc/src/erl_pp.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -63,6 +63,12 @@ breaks and only a space is used as a separator.</p> </desc> </datatype> + <datatype> + <name name="option"/> + </datatype> + <datatype> + <name name="options"/> + </datatype> </datatypes> <funcs> <func> diff --git a/lib/stdlib/doc/src/erl_scan.xml b/lib/stdlib/doc/src/erl_scan.xml index 54240dea19..855c8fc195 100644 --- a/lib/stdlib/doc/src/erl_scan.xml +++ b/lib/stdlib/doc/src/erl_scan.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/erl_tar.xml b/lib/stdlib/doc/src/erl_tar.xml index fe166dbd01..7f25f5b7bc 100644 --- a/lib/stdlib/doc/src/erl_tar.xml +++ b/lib/stdlib/doc/src/erl_tar.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2003</year><year>2011</year> + <year>2003</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -35,10 +35,11 @@ <modulesummary>Unix 'tar' utility for reading and writing tar archives</modulesummary> <description> <p>The <c>erl_tar</c> module archives and extract files to and from - a tar file. The tar file format is the POSIX extended tar file format - specified in IEEE Std 1003.1 and ISO/IEC 9945-1. That is the same - format as used by <c>tar</c> program on Solaris, but is not the same - as used by the GNU tar program.</p> + a tar file. <c>erl_tar</c> supports the <c>ustar</c> format + (IEEE Std 1003.1 and ISO/IEC 9945-1). All modern <c>tar</c> + programs (including GNU tar) can read this format. To ensure that + that GNU tar produces a tar file that <c>erl_tar</c> can read, + give the <c>--format=ustar</c> option to GNU tar.</p> <p>By convention, the name of a tar file should end in "<c>.tar</c>". To abide to the convention, you'll need to add "<c>.tar</c>" yourself to the name.</p> @@ -65,6 +66,20 @@ </description> <section> + <title>UNICODE SUPPORT</title> + <p>If <seealso + marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso> + returns <c>utf8</c>, path names will be encoded in UTF-8 when + creating tar files and path names will be assumed to be encoded in + UTF-8 when extracting tar files.</p> + + <p>If <seealso + marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso> + returns <c>latin1</c>, no translation of path names will be + done.</p> + </section> + + <section> <title>LIMITATIONS</title> <p>For maximum compatibility, it is safe to archive files with names up to 100 characters in length. Such tar files can generally be @@ -112,8 +127,8 @@ <fsummary>Add a file to an open tar file</fsummary> <type> <v>TarDescriptor = term()</v> - <v>FilenameOrBin = Filename()|binary()</v> - <v>Filename = filename()()</v> + <v>FilenameOrBin = filename()|binary()</v> + <v>Filename = filename()</v> <v>NameInArchive = filename()</v> <v>Options = [Option]</v> <v>Option = dereference|verbose</v> diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 487b06473f..3df24bf688 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2012</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -128,11 +128,17 @@ <datatypes> <datatype> + <name name="access"/> + </datatype> + <datatype> <name><marker id="type-continuation">continuation()</marker></name> <desc> <p>Opaque continuation used by <seealso marker="#select/1"> - <c>select/1</c></seealso> and <seealso marker="#select/3"> - <c>select/3</c></seealso>.</p> + <c>select/1,3</c></seealso>, <seealso marker="#select_reverse/1"> + <c>select_reverse/1,3</c></seealso>, <seealso + marker="#match/1"> + <c>match/1,3</c></seealso>, and <seealso marker="#match_object/1"> + <c>match_object/1,3</c></seealso>.</p> </desc> </datatype> <datatype> @@ -140,6 +146,10 @@ <desc><p>A match specification, see above.</p></desc> </datatype> <datatype> + <name name="comp_match_spec"/> + <desc><p>A compiled match specification.</p></desc> + </datatype> + <datatype> <name name="match_pattern"/> </datatype> <datatype> @@ -149,63 +159,53 @@ <name name="tid"/> <desc><p>A table identifier, as returned by new/2.</p></desc> </datatype> + <datatype> + <name name="type"/> + </datatype> </datatypes> <funcs> <func> - <name>all() -> [Tab]</name> + <name name="all" arity="0"/> <fsummary>Return a list of all ETS tables.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - </type> <desc> <p>Returns a list of all tables at the node. Named tables are given by their names, unnamed tables are given by their table identifiers.</p> + <p>There is no guarantee of consistency in the returned list. Tables created + or deleted by other processes "during" the ets:all() call may or may + not be included in the list. Only tables created/deleted <em>before</em> + ets:all() is called are guaranteed to be included/excluded.</p> </desc> </func> <func> - <name>delete(Tab) -> true</name> + <name name="delete" arity="1"/> <fsummary>Delete an entire ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - </type> <desc> - <p>Deletes the entire table <c>Tab</c>.</p> + <p>Deletes the entire table <c><anno>Tab</anno></c>.</p> </desc> </func> <func> - <name>delete(Tab, Key) -> true</name> + <name name="delete" arity="2"/> <fsummary>Delete all objects with a given key from an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - </type> <desc> - <p>Deletes all objects with the key <c>Key</c> from the table - <c>Tab</c>.</p> + <p>Deletes all objects with the key <c><anno>Key</anno></c> from the table + <c><anno>Tab</anno></c>.</p> </desc> </func> <func> - <name>delete_all_objects(Tab) -> true</name> + <name name="delete_all_objects" arity="1"/> <fsummary>Delete all objects in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - </type> <desc> - <p>Delete all objects in the ETS table <c>Tab</c>. + <p>Delete all objects in the ETS table <c><anno>Tab</anno></c>. The operation is guaranteed to be <seealso marker="#concurrency">atomic and isolated</seealso>.</p> </desc> </func> <func> - <name>delete_object(Tab,Object) -> true</name> + <name name="delete_object" arity="2"/> <fsummary>Deletes a specific from an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Object = tuple()</v> - </type> <desc> - <p>Delete the exact object <c>Object</c> from the ETS table, + <p>Delete the exact object <c><anno>Object</anno></c> from the ETS table, leaving objects with the same key but other differences (useful for type <c>bag</c>). In a <c>duplicate_bag</c>, all instances of the object will be deleted.</p> @@ -257,14 +257,10 @@ </desc> </func> <func> - <name>first(Tab) -> Key | '$end_of_table'</name> + <name name="first" arity="1"/> <fsummary>Return the first key in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - </type> <desc> - <p>Returns the first key <c>Key</c> in the table <c>Tab</c>. + <p>Returns the first key <c><anno>Key</anno></c> in the table <c><anno>Tab</anno></c>. If the table is of the <c>ordered_set</c> type, the first key in Erlang term order will be returned. If the table is of any other type, the first key according to the table's internal @@ -336,7 +332,7 @@ the source file.</p> <p>The fun is very restricted, it can take only a single parameter (the object to match): a sole variable or a - tuple. It needs to use the <c>is_</c>XXX guard tests. + tuple. It needs to use the <c>is_</c> guard tests. Language constructs that have no representation in a match_spec (like <c>if</c>, <c>case</c>, <c>receive</c> etc) are not allowed.</p> @@ -386,19 +382,14 @@ Error: fun containing local Erlang function calls </desc> </func> <func> - <name>give_away(Tab, Pid, GiftData) -> true</name> + <name name="give_away" arity="3"/> <fsummary>Change owner of a table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Pid = pid()</v> - <v>GiftData = term()</v> - </type> <desc> - <p>Make process <c>Pid</c> the new owner of table <c>Tab</c>. + <p>Make process <c><anno>Pid</anno></c> the new owner of table <c><anno>Tab</anno></c>. If successful, the message - <c>{'ETS-TRANSFER',Tab,FromPid,GiftData}</c> will be sent + <c>{'ETS-TRANSFER',<anno>Tab</anno>,FromPid,<anno>GiftData</anno>}</c> will be sent to the new owner.</p> - <p>The process <c>Pid</c> must be alive, local and not already the + <p>The process <c><anno>Pid</anno></c> must be alive, local and not already the owner of the table. The calling process must be the table owner.</p> <p>Note that <c>give_away</c> does not at all affect the <seealso marker="#heir">heir</seealso> option of the table. A table @@ -421,81 +412,72 @@ Error: fun containing local Erlang function calls </desc> </func> <func> - <name>info(Tab) -> [{Item, Value}] | undefined</name> + <name name="info" arity="1"/> <fsummary>Return information about an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Item = atom(), see below</v> - <v>Value = term(), see below</v> - </type> <desc> - <p>Returns information about the table <c>Tab</c> as a list of - <c>{Item, Value}</c> tuples. If <c>Tab</c> has the correct type + <p>Returns information about the table <c><anno>Tab</anno></c> as a list of + tuples. If <c><anno>Tab</anno></c> has the correct type for a table identifier, but does not refer to an existing ETS - table, <c>undefined</c> is returned. If <c>Tab</c> is not of the + table, <c>undefined</c> is returned. If <c><anno>Tab</anno></c> is not of the correct type, this function fails with reason <c>badarg</c>.</p> <list type="bulleted"> - <item><c>Item=memory, Value=integer()</c> <br></br> + <item><c>{compressed, boolean()}</c> <br></br> - The number of words allocated to the table.</item> - <item><c>Item=owner, Value=pid()</c> <br></br> - - The pid of the owner of the table.</item> - <item><c>Item=heir, Value=pid()|none</c> <br></br> + Indicates if the table is compressed or not.</item> + <item><c>{heir, pid() | none}</c> <br></br> The pid of the heir of the table, or <c>none</c> if no heir is set.</item> - <item><c>Item=name, Value=atom()</c> <br></br> + <item><c>{keypos, integer() >= 1}</c> <br></br> - The name of the table.</item> - <item><c>Item=size, Value=integer()</c> <br></br> + The key position.</item> + <item><c>{memory, integer() >= 0</c> <br></br> - The number of objects inserted in the table.</item> - <item><c>Item=node, Value=atom()</c> <br></br> + The number of words allocated to the table.</item> + <item><c>{name, atom()}</c> <br></br> - The node where the table is stored. This field is no longer - meaningful as tables cannot be accessed from other nodes.</item> - <item><c>Item=named_table, Value=true|false</c> <br></br> + The name of the table.</item> + <item><c>{named_table, boolean()}</c> <br></br> Indicates if the table is named or not.</item> - <item><c>Item=type, Value=set|ordered_set|bag|duplicate_bag</c> <br></br> + <item><c>{node, node()}</c> <br></br> - The table type.</item> - <item><c>Item=keypos, Value=integer()</c> <br></br> + The node where the table is stored. This field is no longer + meaningful as tables cannot be accessed from other nodes.</item> + <item><c>{owner, pid()}</c> <br></br> - The key position.</item> - <item><c>Item=protection, Value=public|protected|private</c> <br></br> + The pid of the owner of the table.</item> + <item><c>{protection, <seealso marker="#type-access">access()</seealso>}</c> <br></br> The table access rights.</item> - <item><c>Item=compressed, Value=true|false</c> <br></br> + <item><c>{size, integer() >= 0</c> <br></br> - Indicates if the table is compressed or not.</item> + The number of objects inserted in the table.</item> + <item><c>{type, <seealso marker="#type-type">type()</seealso>}</c> <br></br> + + The table type.</item> </list> </desc> </func> <func> - <name>info(Tab, Item) -> Value | undefined</name> + <name name="info" arity="2"/> <fsummary>Return the information associated with given item for an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Item, Value - see below</v> - </type> <desc> <p>Returns the information associated with <c>Item</c> for - the table <c>Tab</c>, or returns <c>undefined</c> if <c>Tab</c> + the table <c><anno>Tab</anno></c>, or returns <c>undefined</c> if <c>Tab</c> does not refer an existing ETS table. - If <c>Tab</c> is not of the correct type, or if <c>Item</c> is not + If <c><anno>Tab</anno></c> is not of the correct type, or if <c><anno>Item</anno></c> is not one of the allowed values, this function fails with reason <c>badarg</c>.</p> <warning><p>In R11B and earlier, this function would not fail but return <c>undefined</c> for invalid values for <c>Item</c>.</p> </warning> - <p>In addition to the <c>{Item,Value}</c> + <p>In addition to the <c>{<anno>Item</anno>,<anno>Value</anno>}</c> pairs defined for <c>info/1</c>, the following items are allowed:</p> <list type="bulleted"> - <item><c>Item=fixed, Value=true|false</c> <br></br> + <item><c>Item=fixed, Value=boolean()</c> <br></br> Indicates if the table is fixed by any process or not.</item> <item> @@ -547,15 +529,11 @@ Error: fun containing local Erlang function calls </desc> </func> <func> - <name>insert(Tab, ObjectOrObjects) -> true</name> + <name name="insert" arity="2"/> <fsummary>Insert an object into an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>ObjectOrObjects = tuple() | [tuple()]</v> - </type> <desc> <p>Inserts the object or all of the objects in the list - <c>ObjectOrObjects</c> into the table <c>Tab</c>. + <c><anno>ObjectOrObjects</anno></c> into the table <c><anno>Tab</anno></c>. If the table is a <c>set</c> and the key of the inserted objects <em>matches</em> the key of any object in the table, the old object will be replaced. If the table is an @@ -572,19 +550,15 @@ Error: fun containing local Erlang function calls </desc> </func> <func> - <name>insert_new(Tab, ObjectOrObjects) -> boolean()</name> + <name name="insert_new" arity="2"/> <fsummary>Insert an object into an ETS table if the key is not already present.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>ObjectOrObjects = tuple() | [tuple()]</v> - </type> <desc> <p>This function works exactly like <c>insert/2</c>, with the exception that instead of overwriting objects with the same key (in the case of <c>set</c> or <c>ordered_set</c>) or adding more objects with keys already existing in the table (in the case of <c>bag</c> and <c>duplicate_bag</c>), it - simply returns <c>false</c>. If <c>ObjectOrObjects</c> is a + simply returns <c>false</c>. If <c><anno>ObjectOrObjects</anno></c> is a list, the function checks <em>every</em> key prior to inserting anything. Nothing will be inserted if not <em>all</em> keys present in the list are absent from the @@ -593,11 +567,8 @@ Error: fun containing local Erlang function calls </desc> </func> <func> - <name>is_compiled_ms(Term) -> boolean()</name> + <name name="is_compiled_ms" arity="1"/> <fsummary>Checks if an Erlang term is the result of ets:match_spec_compile</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> <p>This function is used to check if a term is a valid compiled <seealso marker="#match_spec">match_spec</seealso>. @@ -626,14 +597,10 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>last(Tab) -> Key | '$end_of_table'</name> + <name name="last" arity="1"/> <fsummary>Return the last key in an ETS table of type<c>ordered_set</c>.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - </type> <desc> - <p>Returns the last key <c>Key</c> according to Erlang term + <p>Returns the last key <c><anno>Key</anno></c> according to Erlang term order in the table <c>Tab</c> of the <c>ordered_set</c> type. If the table is of any other type, the function is synonymous to <c>first/2</c>. If the table is empty, @@ -642,16 +609,11 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>lookup(Tab, Key) -> [Object]</name> + <name name="lookup" arity="2"/> <fsummary>Return all objects with a given key in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - <v>Object = tuple()</v> - </type> <desc> - <p>Returns a list of all objects with the key <c>Key</c> in - the table <c>Tab</c>.</p> + <p>Returns a list of all objects with the key <c><anno>Key</anno></c> in + the table <c><anno>Tab</anno></c>.</p> <p>In the case of <c>set, bag and duplicate_bag</c>, an object is returned only if the given key <em>matches</em> the key of the object in the table. If the table is an @@ -681,22 +643,16 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>lookup_element(Tab, Key, Pos) -> Elem</name> + <name name="lookup_element" arity="3"/> <fsummary>Return the <c>Pos</c>:th element of all objects with a given key in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - <v>Pos = integer()</v> - <v>Elem = term() | [term()]</v> - </type> <desc> - <p>If the table <c>Tab</c> is of type <c>set</c> or - <c>ordered_set</c>, the function returns the <c>Pos</c>:th - element of the object with the key <c>Key</c>.</p> + <p>If the table <c><anno>Tab</anno></c> is of type <c>set</c> or + <c>ordered_set</c>, the function returns the <c><anno>Pos</anno></c>:th + element of the object with the key <c><anno>Key</anno></c>.</p> <p>If the table is of type <c>bag</c> or <c>duplicate_bag</c>, - the functions returns a list with the <c>Pos</c>:th element of - every object with the key <c>Key</c>.</p> - <p>If no object with the key <c>Key</c> exists, the function + the functions returns a list with the <c><anno>Pos</anno></c>:th element of + every object with the key <c><anno>Key</anno></c>.</p> + <p>If no object with the key <c><anno>Key</anno></c> exists, the function will exit with reason <c>badarg</c>.</p> <p>The difference between <c>set</c>, <c>bag</c> and <c>duplicate_bag</c> on one hand, and <c>ordered_set</c> on @@ -708,16 +664,11 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match(Tab, Pattern) -> [Match]</name> + <name name="match" arity="2"/> <fsummary>Match the objects in an ETS table against a pattern.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Pattern = tuple()</v> - <v>Match = [term()]</v> - </type> <desc> - <p>Matches the objects in the table <c>Tab</c> against the - pattern <c>Pattern</c>.</p> + <p>Matches the objects in the table <c><anno>Tab</anno></c> against the + pattern <c><anno>Pattern</anno></c>.</p> <p>A pattern is a term that may contain:</p> <list type="bulleted"> <item>bound parts (Erlang terms),</item> @@ -744,18 +695,12 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match(Tab, Pattern, Limit) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="match" arity="3"/> <fsummary>Match the objects in an ETS table against a pattern and returns part of the answers.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Pattern = tuple()</v> - <v>Match = [term()]</v> - <v>Continuation = term()</v> - </type> <desc> <p>Works like <c>ets:match/2</c> but only returns a limited - (<c>Limit</c>) number of matching objects. The - <c>Continuation</c> term can then be used in subsequent calls + (<c><anno>Limit</anno></c>) number of matching objects. The + <c><anno>Continuation</anno></c> term can then be used in subsequent calls to <c>ets:match/1</c> to get the next chunk of matching objects. This is a space efficient way to work on objects in a table which is still faster than traversing the table object @@ -764,16 +709,12 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match(Continuation) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="match" arity="1"/> <fsummary>Continues matching objects in an ETS table.</fsummary> - <type> - <v>Match = [term()]</v> - <v>Continuation = term()</v> - </type> <desc> <p>Continues a match started with <c>ets:match/3</c>. The next chunk of the size given in the initial <c>ets:match/3</c> - call is returned together with a new <c>Continuation</c> + call is returned together with a new <c><anno>Continuation</anno></c> that can be used in subsequent calls to this function.</p> <p><c>'$end_of_table'</c> is returned when there are no more objects in the table.</p> @@ -789,15 +730,11 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match_object(Tab, Pattern) -> [Object]</name> + <name name="match_object" arity="2"/> <fsummary>Match the objects in an ETS table against a pattern.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Pattern = Object = tuple()</v> - </type> <desc> - <p>Matches the objects in the table <c>Tab</c> against the - pattern <c>Pattern</c>. See <c>match/2</c> for a description + <p>Matches the objects in the table <c><anno>Tab</anno></c> against the + pattern <c><anno>Pattern</anno></c>. See <c>match/2</c> for a description of patterns. The function returns a list of all objects which match the pattern.</p> <p>If the key is specified in the pattern, the match is very @@ -809,18 +746,12 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match_object(Tab, Pattern, Limit) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="match_object" arity="3"/> <fsummary>Match the objects in an ETS table against a pattern and returns part of the answers.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Pattern = tuple()</v> - <v>Match = [term()]</v> - <v>Continuation = term()</v> - </type> <desc> <p>Works like <c>ets:match_object/2</c> but only returns a - limited (<c>Limit</c>) number of matching objects. The - <c>Continuation</c> term can then be used in subsequent calls + limited (<c><anno>Limit</anno></c>) number of matching objects. The + <c><anno>Continuation</anno></c> term can then be used in subsequent calls to <c>ets:match_object/1</c> to get the next chunk of matching objects. This is a space efficient way to work on objects in a table which is still faster than traversing the table object @@ -829,29 +760,21 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match_object(Continuation) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="match_object" arity="1"/> <fsummary>Continues matching objects in an ETS table.</fsummary> - <type> - <v>Match = [term()]</v> - <v>Continuation = term()</v> - </type> <desc> <p>Continues a match started with <c>ets:match_object/3</c>. The next chunk of the size given in the initial <c>ets:match_object/3</c> call is returned together with a - new <c>Continuation</c> that can be used in subsequent calls + new <c><anno>Continuation</anno></c> that can be used in subsequent calls to this function.</p> <p><c>'$end_of_table'</c> is returned when there are no more objects in the table.</p> </desc> </func> <func> - <name>match_spec_compile(MatchSpec) -> CompiledMatchSpec</name> + <name name="match_spec_compile" arity="1"/> <fsummary>Compiles a match specification into its internal representation</fsummary> - <type> - <v>MatchSpec = match_spec()</v> - <v>CompiledMatchSpec = comp_match_spec()</v> - </type> <desc> <p>This function transforms a <seealso marker="#match_spec">match_spec</seealso> into an @@ -863,7 +786,7 @@ ets:is_compiled_ms(Broken).</code> valid compiled match_spec, nor can it be stored on disk). The validity of a compiled match_spec can be checked using <c>ets:is_compiled_ms/1</c>.</p> - <p>If the term <c>MatchSpec</c> can not be compiled (does not + <p>If the term <c><anno>MatchSpec</anno></c> can not be compiled (does not represent a valid match_spec), a <c>badarg</c> fault is thrown.</p> <note> @@ -873,25 +796,21 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match_spec_run(List,CompiledMatchSpec) -> list()</name> + <name name="match_spec_run" arity="2"/> <fsummary>Performs matching, using a compiled match_spec, on a list of tuples</fsummary> - <type> - <v>List = [ tuple() ]</v> - <v>CompiledMatchSpec = comp_match_spec()</v> - </type> <desc> <p>This function executes the matching specified in a compiled <seealso marker="#match_spec">match_spec</seealso> on - a list of tuples. The <c>CompiledMatchSpec</c> term should be + a list of tuples. The <c><anno>CompiledMatchSpec</anno></c> term should be the result of a call to <c>ets:match_spec_compile/1</c> and is hence the internal representation of the match_spec one wants to use.</p> - <p>The matching will be executed on each element in <c>List</c> + <p>The matching will be executed on each element in <c><anno>List</anno></c> and the function returns a list containing all results. If an - element in <c>List</c> does not match, nothing is returned + element in <c><anno>List</anno></c> does not match, nothing is returned for that element. The length of the result list is therefore equal or less than the the length of the parameter - <c>List</c>. The two calls in the following example will give + <c><anno>List</anno></c>. The two calls in the following example will give the same result (but certainly not the same execution time...):</p> <code type="none"> @@ -910,37 +829,23 @@ ets:select(Table,MatchSpec),</code> </desc> </func> <func> - <name>member(Tab, Key) -> true | false</name> + <name name="member" arity="2"/> <fsummary>Tests for occurrence of a key in an ETS table</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - </type> <desc> <p>Works like <c>lookup/2</c>, but does not return the objects. The function returns <c>true</c> if one or more elements in - the table has the key <c>Key</c>, <c>false</c> otherwise.</p> + the table has the key <c><anno>Key</anno></c>, <c>false</c> otherwise.</p> </desc> </func> <func> - <name>new(Name, Options) -> tid() | atom()</name> + <name name="new" arity="2"/> <fsummary>Create a new ETS table.</fsummary> - <type> - <v>Name = atom()</v> - <v>Options = [Option]</v> - <v> Option = Type | Access | named_table | {keypos,Pos} | {heir,pid(),HeirData} | {heir,none} | Tweaks</v> - <v> Type = set | ordered_set | bag | duplicate_bag</v> - <v> Access = public | protected | private</v> - <v> Tweaks = {write_concurrency,boolean()} | {read_concurrency,boolean()} | compressed</v> - <v> Pos = integer()</v> - <v> HeirData = term()</v> - </type> <desc> <p>Creates a new table and returns a table identifier which can be used in subsequent operations. The table identifier can be sent to other processes so that a table can be shared between different processes within a node.</p> - <p>The parameter <c>Options</c> is a list of atoms which + <p>The parameter <c><anno>Options</anno></c> is a list of atoms which specifies table type, access rights, key position and if the table is named or not. If one or more options are left out, the default values are used. This means that not specifying @@ -997,27 +902,27 @@ ets:select(Table,MatchSpec),</code> </item> <item> <p><c>named_table</c> - If this option is present, the name <c>Name</c> is + If this option is present, the name <c><anno>Name</anno></c> is associated with the table identifier. The name can then be used instead of the table identifier in subsequent operations.</p> </item> <item> - <p><c>{keypos,Pos}</c> + <p><c>{keypos,<anno>Pos</anno>}</c> Specfies which element in the stored tuples should be used as key. By default, it is the first element, i.e. - <c>Pos=1</c>. However, this is not always appropriate. In + <c><anno>Pos</anno>=1</c>. However, this is not always appropriate. In particular, we do not want the first element to be the key if we want to store Erlang records in a table.</p> <p>Note that any tuple stored in the table must have at - least <c>Pos</c> number of elements.</p> + least <c><anno>Pos</anno></c> number of elements.</p> </item> <item> <marker id="heir"></marker> - <p><c>{heir,Pid,HeirData} | {heir,none}</c><br></br> + <p><c>{heir,<anno>Pid</anno>,<anno>HeirData</anno>} | {heir,none}</c><br></br> Set a process as heir. The heir will inherit the table if the owner terminates. The message - <c>{'ETS-TRANSFER',tid(),FromPid,HeirData}</c> will be sent to + <c>{'ETS-TRANSFER',tid(),FromPid,<anno>HeirData</anno>}</c> will be sent to the heir when that happens. The heir must be a local process. Default heir is <c>none</c>, which will destroy the table when the owner terminates.</p> @@ -1031,7 +936,8 @@ ets:select(Table,MatchSpec),</code> If set to <c>true</c>, the table is optimized towards concurrent write access. Different objects of the same table can be mutated (and read) by concurrent processes. This is achieved to some degree - at the expense of sequential access and concurrent reader performance. + at the expense of memory consumption and the performance of + sequential access and concurrent reading. The <c>write_concurrency</c> option can be combined with the <seealso marker="#new_2_read_concurrency">read_concurrency</seealso> option. You typically want to combine these when large concurrent @@ -1043,8 +949,11 @@ ets:select(Table,MatchSpec),</code> <seealso marker="#concurrency">atomicy and isolation</seealso>. Functions that makes such promises over several objects (like <c>insert/2</c>) will gain less (or nothing) from this option.</p> - <p>Table type <c>ordered_set</c> is not affected by this option in current - implementation.</p> + <p>In current implementation, table type <c>ordered_set</c> is not + affected by this option. Also, the memory consumption inflicted by + both <c>write_concurrency</c> and <c>read_concurrency</c> is a + constant overhead per table. This overhead can be especially large + when both options are combined.</p> </item> <item> <marker id="new_2_read_concurrency"></marker> @@ -1082,15 +991,11 @@ ets:select(Table,MatchSpec),</code> </desc> </func> <func> - <name>next(Tab, Key1) -> Key2 | '$end_of_table'</name> + <name name="next" arity="2"/> <fsummary>Return the next key in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key1 = Key2 = term()</v> - </type> <desc> - <p>Returns the next key <c>Key2</c>, following the key - <c>Key1</c> in the table <c>Tab</c>. If the table is of the + <p>Returns the next key <c><anno>Key2</anno></c>, following the key + <c><anno>Key1</anno></c> in the table <c><anno>Tab</anno></c>. If the table is of the <c>ordered_set</c> type, the next key in Erlang term order is returned. If the table is of any other type, the next key according to the table's internal order is returned. If there @@ -1105,16 +1010,12 @@ ets:select(Table,MatchSpec),</code> </desc> </func> <func> - <name>prev(Tab, Key1) -> Key2 | '$end_of_table'</name> + <name name="prev" arity="2"/> <fsummary>Return the previous key in an ETS table of type<c>ordered_set</c>.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key1 = Key2 = term()</v> - </type> <desc> - <p>Returns the previous key <c>Key2</c>, preceding the key - <c>Key1</c> according the Erlang term order in the table - <c>Tab</c> of the <c>ordered_set</c> type. If the table is of + <p>Returns the previous key <c><anno>Key2</anno></c>, preceding the key + <c><anno>Key1</anno></c> according the Erlang term order in the table + <c><anno>Tab</anno></c> of the <c>ordered_set</c> type. If the table is of any other type, the function is synonymous to <c>next/2</c>. If there is no previous key, <c>'$end_of_table'</c> is returned.</p> @@ -1122,14 +1023,11 @@ ets:select(Table,MatchSpec),</code> </desc> </func> <func> - <name>rename(Tab, Name) -> Name</name> + <name name="rename" arity="2"/> <fsummary>Rename a named ETS table.</fsummary> - <type> - <v>Tab = Name = atom()</v> - </type> <desc> - <p>Renames the named table <c>Tab</c> to the new name - <c>Name</c>. Afterwards, the old name can not be used to + <p>Renames the named table <c><anno>Tab</anno></c> to the new name + <c><anno>Name</anno></c>. Afterwards, the old name can not be used to access the table. Renaming an unnamed table has no effect.</p> </desc> </func> @@ -1186,18 +1084,15 @@ ets:select(ets:repair_continuation(Broken,MS)).</code> </desc> </func> <func> - <name>safe_fixtable(Tab, true|false) -> true</name> + <name name="safe_fixtable" arity="2"/> <fsummary>Fix an ETS table for safe traversal.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - </type> <desc> <p>Fixes a table of the <c>set</c>, <c>bag</c> or <c>duplicate_bag</c> table type for safe traversal.</p> <p>A process fixes a table by calling - <c>safe_fixtable(Tab,true)</c>. The table remains fixed until + <c>safe_fixtable(<anno>Tab</anno>, true)</c>. The table remains fixed until the process releases it by calling - <c>safe_fixtable(Tab,false)</c>, or until the process + <c>safe_fixtable(<anno>Tab</anno>, false)</c>, or until the process terminates.</p> <p>If several processes fix a table, the table will remain fixed until all processes have released it (or terminated). @@ -1242,15 +1137,10 @@ clean_all_with_value(Tab,X,Key) -> </desc> </func> <func> - <name>select(Tab, MatchSpec) -> [Match]</name> + <name name="select" arity="2"/> <fsummary>Match the objects in an ETS table against a match_spec.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Match = term()</v> - <v>MatchSpec = match_spec()</v> - </type> <desc> - <p>Matches the objects in the table <c>Tab</c> using a + <p>Matches the objects in the table <c><anno>Tab</anno></c> using a <seealso marker="#match_spec">match_spec</seealso>. This is a more general call than the <c>ets:match/2</c> and <c>ets:match_object/2</c> calls. In its simplest forms the @@ -1337,18 +1227,12 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>select(Tab, MatchSpec, Limit) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="select" arity="3"/> <fsummary>Match the objects in an ETS table against a match_spec and returns part of the answers.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Match = term()</v> - <v>MatchSpec = match_spec()</v> - <v>Continuation = term()</v> - </type> <desc> <p>Works like <c>ets:select/2</c> but only returns a limited - (<c>Limit</c>) number of matching objects. The - <c>Continuation</c> term can then be used in subsequent calls + (<c><anno>Limit</anno></c>) number of matching objects. The + <c><anno>Continuation</anno></c> term can then be used in subsequent calls to <c>ets:select/1</c> to get the next chunk of matching objects. This is a space efficient way to work on objects in a table which is still faster than traversing the table object @@ -1357,33 +1241,23 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>select(Continuation) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="select" arity="1"/> <fsummary>Continue matching objects in an ETS table.</fsummary> - <type> - <v>Match = term()</v> - <v>Continuation = term()</v> - </type> <desc> <p>Continues a match started with <c>ets:select/3</c>. The next chunk of the size given in the initial <c>ets:select/3</c> - call is returned together with a new <c>Continuation</c> + call is returned together with a new <c><anno>Continuation</anno></c> that can be used in subsequent calls to this function.</p> <p><c>'$end_of_table'</c> is returned when there are no more objects in the table.</p> </desc> </func> <func> - <name>select_count(Tab, MatchSpec) -> NumMatched</name> + <name name="select_count" arity="2"/> <fsummary>Match the objects in an ETS table against a match_spec and returns the number of objects for which the match_spec returned 'true'</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Object = tuple()</v> - <v>MatchSpec = match_spec()</v> - <v>NumMatched = integer()</v> - </type> <desc> - <p>Matches the objects in the table <c>Tab</c> using a + <p>Matches the objects in the table <c><anno>Tab</anno></c> using a <seealso marker="#match_spec">match_spec</seealso>. If the match_spec returns <c>true</c> for an object, that object considered a match and is counted. For any other result from @@ -1396,16 +1270,10 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>select_delete(Tab, MatchSpec) -> NumDeleted</name> + <name name="select_delete" arity="2"/> <fsummary>Match the objects in an ETS table against a match_spec and deletes objects where the match_spec returns 'true'</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Object = tuple()</v> - <v>MatchSpec = match_spec()</v> - <v>NumDeleted = integer()</v> - </type> <desc> - <p>Matches the objects in the table <c>Tab</c> using a + <p>Matches the objects in the table <c><anno>Tab</anno></c> using a <seealso marker="#match_spec">match_spec</seealso>. If the match_spec returns <c>true</c> for an object, that object is removed from the table. For any other result from the @@ -1422,13 +1290,8 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>select_reverse(Tab, MatchSpec) -> [Match]</name> + <name name="select_reverse" arity="2"/> <fsummary>Match the objects in an ETS table against a match_spec.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Match = term()</v> - <v>MatchSpec = match_spec()</v> - </type> <desc> <p>Works like <c>select/2</c>, but returns the list in reverse @@ -1438,14 +1301,8 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>select_reverse(Tab, MatchSpec, Limit) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="select_reverse" arity="3"/> <fsummary>Match the objects in an ETS table against a match_spec and returns part of the answers.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Match = term()</v> - <v>MatchSpec = match_spec()</v> - <v>Continuation = term()</v> - </type> <desc> <p>Works like <c>select/3</c>, but for the <c>ordered_set</c> @@ -1456,18 +1313,14 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> <p>Note that this is <em>not</em> equivalent to reversing the result list of a <c>select/3</c> call, as the result list - is not only reversed, but also contains the last <c>Limit</c> + is not only reversed, but also contains the last <c><anno>Limit</anno></c> matching objects in the table, not the first.</p> </desc> </func> <func> - <name>select_reverse(Continuation) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="select_reverse" arity="1"/> <fsummary>Continue matching objects in an ETS table.</fsummary> - <type> - <v>Match = term()</v> - <v>Continuation = term()</v> - </type> <desc> <p>Continues a match started with @@ -1477,7 +1330,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> returned list will also contain objects with keys in reverse order.</p> - <p>For all other table types, the behaviour is exatly that of <c>select/1</c>.</p> + <p>For all other table types, the behaviour is exactly that of <c>select/1</c>.</p> <p>Example:</p> <code> 1> T = ets:new(x,[ordered_set]). @@ -1501,14 +1354,8 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>setopts(Tab, Opts) -> true</name> + <name name="setopts" arity="2"/> <fsummary>Set table options.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Opts = Opt | [Opt]</v> - <v>Opt = {heir,pid(),HeirData} | {heir,none}</v> - <v>HeirData = term()</v> - </type> <desc> <p>Set table options. The only option that currently is allowed to be set after the table has been created is @@ -1517,28 +1364,23 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>slot(Tab, I) -> [Object] | '$end_of_table'</name> + <name name="slot" arity="2"/> <fsummary>Return all objects in a given slot of an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>I = integer()</v> - <v>Object = tuple()</v> - </type> <desc> <p>This function is mostly for debugging purposes, Normally one should use <c>first/next</c> or <c>last/prev</c> instead.</p> - <p>Returns all objects in the <c>I</c>:th slot of the table - <c>Tab</c>. A table can be traversed by repeatedly calling - the function, starting with the first slot <c>I=0</c> and + <p>Returns all objects in the <c><anno>I</anno></c>:th slot of the table + <c><anno>Tab</anno></c>. A table can be traversed by repeatedly calling + the function, starting with the first slot <c><anno>I</anno>=0</c> and ending when <c>'$end_of_table'</c> is returned. The function will fail with reason <c>badarg</c> if the - <c>I</c> argument is out of range.</p> + <c><anno>I</anno></c> argument is out of range.</p> <p>Unless a table of type <c>set</c>, <c>bag</c> or <c>duplicate_bag</c> is protected using <c>safe_fixtable/2</c>, see above, a traversal may fail if concurrent updates are made to the table. If the table is of type <c>ordered_set</c>, the function returns a list - containing the <c>I</c>:th object in Erlang term order.</p> + containing the <c><anno>I</anno></c>:th object in Erlang term order.</p> </desc> </func> <func> @@ -1754,16 +1596,16 @@ true</pre> </desc> </func> <func> - <name>update_counter(Tab, Key, UpdateOp) -> Result</name> - <name>update_counter(Tab, Key, [UpdateOp]) -> [Result]</name> - <name>update_counter(Tab, Key, Incr) -> Result</name> + <name name="update_counter" arity="3" clause_i="1"/> + <name name="update_counter" arity="3" clause_i="2"/> + <name name="update_counter" arity="3" clause_i="3"/> + <type variable="Tab"/> + <type variable="Key"/> + <type variable="UpdateOp" name_i="1"/> + <type variable="Pos" name_i="1"/> + <type variable="Threshold" name_i="1"/> + <type variable="SetValue" name_i="1"/> <fsummary>Update a counter object in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - <v>UpdateOp = {Pos,Incr} | {Pos,Incr,Threshold,SetValue}</v> - <v>Pos = Incr = Threshold = SetValue = Result = integer()</v> - </type> <desc> <p>This function provides an efficient way to update one or more counters, without the hassle of having to look up an object, update @@ -1771,22 +1613,22 @@ true</pre> into the table again. (The update is done atomically; i.e. no process can access the ets table in the middle of the operation.) </p> - <p>It will destructively update the object with key <c>Key</c> - in the table <c>Tab</c> by adding <c>Incr</c> to the element - at the <c>Pos</c>:th position. The new counter value is + <p>It will destructively update the object with key <c><anno>Key</anno></c> + in the table <c><anno>Tab</anno></c> by adding <c><anno>Incr</anno></c> to the element + at the <c><anno>Pos</anno></c>:th position. The new counter value is returned. If no position is specified, the element directly following the key (<c><![CDATA[<keypos>+1]]></c>) is updated.</p> - <p>If a <c>Threshold</c> is specified, the counter will be - reset to the value <c>SetValue</c> if the following + <p>If a <c><anno>Threshold</anno></c> is specified, the counter will be + reset to the value <c><anno>SetValue</anno></c> if the following conditions occur:</p> <list type="bulleted"> - <item>The <c>Incr</c> is not negative (<c>>= 0</c>) and the - result would be greater than (<c>></c>) <c>Threshold</c></item> - <item>The <c>Incr</c> is negative (<c><![CDATA[< 0]]></c>) and the + <item>The <c><anno>Incr</anno></c> is not negative (<c>>= 0</c>) and the + result would be greater than (<c>></c>) <c><anno>Threshold</anno></c></item> + <item>The <c><anno>Incr</anno></c> is negative (<c><![CDATA[< 0]]></c>) and the result would be less than (<c><![CDATA[<]]></c>) - <c>Threshold</c></item> + <c><anno>Threshold</anno></c></item> </list> - <p>A list of <c>UpdateOp</c> can be supplied to do several update + <p>A list of <c><anno>UpdateOp</anno></c> can be supplied to do several update operations within the object. The operations are carried out in the order specified in the list. If the same counter position occurs more than one time in the list, the corresponding counter will thus @@ -1797,7 +1639,7 @@ true</pre> returned. If the function should fail, no updates will be done at all. </p> - <p>The given Key is used to identify the object by either + <p>The given <c><anno>Key</anno></c> is used to identify the object by either <em>matching</em> the key of an object in a <c>set</c> table, or <em>compare equal</em> to the key of an object in an <c>ordered_set</c> table (see @@ -1812,29 +1654,28 @@ true</pre> <item>the object has the wrong arity,</item> <item>the element to update is not an integer,</item> <item>the element to update is also the key, or,</item> - <item>any of <c>Pos</c>, <c>Incr</c>, <c>Threshold</c> or - <c>SetValue</c> is not an integer</item> + <item>any of <c><anno>Pos</anno></c>, <c><anno>Incr</anno></c>, <c><anno>Threshold</anno></c> or + <c><anno>SetValue</anno></c> is not an integer</item> </list> </desc> </func> <func> - <name>update_element(Tab, Key, {Pos,Value}) -> true | false</name> - <name>update_element(Tab, Key, [{Pos,Value}]) -> true | false</name> + <name name="update_element" arity="3" clause_i="1"/> + <name name="update_element" arity="3" clause_i="2"/> + <type variable="Tab"/> + <type variable="Key"/> + <type variable="Value"/> + <type variable="Pos"/> <fsummary>Updates the <c>Pos</c>:th element of the object with a given key in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = Value = term()</v> - <v>Pos = integer()</v> - </type> <desc> <p>This function provides an efficient way to update one or more elements within an object, without the hassle of having to look up, update and write back the entire object. </p> - <p>It will destructively update the object with key <c>Key</c> - in the table <c>Tab</c>. The element at the <c>Pos</c>:th position - will be given the value <c>Value</c>. </p> - <p>A list of <c>{Pos,Value}</c> can be supplied to update several + <p>It will destructively update the object with key <c><anno>Key</anno></c> + in the table <c><anno>Tab</anno></c>. The element at the <c><anno>Pos</anno></c>:th position + will be given the value <c><anno>Value</anno></c>. </p> + <p>A list of <c>{<anno>Pos</anno>,<anno>Value</anno>}</c> can be supplied to update several elements within the same object. If the same position occurs more than one in the list, the last value in the list will be written. If the list is empty or the function fails, no updates will be done at @@ -1842,9 +1683,9 @@ true</pre> can never see any intermediate results. </p> <p>The function returns <c>true</c> if an object with the key - <c>Key</c> was found, <c>false</c> otherwise. + <c><anno>Key</anno></c> was found, <c>false</c> otherwise. </p> - <p>The given Key is used to identify the object by either + <p>The given <c><anno>Key</anno></c> is used to identify the object by either <em>matching</em> the key of an object in a <c>set</c> table, or <em>compare equal</em> to the key of an object in an <c>ordered_set</c> table (see @@ -1855,7 +1696,7 @@ true</pre> <list type="bulleted"> <item>the table is not of type <c>set</c> or <c>ordered_set</c>,</item> - <item><c>Pos</c> is less than 1 or greater than the object + <item><c><anno>Pos</anno></c> is less than 1 or greater than the object arity, or,</item> <item>the element to update is also the key</item> </list> diff --git a/lib/stdlib/doc/src/fascicules.xml b/lib/stdlib/doc/src/fascicules.xml index b30d34186e..0ded9007e0 100644 --- a/lib/stdlib/doc/src/fascicules.xml +++ b/lib/stdlib/doc/src/fascicules.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE fascicules SYSTEM "fascicules.dtd"> <fascicules> diff --git a/lib/stdlib/doc/src/file_sorter.xml b/lib/stdlib/doc/src/file_sorter.xml index a6b3633066..16572df3c5 100644 --- a/lib/stdlib/doc/src/file_sorter.xml +++ b/lib/stdlib/doc/src/file_sorter.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2001</year><year>2011</year> + <year>2001</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml index f3079c7337..6fa39f97f6 100644 --- a/lib/stdlib/doc/src/filelib.xml +++ b/lib/stdlib/doc/src/filelib.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2003</year><year>2011</year> + <year>2003</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -36,8 +36,9 @@ <description> <p>This module contains utilities on a higher level than the <c>file</c> module.</p> - <p>The module supports Unicode file names, so that it will match against regular expressions given in Unicode and that it will find and process raw file names (i.e. files named in a way that does not confirm to the expected encoding).</p> - <p>If the VM operates in Unicode file naming mode on a machine with transparent file naming, the <c>fun()</c> provided to <c>fold_files/5</c> needs to be prepared to handle binary file names.</p> + <p>This module does not support "raw" file names (i.e. files whose names + do not comply with the expected encoding). Such files will be ignored + by the functions in this module.</p> <p>For more information about raw file names, see the <seealso marker="kernel:file">file</seealso> module.</p> </description> @@ -48,6 +49,12 @@ <datatype> <name name="dirname"/> </datatype> + <datatype> + <name name="dirname_all"/> + </datatype> + <datatype> + <name name="filename_all"/> + </datatype> </datatypes> <funcs> @@ -150,6 +157,11 @@ <p>Matches any number of characters up to the end of the filename, the next dot, or the next slash.</p> </item> + <tag>**</tag> + <item> + <p>Two adjacent <c>*</c>'s used as a single pattern will + match all files and zero or more directories and subdirectories.</p> + </item> <tag>[Character1,Character2,...]</tag> <item> <p>Matches any of the characters listed. Two characters @@ -192,6 +204,10 @@ <c>src</c> or <c>include</c> directories, use:</p> <code type="none"> filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}") </code> + <p>To find all <c>.erl</c> or <c>.hrl</c> files in any + subdirectory, use:</p> + <code type="none"> + filelib:wildcard("lib/**/*.{erl,hrl}") </code> </desc> </func> <func> diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index 9296319b83..49b652f969 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1997</year><year>2011</year> + <year>1997</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/gb_sets.xml b/lib/stdlib/doc/src/gb_sets.xml index f91fac9c82..ea96c14472 100644 --- a/lib/stdlib/doc/src/gb_sets.xml +++ b/lib/stdlib/doc/src/gb_sets.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2001</year><year>2011</year> + <year>2001</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -115,28 +115,40 @@ <datatypes> <datatype> - <name><marker id="type-gb_set">gb_set()</marker></name> + <name name="set" n_vars="1"/> <desc><p>A GB set.</p></desc> </datatype> <datatype> - <name name="iter"/> + <name name="set" n_vars="0"/> + <desc> + <p><c>set()</c> is equivalent to <c>set(term())</c>.</p> + </desc> + </datatype> + <datatype> + <name name="iter" n_vars="1"/> <desc><p>A GB set iterator.</p></desc> </datatype> + <datatype> + <name name="iter" n_vars="0"/> + <desc> + <p><c>iter()</c> is equivalent to <c>iter(term())</c>.</p> + </desc> + </datatype> </datatypes> <funcs> <func> <name name="add" arity="2"/> <name name="add_element" arity="2"/> - <fsummary>Add a (possibly existing) element to a gb_set</fsummary> + <fsummary>Add a (possibly existing) element to a set</fsummary> <desc> - <p>Returns a new gb_set formed from <c><anno>Set1</anno></c> with + <p>Returns a new set formed from <c><anno>Set1</anno></c> with <c><anno>Element</anno></c> inserted. If <c><anno>Element</anno></c> is already an element in <c><anno>Set1</anno></c>, nothing is changed.</p> </desc> </func> <func> <name name="balance" arity="1"/> - <fsummary>Rebalance tree representation of a gb_set</fsummary> + <fsummary>Rebalance tree representation of a set</fsummary> <desc> <p>Rebalances the tree representation of <c><anno>Set1</anno></c>. Note that this is rarely necessary, but may be motivated when a large @@ -148,9 +160,9 @@ </func> <func> <name name="delete" arity="2"/> - <fsummary>Remove an element from a gb_set</fsummary> + <fsummary>Remove an element from a set</fsummary> <desc> - <p>Returns a new gb_set formed from <c><anno>Set1</anno></c> with + <p>Returns a new set formed from <c><anno>Set1</anno></c> with <c><anno>Element</anno></c> removed. Assumes that <c><anno>Element</anno></c> is present in <c><anno>Set1</anno></c>.</p> </desc> @@ -158,9 +170,9 @@ <func> <name name="delete_any" arity="2"/> <name name="del_element" arity="2"/> - <fsummary>Remove a (possibly non-existing) element from a gb_set</fsummary> + <fsummary>Remove a (possibly non-existing) element from a set</fsummary> <desc> - <p>Returns a new gb_set formed from <c><anno>Set1</anno></c> with + <p>Returns a new set formed from <c><anno>Set1</anno></c> with <c><anno>Element</anno></c> removed. If <c><anno>Element</anno></c> is not an element in <c><anno>Set1</anno></c>, nothing is changed.</p> </desc> @@ -168,7 +180,7 @@ <func> <name name="difference" arity="2"/> <name name="subtract" arity="2"/> - <fsummary>Return the difference of two gb_sets</fsummary> + <fsummary>Return the difference of two sets</fsummary> <desc> <p>Returns only the elements of <c><anno>Set1</anno></c> which are not also elements of <c><anno>Set2</anno></c>.</p> @@ -177,14 +189,14 @@ <func> <name name="empty" arity="0"/> <name name="new" arity="0"/> - <fsummary>Return an empty gb_set</fsummary> + <fsummary>Return an empty set</fsummary> <desc> - <p>Returns a new empty gb_set.</p> + <p>Returns a new empty set.</p> </desc> </func> <func> <name name="filter" arity="2"/> - <fsummary>Filter gb_set elements</fsummary> + <fsummary>Filter set elements</fsummary> <desc> <p>Filters elements in <c><anno>Set1</anno></c> using predicate function <c><anno>Pred</anno></c>.</p> @@ -192,7 +204,7 @@ </func> <func> <name name="fold" arity="3"/> - <fsummary>Fold over gb_set elements</fsummary> + <fsummary>Fold over set elements</fsummary> <desc> <p>Folds <c><anno>Function</anno></c> over every element in <c><anno>Set</anno></c> returning the final value of the accumulator.</p> @@ -200,46 +212,46 @@ </func> <func> <name name="from_list" arity="1"/> - <fsummary>Convert a list into a gb_set</fsummary> + <fsummary>Convert a list into a set</fsummary> <desc> - <p>Returns a gb_set of the elements in <c><anno>List</anno></c>, where + <p>Returns a set of the elements in <c><anno>List</anno></c>, where <c><anno>List</anno></c> may be unordered and contain duplicates.</p> </desc> </func> <func> <name name="from_ordset" arity="1"/> - <fsummary>Make a gb_set from an ordset list</fsummary> + <fsummary>Make a set from an ordset list</fsummary> <desc> - <p>Turns an ordered-set list <c><anno>List</anno></c> into a gb_set. The list + <p>Turns an ordered-set list <c><anno>List</anno></c> into a set. The list must not contain duplicates.</p> </desc> </func> <func> <name name="insert" arity="2"/> - <fsummary>Add a new element to a gb_set</fsummary> + <fsummary>Add a new element to a set</fsummary> <desc> - <p>Returns a new gb_set formed from <c><anno>Set1</anno></c> with + <p>Returns a new set formed from <c><anno>Set1</anno></c> with <c><anno>Element</anno></c> inserted. Assumes that <c><anno>Element</anno></c> is not present in <c><anno>Set1</anno></c>.</p> </desc> </func> <func> <name name="intersection" arity="2"/> - <fsummary>Return the intersection of two gb_sets</fsummary> + <fsummary>Return the intersection of two sets</fsummary> <desc> <p>Returns the intersection of <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c>.</p> </desc> </func> <func> <name name="intersection" arity="1"/> - <fsummary>Return the intersection of a list of gb_sets</fsummary> + <fsummary>Return the intersection of a list of sets</fsummary> <desc> - <p>Returns the intersection of the non-empty list of gb_sets.</p> + <p>Returns the intersection of the non-empty list of sets.</p> </desc> </func> <func> <name name="is_disjoint" arity="2"/> - <fsummary>Check whether two gb_sets are disjoint</fsummary> + <fsummary>Check whether two sets are disjoint</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c> are disjoint (have no elements in common), @@ -248,7 +260,7 @@ </func> <func> <name name="is_empty" arity="1"/> - <fsummary>Test for empty gb_set</fsummary> + <fsummary>Test for empty set</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Set</anno></c> is an empty set, and <c>false</c> otherwise.</p> @@ -257,7 +269,7 @@ <func> <name name="is_member" arity="2"/> <name name="is_element" arity="2"/> - <fsummary>Test for membership of a gb_set</fsummary> + <fsummary>Test for membership of a set</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Element</anno></c> is an element of <c><anno>Set</anno></c>, otherwise <c>false</c>.</p> @@ -265,9 +277,9 @@ </func> <func> <name name="is_set" arity="1"/> - <fsummary>Test for a gb_set</fsummary> + <fsummary>Test for a set</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> appears to be a gb_set, + <p>Returns <c>true</c> if <c><anno>Term</anno></c> appears to be a set, otherwise <c>false</c>.</p> </desc> </func> @@ -281,7 +293,7 @@ </func> <func> <name name="iterator" arity="1"/> - <fsummary>Return an iterator for a gb_set</fsummary> + <fsummary>Return an iterator for a set</fsummary> <desc> <p>Returns an iterator that can be used for traversing the entries of <c><anno>Set</anno></c>; see <c>next/1</c>. The implementation @@ -303,7 +315,7 @@ </func> <func> <name name="next" arity="1"/> - <fsummary>Traverse a gb_set with an iterator</fsummary> + <fsummary>Traverse a set with an iterator</fsummary> <desc> <p>Returns <c>{<anno>Element</anno>, <anno>Iter2</anno>}</c> where <c><anno>Element</anno></c> is the smallest element referred to by the iterator <c><anno>Iter1</anno></c>, @@ -314,14 +326,14 @@ </func> <func> <name name="singleton" arity="1"/> - <fsummary>Return a gb_set with one element</fsummary> + <fsummary>Return a set with one element</fsummary> <desc> - <p>Returns a gb_set containing only the element <c><anno>Element</anno></c>.</p> + <p>Returns a set containing only the element <c><anno>Element</anno></c>.</p> </desc> </func> <func> <name name="size" arity="1"/> - <fsummary>Return the number of elements in a gb_set</fsummary> + <fsummary>Return the number of elements in a set</fsummary> <desc> <p>Returns the number of elements in <c><anno>Set</anno></c>.</p> </desc> @@ -356,24 +368,24 @@ </func> <func> <name name="to_list" arity="1"/> - <fsummary>Convert a gb_set into a list</fsummary> + <fsummary>Convert a set into a list</fsummary> <desc> <p>Returns the elements of <c><anno>Set</anno></c> as a list.</p> </desc> </func> <func> <name name="union" arity="2"/> - <fsummary>Return the union of two gb_sets</fsummary> + <fsummary>Return the union of two sets</fsummary> <desc> - <p>Returns the merged (union) gb_set of <c><anno>Set1</anno></c> and + <p>Returns the merged (union) set of <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c>.</p> </desc> </func> <func> <name name="union" arity="1"/> - <fsummary>Return the union of a list of gb_sets</fsummary> + <fsummary>Return the union of a list of sets</fsummary> <desc> - <p>Returns the merged (union) gb_set of the list of gb_sets.</p> + <p>Returns the merged (union) set of the list of sets.</p> </desc> </func> </funcs> diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml index 9316d60b1a..b2f237e1d7 100644 --- a/lib/stdlib/doc/src/gb_trees.xml +++ b/lib/stdlib/doc/src/gb_trees.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2001</year><year>2011</year> + <year>2001</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -59,13 +59,25 @@ <datatypes> <datatype> - <name><marker id="type-gb_tree">gb_tree()</marker></name> + <name name="tree" n_vars="2"/> <desc><p>A GB tree.</p></desc> </datatype> <datatype> - <name name="iter"/> + <name name="tree" n_vars="0"/> + <desc> + <p><c>tree()</c> is equivalent to <c>tree(term(), term())</c>.</p> + </desc> + </datatype> + <datatype> + <name name="iter" n_vars="2"/> <desc><p>A GB tree iterator.</p></desc> </datatype> + <datatype> + <name name="iter" n_vars="0"/> + <desc> + <p><c>iter()</c> is equivalent to <c>iter(term(), term())</c>.</p> + </desc> + </datatype> </datatypes> <funcs> <func> @@ -108,9 +120,9 @@ <name name="enter" arity="3"/> <fsummary>Insert or update key with value in a tree</fsummary> <desc> - <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Val</anno></c> into <c><anno>Tree1</anno></c> if + <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Value</anno></c> into <c><anno>Tree1</anno></c> if the key is not present in the tree, otherwise updates - <c><anno>Key</anno></c> to value <c><anno>Val</anno></c> in <c><anno>Tree1</anno></c>. Returns the + <c><anno>Key</anno></c> to value <c><anno>Value</anno></c> in <c><anno>Tree1</anno></c>. Returns the new tree.</p> </desc> </func> @@ -135,7 +147,7 @@ <name name="insert" arity="3"/> <fsummary>Insert a new key and value in a tree</fsummary> <desc> - <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Val</anno></c> into <c><anno>Tree1</anno></c>; + <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Value</anno></c> into <c><anno>Tree1</anno></c>; returns the new tree. Assumes that the key is not present in the tree, crashes otherwise.</p> </desc> @@ -181,8 +193,8 @@ <name name="largest" arity="1"/> <fsummary>Return largest key and value</fsummary> <desc> - <p>Returns <c>{<anno>Key</anno>, <anno>Val</anno>}</c>, where <c><anno>Key</anno></c> is the largest - key in <c><anno>Tree</anno></c>, and <c><anno>Val</anno></c> is the value associated + <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>}</c>, where <c><anno>Key</anno></c> is the largest + key in <c><anno>Tree</anno></c>, and <c><anno>Value</anno></c> is the value associated with this key. Assumes that the tree is nonempty.</p> </desc> </func> @@ -191,7 +203,7 @@ <fsummary>Look up a key in a tree</fsummary> <desc> <p>Looks up <c><anno>Key</anno></c> in <c><anno>Tree</anno></c>; returns - <c>{value, <anno>Val</anno>}</c>, or <c>none</c> if <c><anno>Key</anno></c> is not + <c>{value, <anno>Value</anno>}</c>, or <c>none</c> if <c><anno>Key</anno></c> is not present.</p> </desc> </func> @@ -207,7 +219,7 @@ <name name="next" arity="1"/> <fsummary>Traverse a tree with an iterator</fsummary> <desc> - <p>Returns <c>{<anno>Key</anno>, <anno>Val</anno>, <anno>Iter2</anno>}</c> where <c><anno>Key</anno></c> is the + <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, <anno>Iter2</anno>}</c> where <c><anno>Key</anno></c> is the smallest key referred to by the iterator <c><anno>Iter1</anno></c>, and <c><anno>Iter2</anno></c> is the new iterator to be used for traversing the remaining nodes, or the atom <c>none</c> if no @@ -225,8 +237,8 @@ <name name="smallest" arity="1"/> <fsummary>Return smallest key and value</fsummary> <desc> - <p>Returns <c>{<anno>Key</anno>, <anno>Val</anno>}</c>, where <c><anno>Key</anno></c> is the smallest - key in <c><anno>Tree</anno></c>, and <c><anno>Val</anno></c> is the value associated + <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>}</c>, where <c><anno>Key</anno></c> is the smallest + key in <c><anno>Tree</anno></c>, and <c><anno>Value</anno></c> is the value associated with this key. Assumes that the tree is nonempty.</p> </desc> </func> @@ -234,8 +246,8 @@ <name name="take_largest" arity="1"/> <fsummary>Extract largest key and value</fsummary> <desc> - <p>Returns <c>{<anno>Key</anno>, <anno>Val</anno>, <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the - largest key in <c><anno>Tree1</anno></c>, <c><anno>Val</anno></c> is the value + <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the + largest key in <c><anno>Tree1</anno></c>, <c><anno>Value</anno></c> is the value associated with this key, and <c><anno>Tree2</anno></c> is this tree with the corresponding node deleted. Assumes that the tree is nonempty.</p> @@ -245,8 +257,8 @@ <name name="take_smallest" arity="1"/> <fsummary>Extract smallest key and value</fsummary> <desc> - <p>Returns <c>{<anno>Key</anno>, <anno>Val</anno>, <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the - smallest key in <c><anno>Tree1</anno></c>, <c><anno>Val</anno></c> is the value + <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the + smallest key in <c><anno>Tree1</anno></c>, <c><anno>Value</anno></c> is the value associated with this key, and <c><anno>Tree2</anno></c> is this tree with the corresponding node deleted. Assumes that the tree is nonempty.</p> @@ -263,7 +275,7 @@ <name name="update" arity="3"/> <fsummary>Update a key to new value in a tree</fsummary> <desc> - <p>Updates <c><anno>Key</anno></c> to value <c><anno>Val</anno></c> in <c><anno>Tree1</anno></c>; + <p>Updates <c><anno>Key</anno></c> to value <c><anno>Value</anno></c> in <c><anno>Tree1</anno></c>; returns the new tree. Assumes that the key is present in the tree.</p> </desc> diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index 1601ea9892..b9dfff833e 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2012</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml index 73c1911f1e..848d57f3e6 100644 --- a/lib/stdlib/doc/src/gen_fsm.xml +++ b/lib/stdlib/doc/src/gen_fsm.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -115,7 +115,7 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 If <c>FsmName={global,GlobalName}</c>, the gen_fsm is registered globally as <c>GlobalName</c> using <c>global:register_name/2</c>. - If <c>EventMgrName={via,Module,ViaName}</c>, the event manager will + If <c>FsmName={via,Module,ViaName}</c>, the gen_fsm will register with the registry represented by <c>Module</c>. The <c>Module</c> callback should export the functions <c>register_name/2</c>, <c>unregister_name/1</c>, @@ -210,7 +210,7 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 registered at another node, or</item> <item><c>{global,GlobalName}</c>, if the gen_fsm is globally registered.</item> - <item><c>{via,Module,ViaName}</c>, if the event manager is registered + <item><c>{via,Module,ViaName}</c>, if the gen_fsm is registered through an alternative process registry.</item> </list> <p><c>Event</c> is an arbitrary term which is passed as one of diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index abb4c73c7b..62c0394479 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2012</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -113,7 +113,7 @@ gen_server:abcast -----> Module:handle_cast/2 registered globally as <c>GlobalName</c> using <c>global:register_name/2</c>. If no name is provided, the gen_server is not registered. - If <c>EventMgrName={via,Module,ViaName}</c>, the event manager will + If <c>ServerName={via,Module,ViaName}</c>, the gen_server will register with the registry represented by <c>Module</c>. The <c>Module</c> callback should export the functions <c>register_name/2</c>, <c>unregister_name/1</c>, diff --git a/lib/stdlib/doc/src/io.xml b/lib/stdlib/doc/src/io.xml index e6d262466c..a28180b42a 100644 --- a/lib/stdlib/doc/src/io.xml +++ b/lib/stdlib/doc/src/io.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,9 +28,9 @@ <rev></rev> </header> <module>io</module> - <modulesummary>Standard IO Server Interface Functions</modulesummary> + <modulesummary>Standard I/O Server Interface Functions</modulesummary> <description> - <p>This module provides an interface to standard Erlang IO servers. + <p>This module provides an interface to standard Erlang I/O servers. The output functions all return <c>ok</c> if they are successful, or exit if they are not.</p> <p>In the following description, all functions have an optional @@ -38,17 +38,16 @@ process which handles the IO protocols. Normally, it is the <c>IoDevice</c> returned by <seealso marker="kernel:file#open/2">file:open/2</seealso>.</p> - <p>For a description of the IO protocols refer to the STDLIB Users Guide.</p> + <p>For a description of the IO protocols refer to the <seealso marker="io_protocol">STDLIB User's Guide</seealso>.</p> <warning> <p>As of R13A, data supplied to the <seealso marker="#put_chars/2">put_chars</seealso> function should be in the <seealso marker="unicode#type-chardata"><c>unicode:chardata()</c></seealso> format. This means that programs supplying binaries to this function need to convert them to UTF-8 - before trying to output the data on an - <c>io_device()</c>.</p> + before trying to output the data on an IO device.</p> - <p>If an io_device() is set in binary mode, the functions <seealso + <p>If an IO device is set in binary mode, the functions <seealso marker="#get_chars/3">get_chars</seealso> and <seealso marker="#get_line/2">get_line</seealso> may return binaries instead of lists. The binaries will, as of R13A, be encoded in @@ -68,9 +67,9 @@ <datatype> <name name="device"/> <desc> - <p>Either <c>standard_io</c>, <c>standard_error</c>, a + <p>An IO device. Either <c>standard_io</c>, <c>standard_error</c>, a registered name, or a pid handling IO protocols (returned from - <seealso marker="kernel:file#open/2">file:open/2</seealso>).</p> + <seealso marker="kernel:file#open/2">file:open/2</seealso>).</p> </desc> </datatype> <datatype> @@ -89,17 +88,14 @@ <name name="format"/> </datatype> <datatype> - <name name="line"/> + <name name="location"/> </datatype> <datatype> <name name="prompt"/> </datatype> <datatype> - <name name="request_error"/> - </datatype> - <datatype> - <name name="error_description"/> - <desc><p>Whatever the I/O-server sends.</p></desc> + <name name="server_no_data"/> + <desc><p>What the I/O-server sends when there is no data.</p></desc> </datatype> </datatypes> @@ -107,11 +103,11 @@ <func> <name name="columns" arity="0"/> <name name="columns" arity="1"/> - <fsummary>Get the number of columns of a device</fsummary> + <fsummary>Get the number of columns of an IO device</fsummary> <desc> <p>Retrieves the number of columns of the <c><anno>IoDevice</anno></c> (i.e. the width of a terminal). The function - only succeeds for terminal devices, for all other devices + only succeeds for terminal devices, for all other IO devices the function returns <c>{error, enotsup}</c></p> </desc> </func> @@ -120,7 +116,7 @@ <name name="put_chars" arity="2"/> <fsummary>Write a list of characters</fsummary> <desc> - <p>Writes the characters of <c><anno>CharData</anno></c> to the io_server() + <p>Writes the characters of <c><anno>CharData</anno></c> to the I/O server (<c><anno>IoDevice</anno></c>).</p> </desc> </func> @@ -135,6 +131,7 @@ <func> <name name="get_chars" arity="2"/> <name name="get_chars" arity="3"/> + <type name="server_no_data"/> <fsummary>Read a specified number of characters</fsummary> <desc> <p>Reads <c><anno>Count</anno></c> characters from standard input @@ -143,19 +140,19 @@ <taglist> <tag><c><anno>Data</anno></c></tag> <item> - <p>The input characters. If the device supports Unicode, + <p>The input characters. If the IO device supports Unicode, the data may represent codepoints larger than 255 (the - latin1 range). If the io_server() is set to deliver + latin1 range). If the I/O server is set to deliver binaries, they will be encoded in UTF-8 (regardless of if - the device actually supports Unicode or not).</p> + the IO device actually supports Unicode or not).</p> </item> <tag><c>eof</c></tag> <item> <p>End of file was encountered.</p> </item> - <tag><c>{error,<anno>Reason</anno>}</c></tag> + <tag><c>{error, <anno>ErrorDescription</anno>}</c></tag> <item> - <p>Other (rare) error condition, for instance <c>{error,estale}</c> + <p>Other (rare) error condition, for instance <c>{error, estale}</c> if reading from an NFS file system.</p> </item> </taglist> @@ -164,6 +161,7 @@ <func> <name name="get_line" arity="1"/> <name name="get_line" arity="2"/> + <type name="server_no_data"/> <fsummary>Read a line</fsummary> <desc> <p>Reads a line from the standard input (<c><anno>IoDevice</anno></c>), @@ -172,19 +170,19 @@ <tag><c><anno>Data</anno></c></tag> <item> <p>The characters in the line terminated by a LF (or end of - file). If the device supports Unicode, + file). If the IO device supports Unicode, the data may represent codepoints larger than 255 (the - latin1 range). If the io_server() is set to deliver + latin1 range). If the I/O server is set to deliver binaries, they will be encoded in UTF-8 (regardless of if - the device actually supports Unicode or not).</p> + the IO device actually supports Unicode or not).</p> </item> <tag><c>eof</c></tag> <item> <p>End of file was encountered.</p> </item> - <tag><c>{error,<anno>Reason</anno>}</c></tag> + <tag><c>{error, <anno>ErrorDescription</anno>}</c></tag> <item> - <p>Other (rare) error condition, for instance <c>{error,estale}</c> + <p>Other (rare) error condition, for instance <c>{error, estale}</c> if reading from an NFS file system.</p> </item> </taglist> @@ -195,7 +193,7 @@ <name name="getopts" arity="1"/> <fsummary>Get the supported options and values from an I/O-server</fsummary> <desc> - <p>This function requests all available options and their current values for a specific io_device(). Example:</p> + <p>This function requests all available options and their current values for a specific IO device. Example:</p> <pre> 1> <input>{ok,F} = file:open("/dev/null",[read]).</input> {ok,<0.42.0>} @@ -213,34 +211,46 @@ </desc> </func> <func> + <name name="printable_range" arity="0"/> + <fsummary>Get user requested printable character range</fsummary> + <desc> + <p>Return the user requested range of printable Unicode characters.</p> + <p>The user can request a range of characters that are to be considered printable in heuristic detection of strings by the shell and by the formatting functions. This is done by supplying <c>+pc <range></c> when starting Erlang.</p> + <p>Currently the only valid values for <c><range></c> are <c>latin1</c> and <c>unicode</c>. <c>latin1</c> means that only code points below 256 (with the exception of control characters etc) will be considered printable. <c>unicode</c> means that all printable characters in all unicode character ranges are considered printable by the io functions.</p> + <p>By default, Erlang is started so that only the <c>latin1</c> range of characters will indicate that a list of integers is a string.</p> + <p>The simplest way to utilize the setting is to call <seealso marker="io_lib#printable_list/1">io_lib:printable_list/1</seealso>, which will use the return value of this function to decide if a list is a string of printable characters or not.</p> + <note><p>In the future, this function may return more values and ranges. It is recommended to use the io_lib:printable_list/1 function to avoid compatibility problems.</p></note> + </desc> + </func> + <func> <name name="setopts" arity="1"/> <name name="setopts" arity="2"/> <fsummary>Set options</fsummary> <desc> - <p>Set options for the io_device() (<c><anno>IoDevice</anno></c>).</p> + <p>Set options for the standard IO device (<c><anno>IoDevice</anno></c>).</p> <p>Possible options and values vary depending on the actual - io_device(). For a list of supported options and their current values - on a specific device, use the <seealso + IO device. For a list of supported options and their current values + on a specific IO device, use the <seealso marker="#getopts/1">getopts/1</seealso> function.</p> - <p>The options and values supported by the current OTP io_devices are:</p> + <p>The options and values supported by the current OTP IO devices are:</p> <taglist> <tag><c>binary, list or {binary, boolean()}</c></tag> <item> - <p>If set in binary mode (binary or {binary,true}), the io_server() sends binary data (encoded in UTF-8) as answers to the get_line, get_chars and, if possible, get_until requests (see the I/O protocol description in STDLIB User's Guide for details). The immediate effect is that <c>get_chars/2,3</c> and <c>get_line/1,2</c> return UTF-8 binaries instead of lists of chars for the affected device.</p> - <p>By default, all io_devices in OTP are set in list mode, but the io functions can handle any of these modes and so should other, user written, modules behaving as clients to I/O-servers.</p> - <p>This option is supported by the standard shell (group.erl), the 'oldshell' (user.erl) and the file I/O servers.</p> + <p>If set in binary mode (<c>binary</c> or <c>{binary, true}</c>), the I/O server sends binary data (encoded in UTF-8) as answers to the <c>get_line</c>, <c>get_chars</c> and, if possible, <c>get_until</c> requests (see the I/O protocol description in <seealso marker="io_protocol">STDLIB User's Guide</seealso> for details). The immediate effect is that <c>get_chars/2,3</c> and <c>get_line/1,2</c> return UTF-8 binaries instead of lists of chars for the affected IO device.</p> + <p>By default, all IO devices in OTP are set in list mode, but the I/O functions can handle any of these modes and so should other, user written, modules behaving as clients to I/O-servers.</p> + <p>This option is supported by the standard shell (<c>group.erl</c>), the 'oldshell' (<c>user.erl</c>) and the file I/O servers.</p> </item> <tag><c>{echo, boolean()}</c></tag> <item> - <p>Denotes if the terminal should echo input. Only supported for the standard shell I/O-server (group.erl)</p> + <p>Denotes if the terminal should echo input. Only supported for the standard shell I/O-server (<c>group.erl</c>)</p> </item> <tag><c>{expand_fun, expand_fun()}</c></tag> <item> <p>Provide a function for tab-completion (expansion) - like the erlang shell. This function is called - when the user presses the Tab key. The expansion is + like the Erlang shell. This function is called + when the user presses the TAB key. The expansion is active when calling line-reading functions such as <c>get_line/1,2</c>.</p> <p>The function is called with the current line, upto @@ -253,25 +263,25 @@ will be printed and the current input line will be written once again.</p> <p>Trivial example (beep on anything except empty line, which - is expanded to "quit"):</p> + is expanded to <c>"quit"</c>):</p> <code type="none"> fun("") -> {yes, "quit", []}; (_) -> {no, "", ["quit"]} end</code> - <p>This option is supported by the standard shell only (group.erl).</p> + <p>This option is supported by the standard shell only (<c>group.erl</c>).</p> </item> <tag><c>{encoding, latin1 | unicode}</c></tag> <item> - <p>Specifies how characters are input or output from or to the actual device, implying that i.e. a terminal is set to handle Unicode input and output or a file is set to handle UTF-8 data encoding.</p> - <p>The option <em>does not</em> affect how data is returned from the io-functions or how it is sent in the I/O-protocol, it only affects how the io_device() is to handle Unicode characters towards the "physical" device.</p> - <p>The standard shell will be set for either unicode or latin1 encoding when the system is started. The actual encoding is set with the help of the "LANG" or "LC_CTYPE" environment variables on Unix-like system or by other means on other systems. The bottom line is that the user can input Unicode characters and the device will be in {encoding, unicode} mode if the device supports it. The mode can be changed, if the assumption of the runtime system is wrong, by setting this option.</p> - <p>The io_device() used when Erlang is started with the "-oldshell" or "-noshell" flags is by default set to latin1 encoding, meaning that any characters beyond codepoint 255 will be escaped and that input is expected to be plain 8-bit ISO-latin-1. If the encoding is changed to Unicode, input and output from the standard file descriptors will be in UTF-8 (regardless of operating system).</p> - <p>Files can also be set in {encoding, unicode}, meaning that data is written and read as UTF-8. More encodings are possible for files, see below.</p> - <p>{encoding, unicode | latin1} is supported by both the standard shell (group.erl including werl on windows), the 'oldshell' (user.erl) and the file I/O servers.</p> + <p>Specifies how characters are input or output from or to the actual IO device, implying that i.e. a terminal is set to handle Unicode input and output or a file is set to handle UTF-8 data encoding.</p> + <p>The option <em>does not</em> affect how data is returned from the I/O functions or how it is sent in the I/O-protocol, it only affects how the IO device is to handle Unicode characters towards the "physical" device.</p> + <p>The standard shell will be set for either Unicode or latin1 encoding when the system is started. The actual encoding is set with the help of the <c>LANG</c> or <c>LC_CTYPE</c> environment variables on Unix-like system or by other means on other systems. The bottom line is that the user can input Unicode characters and the IO device will be in <c>{encoding, unicode}</c> mode if the IO device supports it. The mode can be changed, if the assumption of the runtime system is wrong, by setting this option.</p> + <p>The IO device used when Erlang is started with the "-oldshell" or "-noshell" flags is by default set to latin1 encoding, meaning that any characters beyond codepoint 255 will be escaped and that input is expected to be plain 8-bit ISO-latin-1. If the encoding is changed to Unicode, input and output from the standard file descriptors will be in UTF-8 (regardless of operating system).</p> + <p>Files can also be set in <c>{encoding, unicode}</c>, meaning that data is written and read as UTF-8. More encodings are possible for files, see below.</p> + <p><c>{encoding, unicode | latin1}</c> is supported by both the standard shell (<c>group.erl</c> including <c>werl</c> on Windows®), the 'oldshell' (<c>user.erl</c>) and the file I/O servers.</p> </item> <tag><c>{encoding, utf8 | utf16 | utf32 | {utf16,big} | {utf16,little} | {utf32,big} | {utf32,little}}</c></tag> <item> <p>For disk files, the encoding can be set to various UTF variants. This will have the effect that data is expected to be read as the specified encoding from the file and the data will be written in the specified encoding to the disk file.</p> - <p>{encoding, utf8} will have the same effect as {encoding,unicode} on files.</p> + <p><c>{encoding, utf8}</c> will have the same effect as <c>{encoding, unicode}</c> on files.</p> <p>The extended encodings are only supported on disk files (opened by the <seealso marker="kernel:file#open/2">file:open/2</seealso> function)</p> </item> </taglist> @@ -289,6 +299,7 @@ <func> <name name="read" arity="1"/> <name name="read" arity="2"/> + <type name="server_no_data"/> <fsummary>Read a term</fsummary> <desc> <p>Reads a term <c><anno>Term</anno></c> from the standard input @@ -307,29 +318,43 @@ <item> <p>The parsing failed.</p> </item> + <tag><c>{error, <anno>ErrorDescription</anno>}</c></tag> + <item> + <p>Other (rare) error condition, for instance <c>{error, estale}</c> + if reading from an NFS file system.</p> + </item> </taglist> </desc> </func> <func> <name name="read" arity="3"/> + <name name="read" arity="4"/> + <type name="server_no_data"/> <fsummary>Read a term</fsummary> <desc> <p>Reads a term <c><anno>Term</anno></c> from <c><anno>IoDevice</anno></c>, prompting it - with <c><anno>Prompt</anno></c>. Reading starts at line number - <c><anno>StartLine</anno></c>. It returns:</p> + with <c><anno>Prompt</anno></c>. Reading starts at location + <c><anno>StartLocation</anno></c>. The argument + <c><anno>Options</anno></c> is passed on as the <c>Options</c> + argument of the <c>erl_scan:tokens/4</c> function. It returns:</p> <taglist> - <tag><c>{ok, Term, <anno>EndLine</anno>}</c></tag> + <tag><c>{ok, Term, <anno>EndLocation</anno>}</c></tag> <item> <p>The parsing was successful.</p> </item> - <tag><c>{eof, <anno>EndLine</anno>}</c></tag> + <tag><c>{eof, <anno>EndLocation</anno>}</c></tag> <item> <p>End of file was encountered.</p> </item> - <tag><c>{error, <anno>ErrorInfo</anno>, <anno>ErrorLine</anno>}</c></tag> + <tag><c>{error, <anno>ErrorInfo</anno>, <anno>ErrorLocation</anno>}</c></tag> <item> <p>The parsing failed.</p> </item> + <tag><c>{error, <anno>ErrorDescription</anno>}</c></tag> + <item> + <p>Other (rare) error condition, for instance <c>{error, estale}</c> + if reading from an NFS file system.</p> + </item> </taglist> </desc> </func> @@ -377,10 +402,11 @@ ok</pre> applicable, it is used for both the field width and precision. The default padding character is <c>' '</c> (space).</p> <p><c>Mod</c> is the control sequence modifier. It is either a - single character (currently only 't', for unicode translation, - is supported) that changes the interpretation of Data.</p> - - <p>The following control sequences are available:</p> + single character (currently only <c>t</c>, for Unicode + translation, and <c>l</c>, for stopping <c>p</c> and + <c>P</c> from detecting printable characters, are supported) + that changes the interpretation of Data.</p> + <p>The following control sequences are available:</p> <taglist> <tag><c>~</c></tag> <item> @@ -394,18 +420,18 @@ ok</pre> which in turn defaults to 1. The following example illustrates:</p> <pre> -2> <input>io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]).</input> +1> <input>io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]).</input> | aaaaa|bbbbb |ccccc| ok</pre> - <p>If the Unicode translation modifier ('t') is in effect, + <p>If the Unicode translation modifier (<c>t</c>) is in effect, the integer argument can be any number representing a - valid unicode codepoint, otherwise it should be an integer + valid Unicode codepoint, otherwise it should be an integer less than or equal to 255, otherwise it is masked with 16#FF:</p> <pre> -1> <input>io:fwrite("~tc~n",[1024]).</input> +2> <input>io:fwrite("~tc~n",[1024]).</input> \x{400} ok -2> <input>io:fwrite("~c~n",[1024]).</input> +3> <input>io:fwrite("~c~n",[1024]).</input> ^@ ok</pre> @@ -437,29 +463,32 @@ ok</pre> </item> <tag><c>s</c></tag> <item> - <p>Prints the argument with the <c>string</c> syntax. The + <p>Prints the argument with the string syntax. The argument is, if no Unicode translation modifier is present, an - iolist(), a binary, or an atom. If the Unicode translation modifier ('t') is in effect, the argument is unicode:chardata(), meaning that binaries are in UTF-8. The characters + <c>iolist()</c>, a <c>binary()</c>, or an <c>atom()</c>. + If the Unicode translation modifier (<c>t</c>) is in effect, + the argument is <c>unicode:chardata()</c>, meaning that + binaries are in UTF-8. The characters are printed without quotes. The string is first truncated by the given precision and then padded and justified to the given field width. The default precision is the field width.</p> <p>This format can be used for printing any object and truncating the output so it fits a specified field:</p> <pre> -3> <input>io:fwrite("|~10w|~n", [{hey, hey, hey}]).</input> +1> <input>io:fwrite("|~10w|~n", [{hey, hey, hey}]).</input> |**********| ok -4> <input>io:fwrite("|~10s|~n", [io_lib:write({hey, hey, hey})]).</input> +2> <input>io:fwrite("|~10s|~n", [io_lib:write({hey, hey, hey})]).</input> |{hey,hey,h| -5> <input>io:fwrite("|~-10.8s|~n", [io_lib:write({hey, hey, hey})]).</input> +3> <input>io:fwrite("|~-10.8s|~n", [io_lib:write({hey, hey, hey})]).</input> |{hey,hey | ok</pre> <p>A list with integers larger than 255 is considered an error if the Unicode translation modifier is not given:</p> <pre> -1> <input>io:fwrite("~ts~n",[[1024]]).</input> +4> <input>io:fwrite("~ts~n",[[1024]]).</input> \x{400} ok -2> io:fwrite("~s~n",[[1024]]). +5> <input>io:fwrite("~s~n",[[1024]]).</input> ** exception exit: {badarg,[{io,format,[<0.26.0>,"~s~n",[[1024]]]}, ...</pre> </item> @@ -476,20 +505,22 @@ ok <p>Writes the data with standard syntax in the same way as <c>~w</c>, but breaks terms whose printed representation is longer than one line into many lines and indents each - line sensibly. It also tries to detect lists of printable - characters and to output these as strings. For example:</p> + line sensibly. It also tries to detect lists of + printable characters and to output these as strings. The + Unicode translation modifier is used for determining + what characters are printable. For example:</p> <pre> -5> <input>T = [{attributes,[[{id,age,1.50000},{mode,explicit},</input> +1> <input>T = [{attributes,[[{id,age,1.50000},{mode,explicit},</input> <input>{typename,"INTEGER"}], [{id,cho},{mode,explicit},{typename,'Cho'}]]},</input> <input>{typename,'Person'},{tag,{'PRIVATE',3}},{mode,implicit}].</input> ... -6> <input>io:fwrite("~w~n", [T]).</input> +2> <input>io:fwrite("~w~n", [T]).</input> [{attributes,[[{id,age,1.5},{mode,explicit},{typename, [73,78,84,69,71,69,82]}],[{id,cho},{mode,explicit},{typena me,'Cho'}]]},{typename,'Person'},{tag,{'PRIVATE',3}},{mode ,implicit}] ok -7> <input>io:fwrite("~62p~n", [T]).</input> +3> <input>io:fwrite("~62p~n", [T]).</input> [{attributes,[[{id,age,1.5}, {mode,explicit}, {typename,"INTEGER"}], @@ -505,7 +536,7 @@ ok</pre> <c>io:fwrite</c> or <c>io:format</c>. For example, using <c>T</c> above:</p> <pre> -8> <input>io:fwrite("Here T = ~62p~n", [T]).</input> +4> <input>io:fwrite("Here T = ~62p~n", [T]).</input> Here T = [{attributes,[[{id,age,1.5}, {mode,explicit}, {typename,"INTEGER"}], @@ -516,6 +547,31 @@ Here T = [{attributes,[[{id,age,1.5}, {tag,{'PRIVATE',3}}, {mode,implicit}] ok</pre> + <p>When the modifier <c>l</c> is given no detection of + printable character lists will take place. For example:</p> + <pre> +5> <input>S = [{a,"a"}, {b, "b"}].</input> +6> <input>io:fwrite("~15p~n", [S]).</input> +[{a,"a"}, + {b,"b"}] +ok +7> <input>io:fwrite("~15lp~n", [S]).</input> +[{a,[97]}, + {b,[98]}] +ok</pre> + <p>Binaries that look like UTF-8 encoded strings will be + output with the string syntax if the Unicode translation + modifier is given:</p> + <pre> +9> <input>io:fwrite("~p~n",[[1024]]).</input> +[1024] +10> <input>io:fwrite("~tp~n",[[1024]]).</input> +"\x{400}" +11> <input>io:fwrite("~tp~n", [<<128,128>>]).</input> +<<128,128>> +12> <input>io:fwrite("~tp~n", [<<208,128>>]).</input> +<<"\x{400}"/utf8>> +ok</pre> </item> <tag><c>W</c></tag> <item> @@ -524,7 +580,7 @@ ok</pre> are printed. Anything below this depth is replaced with <c>...</c>. For example, using <c>T</c> above:</p> <pre> -9> <input>io:fwrite("~W~n", [T,9]).</input> +8> <input>io:fwrite("~W~n", [T,9]).</input> [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}], [{id,cho},{mode,...},{...}]]},{typename,'Person'}, {tag,{'PRIVATE',3}},{mode,implicit}] @@ -541,7 +597,7 @@ ok</pre> are printed. Anything below this depth is replaced with <c>...</c>. For example:</p> <pre> -10> <input>io:fwrite("~62P~n", [T,9]).</input> +9> <input>io:fwrite("~62P~n", [T,9]).</input> [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}], [{id,cho},{mode,...},{...}]]}, {typename,'Person'}, @@ -555,13 +611,13 @@ ok</pre> 10. A leading dash is printed for negative integers.</p> <p>The precision field selects base. For example:</p> <pre> -11> <input>io:fwrite("~.16B~n", [31]).</input> +1> <input>io:fwrite("~.16B~n", [31]).</input> 1F ok -12> <input>io:fwrite("~.2B~n", [-19]).</input> +2> <input>io:fwrite("~.2B~n", [-19]).</input> -10011 ok -13> <input>io:fwrite("~.36B~n", [5*36+35]).</input> +3> <input>io:fwrite("~.36B~n", [5*36+35]).</input> 5Z ok</pre> </item> @@ -573,22 +629,22 @@ ok</pre> <p>The prefix can be a possibly deep list of characters or an atom.</p> <pre> -14> <input>io:fwrite("~X~n", [31,"10#"]).</input> +1> <input>io:fwrite("~X~n", [31,"10#"]).</input> 10#31 ok -15> <input>io:fwrite("~.16X~n", [-31,"0x"]).</input> +2> <input>io:fwrite("~.16X~n", [-31,"0x"]).</input> -0x1F ok</pre> </item> <tag><c>#</c></tag> <item> <p>Like <c>B</c>, but prints the number with an Erlang style - '#'-separated base prefix.</p> + <c>#</c>-separated base prefix.</p> <pre> -16> <input>io:fwrite("~.10#~n", [31]).</input> +1> <input>io:fwrite("~.10#~n", [31]).</input> 10#31 ok -17> <input>io:fwrite("~.16#~n", [-31]).</input> +2> <input>io:fwrite("~.16#~n", [-31]).</input> -16#1F ok</pre> </item> @@ -622,10 +678,10 @@ ok</pre> </taglist> <p>If an error occurs, there is no output. For example:</p> <pre> -18> <input>io:fwrite("~s ~w ~i ~w ~c ~n",['abc def', 'abc def', {foo, 1},{foo, 1}, 65]).</input> +1> <input>io:fwrite("~s ~w ~i ~w ~c ~n",['abc def', 'abc def', {foo, 1},{foo, 1}, 65]).</input> abc def 'abc def' {foo,1} A ok -19> <input>io:fwrite("~s", [65]).</input> +2> <input>io:fwrite("~s", [65]).</input> ** exception exit: {badarg,[{io,format,[<0.22.0>,"~s","A"]}, {erl_eval,do_apply,5}, {shell,exprs,6}, @@ -633,13 +689,14 @@ ok {shell,eval_loop,3}]} in function io:o_request/2</pre> <p>In this example, an attempt was made to output the single - character '65' with the aid of the string formatting directive + character 65 with the aid of the string formatting directive "~s".</p> </desc> </func> <func> <name name="fread" arity="2"/> <name name="fread" arity="3"/> + <type name="server_no_data"/> <fsummary>Read formatted input</fsummary> <desc> <p>Reads characters from the standard input (<c><anno>IoDevice</anno></c>), @@ -664,7 +721,7 @@ ok return suppression character. It provides a method to specify a field which is to be omitted. <c>F</c> is the <c>field width</c> of the input field, <c>M</c> is an optional - translation modifier (of which 't' is the only currently + translation modifier (of which <c>t</c> is the only currently supported, meaning Unicode translation) and <c>C</c> determines the type of control sequence.</p> @@ -690,8 +747,8 @@ ok <tag><c>-</c></tag> <item> <p>An optional sign character is expected. A sign - character '-' gives the return value <c>-1</c>. Sign - character '+' or none gives <c>1</c>. The field width + character <c>-</c> gives the return value <c>-1</c>. Sign + character <c>+</c> or none gives <c>1</c>. The field width parameter is ignored. Leading white-space characters are not skipped.</p> </item> @@ -713,7 +770,7 @@ ok characters are stripped. An Erlang string (list of characters) is returned.</p> - <p>If Unicode translation is in effect (~ts), + <p>If Unicode translation is in effect (<c>~ts</c>), characters larger than 255 are accepted, otherwise not. With the translation modifier, the list returned may as a consequence also contain @@ -769,10 +826,15 @@ Prompt> <input><Character beyond latin1 range not printable in this medium> <item> <p>End of file was encountered.</p> </item> - <tag><c>{error, <anno>What</anno>}</c></tag> + <tag><c>{error, <anno>FreadError</anno>}</c></tag> + <item> + <p>The reading failed and <c>FreadError</c> gives a + hint about the error.</p> + </item> + <tag><c>{error, <anno>ErrorDescription</anno>}</c></tag> <item> <p>The read operation failed and the parameter - <c><anno>What</anno></c> gives a hint about the error.</p> + <c><anno>ErrorDescription</anno></c> gives a hint about the error.</p> </item> </taglist> </item> @@ -793,11 +855,11 @@ enter><input>:</input> <input>alan</input> <input>:</input> <input>joe</in <func> <name name="rows" arity="0"/> <name name="rows" arity="1"/> - <fsummary>Get the number of rows of a device</fsummary> + <fsummary>Get the number of rows of an IO device</fsummary> <desc> <p>Retrieves the number of rows of the <c><anno>IoDevice</anno></c> (i.e. the height of a terminal). The function - only succeeds for terminal devices, for all other devices + only succeeds for terminal devices, for all other IO devices the function returns <c>{error, enotsup}</c></p> </desc> </func> @@ -805,26 +867,40 @@ enter><input>:</input> <input>alan</input> <input>:</input> <input>joe</in <name name="scan_erl_exprs" arity="1"/> <name name="scan_erl_exprs" arity="2"/> <name name="scan_erl_exprs" arity="3"/> + <name name="scan_erl_exprs" arity="4"/> + <type name="server_no_data"/> <fsummary>Read and tokenize Erlang expressions</fsummary> <desc> <p>Reads data from the standard input (<c>IoDevice</c>), - prompting it with <c>Prompt</c>. Reading starts at line number - <c>StartLine</c> (1). The data is tokenized as if it were a - sequence of Erlang expressions until a final <c>'.'</c> is + prompting it with <c>Prompt</c>. Reading starts at location + <c>StartLocation</c> (<c>1</c>). The argument <c><anno>Options</anno></c> + is passed on as the <c>Options</c> argument of the + <c>erl_scan:tokens/4</c> function. The data is tokenized as if + it were a + sequence of Erlang expressions until a final dot (<c>.</c>) is reached. This token is also returned. It returns:</p> <taglist> - <tag><c>{ok, Tokens, EndLine}</c></tag> + <tag><c>{ok, Tokens, EndLocation}</c></tag> <item> <p>The tokenization succeeded.</p> </item> - <tag><c>{eof, EndLine}</c></tag> + <tag><c>{eof, EndLocation}</c></tag> <item> - <p>End of file was encountered.</p> + <p>End of file was encountered by the tokenizer.</p> </item> - <tag><c>{error, ErrorInfo, ErrorLine}</c></tag> + <tag><c>eof</c></tag> + <item> + <p>End of file was encountered by the I/O-server.</p> + </item> + <tag><c>{error, ErrorInfo, ErrorLocation}</c></tag> <item> - <p>An error occurred.</p> + <p>An error occurred while tokenizing.</p> </item> + <tag><c>{error, <anno>ErrorDescription</anno>}</c></tag> + <item> + <p>Other (rare) error condition, for instance <c>{error, estale}</c> + if reading from an NFS file system.</p> + </item> </taglist> <p>Example:</p> <pre> @@ -840,13 +916,18 @@ enter><input>1.0er.</input> <name name="scan_erl_form" arity="1"/> <name name="scan_erl_form" arity="2"/> <name name="scan_erl_form" arity="3"/> + <name name="scan_erl_form" arity="4"/> + <type name="server_no_data"/> <fsummary>Read and tokenize an Erlang form</fsummary> <desc> <p>Reads data from the standard input (<c><anno>IoDevice</anno></c>), - prompting it with <c><anno>Prompt</anno></c>. Starts reading at line number - <c><anno>StartLine</anno></c> (1). The data is tokenized as if it were an + prompting it with <c><anno>Prompt</anno></c>. Starts reading + at location <c><anno>StartLocation</anno></c> (<c>1</c>). The + argument <c><anno>Options</anno></c> is passed on as the + <c>Options</c> argument of the <c>erl_scan:tokens/4</c> + function. The data is tokenized as if it were an Erlang form - one of the valid Erlang expressions in an - Erlang source file - until a final <c>'.'</c> is reached. + Erlang source file - until a final dot (<c>.</c>) is reached. This last token is also returned. The return values are the same as for <c>scan_erl_exprs/1,2,3</c> above.</p> </desc> @@ -855,27 +936,42 @@ enter><input>1.0er.</input> <name name="parse_erl_exprs" arity="1"/> <name name="parse_erl_exprs" arity="2"/> <name name="parse_erl_exprs" arity="3"/> + <name name="parse_erl_exprs" arity="4"/> <type name="parse_ret"/> + <type name="server_no_data"/> <fsummary>Read, tokenize and parse Erlang expressions</fsummary> <desc> - <p>Reads data from the standard input (<c><anno>IoDevice</anno></c>), - prompting it with <c><anno>Prompt</anno></c>. Starts reading at line number - <c><anno>StartLine</anno></c> (1). The data is tokenized and parsed as if - it were a sequence of Erlang expressions until a final '.' is - reached. It returns:</p> + <p>Reads data from the standard input + (<c><anno>IoDevice</anno></c>), prompting it with + <c><anno>Prompt</anno></c>. Starts reading at location + <c><anno>StartLocation</anno></c> (<c>1</c>). The argument + <c><anno>Options</anno></c> is passed on as the + <c>Options</c> argument of the <c>erl_scan:tokens/4</c> + function. The data is tokenized and parsed as if it were a + sequence of Erlang expressions until a final dot (<c>.</c>) is reached. + It returns:</p> <taglist> - <tag><c>{ok, ExprList, EndLine}</c></tag> + <tag><c>{ok, ExprList, EndLocation}</c></tag> <item> <p>The parsing was successful.</p> </item> - <tag><c>{eof, EndLine}</c></tag> + <tag><c>{eof, EndLocation}</c></tag> <item> - <p>End of file was encountered.</p> + <p>End of file was encountered by the tokenizer.</p> + </item> + <tag><c>eof</c></tag> + <item> + <p>End of file was encountered by the I/O-server.</p> </item> - <tag><c>{error, ErrorInfo, ErrorLine}</c></tag> + <tag><c>{error, ErrorInfo, ErrorLocation}</c></tag> <item> - <p>An error occurred.</p> + <p>An error occurred while tokenizing or parsing.</p> </item> + <tag><c>{error, <anno>ErrorDescription</anno>}</c></tag> + <item> + <p>Other (rare) error condition, for instance <c>{error, estale}</c> + if reading from an NFS file system.</p> + </item> </taglist> <p>Example:</p> <pre> @@ -891,28 +987,42 @@ enter><input>abc("hey".</input> <name name="parse_erl_form" arity="1"/> <name name="parse_erl_form" arity="2"/> <name name="parse_erl_form" arity="3"/> + <name name="parse_erl_form" arity="4"/> <type name="parse_form_ret"/> + <type name="server_no_data"/> <fsummary>Read, tokenize and parse an Erlang form</fsummary> <desc> <p>Reads data from the standard input (<c><anno>IoDevice</anno></c>), - prompting it with <c><anno>Prompt</anno></c>. Starts reading at line number - <c><anno>StartLine</anno></c> (1). The data is tokenized and parsed as if + prompting it with <c><anno>Prompt</anno></c>. Starts reading at + location <c><anno>StartLocation</anno></c> (<c>1</c>). The argument + <c><anno>Options</anno></c> is passed on as the + <c>Options</c> argument of the <c>erl_scan:tokens/4</c> + function. The data is tokenized and parsed as if it were an Erlang form - one of the valid Erlang expressions - in an Erlang source file - until a final '.' is reached. It + in an Erlang source file - until a final dot (<c>.</c>) is reached. It returns:</p> <taglist> - <tag><c>{ok, AbsForm, EndLine}</c></tag> + <tag><c>{ok, AbsForm, EndLocation}</c></tag> <item> <p>The parsing was successful.</p> </item> - <tag><c>{eof, EndLine}</c></tag> + <tag><c>{eof, EndLocation}</c></tag> <item> - <p>End of file was encountered.</p> + <p>End of file was encountered by the tokenizer.</p> + </item> + <tag><c>eof</c></tag> + <item> + <p>End of file was encountered by the I/O-server.</p> </item> - <tag><c>{error, ErrorInfo, ErrorLine}</c></tag> + <tag><c>{error, ErrorInfo, ErrorLocation}</c></tag> <item> - <p>An error occurred.</p> + <p>An error occurred while tokenizing or parsing.</p> </item> + <tag><c>{error, <anno>ErrorDescription</anno>}</c></tag> + <item> + <p>Other (rare) error condition, for instance <c>{error, estale}</c> + if reading from an NFS file system.</p> + </item> </taglist> </desc> </func> @@ -940,7 +1050,7 @@ enter><input>bar.</input> </section> <section> <title>Standard Error</title> - <p>In certain situations, especially when the standard output is redirected, access to an io_server() specific for error messages might be convenient. The io_device 'standard_error' can be used to direct output to whatever the current operating system considers a suitable device for error output. Example on a Unix-like operating system:</p> + <p>In certain situations, especially when the standard output is redirected, access to an I/O-server specific for error messages might be convenient. The IO device <c>standard_error</c> can be used to direct output to whatever the current operating system considers a suitable IO device for error output. Example on a Unix-like operating system:</p> <pre> $ <input>erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\</input> <input>'init:stop().' > /dev/null</input> @@ -956,7 +1066,7 @@ Error: error 11</pre> <c>ErrorInfo</c> structure which is returned from all IO modules. It has the format:</p> <code type="none"> -{ErrorLine, Module, ErrorDescriptor}</code> +{ErrorLocation, Module, ErrorDescriptor}</code> <p>A string which describes the error is obtained with the following call:</p> <code type="none"> diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index 506c1792f1..3312b08064 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -50,6 +50,15 @@ <datatype> <name name="depth"/> </datatype> + <datatype> + <name name="fread_error"/> + </datatype> + <datatype> + <name name="fread_item"/> + </datatype> + <datatype> + <name name="latin1_string"/> + </datatype> </datatypes> <funcs> <func> @@ -204,8 +213,25 @@ <name name="write_string" arity="1"/> <fsummary>Write a string</fsummary> <desc> - <p>Returns the list of characters needed to print <c><anno>String</anno></c> - as a string.</p> + <p>Returns the list of characters needed to print + <c><anno>String</anno></c> as a string.</p> + </desc> + </func> + <func> + <name name="write_string_as_latin1" arity="1"/> + <fsummary>Write a string</fsummary> + <desc> + <p>Returns the list of characters needed to print + <c><anno>String</anno></c> as a string. Non-Latin-1 + characters are escaped.</p> + </desc> + </func> + <func> + <name name="write_latin1_string" arity="1"/> + <fsummary>Write an ISO-latin-1 string</fsummary> + <desc> + <p>Returns the list of characters needed to print + <c><anno>Latin1String</anno></c> as a string.</p> </desc> </func> <func> @@ -213,6 +239,23 @@ <fsummary>Write a character</fsummary> <desc> <p>Returns the list of characters needed to print a character + constant in the Unicode character set.</p> + </desc> + </func> + <func> + <name name="write_char_as_latin1" arity="1"/> + <fsummary>Write a character</fsummary> + <desc> + <p>Returns the list of characters needed to print a character + constant in the Unicode character set. Non-Latin-1 characters + are escaped.</p> + </desc> + </func> + <func> + <name name="write_latin1_char" arity="1"/> + <fsummary>Write an ISO-latin-1 character</fsummary> + <desc> + <p>Returns the list of characters needed to print a character constant in the ISO-latin-1 character set.</p> </desc> </func> @@ -229,6 +272,14 @@ <fsummary>Test for a list of characters</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of + characters in the Unicode range, otherwise it returns <c>false</c>.</p> + </desc> + </func> + <func> + <name name="latin1_char_list" arity="1"/> + <fsummary>Test for a list of ISO-latin-1 characters</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of characters in the ISO-latin-1 range, otherwise it returns <c>false</c>.</p> </desc> </func> @@ -237,17 +288,45 @@ <fsummary>Test for a deep list of characters</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a, possibly deep, list + of characters in the Unicode range, otherwise it returns <c>false</c>.</p> + </desc> + </func> + <func> + <name name="deep_latin1_char_list" arity="1"/> + <fsummary>Test for a deep list of characters</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a, possibly deep, list of characters in the ISO-latin-1 range, otherwise it returns <c>false</c>.</p> </desc> </func> <func> <name name="printable_list" arity="1"/> + <fsummary>Test for a list of printable characters</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of + printable characters, otherwise it returns <c>false</c>.</p> + <p>What is a printable character in this case is determined by the + <c>+pc</c> start up flag to the Erlang VM. See + <seealso marker="io#printable_range/0">io:printable_range/0</seealso> + and <seealso marker="erts:erl#erl">erl(1)</seealso>.</p> + </desc> + </func> + <func> + <name name="printable_latin1_list" arity="1"/> <fsummary>Test for a list of printable ISO-latin-1 characters</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of printable ISO-latin-1 characters, otherwise it returns <c>false</c>.</p> </desc> </func> + <func> + <name name="printable_unicode_list" arity="1"/> + <fsummary>Test for a list of printable Unicode characters</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of + printable Unicode characters, otherwise it returns <c>false</c>.</p> + </desc> + </func> </funcs> </erlref> diff --git a/lib/stdlib/doc/src/io_protocol.xml b/lib/stdlib/doc/src/io_protocol.xml index 0ff3d5c1ee..9328704e11 100644 --- a/lib/stdlib/doc/src/io_protocol.xml +++ b/lib/stdlib/doc/src/io_protocol.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> <year>1999</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -35,10 +35,10 @@ <p>The I/O-protocol in Erlang specifies a way for a client to communicate -with an io_server and vice versa. The io_server is a process handling the -requests and that performs the requested task on i.e. a device. The +with an I/O server and vice versa. The I/O server is a process that handles +the requests and performs the requested task on e.g. an IO device. The client is any Erlang process wishing to read or write data from/to the -device.</p> +IO device.</p> <p>The common I/O-protocol has been present in OTP since the beginning, but has been fairly undocumented and has also somewhat @@ -53,85 +53,85 @@ implement than the original. It can certainly be argumented that the current protocol is too complex, but this text describes how it looks today, not how it should have looked.</p> -<p>The basic ideas from the original protocol still hold. The io_server +<p>The basic ideas from the original protocol still hold. The I/O server and client communicate with one single, rather simplistic protocol and -no server state is ever present in the client. Any io_server can be +no server state is ever present in the client. Any I/O server can be used together with any client code and client code need not be aware -of the actual device the io_server communicates with.</p> +of the actual IO device the I/O server communicates with.</p> <section> -<title>Protocol basics</title> +<title>Protocol Basics</title> -<p>As described in Robert's paper, servers and clients communicate using -io_request/io_reply tuples as follows:</p> +<p>As described in Robert's paper, I/O servers and clients communicate using +<c>io_request</c>/<c>io_reply</c> tuples as follows:</p> <p><em>{io_request, From, ReplyAs, Request}</em><br/> <em>{io_reply, ReplyAs, Reply}</em></p> -<p>The client sends an io_request to the io_server and the server -eventually sends a corresponding reply.</p> +<p>The client sends an <c>io_request</c> tuple to the I/O server and +the server eventually sends a corresponding <c>io_reply</c> tuple.</p> <list type="bulleted"> -<item>From is the pid() of the client, the process which the io_server -sends the reply to.</item> - -<item>ReplyAs can be any datum and is simply returned in the corresponding -io_reply. The io-module in the Erlang standard library simply uses the pid() -of the io_server as the ReplyAs datum, but a more complicated client -could have several outstanding io-requests to the same server and -would then use i.e. a reference() or something else to differentiate among -the incoming io_reply's. The ReplyAs element should be considered -opaque by the io_server. Note that the pid() of the server is not -explicitly present in the io_reply. The reply can be sent from any -process, not necessarily the actual io_server. The ReplyAs element is -the only thing that connects one io_request with an io_reply.</item> - -<item>Request and Reply are described below.</item> +<item><c>From</c> is the <c>pid()</c> of the client, the process which +the I/O server sends the IO reply to.</item> + +<item><c>ReplyAs</c> can be any datum and is returned in the corresponding +<c>io_reply</c>. The <seealso marker="stdlib:io">io</seealso> module simply uses the pid() +of the I/O server as the <c>ReplyAs</c> datum, but a more complicated client +could have several outstanding I/O requests to the same I/O server and +would then use i.e. a <c>reference()</c> or something else to differentiate among +the incoming IO replies. The <c>ReplyAs</c> element should be considered +opaque by the I/O server. Note that the <c>pid()</c> of the I/O server is not +explicitly present in the <c>io_reply</c> tuple. The reply can be sent from any +process, not necessarily the actual I/O server. The <c>ReplyAs</c> element is +the only thing that connects one I/O request with an I/O-reply.</item> + +<item><c>Request</c> and <c>Reply</c> are described below.</item> </list> -<p>When an io_server receives an io_request, it acts upon the actual -Request part and eventually sends an io_reply with the corresponding -Reply part.</p> +<p>When an I/O server receives an <c>io_request</c> tuple, it acts upon the actual +<c>Request</c> part and eventually sends an <c>io_reply</c> tuple with the corresponding +<c>Reply</c> part.</p> </section> <section> -<title>Output requests</title> +<title>Output Requests</title> -<p>To output characters on a device, the following Requests exist:</p> +<p>To output characters on an IO device, the following <c>Request</c>s exist:</p> <p> <em>{put_chars, Encoding, Characters}</em><br/> <em>{put_chars, Encoding, Module, Function, Args}</em> </p> <list type="bulleted"> -<item>Encoding is either 'unicode' or 'latin1', meaning that the +<item><c>Encoding</c> is either <c>unicode</c> or <c>latin1</c>, meaning that the characters are (in case of binaries) encoded as either UTF-8 or - iso-latin-1 (pure bytes). A well behaved io_server should also - return error if list elements contain integers > 255 when the - Encoding is set to latin1. Note that this does not in any way tell - how characters should be put on the actual device or how the - io_server should handle them. Different io_servers may handle the - characters however they want, this simply tells the io_server which - format the data is expected to have. In the Module/Function/argument - case, the Encoding tells which format the designated function - produces. Note that byte-oriented data is simplest sent using latin1 - Encoding</item> - -<item>Characters are the data to be put on the device. If Encoding is - latin1, this is an iolist(). If Encoding is unicode, this is an - Erlang standard mixed unicode list (one integer in a list per + ISO-latin-1 (pure bytes). A well behaved I/O server should also + return error if list elements contain integers > 255 when + <c>Encoding</c> is set to <c>latin1</c>. Note that this does not in any way tell + how characters should be put on the actual IO device or how the + I/O server should handle them. Different I/O servers may handle the + characters however they want, this simply tells the I/O server which + format the data is expected to have. In the <c>Module</c>/<c>Function</c>/<c>Args</c> + case, <c>Encoding</c> tells which format the designated function + produces. Note that byte-oriented data is simplest sent using the ISO-latin-1 + encoding.</item> + +<item>Characters are the data to be put on the IO device. If <c>Encoding</c> is + <c>latin1</c>, this is an <c>iolist()</c>. If <c>Encoding</c> is <c>unicode</c>, this is an + Erlang standard mixed Unicode list (one integer in a list per character, characters in binaries represented as UTF-8).</item> -<item>Module, Function, Args denotes a function which will be called to - produce the data (like io_lib:format). Args is a list of arguments +<item><c>Module</c>, <c>Function</c>, and <c>Args</c> denote a function which will be called to + produce the data (like <c>io_lib:format/2</c>). <c>Args</c> is a list of arguments to the function. The function should produce data in the given - Encoding. The io_server should call the function as apply(Mod, Func, - Args) and will put the returned data on the device as if it was sent - in a {put_chars, Encoding, Characters} request. If the function + <c>Encoding</c>. The I/O server should call the function as + <c>apply(Mod, Func, Args)</c> and will put the returned data on the IO device as if it was sent + in a <c>{put_chars, Encoding, Characters}</c> request. If the function returns anything else than a binary or list or throws an exception, an error should be sent back to the client.</item> </list> -<p>The server replies to the client with an io_reply where the Reply +<p>The I/O server replies to the client with an <c>io_reply</c> tuple where the <c>Reply</c> element is one of:</p> <p> <em>ok</em><br/> @@ -139,49 +139,50 @@ element is one of:</p> </p> <list type="bulleted"> -<item>Error describes the error to the client, which may do whatever it - wants with it. The Erlang io-module typically returns it as is.</item> +<item><c>Error</c> describes the error to the client, which may do whatever + it wants with it. The Erlang <seealso marker="stdlib:io">io</seealso> + module typically returns it as is.</item> </list> -<p>For backward compatibility the following Requests should also be -handled by an io_server (these messages should not be present after +<p>For backward compatibility the following <c>Request</c>s should also be +handled by an I/O server (these requests should not be present after R15B of OTP):</p> <p> <em>{put_chars, Characters}</em><br/> <em>{put_chars, Module, Function, Args}</em> </p> -<p>These should behave as {put_chars, latin1, Characters} and {put_chars, -latin1, Module, Function, Args} respectively. </p> +<p>These should behave as <c>{put_chars, latin1, Characters}</c> and +<c>{put_chars, latin1, Module, Function, Args}</c> respectively. </p> </section> <section> <title>Input Requests</title> -<p>To read characters from a device, the following Requests exist:</p> +<p>To read characters from an IO device, the following <c>Request</c>s exist:</p> <p><em>{get_until, Encoding, Prompt, Module, Function, ExtraArgs}</em></p> <list type="bulleted"> -<item>Encoding denotes how data is to be sent back to the client and +<item><c>Encoding</c> denotes how data is to be sent back to the client and what data is sent to the function denoted by - Module/Function/ExtraArgs. If the function supplied returns data as a + <c>Module</c>/<c>Function</c>/<c>ExtraArgs</c>. If the function supplied returns data as a list, the data is converted to this encoding. If however the function supplied returns data in some other format, no conversion - can be done and it's up to the client supplied function to return - data in a proper way. If Encoding is latin1, lists of integers + can be done and it is up to the client supplied function to return + data in a proper way. If <c>Encoding</c> is <c>latin1</c>, lists of integers 0..255 or binaries containing plain bytes are sent back to the - client when possible, if Encoding is unicode, lists with integers in - the whole unicode range or binaries encoded in UTF-8 are sent to the + client when possible; if <c>Encoding</c> is <c>unicode</c>, lists with integers in + the whole Unicode range or binaries encoded in UTF-8 are sent to the client. The user supplied function will always see lists of integers, never - binaries, but the list may contain numbers > 255 if the Encoding is - 'unicode'.</item> + binaries, but the list may contain numbers > 255 if the <c>Encoding</c> is + <c>unicode</c>.</item> -<item>Prompt is a list of characters (not mixed, no binaries) or an atom() - to be output as a prompt for input on the device. The Prompt is - often ignored by the io_server and a Prompt set to '' should always - be ignored (and result in nothing being written to the device).</item> +<item><c>Prompt</c> is a list of characters (not mixed, no binaries) or an atom + to be output as a prompt for input on the IO device. <c>Prompt</c> is + often ignored by the I/O server and if set to <c>''</c> it should always + be ignored (and result in nothing being written to the IO device).</item> -<item><p>Module, Function, ExtraArgs denotes a function and arguments to +<item><p><c>Module</c>, <c>Function</c>, and <c>ExtraArgs</c> denote a function and arguments to determine when enough data is written. The function should take two additional arguments, the last state, and a list of characters. The function should return one of:</p> @@ -189,23 +190,23 @@ latin1, Module, Function, Args} respectively. </p> <em>{done, Result, RestChars}</em><br/> <em>{more, Continuation}</em> </p> - <p>The Result can be any Erlang term, but if it is a list(), the - io_server may convert it to a binary() of appropriate format before - returning it to the client, if the server is set in binary mode (see + <p>The <c>Result</c> can be any Erlang term, but if it is a <c>list()</c>, the + I/O server may convert it to a <c>binary()</c> of appropriate format before + returning it to the client, if the I/O server is set in binary mode (see below).</p> - <p>The function will be called with the data the io_server finds on - its device, returning {done, Result, RestChars} when enough data is - read (in which case Result is sent to the client and RestChars are - kept in the io_server as a buffer for subsequent input) or {more, - Continuation}, indicating that more characters are needed to - complete the request. The Continuation will be sent as the state in + <p>The function will be called with the data the I/O server finds on + its IO device, returning <c>{done, Result, RestChars}</c> when enough data is + read (in which case <c>Result</c> is sent to the client and <c>RestChars</c> is + kept in the I/O server as a buffer for subsequent input) or + <c>{more, Continuation}</c>, indicating that more characters are needed to + complete the request. The <c>Continuation</c> will be sent as the state in subsequent calls to the function when more characters are available. When no more characters are available, the function - shall return {done,eof,Rest}. + shall return <c>{done, eof, Rest}</c>. The initial state is the empty list and the data when an - end of file is reached on the device is the atom 'eof'. An emulation - of the get_line request could be (inefficiently) implemented using + end of file is reached on the IO device is the atom <c>eof</c>. An emulation + of the <c>get_line</c> request could be (inefficiently) implemented using the following functions:</p> <code> -module(demo). @@ -214,7 +215,9 @@ latin1, Module, Function, Args} respectively. </p> until_newline(_ThisFar,eof,_MyStopCharacter) -> {done,eof,[]}; until_newline(ThisFar,CharList,MyStopCharacter) -> - case lists:splitwith(fun(X) -> X =/= MyStopCharacter end, CharList) of + case + lists:splitwith(fun(X) -> X =/= MyStopCharacter end, CharList) + of {L,[]} -> {more,ThisFar++L}; {L2,[MyStopCharacter|Rest]} -> @@ -222,45 +225,47 @@ until_newline(ThisFar,CharList,MyStopCharacter) -> end. get_line(IoServer) -> - IoServer ! {io_request, self(), IoServer, {get_until, unicode, '', - ?MODULE, until_newline, [$\n]}}, + IoServer ! {io_request, + self(), + IoServer, + {get_until, unicode, '', ?MODULE, until_newline, [$\n]}}, receive {io_reply, IoServer, Data} -> Data end. </code> - <p>Note especially that the last element in the Request tuple ([$\n]) + <p>Note especially that the last element in the <c>Request</c> tuple (<c>[$\n]</c>) is appended to the argument list when the function is called. The function should be called like - apply(Module, Function, [ State, Data | ExtraArgs ]) by the io_server</p> + <c>apply(Module, Function, [ State, Data | ExtraArgs ])</c> by the I/O server</p> </item> </list> -<p>A defined number of characters is requested using this Request:</p> +<p>A fixed number of characters is requested using this <c>Request</c>:</p> <p> <em>{get_chars, Encoding, Prompt, N}</em> </p> <list type="bulleted"> -<item>Encoding and Prompt as for get_until.</item> +<item><c>Encoding</c> and <c>Prompt</c> as for <c>get_until</c>.</item> -<item>N is the number of characters to be read from the device.</item> +<item><c>N</c> is the number of characters to be read from the IO device.</item> </list> -<p>A single line (like in the example above) is requested with this Request:</p> +<p>A single line (like in the example above) is requested with this <c>Request</c>:</p> <p> <em>{get_line, Encoding, Prompt}</em> </p> <list type="bulleted"> -<item>Encoding and prompt as above.</item> +<item><c>Encoding</c> and <c>Prompt</c> as above.</item> </list> -<p>Obviously, get_chars and get_line could be implemented with the -get_until request (and indeed was originally), but demands for +<p>Obviously, the <c>get_chars</c> and <c>get_line</c> could be implemented with the +<c>get_until</c> request (and indeed they were originally), but demands for efficiency has made these additions necessary.</p> -<p>The server replies to the client with an io_reply where the Reply +<p>The I/O server replies to the client with an <c>io_reply</c> tuple where the <c>Reply</c> element is one of:</p> <p> <em>Data</em><br/> @@ -269,16 +274,17 @@ element is one of:</p> </p> <list type="bulleted"> -<item>Data is the characters read, in either list or binary form - (depending on the io_server mode, see below).</item> -<item>Error describes the error to the client, which may do whatever it - wants with it. The Erlang io-module typically returns it as is.</item> -<item>eof is returned when input end is reached and no more data is +<item><c>Data</c> is the characters read, in either list or binary form + (depending on the I/O server mode, see below).</item> +<item><c>Error</c> describes the error to the client, which may do whatever it + wants with it. The Erlang <seealso marker="stdlib:io">io</seealso> + module typically returns it as is.</item> +<item><c>eof</c> is returned when input end is reached and no more data is available to the client process.</item> </list> -<p>For backward compatibility the following Requests should also be -handled by an io_server (these messages should not be present after +<p>For backward compatibility the following <c>Request</c>s should also be +handled by an I/O server (these reqeusts should not be present after R15B of OTP):</p> <p> @@ -287,30 +293,30 @@ R15B of OTP):</p> <em>{get_line, Prompt}</em><br/> </p> -<p>These should behave as {get_until, latin1, Prompt, Module, Function, -ExtraArgs}, {get_chars, latin1, Prompt, N} and {get_line, latin1, -Prompt} respectively.</p> +<p>These should behave as <c>{get_until, latin1, Prompt, Module, Function, +ExtraArgs}</c>, <c>{get_chars, latin1, Prompt, N}</c> and <c>{get_line, latin1, +Prompt}</c> respectively.</p> </section> <section> -<title>I/O-server modes</title> - -<p>Demands for efficiency when reading data from an io_server has not -only lead to the addition of the get_line and get_chars requests, but -has also added the concept of io_server options. No options are -mandatory to implement, but all io_servers in the Erlang standard -libraries honor the 'binary' option, which allows the Data in the -io_reply to be binary instead of in list form <em>when possible</em>. +<title>I/O-server Modes</title> + +<p>Demands for efficiency when reading data from an I/O server has not +only lead to the addition of the <c>get_line</c> and <c>get_chars</c> requests, but +has also added the concept of I/O server options. No options are +mandatory to implement, but all I/O servers in the Erlang standard +libraries honor the <c>binary</c> option, which allows the <c>Data</c> element of the +<c>io_reply</c> tuple to be a binary instead of a list <em>when possible</em>. If the data is sent as a binary, Unicode data will be sent in the -standard Erlang unicode -format, i.e. UTF-8 (note that the function in get_until still gets -list data regardless of the io_server mode).</p> +standard Erlang Unicode +format, i.e. UTF-8 (note that the function of the <c>get_until</c> request still gets +list data regardless of the I/O server mode).</p> -<p>Note that i.e. the <c>get_until</c> request allows for a function with the data specified as always being a list. Also the return value data from such a function can be of any type (as is indeed the case when an io:fread request is sent to an io_server). The client has to be prepared for data received as answers to those requests to be in a variety of forms, but the server should convert the results to binaries whenever possible (i.e. when the function supplied to get_until actually returns a list). The example shown later in this text does just that.</p> +<p>Note that i.e. the <c>get_until</c> request allows for a function with the data specified as always being a list. Also the return value data from such a function can be of any type (as is indeed the case when an <c>io:fread</c> request is sent to an I/O server). The client has to be prepared for data received as answers to those requests to be in a variety of forms, but the I/O server should convert the results to binaries whenever possible (i.e. when the function supplied to <c>get_until</c> actually returns a list). The example shown later in this text does just that.</p> <p>An I/O-server in binary mode will affect the data sent to the client, so that it has to be able to handle binary data. For convenience, it -is possible to set and retrieve the modes of an io_server using the -following I/O-requests:</p> +is possible to set and retrieve the modes of an I/O server using the +following I/O requests:</p> <p> <em>{setopts, Opts}</em> @@ -318,72 +324,72 @@ following I/O-requests:</p> <list type="bulleted"> -<item>Opts is a list of options in the format recognized by proplists (and - of course by the io_server itself).</item> +<item><c>Opts</c> is a list of options in the format recognized by <seealso marker="stdlib:proplists">proplists</seealso> (and + of course by the I/O server itself).</item> </list> -<p>As an example, the io_server for the interactive shell (in group.erl) +<p>As an example, the I/O server for the interactive shell (in <c>group.erl</c>) understands the following options:</p> <p> -<em>{binary, bool()} (or 'binary'/'list')</em><br/> -<em>{echo, bool()}</em><br/> +<em>{binary, boolean()}</em> (or <em>binary</em>/<em>list</em>)<br/> +<em>{echo, boolean()}</em><br/> <em>{expand_fun, fun()}</em><br/> -<em>{encoding, 'unicode'/'latin1'} (or 'unicode'/'latin1')</em> +<em>{encoding, unicode/latin1}</em> (or <em>unicode</em>/<em>latin1</em>) </p> -<p>- of which the 'binary' and 'encoding' options are common for all -io_servers in OTP, while 'echo' and 'expand' is valid only for this -io_server. It's worth noting that the 'unicode' option notifies how -characters are actually put on the physical device, i.e. if the -terminal per se is unicode aware, it does not affect how characters +<p>- of which the <c>binary</c> and <c>encoding</c> options are common for all +I/O servers in OTP, while <c>echo</c> and <c>expand</c> are valid only for this +I/O server. It is worth noting that the <c>unicode</c> option notifies how +characters are actually put on the physical IO device, i.e. if the +terminal per se is Unicode aware, it does not affect how characters are sent in the I/O-protocol, where each request contains encoding information for the provided or returned data.</p> -<p>The server should send one of the following as Reply:</p> +<p>The I/O server should send one of the following as <c>Reply</c>:</p> <p> <em>ok</em><br/> <em>{error, Error}</em> </p> -<p>An error (preferably enotsup) is to be expected if the option is -not supported by the io_server (like if an 'echo' option is sent in a -setopt Request to a plain file).</p> +<p>An error (preferably <c>enotsup</c>) is to be expected if the option is +not supported by the I/O server (like if an <c>echo</c> option is sent in a +<c>setopts</c> request to a plain file).</p> -<p>To retrieve options, this message is used:</p> +<p>To retrieve options, this request is used:</p> <p> <em>getopts</em> </p> -<p>The 'getopts' message requests a complete list of all options -supported by the io_server as well as their current values.</p> +<p>The <c>getopts</c> request asks for a complete list of all options +supported by the I/O server as well as their current values.</p> -<p>The server replies:</p> +<p>The I/O server replies:</p> <p> <em>OptList</em><br/> -<em>{error,Error}</em> +<em>{error, Error}</em> </p> <list type="bulleted"> -<item>OptList is a list of tuples {Option, Value} where Option is always +<item><c>OptList</c> is a list of tuples <c>{Option, Value}</c> where <c>Option</c> is always an atom.</item> </list> </section> <section> -<title>Multiple I/O requests</title> +<title>Multiple I/O Requests</title> -<p>The Request element can in itself contain several Requests by using +<p>The <c>Request</c> element can in itself contain several <c>Request</c>s by using the following format:</p> <p> <em>{requests, Requests}</em> </p> <list type="bulleted"> -<item>Requests is a list of valid Request tuples for the protocol, they +<item><c>Requests</c> is a list of valid <c>io_request</c> tuples for the protocol, they shall be executed in the order in which they appear in the list and the execution should continue until one of the requests result in an error or the list is consumed. The result of the last request is sent back to the client.</item> </list> -<p>The server can for a list of requests send any of the valid results in +<p>The I/O server can for a list of requests send any of the valid results in the reply:</p> <p> @@ -395,7 +401,7 @@ the reply:</p> <p>- depending on the actual requests in the list.</p> </section> <section> -<title>Optional I/O-requests</title> +<title>Optional I/O Requests</title> <p>The following I/O request is optional to implement and a client should be prepared for an error return:</p> @@ -403,47 +409,47 @@ should be prepared for an error return:</p> <em>{get_geometry, Geometry}</em> </p> <list type="bulleted"> -<item>Geometry is either the atom 'rows' or the atom 'columns'.</item> +<item><c>Geometry</c> is either the atom <c>rows</c> or the atom <c>columns</c>.</item> </list> -<p>The server should send the Reply as:</p> +<p>The I/O server should send the <c>Reply</c> as:</p> <p> <em>{ok, N}</em><br/> <em>{error, Error}</em> </p> <list type="bulleted"> -<item>N is the number of character rows or columns the device has, if - applicable to the device the io_server handles, otherwise {error, - enotsup} is a good answer.</item> +<item><c>N</c> is the number of character rows or columns the IO device has, if + applicable to the IO device the I/O server handles, otherwise <c>{error, + enotsup}</c> is a good answer.</item> </list> </section> <section> -<title>Unimplemented request types:</title> +<title>Unimplemented Request Types</title> -<p>If an io_server encounters a request it does not recognize (i.e. the -io_request tuple is in the expected format, but the actual Request is -unknown), the server should send a valid reply with the error tuple:</p> +<p>If an I/O server encounters a request it does not recognize (i.e. the +<c>io_request</c> tuple is in the expected format, but the actual <c>Request</c> is +unknown), the I/O server should send a valid reply with the error tuple:</p> <p> <em>{error, request}</em> </p> -<p>This makes it possible to extend the protocol with optional messages +<p>This makes it possible to extend the protocol with optional requests and for the clients to be somewhat backwards compatible.</p> </section> <section> -<title>An annotated and working example io_server:</title> +<title>An Annotated and Working Example I/O Server</title> -<p>An io_server is any process capable of handling the protocol. There is -no generic io_server behavior, but could well be. The framework is +<p>An I/O server is any process capable of handling the I/O protocol. There is +no generic I/O server behavior, but could well be. The framework is simple enough, a process handling incoming requests, usually both -io_requests and other device-specific requests (for i.e. positioning , +I/O-requests and other IO device-specific requests (for i.e. positioning, closing etc.).</p> -<p>Our example io_server stores characters in an ets table, making up a +<p>Our example I/O server stores characters in an ETS table, making up a fairly crude ram-file (it is probably not useful, but working).</p> <p>The module begins with the usual directives, a function to start the -server and a main loop handling the requests:</p> +I/O server and a main loop handling the requests:</p> <code> -module(ets_io_server). @@ -486,18 +492,19 @@ loop(State) -> </code> <p>The main loop receives messages from the client (which might be using -the io-module to send requests). For each request the function -request/2 is called and a reply is eventually sent using the reply/3 +the <seealso marker="stdlib:io">io</seealso> module to send requests). +For each request the function +<c>request/2</c> is called and a reply is eventually sent using the <c>reply/3</c> function.</p> -<p>The "private" message {From, rewind} results in the +<p>The "private" message <c>{From, rewind}</c> results in the current position in the pseudo-file to be reset to 0 (the beginning of -the "file"). This is a typical example of device-specific +the "file"). This is a typical example of IO device-specific messages not being part of the I/O-protocol. It is usually a bad idea -to embed such private messages in io_request tuples, as that might be +to embed such private messages in <c>io_request</c> tuples, as that might be confusing to the reader.</p> -<p>Let's look at the reply function first...</p> +<p>Let us look at the reply function first...</p> <code> @@ -506,8 +513,8 @@ reply(From, ReplyAs, Reply) -> </code> -<p>Simple enough, it sends the io_reply tuple back to the client, -providing the ReplyAs element received in the request along with the +<p>Simple enough, it sends the <c>io_reply</c> tuple back to the client, +providing the <c>ReplyAs</c> element received in the request along with the result of the request, as described above.</p> <p>Now look at the different requests we need to handle. First the @@ -525,18 +532,18 @@ request({put_chars, Encoding, Module, Function, Args}, State) -> end; </code> -<p>The Encoding tells us how the characters in the message are +<p>The <c>Encoding</c> tells us how the characters in the request are represented. We want to store the characters as lists in the -ets-table, so we convert them to lists using the -unicode:characters_to_list/2 function. The conversion function -conveniently accepts the encoding types unicode or latin1, so we can -use the Encoding parameter directly.</p> +ETS table, so we convert them to lists using the +<seealso marker="stdlib:unicode#characters_to_list/2"><c>unicode:characters_to_list/2</c></seealso> function. The conversion function +conveniently accepts the encoding types <c>unicode</c> or <c>latin1</c>, so we can +use <c>Encoding</c> directly.</p> -<p>When Module, Function and Arguments are provided, we simply apply it +<p>When <c>Module</c>, <c>Function</c> and <c>Arguments</c> are provided, we simply apply it and do the same thing with the result as if the data was provided directly.</p> -<p>Let's handle the requests for retrieving data too:</p> +<p>Let us handle the requests for retrieving data too:</p> <code> request({get_until, Encoding, _Prompt, M, F, As}, State) -> @@ -550,11 +557,11 @@ request({get_line, Encoding, _Prompt}, State) -> </code> <p>Here we have cheated a little by more or less only implementing -get_until and using internal helpers to implement get_chars and -get_line. In production code, this might be to inefficient, but that +<c>get_until</c> and using internal helpers to implement <c>get_chars</c> and +<c>get_line</c>. In production code, this might be too inefficient, but that of course depends on the frequency of the different requests. Before -we start actually implementing the functions put_chars/2 and -get_until/5, lets look into the few remaining requests:</p> +we start actually implementing the functions <c>put_chars/2</c> and +<c>get_until/5</c>, let us look into the few remaining requests:</p> <code> request({get_geometry,_}, State) -> @@ -567,18 +574,18 @@ request({requests, Reqs}, State) -> multi_request(Reqs, {ok, ok, State}); </code> -<p>The get_geometry request has no meaning for this io_server, so the -reply will be {error, enotsup}. The only option we handle is the -binary/list option, which is done in separate functions.</p> +<p>The <c>get_geometry</c> request has no meaning for this I/O server, so the +reply will be <c>{error, enotsup}</c>. The only option we handle is the +<c>binary</c>/<c>list</c> option, which is done in separate functions.</p> -<p>The multi-request tag (requests) is handled in a separate loop +<p>The multi-request tag (<c>requests</c>) is handled in a separate loop function applying the requests in the list one after another, returning the last result.</p> -<p>What's left is to handle backward compatibility and the file-module +<p>What is left is to handle backward compatibility and the <seealso marker="kernel:file">file</seealso> module (which uses the old requests until backward compatibility with pre-R13 -nodes is no longer needed). Note that the io_server will not work with -a simple file:write if these are not added:</p> +nodes is no longer needed). Note that the I/O server will not work with +a simple <c>file:write/2</c> if these are not added:</p> <code> request({put_chars,Chars}, State) -> @@ -593,7 +600,7 @@ request({get_until, Prompt,M,F,As}, State) -> request({get_until,latin1,Prompt,M,F,As}, State); </code> -<p>Ok, what's left now is to return {error, request} if the request is +<p>OK, what is left now is to return <c>{error, request}</c> if the request is not recognized:</p> <code> @@ -601,7 +608,7 @@ request(_Other, State) -> {error, {error, request}, State}. </code> -<p>Let's move further and actually handle the different requests, first +<p>Let us move further and actually handle the different requests, first the fairly generic multi-request type:</p> <code> @@ -615,10 +622,10 @@ multi_request([], Result) -> <p>We loop through the requests one at the time, stopping when we either encounter an error or the list is exhausted. The last return value is -sent back to the client (it's first returned to the main loop and then -sent back by the function io_reply).</p> +sent back to the client (it is first returned to the main loop and then +sent back by the function <c>io_reply</c>).</p> -<p>The getopt and setopt requests are also simple to handle, we just +<p>The <c>getopts</c> and <c>setopts</c> requests are also simple to handle, we just change or read our state record:</p> <code> @@ -656,24 +663,24 @@ getopts(#state{mode=M} = S) -> end}],S}. </code> -<p>As a convention, all io_servers handle both {setopts, [binary]}, -{setopts, [list]} and {setopts,[{binary, bool()}]}, hence the trick -with proplists:substitute_negations/2 and proplists:unfold/1. If -invalid options are sent to us, we send {error,enotsup} back to the +<p>As a convention, all I/O servers handle both <c>{setopts, [binary]}</c>, +<c>{setopts, [list]}</c> and <c>{setopts,[{binary, boolean()}]}</c>, hence the trick +with <c>proplists:substitute_negations/2</c> and <c>proplists:unfold/1</c>. If +invalid options are sent to us, we send <c>{error, enotsup}</c> back to the client.</p> -<p>The getopts request should return a list of {Option, Value} tuples, +<p>The <c>getopts</c> request should return a list of <c>{Option, Value}</c> tuples, which has the twofold function of providing both the current values -and the available options of this io_server. We have only one option, +and the available options of this I/O server. We have only one option, and hence return that.</p> -<p>So far our io_server has been fairly generic (except for the rewind -request handled in the main loop and the creation of an ets table). -Most io_servers contain code similar to what's above.</p> +<p>So far our I/O server has been fairly generic (except for the <c>rewind</c> +request handled in the main loop and the creation of an ETS table). +Most I/O servers contain code similar to the one above.</p> <p>To make the example runnable, we now start implementing the actual -reading and writing of the data to/from the ets-table. First the -put_chars function:</p> +reading and writing of the data to/from the ETS table. First the +<c>put_chars/3</c> function:</p> <code> put_chars(Chars, #state{table = T, position = P} = State) -> @@ -686,10 +693,10 @@ put_chars(Chars, #state{table = T, position = P} = State) -> <p>We already have the data as (Unicode) lists and therefore just split the list in runs of a predefined size and put each run in the table at the current position (and forward). The functions -split_data/3 and apply_update/2 are implemented below.</p> +<c>split_data/3</c> and <c>apply_update/2</c> are implemented below.</p> -<p>Now we want to read data from the table. The get_until function reads -data and applies the function until it says it's done. The result is +<p>Now we want to read data from the table. The <c>get_until/5</c> function reads +data and applies the function until it says it is done. The result is sent back to the client:</p> <code> @@ -700,11 +707,12 @@ get_until(Encoding, Mod, Func, As, if M =:= binary -> {ok, - unicode:characters_to_binary(Data,unicode,Encoding), + unicode:characters_to_binary(Data, unicode, Encoding), State#state{position = NewP}}; true -> case check(Encoding, - unicode:characters_to_list(Data, unicode)) of + unicode:characters_to_list(Data, unicode)) + of {error, _} = E -> {error, E, State}; List -> @@ -730,24 +738,24 @@ get_loop(M,F,A,T,P,C) -> end. </code> -<p>Here we also handle the mode (binary or list) that can be set by -the setopts request. By default, all OTP io_servers send data back to -the client as lists, but switching mode to binary might increase -efficiency if the server handles it in an appropriate way. The -implementation of get_until is hard to get efficient as the supplied -function is defined to take lists as arguments, but get_chars and -get_line can be optimized for binary mode. This example does not +<p>Here we also handle the mode (<c>binary</c> or <c>list</c>) that can be set by +the <c>setopts</c> request. By default, all OTP I/O servers send data back to +the client as lists, but switching mode to <c>binary</c> might increase +efficiency if the I/O server handles it in an appropriate way. The +implementation of <c>get_until</c> is hard to get efficient as the supplied +function is defined to take lists as arguments, but <c>get_chars</c> and +<c>get_line</c> can be optimized for binary mode. This example does not optimize anything however. It is important though that the returned data is of the right type depending on the options set, so we convert the lists to binaries in the correct encoding <em>if possible</em> -before returning. The function supplied in the get_until request may, +before returning. The function supplied in the <c>get_until</c> request tuple may, as its final result return anything, so only functions actually returning lists can get them converted to binaries. If the request -contained the encoding tag unicode, the lists can contain all unicode +contained the encoding tag <c>unicode</c>, the lists can contain all Unicode codepoints and the binaries should be in UTF-8, if the encoding tag -was latin1, the client should only get characters in the range -0..255. The function check/2 takes care of not returning arbitrary -unicode codepoints in lists if the encoding was given as latin1. If +was <c>latin1</c>, the client should only get characters in the range +0..255. The function <c>check/2</c> takes care of not returning arbitrary +Unicode codepoints in lists if the encoding was given as <c>latin1</c>. If the function did not return a list, the check cannot be performed and the result will be that of the supplied function untouched.</p> @@ -768,13 +776,13 @@ check(latin1, List) -> end. </code> -<p>The function check takes care of providing an error tuple if unicode +<p>The function check takes care of providing an error tuple if Unicode codepoints above 255 is to be returned if the client requested latin1.</p> -<p>The two functions until_newline/3 and until_enough/3 are helpers used -together with the get_until function to implement get_chars and -get_line (inefficiently):</p> +<p>The two functions <c>until_newline/3</c> and <c>until_enough/3</c> are helpers used +together with the <c>get_until/5</c> function to implement <c>get_chars</c> and +<c>get_line</c> (inefficiently):</p> <code> until_newline([],eof,_MyStopCharacter) -> @@ -782,7 +790,9 @@ until_newline([],eof,_MyStopCharacter) -> until_newline(ThisFar,eof,_MyStopCharacter) -> {done,ThisFar,[]}; until_newline(ThisFar,CharList,MyStopCharacter) -> - case lists:splitwith(fun(X) -> X =/= MyStopCharacter end, CharList) of + case + lists:splitwith(fun(X) -> X =/= MyStopCharacter end, CharList) + of {L,[]} -> {more,ThisFar++L}; {L2,[MyStopCharacter|Rest]} -> @@ -802,10 +812,10 @@ until_enough(ThisFar,CharList,_N) -> </code> <p>As can be seen, the functions above are just the type of functions -that should be provided in get_until requests.</p> +that should be provided in <c>get_until</c> requests.</p> <p>Now we only need to read and write the table in an appropriate way to -complete the server:</p> +complete the I/O server:</p> <code> get(P,Tab) -> @@ -847,13 +857,13 @@ apply_update(Table, {Row, Col, List}) -> end. </code> -<p>The table is read or written in chunks of ?CHARS_PER_REC, overwriting +<p>The table is read or written in chunks of <c>?CHARS_PER_REC</c>, overwriting when necessary. The implementation is obviously not efficient, it is just working.</p> <p>This concludes the example. It is fully runnable and you can read or -write to the io_server by using i.e. the io_module or even the file -module. It's as simple as that to implement a fully fledged io_server +write to the I/O server by using i.e. the <seealso marker="stdlib:io">io</seealso> module or even the <seealso marker="kernel:file">file</seealso> +module. It is as simple as that to implement a fully fledged I/O server in Erlang.</p> </section> </chapter> diff --git a/lib/stdlib/doc/src/lib.xml b/lib/stdlib/doc/src/lib.xml index 19fb827cbf..30f164826c 100644 --- a/lib/stdlib/doc/src/lib.xml +++ b/lib/stdlib/doc/src/lib.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/lists.xml b/lib/stdlib/doc/src/lists.xml index 8b31f3ac3d..ee3c51c62c 100644 --- a/lib/stdlib/doc/src/lists.xml +++ b/lib/stdlib/doc/src/lists.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2012</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -123,6 +123,14 @@ </desc> </func> <func> + <name name="droplast" arity="1"/> + <fsummary>Drop the last element of a list</fsummary> + <desc> + <p>Drops the last element of a <c><anno>List</anno></c>. The list should + be non-empty, otherwise the function will crash with a <c>function_clause</c></p> + </desc> + </func> + <func> <name name="dropwhile" arity="2"/> <fsummary>Drop elements from a list while a predicate is true</fsummary> <desc> @@ -152,6 +160,31 @@ </desc> </func> <func> + <name name="filtermap" arity="2"/> + <fsummary>Filter and map elements which satisfy a function</fsummary> + <desc> + <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>)</c> on successive elements <c>Elem</c> + of <c><anno>List1</anno></c>. <c><anno>Fun</anno>/2</c> must return either a boolean + or a tuple <c>{true, <anno>Value</anno>}</c>. The function returns the list of elements + for which <c><anno>Fun</anno></c> returns a new value, where a value of <c>true</c> + is synonymous with <c>{true, <anno>Elem</anno>}</c>.</p> + <p>That is, <c>filtermap</c> behaves as if it had been defined as follows:</p> + <code type="none"> +filtermap(Fun, List1) -> + lists:foldr(fun(Elem, Acc) -> + case Fun(Elem) of + false -> Acc; + true -> [Elem|Acc]; + {true,Value} -> [Value|Acc] + end, + end, [], List1).</code> + <p>Example:</p> + <pre> +> <input>lists:filtermap(fun(X) -> case X rem 2 of 0 -> {true, X div 2}; _ -> false end end, [1,2,3,4,5]).</input> +[1,2]</pre> + </desc> + </func> + <func> <name name="flatlength" arity="1"/> <fsummary>Length of flattened deep list</fsummary> <desc> @@ -248,18 +281,13 @@ flatmap(Fun, List1) -> </desc> </func> <func> - <name>keyfind(Key, N, TupleList) -> Tuple | false</name> + <name name="keyfind" arity="3"/> + <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <fsummary>Search for an element in a list of tuples</fsummary> - <type> - <v>Key = term()</v> - <v>N = 1..tuple_size(Tuple)</v> - <v>TupleList = [Tuple]</v> - <v>Tuple = tuple()</v> - </type> - <desc> - <p>Searches the list of tuples <c>TupleList</c> for a - tuple whose <c>N</c>th element compares equal to <c>Key</c>. - Returns <c>Tuple</c> if such a tuple is found, + <desc> + <p>Searches the list of tuples <c><anno>TupleList</anno></c> for a + tuple whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>. + Returns <c><anno>Tuple</anno></c> if such a tuple is found, otherwise <c>false</c>.</p> </desc> </func> @@ -281,17 +309,12 @@ flatmap(Fun, List1) -> </desc> </func> <func> - <name>keymember(Key, N, TupleList) -> boolean()</name> + <name name="keymember" arity="3"/> + <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <fsummary>Test for membership of a list of tuples</fsummary> - <type> - <v>Key = term()</v> - <v>N = 1..tuple_size(Tuple)</v> - <v>TupleList = [Tuple]</v> - <v> Tuple = tuple()</v> - </type> - <desc> - <p>Returns <c>true</c> if there is a tuple in <c>TupleList</c> - whose <c>N</c>th element compares equal to <c>Key</c>, otherwise + <desc> + <p>Returns <c>true</c> if there is a tuple in <c><anno>TupleList</anno></c> + whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>, otherwise <c>false</c>.</p> </desc> </func> @@ -321,18 +344,13 @@ flatmap(Fun, List1) -> </desc> </func> <func> - <name>keysearch(Key, N, TupleList) -> {value, Tuple} | false</name> + <name name="keysearch" arity="3"/> + <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <fsummary>Search for an element in a list of tuples</fsummary> - <type> - <v>Key = term()</v> - <v>N = 1..tuple_size(Tuple)</v> - <v>TupleList = [Tuple]</v> - <v>Tuple = tuple()</v> - </type> - <desc> - <p>Searches the list of tuples <c>TupleList</c> for a - tuple whose <c>N</c>th element compares equal to <c>Key</c>. - Returns <c>{value, Tuple}</c> if such a tuple is found, + <desc> + <p>Searches the list of tuples <c><anno>TupleList</anno></c> for a + tuple whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>. + Returns <c>{value, <anno>Tuple</anno>}</c> if such a tuple is found, otherwise <c>false</c>.</p> <note><p>This function is retained for backward compatibility. The function <c>lists:keyfind/3</c> (introduced in R13A) @@ -425,15 +443,11 @@ flatmap(Fun, List1) -> </desc> </func> <func> - <name>member(Elem, List) -> boolean()</name> + <name name="member" arity="2"/> <fsummary>Test for membership of a list</fsummary> - <type> - <v>Elem = term()</v> - <v>List = [term()]</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Elem</c> matches some element of - <c>List</c>, otherwise <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Elem</anno></c> matches some element of + <c><anno>List</anno></c>, otherwise <c>false</c>.</p> </desc> </func> <func> @@ -562,14 +576,11 @@ c</pre> </desc> </func> <func> - <name>reverse(List1, Tail) -> List2</name> + <name name="reverse" arity="2"/> <fsummary>Reverse a list appending a tail</fsummary> - <type> - <v>List1 = Tail = List2 = [term()]</v> - </type> <desc> - <p>Returns a list with the elements in <c>List1</c> - in reverse order, with the tail <c>Tail</c> appended. For + <p>Returns a list with the elements in <c><anno>List1</anno></c> + in reverse order, with the tail <c><anno>Tail</anno></c> appended. For example:</p> <pre> > <input>lists:reverse([1, 2, 3, 4], [a, b, c]).</input> diff --git a/lib/stdlib/doc/src/log_mf_h.xml b/lib/stdlib/doc/src/log_mf_h.xml index f2b09b58eb..3ef659f579 100644 --- a/lib/stdlib/doc/src/log_mf_h.xml +++ b/lib/stdlib/doc/src/log_mf_h.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml new file mode 100644 index 0000000000..b37f7fd7fd --- /dev/null +++ b/lib/stdlib/doc/src/maps.xml @@ -0,0 +1,338 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2013</year><year>2014</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + </legalnotice> + <title>maps</title> + <prepared>Björn-Egil Dahlberg</prepared> + <docno>1</docno> + <date>2014-02-28</date> + <rev>A</rev> + </header> + <module>maps</module> + <modulesummary>Maps Processing Functions</modulesummary> + <description> + <p>This module contains functions for maps processing.</p> + </description> + <funcs> + + <func> + <name name="find" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + Returns a tuple <c>{ok, Value}</c> where <c><anno>Value</anno></c> is the value associated with <c><anno>Key</anno></c>, + or <c>error</c> if no value is associated with <c><anno>Key</anno></c> in <c><anno>Map</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"hi" => 42}, + Key = "hi", + maps:find(Key,Map). +{ok,42} </code> + </desc> + </func> + + <func> + <name name="fold" arity="3"/> + <fsummary></fsummary> + <desc> + <p> + Calls <c>F(K, V, AccIn)</c> for every <c><anno>K</anno></c> to value <c><anno>V</anno></c> + association in <c><anno>Map</anno></c> in + arbitrary order. The function <c>fun F/3</c> must return a new accumulator + which is passed to the next successive call. <c>maps:fold/3</c> returns the final + value of the accumulator. The initial accumulator value <c><anno>Init</anno></c> is returned if + the map is empty. + </p> + <p>Example:</p> + <code type="none"> +> Fun = fun(K,V,AccIn) when is_list(K) -> AccIn + V end, + Map = #{"k1" => 1, "k2" => 2, "k3" => 3}, + maps:fold(Fun,0,Map). +6</code> + </desc> + </func> + + <func> + <name name="from_list" arity="1"/> + <fsummary></fsummary> + <desc> + <p> + The function takes a list of key-value tuples elements and builds a + map. The associations may be in any order and both keys and values in the + association may be of any term. If the same key appears more than once, + the latter (rightmost) value is used and the previous values are ignored. + </p> + <p>Example:</p> + <code type="none"> +> List = [{"a",ignored},{1337,"value two"},{42,value_three},{"a",1}], + maps:from_list(List). +#{42 => value_three,1337 => "value two","a" => 1}</code> + </desc> + </func> + + <func> + <name name="get" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + Returns the value <c><anno>Value</anno></c> associated with <c><anno>Key</anno></c> if + <c><anno>Map</anno></c> contains <c><anno>Key</anno></c>. + If no value is associated with <c><anno>Key</anno></c> then the call will + fail with an exception. + </p> + <p>Example:</p> + <code type="none"> +> Key = 1337, + Map = #{42 => value_two,1337 => "value one","a" => 1}, + maps:get(Key,Map). +"value one"</code> + </desc> + </func> + + <func> + <name name="get" arity="3"/> + <fsummary></fsummary> + <desc> + <p> + Returns the value <c><anno>Value</anno></c> associated with <c><anno>Key</anno></c> if + <c><anno>Map</anno></c> contains <c><anno>Key</anno></c>. + If no value is associated with <c><anno>Key</anno></c> then returns <c><anno>Default</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{ key1 => val1, key2 => val2 }. +#{key1 => val1,key2 => val2} +> maps:get(key1, Map, "Default value"). +val1 +> maps:get(key3, Map, "Default value"). +"Default value"</code> + </desc> + </func> + + <func> + <name name="is_key" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + Returns <c>true</c> if map <c><anno>Map</anno></c> contains <c><anno>Key</anno></c> and returns + <c>false</c> if it does not contain the <c><anno>Key</anno></c>. + The function will fail with an exception if <c><anno>Map</anno></c> is not a Map. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"42" => value}. +#{"42"> => value} +> maps:is_key("42",Map). +true +> maps:is_key(value,Map). +false</code> + </desc> + </func> + + <func> + <name name="keys" arity="1"/> + <fsummary></fsummary> + <desc> + <p> + Returns a complete list of keys, in arbitrary order, which resides within <c><anno>Map</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:keys(Map). +[42,1337,"a"]</code> + </desc> + </func> + + <func> + <name name="map" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + The function produces a new map <c><anno>Map2</anno></c> by calling the function <c>fun F(K, V1)</c> for + every <c><anno>K</anno></c> to value <c><anno>V1</anno></c> association in <c><anno>Map1</anno></c> in arbitrary order. + The function <c>fun F/2</c> must return the value <c><anno>V2</anno></c> to be associated with key <c><anno>K</anno></c> for + the new map <c><anno>Map2</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Fun = fun(K,V1) when is_list(K) -> V1*2 end, + Map = #{"k1" => 1, "k2" => 2, "k3" => 3}, + maps:map(Fun,Map). +#{"k1" => 2,"k2" => 4,"k3" => 6}</code> + </desc> + </func> + + <func> + <name name="merge" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + Merges two maps into a single map <c><anno>Map3</anno></c>. If two keys exists in both maps the + value in <c><anno>Map1</anno></c> will be superseded by the value in <c><anno>Map2</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map1 = #{a => "value_one", b => "value_two"}, + Map2 = #{a => 1, c => 2}, + maps:merge(Map1,Map2). +#{a => 1,b => "value_two",c => 2}</code> + </desc> + </func> + + <func> + <name name="new" arity="0"/> + <fsummary></fsummary> + <desc> + <p> + Returns a new empty map. + </p> + <p>Example:</p> + <code type="none"> +> maps:new(). +#{}</code> + </desc> + </func> + + <func> + <name name="put" arity="3"/> + <fsummary></fsummary> + <desc> + <p> + Associates <c><anno>Key</anno></c> with value <c><anno>Value</anno></c> and inserts the association into map <c>Map2</c>. + If key <c><anno>Key</anno></c> already exists in map <c><anno>Map1</anno></c>, the old associated value is + replaced by value <c><anno>Value</anno></c>. The function returns a new map <c><anno>Map2</anno></c> containing the new association and + the old associations in <c><anno>Map1</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:put("a", 42, Map). +#{"a" => 42} +> maps:put("b", 1337, Map). +#{"a" => 1,"b" => 1337}</code> + </desc> + </func> + + <func> + <name name="remove" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + The function removes the <c><anno>Key</anno></c>, if it exists, and its associated value from + <c><anno>Map1</anno></c> and returns a new map <c><anno>Map2</anno></c> without key <c><anno>Key</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:remove("a",Map). +#{} +> maps:remove("b",Map). +#{"a" => 1}</code> + </desc> + </func> + + <func> + <name name="size" arity="1"/> + <fsummary></fsummary> + <desc> + <p> + The function returns the number of key-value associations in the <c><anno>Map</anno></c>. + This operation happens in constant time. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{42 => value_two,1337 => "value one","a" => 1}, + maps:size(Map). +3</code> + </desc> + </func> + + <func> + <name name="to_list" arity="1"/> + <fsummary></fsummary> + <desc> + <p> + The fuction returns a list of pairs representing the key-value associations of <c><anno>Map</anno></c>, + where the pairs, <c>[{K1,V1}, ..., {Kn,Vn}]</c>, are returned in arbitrary order. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:to_list(Map). +[{42,value_three},{1337,"value two"},{"a",1}]</code> + </desc> + </func> + + <func> + <name name="update" arity="3"/> + <fsummary></fsummary> + <desc> + <p> + If <c><anno>Key</anno></c> exists in <c><anno>Map1</anno></c> the old associated value is + replaced by value <c><anno>Value</anno></c>. The function returns a new map <c><anno>Map2</anno></c> containing + the new associated value. If <c><anno>Key</anno></c> does not exist in <c><anno>Map1</anno></c> an exception is + generated. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:update("a", 42, Map). +#{"a" => 42}</code> + </desc> + </func> + + <func> + <name name="values" arity="1"/> + <fsummary></fsummary> + <desc> + <p> + Returns a complete list of values, in arbitrary order, contained in map <c>M</c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:values(Map). +[value_three,"value two",1]</code> + </desc> + </func> + + <func> + <name name="without" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + Returns a new map <c><anno>Map2</anno></c> without the keys <c>K1</c> through <c>Kn</c> and their associated values from map <c><anno>Map1</anno></c>. + Any key in <c><anno>Ks</anno></c> that does not exist in <c><anno>Map1</anno></c> are ignored. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + Ks = ["a",42,"other key"], + maps:without(Ks,Map). +#{1337 => "value two"}</code> + </desc> + </func> + </funcs> +</erlref> diff --git a/lib/stdlib/doc/src/math.xml b/lib/stdlib/doc/src/math.xml index 518457d5d8..43cd20e726 100644 --- a/lib/stdlib/doc/src/math.xml +++ b/lib/stdlib/doc/src/math.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -52,54 +52,47 @@ </desc> </func> <func> - <name>sin(X)</name> - <name>cos(X)</name> - <name>tan(X)</name> - <name>asin(X)</name> - <name>acos(X)</name> - <name>atan(X)</name> - <name>atan2(Y, X)</name> - <name>sinh(X)</name> - <name>cosh(X)</name> - <name>tanh(X)</name> - <name>asinh(X)</name> - <name>acosh(X)</name> - <name>atanh(X)</name> - <name>exp(X)</name> - <name>log(X)</name> - <name>log10(X)</name> - <name>pow(X, Y)</name> - <name>sqrt(X)</name> + <name name="sin" arity="1"/> + <name name="cos" arity="1"/> + <name name="tan" arity="1"/> + <name name="asin" arity="1"/> + <name name="acos" arity="1"/> + <name name="atan" arity="1"/> + <name name="atan2" arity="2"/> + <name name="sinh" arity="1"/> + <name name="cosh" arity="1"/> + <name name="tanh" arity="1"/> + <name name="asinh" arity="1"/> + <name name="acosh" arity="1"/> + <name name="atanh" arity="1"/> + <name name="exp" arity="1"/> + <name name="log" arity="1"/> + <name name="log10" arity="1"/> + <name name="pow" arity="2"/> + <name name="sqrt" arity="1"/> + <type variable="X" name_i="7"/> + <type variable="Y" name_i="7"/> <fsummary>Diverse math functions</fsummary> - <type> - <v>X = Y = number()</v> - </type> <desc> <p>A collection of math functions which return floats. Arguments are numbers. </p> </desc> </func> <func> - <name>erf(X) -> float()</name> + <name name="erf" arity="1"/> <fsummary>Error function.</fsummary> - <type> - <v>X = number()</v> - </type> <desc> - <p>Returns the error function of <c>X</c>, where</p> + <p>Returns the error function of <c><anno>X</anno></c>, where</p> <pre> erf(X) = 2/sqrt(pi)*integral from 0 to X of exp(-t*t) dt. </pre> </desc> </func> <func> - <name>erfc(X) -> float()</name> + <name name="erfc" arity="1"/> <fsummary>Another error function</fsummary> - <type> - <v>X = number()</v> - </type> <desc> <p><c>erfc(X)</c> returns <c>1.0 - erf(X)</c>, computed by - methods that avoid cancellation for large <c>X</c>. </p> + methods that avoid cancellation for large <c><anno>X</anno></c>. </p> </desc> </func> </funcs> diff --git a/lib/stdlib/doc/src/ms_transform.xml b/lib/stdlib/doc/src/ms_transform.xml index ad5f8bd5ac..e89dd41f26 100644 --- a/lib/stdlib/doc/src/ms_transform.xml +++ b/lib/stdlib/doc/src/ms_transform.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2002</year><year>2011</year> + <year>2002</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index 2a308cbe09..5e74616099 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2004</year><year>2012</year> + <year>2004</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -30,6 +30,1053 @@ </header> <p>This document describes the changes made to the STDLIB application.</p> +<section><title>STDLIB 2.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + OTP-11850 fixed filelib:wildcard/1 to work with broken + symlinks. This correction, however, introduced problems + since symlinks were no longer followed for functions like + filelib:ensure_dir/1, filelib:is_dir/1, + filelib:file_size/1, etc. This is now corrected.</p> + <p> + Own Id: OTP-12054 Aux Id: seq12660 </p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p><c>filelib:wildcard("broken_symlink")</c> would return + an empty list if "broken_symlink" was a symlink that did + not point to an existing file.</p> + <p> + Own Id: OTP-11850 Aux Id: seq12571 </p> + </item> + <item> + <p><c>erl_tar</c> can now handle files names that contain + Unicode characters. See "UNICODE SUPPORT" in the + documentation for <c>erl_tar</c>.</p> + <p>When creating a tar file, <c>erl_tar</c> would + sometime write a too short end of tape marker. GNU tar + would correctly extract files from such tar file, but + would complain about "A lone zero block at...".</p> + <p> + Own Id: OTP-11854</p> + </item> + <item> + <p> When redefining and exporting the type <c>map()</c> + the Erlang Code Linter (<c>erl_lint</c>) erroneously + emitted an error. This bug has been fixed. </p> + <p> + Own Id: OTP-11872</p> + </item> + <item> + <p> + Fix evaluation of map updates in the debugger and + erl_eval</p> + <p> + Reported-by: José Valim</p> + <p> + Own Id: OTP-11922</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>The following native functions now bump an appropriate + amount of reductions and yield when out of + reductions:</p> <list> + <item><c>erlang:binary_to_list/1</c></item> + <item><c>erlang:binary_to_list/3</c></item> + <item><c>erlang:bitstring_to_list/1</c></item> + <item><c>erlang:list_to_binary/1</c></item> + <item><c>erlang:iolist_to_binary/1</c></item> + <item><c>erlang:list_to_bitstring/1</c></item> + <item><c>binary:list_to_bin/1</c></item> </list> + <p>Characteristics impact:</p> <taglist> + <tag>Performance</tag> <item>The functions converting + from lists got a performance loss for very small lists, + and a performance gain for very large lists.</item> + <tag>Priority</tag> <item>Previously a process executing + one of these functions effectively got an unfair priority + boost. This priority boost depended on the input size. + The larger the input was, the larger the priority boost + got. This unfair priority boost is now lost. </item> + </taglist> + <p> + Own Id: OTP-11888</p> + </item> + <item> + <p> + Add <c>maps:get/3</c> to maps module. The function will + return the supplied default value if the key does not + exist in the map.</p> + <p> + Own Id: OTP-11951</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 2.0</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The option dupnames did not work as intended in re. When + looking for names with {capture, [Name, ...]}, re:run + returned a random instance of the match for that name, + instead of the leftmost matching instance, which was what + the documentation stated. This is now corrected to adhere + to the documentation. The option {capture,all_names} + along with a re:inspect/2 function is also added to + further help in using named subpatterns.</p> + <p> + Own Id: OTP-11205</p> + </item> + <item> + <p> + If option 'binary' was set for standard_input, then c:i() + would hang if the output was more than one page long - + i.e. then input after "(c)ontinue (q)uit -->" could + not be read. This has been corrected. (Thanks to José + Valim)</p> + <p> + Own Id: OTP-11589</p> + </item> + <item> + <p> + stdlib/lists: Add function droplast/1 This functions + drops the last element of a non-empty list. lists:last/1 + and lists:droplast/1 are the dual of hd/1 and tl/1 but + for the end of a list. (Thanks to Hans Svensson)</p> + <p> + Own Id: OTP-11677</p> + </item> + <item> + <p> + Allow all auto imports to be suppressed at once. + Introducing the no_auto_import attribute: + -compile(no_auto_import). Useful for code generation + tools that always use the qualified function names and + want to avoid the auto imported functions clashing with + local ones. (Thanks to José Valim.)</p> + <p> + Own Id: OTP-11682</p> + </item> + <item> + <p> + supervisor_bridge does no longer report normal + termination of children. The reason is that in some + cases, for instance when the restart strategy is + simple_one_for_one, the log could be completely + overloaded with reports about normally terminating + processes. (Thanks to Artem Ocheredko)</p> + <p> + Own Id: OTP-11685</p> + </item> + <item> + <p> The type annotations for alternative registries using + the {via, Module, Name} syntax for sup_name() and + sup_ref() in the supervisor module are now consistent + with the documentation. Dialyzer should no longer + complain about valid supervisor:start_link() and + supervisor:start_child() calls. (Thanks to Caleb + Helbling.) </p> + <p> + Own Id: OTP-11707</p> + </item> + <item> + <p> Two Dets bugs have been fixed. When trying to open a + short file that is not a Dets file, the file was deleted + even with just read access. Calling + <c>dets:is_dets_file/1</c> with a file that is not a Dets + file, a file descriptor was left open. (Thanks to Håkan + Mattsson for reporting the bugs.) </p> + <p> + Own Id: OTP-11709</p> + </item> + <item> + <p> + Fix race bug in <c>ets:all</c>. Concurrent creation of + tables could cause other tables to not be included in the + result. (Thanks to Florian Schintke for bug report)</p> + <p> + Own Id: OTP-11726</p> + </item> + <item> + <p> + erl_eval now properly evaluates '=='/2 when it is used in + guards. (Thanks to José Valim)</p> + <p> + Own Id: OTP-11747</p> + </item> + <item> + <p> + Calls to proplists:get_value/3 are replaced by the faster + lists:keyfind/3 in io_lib_pretty. Elements in the list + are always 2-tuples. (Thanks to Andrew Thompson)</p> + <p> + Own Id: OTP-11752</p> + </item> + <item> + <p> A qlc bug where filters were erroneously optimized + away has been fixed. Thanks to Sam Bobroff for reporting + the bug. </p> + <p> + Own Id: OTP-11758</p> + </item> + <item> + <p> + A number of compiler errors where unusual or nonsensical + code would crash the compiler have been reported by Ulf + Norell and corrected by Anthony Ramine.</p> + <p> + Own Id: OTP-11770</p> + </item> + <item> + <p> Since Erlang/OTP R16B the Erlang Core Linter + (<c>erl_lint</c>) has not emitted errors when built-in + types were re-defined. This bug has been fixed. (Thanks + to Roberto Aloi.) </p> + <p> + Own Id: OTP-11772</p> + </item> + <item> + <p> + The functions <c>sys:get_state/1,2</c> and + <c>sys:replace_state/2,3</c> are fixed so they can now be + run while the process is sys suspended. To accomplish + this, the new callbacks <c>Mod:system_get_state/1</c> and + <c>Mod:system_replace_state/2</c> are added, which are + also implemented by the generic behaviours + <c>gen_server</c>, <c>gen_event</c> and <c>gen_fsm</c>.</p> + <p> + The potential incompatibility refers to</p> + <p> + <list> <item>The previous behaviour of intercepting the + system message and passing a tuple of size 2 as the last + argument to <c>sys:handle_system_msg/6</c> is no longer + supported.</item> <item>The error handling when + <c>StateFun</c> in <c>sys:replace_state/2,3</c> fails is + changed from being totally silent to possibly (if the + callback module does not catch) throw an exception in the + client process.</item> </list></p> + <p> + (Thanks to James Fish and Steve Vinoski)</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11817</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Options to set match_limit and match_limit_recursion are + added to re:run. The option report_errors is also added + to get more information when re:run fails due to limits + or compilation errors.</p> + <p> + Own Id: OTP-10285</p> + </item> + <item> + <p> The pre-defined types <c>array/0</c>, <c>dict/0</c>, + <c>digraph/0</c>, <c>gb_set/0</c>, <c>gb_tree/0</c>, + <c>queue/0</c>, <c>set/0</c>, and <c>tid/0</c> have been + deprecated. They will be removed in Erlang/OTP 18.0. </p> + <p> Instead the types <c>array:array/0</c>, + <c>dict:dict/0</c>, <c>digraph:graph/0</c>, + <c>gb_set:set/0</c>, <c>gb_tree:tree/0</c>, + <c>queue:queue/0</c>, <c>sets:set/0</c>, and + <c>ets:tid/0</c> can be used. (Note: it has always been + necessary to use <c>ets:tid/0</c>.) </p> <p> It is + allowed in Erlang/OTP 17.0 to locally re-define the types + <c>array/0</c>, <c>dict/0</c>, and so on. </p> <p> New + types <c>array:array/1</c>, <c>dict:dict/2</c>, + <c>gb_sets:set/1</c>, <c>gb_trees:tree/2</c>, + <c>queue:queue/1</c>, and <c>sets:set/1</c> have been + added. </p> <p> A compiler option, + <c>nowarn_deprecated_type</c>, has been introduced. By + including the attribute </p> <c> + -compile(nowarn_deprecated_type).</c> <p> in an Erlang + source file, warnings about deprecated types can be + avoided in Erlang/OTP 17.0. </p> <p> The option can also + be given as a compiler flag: </p> <c> erlc + +nowarn_deprecated_type file.erl</c> + <p> + Own Id: OTP-10342</p> + </item> + <item> + <p> + Calls to erlang:open_port/2 with 'spawn' are updated to + handle space in the command path.</p> + <p> + Own Id: OTP-10842</p> + </item> + <item> + <p> Dialyzer's <c>unmatched_return</c> warnings have been + corrected. </p> + <p> + Own Id: OTP-10908</p> + </item> + <item> + <p> + Forbid unsized fields in patterns of binary generators + and simplified v3_core's translation of bit string + generators. (Thanks to Anthony Ramine.)</p> + <p> + Own Id: OTP-11186</p> + </item> + <item> + <p> + The version of the PCRE library Used by Erlang's re + module is raised to 8.33 from 7.6. This means, among + other things, better Unicode and Unicode Character + Properties support. New options connected to PCRE 8.33 + are also added to the re module (ucd, notempty_atstart, + no_start_optimize). PCRE has extended the regular + expression syntax between 7.6 and 8.33, why this imposes + a potential incompatibility. Only very complicated + regular expressions may be affected, but if you know you + are using obscure features, please test run your regular + expressions and verify that their behavior has not + changed.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11204</p> + </item> + <item> + <p> + Added dict:is_empty/1 and orddict:is_empty/1. (Thanks to + Magnus Henoch.)</p> + <p> + Own Id: OTP-11353</p> + </item> + <item> + <p> + A call to either the <c>garbage_collect/1</c> BIF or the + <c>check_process_code/2</c> BIF may trigger garbage + collection of another processes than the process calling + the BIF. The previous implementations performed these + kinds of garbage collections without considering the + internal state of the process being garbage collected. In + order to be able to more easily and more efficiently + implement yielding native code, these types of garbage + collections have been rewritten. A garbage collection + like this is now triggered by an asynchronous request + signal, the actual garbage collection is performed by the + process being garbage collected itself, and finalized by + a reply signal to the process issuing the request. Using + this approach processes can disable garbage collection + and yield without having to set up the heap in a state + that can be garbage collected.</p> + <p> + The <seealso + marker="erts:erlang#garbage_collect/2"><c>garbage_collect/2</c></seealso>, + and <seealso + marker="erts:erlang#check_process_code/3"><c>check_process_code/3</c></seealso> + BIFs have been introduced. Both taking an option list as + last argument. Using these, one can issue asynchronous + requests.</p> + <p> + <c>code:purge/1</c> and <c>code:soft_purge/1</c> have + been rewritten to utilize asynchronous + <c>check_process_code</c> requests in order to + parallelize work.</p> + <p> + Characteristics impact: A call to the + <c>garbage_collect/1</c> BIF or the + <c>check_process_code/2</c> BIF will normally take longer + time to complete while the system as a whole wont be as + much negatively effected by the operation as before. A + call to <c>code:purge/1</c> and <c>code:soft_purge/1</c> + may complete faster or slower depending on the state of + the system while the system as a whole wont be as much + negatively effected by the operation as before.</p> + <p> + Own Id: OTP-11388 Aux Id: OTP-11535, OTP-11648 </p> + </item> + <item> + <p> Improve the documentation of the supervisor's + <c>via</c> reference. (Thanks to MaximMinin.) </p> + <p> + Own Id: OTP-11399</p> + </item> + <item> + <p><c>orddict:from_list/1</c> now uses the optimized sort + routines in the <c>lists</c> module instead of + (essentially) an insertion sort. Depending on the input + data, the speed of the new <c>from_list/1</c> is anything + from slightly faster up to several orders of magnitude + faster than the old <c>from_list/1</c>.</p> (Thanks to + Steve Vinoski.) + <p> + Own Id: OTP-11552</p> + </item> + <item> + <p> + EEP43: New data type - Maps</p> + <p> + With Maps you may for instance: <taglist> <item><c>M0 = + #{ a => 1, b => 2}, % create + associations</c></item> <item><c>M1 = M0#{ a := 10 }, % + update values</c></item> <item><c>M2 = M1#{ "hi" => + "hello"}, % add new associations</c></item> <item><c>#{ + "hi" := V1, a := V2, b := V3} = M2. % match keys with + values</c></item> </taglist></p> + <p> + For information on how to use Maps please see Map Expressions in the + <seealso marker="doc/reference_manual:expressions#map_expressions"> + Reference Manual</seealso>.</p> + <p> + The current implementation is without the following + features: <taglist> <item>No variable keys</item> + <item>No single value access</item> <item>No map + comprehensions</item> </taglist></p> + <p> + Note that Maps is <em>experimental</em> during OTP 17.0.</p> + <p> + Own Id: OTP-11616</p> + </item> + <item> + <p> + When tab completing the erlang shell now expands + zero-arity functions all the way to closing parenthesis, + unless there is another function with the same name and a + different arity. (Thanks to Pierre Fenoll.)</p> + <p> + Own Id: OTP-11684</p> + </item> + <item> + <p> The Erlang Code Preprocessor (<c>epp</c>) could loop + when encountering a circular macro definition in an + included file. This bug has been fixed. </p> <p> Thanks + to Maruthavanan Subbarayan for reporting the bug, and to + Richard Carlsson for providing a bug fix. </p> + <p> + Own Id: OTP-11728</p> + </item> + <item> + <p> The Erlang Code Linter (<c>erl_lint</c>) has since + Erlang/OTP R13B emitted warnings whenever any of the + types <c>arity()</c>, <c>bitstring()</c>, + <c>iodata()</c>, or <c>boolean()</c> were re-defined. Now + errors are emitted instead. </p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-11771</p> + </item> + <item> + <p> The <c>encoding</c> option of + <c>erl_parse:abstract/2</c> has been extended to include + <c>none</c> and a callback function (a predicate). </p> + <p> + Own Id: OTP-11807</p> + </item> + <item> + <p> + Export zip option types to allow referal from other + modules.</p> + <p> + Thanks to Pierre Fenoll and Håkan Mattson</p> + <p> + Own Id: OTP-11828</p> + </item> + <item> + <p> + The module <c>pg</c> has been deprecated and will be + removed in Erlang/OTP 18.</p> + <p> + Own Id: OTP-11840</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 1.19.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix typo in gen_server.erl. Thanks to Brian L. Troutwine.</p> + <p> + Own Id: OTP-11398</p> + </item> + <item> + <p> + Spec for atan2 should be atan2(Y, X), not atan2(X, Y). + Thanks to Ary Borenszweig.</p> + <p> + Own Id: OTP-11465</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add XML marker for regexp syntax. Thanks to Håkan + Mattson.</p> + <p> + Own Id: OTP-11442</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 1.19.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> The functions <c>dets:foldl/3</c>, + <c>dets:foldr/3</c>, and <c>dets:traverse/2</c> did not + release the table after having traversed the table to the + end. The bug was introduced in R16B. (Thanks to Manuel + Duran Aguete.) </p> + <p> + Own Id: OTP-11245</p> + </item> + <item> + <p> If the <c>fun M:F/A</c> construct was used + erroneously the linter could crash. (Thanks to Mikhail + Sobolev.) </p> + <p> + Own Id: OTP-11254</p> + </item> + <item> + <p> The specifications of <c>io_lib:fread/2,3</c> have + been corrected. (Thanks to Chris King and Kostis Sagonas + for pinpointing the bug.) </p> + <p> + Own Id: OTP-11261</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Fixed type typo in gen_server.</p> + <p> + Own Id: OTP-11200</p> + </item> + <item> + <p> + Update type specs in filelib and io_prompt. Thanks to + Jose Valim.</p> + <p> + Own Id: OTP-11208</p> + </item> + <item> + <p> + Fix typo in abcast() function comment. Thanks to Johannes + Weissl.</p> + <p> + Own Id: OTP-11219</p> + </item> + <item> + <p> + Make edlin understand a few important control keys. + Thanks to Stefan Zegenhagen.</p> + <p> + Own Id: OTP-11251</p> + </item> + <item> + <p> + Export the edge/0 type from the digraph module. Thanks to + Alex Ronne Petersen.</p> + <p> + Own Id: OTP-11266</p> + </item> + <item> + <p> + Fix variable usage tracking in erl_lint and fixed unsafe + variable tracking in try expressions. Thanks to Anthony + Ramine.</p> + <p> + Own Id: OTP-11268</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 1.19.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> The Erlang scanner no longer accepts floating point + numbers in the input string. </p> + <p> + Own Id: OTP-10990</p> + </item> + <item> + <p> + When converting a faulty binary to a list with + unicode:characters_to_list, the error return value could + contain a faulty "rest", i.e. the io_list of characters + that could not be converted was wrong. This happened only + if input was a sub binary and conversion was from utf8. + This is now corrected.</p> + <p> + Own Id: OTP-11080</p> + </item> + <item> + <p>The type <c>hook_function()</c> has been corrected in + <c>erl_pp</c>, the Erlang Pretty Printer. </p> + <p>The printing of invalid forms, e.g. record field + types, has also been fixed. It has been broken since + R16B. </p> + <p> (Thanks to Tomáš Janoušek.) </p> + <p> + Own Id: OTP-11100</p> + </item> + <item> + <p> + Fix receive support in erl_eval with a BEAM module. + Thanks to Anthony Ramine.</p> + <p> + Own Id: OTP-11137</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Delete obsolete note about simple-one-for-one supervisor. + Thanks to Magnus Henoch.</p> + <p> + Own Id: OTP-10938</p> + </item> + <item> + <p> When selecting encoding of a script written in Erlang + (<c>escript</c>) the optional directive on the second + line is now recognized. </p> + <p> + Own Id: OTP-10951</p> + </item> + <item> + <p> The function <c>erl_parse:abstract/2</c> has been + documented. </p> + <p> + Own Id: OTP-10992</p> + </item> + <item> + <p> + Integrate elliptic curve contribution from Andreas + Schultz </p> + <p> + In order to be able to support elliptic curve cipher + suites in SSL/TLS, additions to handle elliptic curve + infrastructure has been added to public_key and crypto.</p> + <p> + This also has resulted in a rewrite of the crypto API to + gain consistency and remove unnecessary overhead. All OTP + applications using crypto has been updated to use the new + API.</p> + <p> + Impact: Elliptic curve cryptography (ECC) offers + equivalent security with smaller key sizes than other + public key algorithms. Smaller key sizes result in + savings for power, memory, bandwidth, and computational + cost that make ECC especially attractive for constrained + environments.</p> + <p> + Own Id: OTP-11009</p> + </item> + <item> + <p> + Added sys:get_state/1,2 and sys:replace_state/2,3. Thanks + to Steve Vinoski.</p> + <p> + Own Id: OTP-11013</p> + </item> + <item> + <p> + Optimizations to gen mechanism. Thanks to Loïc Hoguin.</p> + <p> + Own Id: OTP-11025</p> + </item> + <item> + <p> + Optimizations to gen.erl. Thanks to Loïc Hoguin.</p> + <p> + Own Id: OTP-11035</p> + </item> + <item> + <p> + Use erlang:demonitor(Ref, [flush]) where applicable. + Thanks to Loïc Hoguin.</p> + <p> + Own Id: OTP-11039</p> + </item> + <item> + <p>Erlang source files with non-ASCII characters are now + encoded in UTF-8 (instead of latin1).</p> + <p> + Own Id: OTP-11041 Aux Id: OTP-10907 </p> + </item> + <item> + <p> + Fix rest_for_one and one_for_all restarting a child not + terminated. Thanks to James Fish.</p> + <p> + Own Id: OTP-11042</p> + </item> + <item> + <p> + Fix excessive CPU consumption of timer_server. Thanks to + Aliaksey Kandratsenka.</p> + <p> + Own Id: OTP-11053</p> + </item> + <item> + <p> + Rename and document lists:zf/2 as lists:filtermap/2. + Thanks to Anthony Ramine.</p> + <p> + Own Id: OTP-11078</p> + </item> + <item> + <p> + Fixed an inconsistent state in epp. Thanks to Anthony + Ramine</p> + <p> + Own Id: OTP-11079</p> + </item> + <item> + <p> + c:ls(File) will now print File, similar to ls(1) in Unix. + The error messages have also been improved. (Thanks to + Bengt Kleberg.)</p> + <p> + Own Id: OTP-11108</p> + </item> + <item> + <p> + Support callback attributes in erl_pp. Thanks to Anthony + Ramine.</p> + <p> + Own Id: OTP-11140</p> + </item> + <item> + <p> + Improve erl_lint performance. Thanks to José Valim.</p> + <p> + Own Id: OTP-11143</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 1.19.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Bugs related to Unicode have been fixed in the + <c>erl_eval</c> module. </p> + <p> + Own Id: OTP-10622 Aux Id: kunagi-351 [262] </p> + </item> + <item> + <p><c>filelib:wildcard("some/relative/path/*.beam", + Path)</c> would fail to match any file. That is, + filelib:wildcard/2 would not work if the first component + of the pattern did not contain any wildcard characters. + (A previous attempt to fix the problem in R15B02 seems to + have made matters worse.)</p> + <p>(Thanks to Samuel Rivas and Tuncer Ayaz.)</p> + <p>There is also an incompatible change to the + <c>Path</c> argument. It is no longer allowed to be a + binary.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10812</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> The new STDLIB application variable + <c>shell_strings</c> can be used for determining how the + Erlang shell outputs lists of integers. The new function + <c>shell:strings/1</c> toggles the value of the variable. + </p> <p> The control sequence modifier <c>l</c> can be + used for turning off the string recognition of <c>~p</c> + and <c>~P</c>. </p> + <p> + Own Id: OTP-10755</p> + </item> + <item> + <p> Miscellaneous updates due to Unicode support. </p> + <p> + Own Id: OTP-10820</p> + </item> + <item> + <p> Extend <c>~ts</c> to handle binaries with characters + coded in ISO-latin-1 </p> + <p> + Own Id: OTP-10836</p> + </item> + <item> + <p> + The +pc flag to erl can be used to set the range of + characters considered printable. This affects how the + shell and io:format("~tp",...) functionality does + heuristic string detection. More can be read in STDLIB + users guide.</p> + <p> + Own Id: OTP-10884</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 1.19</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Wildcards such as "some/path/*" passed to + <c>filelib:wildcard/2</c> would fail to match any file. + (Thanks to Samuel Rivas for reporting this bug.)</p> + <p> + Own Id: OTP-6874 Aux Id: kunagi-190 [101] </p> + </item> + <item> + <p> + Fixed error handling in proc_lib:start which could hang + if the spawned process died in init.</p> + <p> + Own Id: OTP-9803 Aux Id: kunagi-209 [120] </p> + </item> + <item> + <p> + Allow ** in filelib:wildcard</p> + <p> + Two adjacent * used as a single pattern will match all + files and zero or more directories and subdirectories. + (Thanks to José Valim)</p> + <p> + Own Id: OTP-10431</p> + </item> + <item> + <p> + Add the \gN and \g{N} syntax for back references in + re:replace/3,4 to allow use with numeric replacement + strings. (Thanks to Vance Shipley)</p> + <p> + Own Id: OTP-10455</p> + </item> + <item> + <p> + Export ets:match_pattern/0 type (Thanks to Joseph Wayne + Norton)</p> + <p> + Own Id: OTP-10472</p> + </item> + <item> + <p> + Fix printing the empty binary at depth 1 with ~W (Thanks + to Andrew Thompson)</p> + <p> + Own Id: OTP-10504</p> + </item> + <item> + <p> The type <c>ascii_string()</c> in the <c>base64</c> + module has been corrected. The type + <c>file:file_info()</c> has been cleaned up. The type + <c>file:fd()</c> has been made opaque in the + documentation. </p> + <p> + Own Id: OTP-10624 Aux Id: kunagi-352 [263] </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> Dets tables are no longer fixed while traversing with + a bound key (when only the objects with the right key are + matched). This optimization affects the functions + <c>match/2</c>, <c>match_object/2</c>, <c>select/2</c>, + <c>match_delete/2</c>, and <c>select_delete/2</c>. </p> + <p> + Own Id: OTP-10097</p> + </item> + <item> + <p> Support for Unicode has been implemented. </p> + <p> + Own Id: OTP-10302</p> + </item> + <item> + <p> The linter now warns for opaque types that are not + exported, as well as for under-specified opaque types. + </p> + <p> + Own Id: OTP-10436</p> + </item> + <item> + <p> The type <c>file:name()</c> has been substituted for + the type <c>file:filename()</c> in the following + functions in the <c>filename</c> module: + <c>absname/2</c>, <c>absname_join/2</c>, <c>join/1,2</c>, + and <c>split/1</c>. </p> + <p> + Own Id: OTP-10474</p> + </item> + <item> + <p> + If a child process fails in its start function, then the + error reason was earlier only reported as an error report + from the error_handler, and supervisor:start_link would + only return <c>{error,shutdown}</c>. This has been + changed so the supervisor will now return + <c>{error,{shutdown,Reason}}</c>, where <c>Reason</c> + identifies the failing child and its error reason. + (Thanks to Tomas Pihl)</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10490</p> + </item> + <item> + <p>Where necessary a comment stating encoding has been + added to Erlang files. The comment is meant to be removed + in Erlang/OTP R17B when UTF-8 becomes the default + encoding. </p> + <p> + Own Id: OTP-10630</p> + </item> + <item> + <p> The contracts and types of the modules + <c>erl_scan</c> and <c>sys</c> have been corrected and + improved. (Thanks to Kostis Sagonas.) </p> + <p> + Own Id: OTP-10658</p> + </item> + <item> + <p> The Erlang shell now skips the rest of the line when + it encounters an Erlang scanner error. </p> + <p> + Own Id: OTP-10659</p> + </item> + <item> + <p> + Clean up some specs in the proplists module. (Thanks to + Kostis Sagonas.)</p> + <p> + Own Id: OTP-10663</p> + </item> + <item> + <p> Some examples overflowing the width of PDF pages have + been corrected. </p> + <p> + Own Id: OTP-10665</p> + </item> + <item> + <p> + Enable escript to accept emulator arguments when script + file has no shebang. Thanks to Magnus Henoch</p> + <p> + Own Id: OTP-10691</p> + </item> + <item> + <p> + Fix bug in queue:out/1, queue:out_r/1 that makes it + O(N^2) in worst case. Thanks to Aleksandr Erofeev.</p> + <p> + Own Id: OTP-10722</p> + </item> + <item> + <p> There are new functions in the <c>epp</c> module + which read the character encoding from files. See + <c>epp(3)</c> for more information. </p> + <p> + Own Id: OTP-10742 Aux Id: OTP-10302 </p> + </item> + <item> + <p> The functions in <c>io_lib</c> have been adjusted for + Unicode. The existing functions <c>write_string()</c> and + so on now take Unicode strings, while the old behavior + has been taken over by new functions + <c>write_latin1_string()</c> and so on. There are also + new functions to write Unicode strings as Latin-1 + strings, mainly targetted towards the Erlang pretty + printer (<c>erl_pp</c>). </p> + <p> + Own Id: OTP-10745 Aux Id: OTP-10302 </p> + </item> + <item> + <p> The new functions <c>proc_lib:format/2</c> and + <c>erl_parse:abstract/2</c> accept an encoding as second + argument. </p> + <p> + Own Id: OTP-10749 Aux Id: OTP-10302 </p> + </item> + <item> + <p> + Increased potential concurrency in ETS for + <c>write_concurrency</c> option. The number of internal + table locks has increased from 16 to 64. This makes it + four times less likely that two concurrent processes + writing to the same table would collide and thereby + serialized. The cost is an increased constant memory + footprint for tables using write_concurrency. The memory + consumption per inserted record is not affected. The + increased footprint can be particularly large if + <c>write_concurrency</c> is combined with + <c>read_concurrency</c>.</p> + <p> + Own Id: OTP-10787</p> + </item> + </list> + </section> + +</section> + <section><title>STDLIB 1.18.3</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -87,7 +1134,7 @@ Fix filename:nativename/1 on Win32</p> <p> Don't choke on paths given as binary argument on Win32. - Thanks to Jan Kl�tzke</p> + Thanks to Jan Klötzke</p> <p> Own Id: OTP-10188</p> </item> @@ -196,7 +1243,7 @@ <item> <p> Fix the type spec from the doc of binary:part/3 (Thanks - to Ricardo Catalinas Jim�nez)</p> + to Ricardo Catalinas Jiménez)</p> <p> Own Id: OTP-9920</p> </item> @@ -1246,7 +2293,7 @@ platforms than before. If <c>configure</c> warns about no atomic implementation available, try using the <c>libatomic_ops</c> library. Use the <seealso - marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--with-libatomic_ops=PATH</seealso> + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP">--with-libatomic_ops=PATH</seealso> <c>configure</c> command line argument when specifying where the <c>libatomic_ops</c> installation is located. The <c>libatomic_ops</c> library can be downloaded from: @@ -1264,7 +2311,7 @@ the pentium 4 processor. If you want the runtime system to be compatible with older processors (back to 486) you need to pass the <seealso - marker="doc/installation_guide:INSTALL#How-to-Build-and-Install-ErlangOTP_A-Closer-Look-at-the-individual-Steps_Configuring">--enable-ethread-pre-pentium4-compatibility</seealso> + marker="doc/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP">--enable-ethread-pre-pentium4-compatibility</seealso> <c>configure</c> command line argument when configuring the system.</p> <p> @@ -2761,7 +3808,7 @@ It is now possible to hibernate a gen_server/gen_event/gen_fsm. In gen_server and gen_fsm, hibernation is triggered by returning the atom - 'hibernate'�instead of a timeout value. In the gen_event + 'hibernate' instead of a timeout value. In the gen_event case hibernation is triggered by a event handler returning a tuple with an extra element containing the atom 'hibernate'.</p> diff --git a/lib/stdlib/doc/src/notes_history.xml b/lib/stdlib/doc/src/notes_history.xml index 85997f1717..328855f6dd 100644 --- a/lib/stdlib/doc/src/notes_history.xml +++ b/lib/stdlib/doc/src/notes_history.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> - <year>2006</year><year>2009</year> + <year>2006</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml index 319083d35b..6d1702bc59 100644 --- a/lib/stdlib/doc/src/orddict.xml +++ b/lib/stdlib/doc/src/orddict.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2000</year><year>2011</year> + <year>2000</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -187,6 +187,13 @@ merge(Fun, D1, D2) -> </desc> </func> <func> + <name name="is_empty" arity="1"/> + <fsummary>Return true if the dictionary is empty</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>Orddict</anno></c> has no elements, <c>false</c> otherwise.</p> + </desc> + </func> + <func> <name name="store" arity="3"/> <fsummary>Store a value in a dictionary</fsummary> <desc> diff --git a/lib/stdlib/doc/src/ordsets.xml b/lib/stdlib/doc/src/ordsets.xml index 1e26fc2022..277c1c32ab 100644 --- a/lib/stdlib/doc/src/ordsets.xml +++ b/lib/stdlib/doc/src/ordsets.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/part.xml b/lib/stdlib/doc/src/part.xml index 25ca56ad86..5589d11e3e 100644 --- a/lib/stdlib/doc/src/part.xml +++ b/lib/stdlib/doc/src/part.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> <year>1996</year> - <year>2009</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/part_notes.xml b/lib/stdlib/doc/src/part_notes.xml index 66ad294753..cdd35ac370 100644 --- a/lib/stdlib/doc/src/part_notes.xml +++ b/lib/stdlib/doc/src/part_notes.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2004</year><year>2009</year> + <year>2004</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/part_notes_history.xml b/lib/stdlib/doc/src/part_notes_history.xml index 5e055ee606..15e0a0f1d3 100644 --- a/lib/stdlib/doc/src/part_notes_history.xml +++ b/lib/stdlib/doc/src/part_notes_history.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE part SYSTEM "part.dtd"> <part> <header> <copyright> <year>2006</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/pg.xml b/lib/stdlib/doc/src/pg.xml index c56db8c6e6..a3b69884b6 100644 --- a/lib/stdlib/doc/src/pg.xml +++ b/lib/stdlib/doc/src/pg.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2014</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -32,6 +32,9 @@ <module>pg</module> <modulesummary>Distributed, Named Process Groups</modulesummary> <description> + <warning> + <p>This module is deprecated and will be removed in Erlang/OTP 18.</p> + </warning> <p>This (experimental) module implements process groups. A process group is a group of processes that can be accessed by a common name. For example, a group named <c>foobar</c> can include a set diff --git a/lib/stdlib/doc/src/pool.xml b/lib/stdlib/doc/src/pool.xml index 39a79e5dc5..1b903984f9 100644 --- a/lib/stdlib/doc/src/pool.xml +++ b/lib/stdlib/doc/src/pool.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index abc17c4a91..5bf5744622 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -209,6 +209,13 @@ init(Parent) -> <name name="format" arity="1"/> <fsummary>Format a crash report.</fsummary> <desc> + <p>Equivalent to <c>format(<anno>CrashReport</anno>, latin1)</c>.</p> + </desc> + </func> + <func> + <name name="format" arity="2"/> + <fsummary>Format a crash report.</fsummary> + <desc> <p>This function can be used by a user defined event handler to format a crash report. The crash report is sent using <c>error_logger:error_report(crash_report, <anno>CrashReport</anno>)</c>. diff --git a/lib/stdlib/doc/src/proplists.xml b/lib/stdlib/doc/src/proplists.xml index 225c5e97eb..1655133b2b 100644 --- a/lib/stdlib/doc/src/proplists.xml +++ b/lib/stdlib/doc/src/proplists.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2002</year><year>2011</year> + <year>2002</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -70,7 +70,7 @@ <fsummary></fsummary> <desc> <p>Minimizes the representation of all entries in the list. This is - equivalent to <c><![CDATA[[property(P) || P <- List]]]></c>.</p> + equivalent to <c><![CDATA[[property(P) || P <- ListIn]]]></c>.</p> <p>See also: <c>property/1</c>, <c>unfold/1</c>.</p> </desc> </func> @@ -88,11 +88,11 @@ <desc> <p>Expands particular properties to corresponding sets of properties (or other terms). For each pair <c>{<anno>Property</anno>, <anno>Expansion</anno>}</c> in <c><anno>Expansions</anno></c>, if <c>E</c> is - the first entry in <c><anno>List</anno></c> with the same key as + the first entry in <c><anno>ListIn</anno></c> with the same key as <c><anno>Property</anno></c>, and <c>E</c> and <c><anno>Property</anno></c> have equivalent normal forms, then <c>E</c> is replaced with the terms in <c><anno>Expansion</anno></c>, and any following entries with - the same key are deleted from <c><anno>List</anno></c>.</p> + the same key are deleted from <c><anno>ListIn</anno></c>.</p> <p>For example, the following expressions all return <c>[fie, bar, baz, fum]</c>:</p> <code type="none"> expand([{foo, [bar, baz]}], @@ -198,7 +198,7 @@ <name name="normalize" arity="2"/> <fsummary></fsummary> <desc> - <p>Passes <c><anno>List</anno></c> through a sequence of + <p>Passes <c><anno>ListIn</anno></c> through a sequence of substitution/expansion stages. For an <c>aliases</c> operation, the function <c>substitute_aliases/2</c> is applied using the given list of aliases; for a <c>negations</c> operation, @@ -221,9 +221,9 @@ <fsummary></fsummary> <desc> <p>Creates a normal form (minimal) representation of a property. If - <c><anno>Property</anno></c> is <c>{Key, true}</c> where <c>Key</c> is - an atom, this returns <c>Key</c>, otherwise the whole term - <c><anno>Property</anno></c> is returned.</p> + <c><anno>PropertyIn</anno></c> is <c>{Key, true}</c> where + <c>Key</c> is an atom, this returns <c>Key</c>, otherwise + the whole term <c><anno>PropertyIn</anno></c> is returned.</p> <p>See also: <c>property/2</c>.</p> </desc> </func> @@ -260,7 +260,7 @@ <fsummary></fsummary> <desc> <p>Substitutes keys of properties. For each entry in - <c><anno>List</anno></c>, if it is associated with some key <c>K1</c> + <c><anno>ListIn</anno></c>, if it is associated with some key <c>K1</c> such that <c>{K1, K2}</c> occurs in <c><anno>Aliases</anno></c>, the key of the entry is changed to <c>K2</c>. If the same <c>K1</c> occurs more than once in <c><anno>Aliases</anno></c>, only @@ -278,13 +278,13 @@ <desc> <p>Substitutes keys of boolean-valued properties and simultaneously negates their values. For each entry in - <c><anno>List</anno></c>, if it is associated with some key <c>K1</c> + <c><anno>ListIn</anno></c>, if it is associated with some key <c>K1</c> such that <c>{K1, K2}</c> occurs in <c><anno>Negations</anno></c>, then if the entry was <c>{K1, true}</c> it will be replaced with <c>{K2, false}</c>, otherwise it will be replaced with <c>{K2, true}</c>, thus changing the name of the option and simultaneously negating the value given by - <c>get_bool(List)</c>. If the same <c>K1</c> occurs more + <c>get_bool(ListIn)</c>. If the same <c>K1</c> occurs more than once in <c><anno>Negations</anno></c>, only the first occurrence is used.</p> <p>Example: <c>substitute_negations([{no_foo, foo}], L)</c> @@ -300,7 +300,7 @@ <name name="unfold" arity="1"/> <fsummary></fsummary> <desc> - <p>Unfolds all occurrences of atoms in <c><anno>List</anno></c> to tuples + <p>Unfolds all occurrences of atoms in <c><anno>ListIn</anno></c> to tuples <c>{Atom, true}</c>.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/qlc.xml b/lib/stdlib/doc/src/qlc.xml index ce50631ca9..8682936c08 100644 --- a/lib/stdlib/doc/src/qlc.xml +++ b/lib/stdlib/doc/src/qlc.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2004</year><year>2011</year> + <year>2004</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/queue.xml b/lib/stdlib/doc/src/queue.xml index 383f52d10d..9c994154d4 100644 --- a/lib/stdlib/doc/src/queue.xml +++ b/lib/stdlib/doc/src/queue.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -90,9 +90,15 @@ <datatypes> <datatype> - <name><marker id="type-queue">queue()</marker></name> + <name name="queue" n_vars="1"/> <desc><p>As returned by <c>new/0</c>.</p></desc> </datatype> + <datatype> + <name name="queue" n_vars="0"/> + <desc> + <p><c>queue()</c> is equivalent to <c>queue(term())</c>.</p> + </desc> + </datatype> </datatypes> <funcs> diff --git a/lib/stdlib/doc/src/random.xml b/lib/stdlib/doc/src/random.xml index 1b8fa44883..e001058e19 100644 --- a/lib/stdlib/doc/src/random.xml +++ b/lib/stdlib/doc/src/random.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/re.xml b/lib/stdlib/doc/src/re.xml index 6d5336796c..a1833f6a51 100644 --- a/lib/stdlib/doc/src/re.xml +++ b/lib/stdlib/doc/src/re.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>2007</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -40,8 +40,8 @@ <p>This module contains regular expression matching functions for strings and binaries.</p> - <p>The regular expression syntax and semantics resemble that of - Perl.</p> + <p>The <seealso marker="#regexp_syntax">regular expression</seealso> + syntax and semantics resemble that of Perl.</p> <p>The library's matching algorithms are currently based on the PCRE library, but not all of the PCRE library is interfaced and @@ -78,28 +78,15 @@ </datatypes> <funcs> <func> - <name>compile(Regexp) -> {ok, MP} | {error, ErrSpec}</name> + <name name="compile" arity="1"/> <fsummary>Compile a regular expression into a match program</fsummary> - <type> - <v>Regexp = iodata()</v> - </type> <desc> - <p>The same as <c>compile(Regexp,[])</c></p> + <p>The same as <c>compile(<anno>Regexp</anno>,[])</c></p> </desc> </func> <func> - <name>compile(Regexp,Options) -> {ok, MP} | {error, ErrSpec}</name> + <name name="compile" arity="2"/> <fsummary>Compile a regular expression into a match program</fsummary> - <type> - <v>Regexp = iodata() | <seealso marker="unicode#type-charlist">io:charlist()</seealso></v> - <v>Options = [ Option ]</v> - <v>Option = <seealso marker="#type-compile_option">compile_option()</seealso></v> - <v>NLSpec = <seealso marker="#type-nl_spec">nl_spec()</seealso></v> - <v>MP = <seealso marker="#type-mp">mp()</seealso></v> - <v>ErrSpec = {ErrString, Position}</v> - <v>ErrString = string()</v> - <v>Position = non_neg_integer()</v> - </type> <desc> <p>This function compiles a regular expression with the syntax described below into an internal format to be used later as a @@ -109,12 +96,12 @@ subjects during the program's lifetime. Compiling once and executing many times is far more efficient than compiling each time one wants to match.</p> - <p>When the unicode option is given, the regular expression should be given as a valid unicode <c>charlist()</c>, otherwise as any valid <c>iodata()</c>.</p> + <p>When the unicode option is given, the regular expression should be given as a valid Unicode <c>charlist()</c>, otherwise as any valid <c>iodata()</c>.</p> <p><marker id="compile_options"/>The options have the following meanings:</p> <taglist> <tag><c>unicode</c></tag> - <item>The regular expression is given as a unicode <c>charlist()</c> and the resulting regular expression code is to be run against a valid unicode <c>charlist()</c> subject.</item> + <item>The regular expression is given as a Unicode <c>charlist()</c> and the resulting regular expression code is to be run against a valid Unicode <c>charlist()</c> subject. Also consider the <c>ucp</c> option when using Unicode characters.</item> <tag><c>anchored</c></tag> <item>The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched (the "subject string"). This effect can also be achieved by appropriate constructs in the pattern itself.</item> <tag><c>caseless</c></tag> @@ -160,49 +147,68 @@ This option makes it possible to include comments inside complicated patterns. N <item>Specifies specifically that \R is to match only the cr, lf or crlf sequences, not the Unicode specific newline characters.</item> <tag><c>bsr_unicode</c></tag> <item>Specifies specifically that \R is to match all the Unicode newline characters (including crlf etc, the default).</item> + <tag><c>no_start_optimize</c></tag> + <item>This option disables optimization that may malfunction if "Special start-of-pattern items" are present in the regular expression. A typical example would be when matching "DEFABC" against "(*COMMIT)ABC", where the start optimization of PCRE would skip the subject up to the "A" and would never realize that the (*COMMIT) instruction should have made the matching fail. This option is only relevant if you use "start-of-pattern items", as discussed in the section "PCRE regular expression details" below.</item> + <tag><c>ucp</c></tag> + <item>Specifies that Unicode Character Properties should be used when resolving \B, \b, \D, \d, \S, \s, \Wand \w. Without this flag, only ISO-Latin-1 properties are used. Using Unicode properties hurts performance, but is semantically correct when working with Unicode characters beyond the ISO-Latin-1 range.</item> + <tag><c>never_utf</c></tag> + <item>Specifies that the (*UTF) and/or (*UTF8) "start-of-pattern items" are forbidden. This flag can not be combined with <c>unicode</c>. Useful if ISO-Latin-1 patterns from an external source are to be compiled.</item> </taglist> </desc> </func> <func> - <name>run(Subject,RE) -> {match, Captured} | nomatch</name> + <name name="inspect" arity="2"/> + <fsummary>Inspects a compiled regular expression</fsummary> + <desc> + <p>This function takes a compiled regular expression and an item, returning the relevant data from the regular expression. Currently the only supported item is <c>namelist</c>, which returns the tuple <c>{namelist, [ binary()]}</c>, containing the names of all (unique) named subpatterns in the regular expression.</p> + <p>Example:</p> + <code type="none"> +1> {ok,MP} = re:compile("(?<A>A)|(?<B>B)|(?<C>C)"). +{ok,{re_pattern,3,0,0, + <<69,82,67,80,119,0,0,0,0,0,0,0,1,0,0,0,255,255,255,255, + 255,255,...>>}} +2> re:inspect(MP,namelist). +{namelist,[<<"A">>,<<"B">>,<<"C">>]} +3> {ok,MPD} = re:compile("(?<C>A)|(?<B>B)|(?<C>C)",[dupnames]). +{ok,{re_pattern,3,0,0, + <<69,82,67,80,119,0,0,0,0,0,8,0,1,0,0,0,255,255,255,255, + 255,255,...>>}} +4> re:inspect(MPD,namelist). +{namelist,[<<"B">>,<<"C">>]}</code> + <p>Note specifically in the second example that the duplicate name only occurs once in the returned list, and that the list is in alphabetical order regardless of where the names are positioned in the regular expression. The order of the names is the same as the order of captured subexpressions if <c>{capture, all_names}</c> is given as an option to <c>re:run/3</c>. You can therefore create a name-to-value mapping from the result of <c>re:run/3</c> like this:</p> +<code> +1> {ok,MP} = re:compile("(?<A>A)|(?<B>B)|(?<C>C)"). +{ok,{re_pattern,3,0,0, + <<69,82,67,80,119,0,0,0,0,0,0,0,1,0,0,0,255,255,255,255, + 255,255,...>>}} +2> {namelist, N} = re:inspect(MP,namelist). +{namelist,[<<"A">>,<<"B">>,<<"C">>]} +3> {match,L} = re:run("AA",MP,[{capture,all_names,binary}]). +{match,[<<"A">>,<<>>,<<>>]} +4> NameMap = lists:zip(N,L). +[{<<"A">>,<<"A">>},{<<"B">>,<<>>},{<<"C">>,<<>>}]</code> + <p>More items are expected to be added in the future.</p> + </desc> + </func> + <func> + <name name="run" arity="2"/> <fsummary>Match a subject against regular expression and capture subpatterns</fsummary> - <type> - <v>Subject = iodata() | <seealso marker="unicode#type-charlist">io:charlist()</seealso></v> - <v>RE = <seealso marker="#type-mp">mp()</seealso> | iodata()</v> - <v>Captured = [ CaptureData ]</v> - <v>CaptureData = {integer(),integer()}</v> - </type> <desc> - <p>The same as <c>run(Subject,RE,[])</c>.</p> + <p>The same as <c>run(<anno>Subject</anno>,<anno>RE</anno>,[])</c>.</p> </desc> </func> <func> - <name>run(Subject,RE,Options) -> {match, Captured} | match | nomatch</name> + <name name="run" arity="3"/> + <type_desc variable="CompileOpt">See <seealso marker="#compile_options">compile/2</seealso> above.</type_desc> <fsummary>Match a subject against regular expression and capture subpatterns</fsummary> - <type> - <v>Subject = iodata() | <seealso marker="unicode#type-charlist">io:charlist()</seealso></v> - <v>RE = <seealso marker="#type-mp">mp()</seealso> | iodata() | <seealso marker="unicode#type-charlist">io:charlist()</seealso></v> - <v>Options = [ Option ]</v> - <v>Option = anchored | global | notbol | noteol | notempty | {offset, integer() >= 0} | {newline, NLSpec} | bsr_anycrlf | bsr_unicode | {capture, ValueSpec} | {capture, ValueSpec, Type} | CompileOpt</v> - <v>Type = index | list | binary</v> - <v>ValueSpec = all | all_but_first | first | none | ValueList</v> - <v>ValueList = [ ValueID ]</v> - <v>ValueID = integer() | string() | atom()</v> - <v>CompileOpt = <seealso marker="#type-compile_option">compile_option()</seealso></v> - <d>See <seealso marker="#compile_options">compile/2</seealso> above.</d> - <v>NLSpec = <seealso marker="#type-nl_spec">nl_spec()</seealso></v> - <v>Captured = [ CaptureData ] | [ [ CaptureData ] ... ]</v> - <v>CaptureData = {integer(),integer()} | ListConversionData | binary()</v> - <v>ListConversionData = string() | {error, string(), binary()} | {incomplete, string(), binary()}</v> - </type> <desc> <p>Executes a regexp matching, returning <c>match/{match, - Captured}</c> or <c>nomatch</c>. The regular expression can be + <anno>Captured</anno>}</c> or <c>nomatch</c>. The regular expression can be given either as <c>iodata()</c> in which case it is automatically compiled (as by <c>re:compile/2</c>) and executed, - or as a pre compiled <c>mp()</c> in which case it is executed + or as a pre-compiled <c>mp()</c> in which case it is executed against the subject directly.</p> <p>When compilation is involved, the exception <c>badarg</c> is @@ -212,25 +218,30 @@ This option makes it possible to include comments inside complicated patterns. N <p>If the regular expression is previously compiled, the option list can only contain the options <c>anchored</c>, - <c>global</c>, <c>notbol</c>, <c>noteol</c>, - <c>notempty</c>, <c>{offset, integer() >= 0}</c>, <c>{newline, - NLSpec}</c> and <c>{capture, ValueSpec}/{capture, ValueSpec, - Type}</c>. Otherwise all options valid for the + <c>global</c>, <c>notbol</c>, <c>noteol</c>, <c>report_errors</c>, + <c>notempty</c>, <c>notempty_atstart</c>, <c>{offset, integer() >= 0}</c>, + <c>{match_limit, integer() >= 0}</c>, + <c>{match_limit_recursion, integer() >= 0}</c>, + <c>{newline, + <anno>NLSpec</anno>}</c> and + <c>{capture, <anno>ValueSpec</anno>}/{capture, <anno>ValueSpec</anno>, + <anno>Type</anno>}</c>. Otherwise all options valid for the <c>re:compile/2</c> function are allowed as well. Options allowed both for compilation and execution of a match, namely - <c>anchored</c> and <c>{newline, NLSpec}</c>, will affect both + <c>anchored</c> and <c>{newline, <anno>NLSpec</anno>}</c>, + will affect both the compilation and execution if present together with a non pre-compiled regular expression.</p> <p>If the regular expression was previously compiled with the - option <c>unicode</c>, the <c>Subject</c> should be provided as + option <c>unicode</c>, the <c><anno>Subject</anno></c> should be provided as a valid Unicode <c>charlist()</c>, otherwise any <c>iodata()</c> will do. If compilation is involved and the option - <c>unicode</c> is given, both the <c>Subject</c> and the regular + <c>unicode</c> is given, both the <c><anno>Subject</anno></c> and the regular expression should be given as valid Unicode <c>charlists()</c>.</p> - <p>The <c>{capture, ValueSpec}/{capture, ValueSpec, Type}</c> + <p>The <c>{capture, <anno>ValueSpec</anno>}/{capture, <anno>ValueSpec</anno>, <anno>Type</anno>}</c> defines what to return from the function upon successful matching. The <c>capture</c> tuple may contain both a value specification telling which of the captured @@ -244,9 +255,20 @@ This option makes it possible to include comments inside complicated patterns. N at all is to be done (<c>{capture, none}</c>), the function will return the single atom <c>match</c> upon successful matching, otherwise the tuple - <c>{match, ValueList}</c> is returned. Disabling capturing can + <c>{match, <anno>ValueList</anno>}</c> is returned. Disabling capturing can be done either by specifying <c>none</c> or an empty list as - <c>ValueSpec</c>.</p> + <c><anno>ValueSpec</anno></c>.</p> + + <p>The <c>report_errors</c> option adds the possibility that an + error tuple is returned. The tuple will either indicate a + matching error (<c>match_limit</c> or + <c>match_limit_recursion</c>) or a compilation error, where the + error tuple has the format <c>{error, {compile, + <anno>CompileErr</anno>}}</c>. Note that if the option + <c>report_errors</c> is not given, the function never returns + error tuples, but will report compilation errors as a badarg + exception and failed matches due to exceeded match limits simply + as <c>nomatch</c>.</p> <p>The options relevant for execution are:</p> @@ -266,7 +288,7 @@ This option makes it possible to include comments inside complicated patterns. N Perl). Each match is returned as a separate <c>list()</c> containing the specific match as well as any matching subexpressions (or as specified by the <c>capture - option</c>). The <c>Captured</c> part of the return value will + option</c>). The <c><anno>Captured</anno></c> part of the return value will hence be a <c>list()</c> of <c>list()</c>s when this option is given.</p> @@ -275,7 +297,7 @@ This option makes it possible to include comments inside complicated patterns. N When the global option is given, <c>re:run/3</c> handles empty matches in the same way as Perl: a zero-length match at any point will be retried with the options <c>[anchored, - notempty]</c> as well. If that search gives a result of length + notempty_atstart]</c> as well. If that search gives a result of length > 0, the result is included. For example:</p> <code> re:run("cat","(|at)",[global]).</code> @@ -288,9 +310,9 @@ This option makes it possible to include comments inside complicated patterns. N <c>[{0,0},{0,0}]</c> (the second <c>{0,0}</c> is due to the subexpression marked by the parentheses). As the length of the match is 0, we don't advance to the next position yet.</item> - <tag>At offset <c>0</c> with <c>[anchored, notempty]</c></tag> + <tag>At offset <c>0</c> with <c>[anchored, notempty_atstart]</c></tag> <item> The search is retried - with the options <c>[anchored, notempty]</c> at the same + with the options <c>[anchored, notempty_atstart]</c> at the same position, which does not give any interesting result of longer length, so the search position is now advanced to the next character (<c>a</c>).</item> @@ -298,7 +320,7 @@ This option makes it possible to include comments inside complicated patterns. N <item>This time, the search results in <c>[{1,0},{1,0}]</c>, so this search will also be repeated with the extra options.</item> - <tag>At offset <c>1</c> with <c>[anchored, notempty]</c></tag> + <tag>At offset <c>1</c> with <c>[anchored, notempty_atstart]</c></tag> <item>Now the <c>ab</c> alternative is found and the result will be [{1,2},{1,2}]. The result is added to the list of results and the position in the @@ -306,7 +328,7 @@ This option makes it possible to include comments inside complicated patterns. N <tag>At offset <c>3</c></tag> <item>The search now once again matches the empty string, giving <c>[{3,0},{3,0}]</c>.</item> - <tag>At offset <c>1</c> with <c>[anchored, notempty]</c></tag> + <tag>At offset <c>1</c> with <c>[anchored, notempty_atstart]</c></tag> <item>This will give no result of length > 0 and we are at the last position, so the global search is complete.</item> </taglist> @@ -327,15 +349,21 @@ This option makes it possible to include comments inside complicated patterns. N subject. With the <c>notempty</c> option, this match is not valid, so re:run/3 searches further into the string for occurrences of "a" or "b".</p> - - <p>Perl has no direct equivalent of <c>notempty</c>, but it does - make a special case of a pattern match of the empty string - within its split() function, and when using the /g modifier. It - is possible to emulate Perl's behavior after matching a null - string by first trying the match again at the same offset with - <c>notempty</c> and <c>anchored</c>, and then, if that fails, by - advancing the starting offset (see below) and trying an ordinary - match again.</p> + </item> + <tag><c>notempty_atstart</c></tag> + <item> + <p>This is like <c>notempty</c>, except that an empty string + match that is not at the start of the subject is permitted. If + the pattern is anchored, such a match can occur only if the + pattern contains \K.</p> + <p>Perl has no direct equivalent of <c>notempty</c> or <c>notempty_atstart</c>, but it does + make a special case of a pattern match of the empty string + within its split() function, and when using the /g modifier. It + is possible to emulate Perl's behavior after matching a null + string by first trying the match again at the same offset with + <c>notempty_atstart</c> and <c>anchored</c>, and then, if that fails, by + advancing the starting offset (see below) and trying an ordinary + match again.</p> </item> <tag><c>notbol</c></tag> @@ -356,13 +384,123 @@ This option makes it possible to include comments inside complicated patterns. N behavior of the dollar metacharacter. It does not affect \Z or \z.</item> + <tag><c>report_errors</c></tag> + + <item><p>This option gives better control of the error handling in <c>re:run/3</c>. When it is given, compilation errors (if the regular expression isn't already compiled) as well as run-time errors are explicitly returned as an error tuple.</p> + <p>The possible run-time errors are:</p> + <taglist> + <tag><c>match_limit</c></tag> + + <item>The PCRE library sets a limit on how many times the + internal match function can be called. The default value for + this is 10000000 in the library compiled for Erlang. If + <c>{error, match_limit}</c> is returned, it means that the + execution of the regular expression has reached this + limit. Normally this is to be regarded as a <c>nomatch</c>, + which is the default return value when this happens, but by + specifying <c>report_errors</c>, you will get informed when + the match fails due to to many internal calls.</item> + + <tag><c>match_limit_recursion</c></tag> + + <item>This error is very similar to <c>match_limit</c>, but + occurs when the internal match function of PCRE is + "recursively" called more times than the + "match_limit_recursion" limit, which is by default 10000000 as + well. Note that as long as the <c>match_limit</c> and + <c>match_limit_default</c> values are kept at the default + values, the <c>match_limit_recursion</c> error can not occur, + as the <c>match_limit</c> error will occur before that (each + recursive call is also a call, but not vice versa). Both + limits can however be changed, either by setting limits + directly in the regular expression string (see reference + section below) or by giving options to <c>re:run/3</c></item> + + </taglist> + <p>It is important to understand that what is referred to as + "recursion" when limiting matches is not actually recursion on + the C stack of the Erlang machine, neither is it recursion on + the Erlang process stack. The version of PCRE compiled into the + Erlang VM uses machine "heap" memory to store values that needs to be + kept over recursion in regular expression matches.</p> + </item> + <tag><c>{match_limit, integer() >= 0}</c></tag> + + <item><p>This option limits the execution time of a match in an + implementation-specific way. It is described in the following + way by the PCRE documentation:</p> + + <code> +The match_limit field provides a means of preventing PCRE from using +up a vast amount of resources when running patterns that are not going +to match, but which have a very large number of possibilities in their +search trees. The classic example is a pattern that uses nested +unlimited repeats. + +Internally, pcre_exec() uses a function called match(), which it calls +repeatedly (sometimes recursively). The limit set by match_limit is +imposed on the number of times this function is called during a match, +which has the effect of limiting the amount of backtracking that can +take place. For patterns that are not anchored, the count restarts +from zero for each position in the subject string.</code> + + <p>This means that runaway regular expression matches can fail + faster if the limit is lowered using this option. The default + value compiled into the Erlang virtual machine is 10000000</p> + + <note><p>This option does in no way affect the execution of the + Erlang virtual machine in terms of "long running + BIF's". <c>re:run</c> always give control back to the scheduler + of Erlang processes at intervals that ensures the real time + properties of the Erlang system.</p></note> + </item> + + <tag><c>{match_limit_recursion, integer() >= 0}</c></tag> + + <item><p>This option limits the execution time and memory + consumption of a match in an implementation-specific way, very + similar to <c>match_limit</c>. It is described in the following + way by the PCRE documentation:</p> + + <code> +The match_limit_recursion field is similar to match_limit, but instead +of limiting the total number of times that match() is called, it +limits the depth of recursion. The recursion depth is a smaller number +than the total number of calls, because not all calls to match() are +recursive. This limit is of use only if it is set smaller than +match_limit. + +Limiting the recursion depth limits the amount of machine stack that +can be used, or, when PCRE has been compiled to use memory on the heap +instead of the stack, the amount of heap memory that can be +used.</code> + + <p>The Erlang virtual machine uses a PCRE library where heap + memory is used when regular expression match recursion happens, + why this limits the usage of machine heap, not C stack.</p> + + <p>Specifying a lower value may result in matches with deep recursion failing, when they should actually have matched:</p> + <code type="none"> +1> re:run("aaaaaaaaaaaaaz","(a+)*z"). +{match,[{0,14},{0,13}]} +2> re:run("aaaaaaaaaaaaaz","(a+)*z",[{match_limit_recursion,5}]). +nomatch +3> re:run("aaaaaaaaaaaaaz","(a+)*z",[{match_limit_recursion,5},report_errors]). +{error,match_limit_recursion}</code> + + <p>This option, as well as the <c>match_limit</c> option should + only be used in very rare cases. Understanding of the PCRE + library internals is recommended before tampering with these + limits.</p> + </item> + <tag><c>{offset, integer() >= 0}</c></tag> <item>Start matching at the offset (position) given in the subject string. The offset is zero-based, so that the default is <c>{offset,0}</c> (all of the subject string).</item> - <tag><c>{newline, NLSpec}</c></tag> + <tag><c>{newline, <anno>NLSpec</anno>}</c></tag> <item> <p>Override the default definition of a newline in the subject string, which is LF (ASCII 10) in Erlang.</p> <taglist> @@ -383,7 +521,7 @@ This option makes it possible to include comments inside complicated patterns. N <tag><c>bsr_unicode</c></tag> <item>Specifies specifically that \R is to match all the Unicode newline characters (including crlf etc, the default).(overrides compilation option)</item> - <tag><c>{capture, ValueSpec}</c>/<c>{capture, ValueSpec, Type}</c></tag> + <tag><c>{capture, <anno>ValueSpec</anno>}</c>/<c>{capture, <anno>ValueSpec</anno>, <anno>Type</anno>}</c></tag> <item> <p>Specifies which captured substrings are returned and in what @@ -392,7 +530,7 @@ This option makes it possible to include comments inside complicated patterns. N substring as well as all capturing subpatterns (all of the pattern is automatically captured). The default return type is (zero-based) indexes of the captured parts of the string, given as - <c>{Offset,Length}</c> pairs (the <c>index</c> <c>Type</c> of + <c>{Offset,Length}</c> pairs (the <c>index</c> <c><anno>Type</anno></c> of capturing).</p> <p>As an example of the default behavior, the following call:</p> @@ -422,12 +560,15 @@ This option makes it possible to include comments inside complicated patterns. N <p>The capture tuple is built up as follows:</p> <taglist> - <tag><c>ValueSpec</c></tag> - <item><p>Specifies which captured (sub)patterns are to be returned. The ValueSpec can either be an atom describing a predefined set of return values, or a list containing either the indexes or the names of specific subpatterns to return.</p> + <tag><c><anno>ValueSpec</anno></c></tag> + <item><p>Specifies which captured (sub)patterns are to be returned. The <c><anno>ValueSpec</anno></c> can either be an atom describing a predefined set of return values, or a list containing either the indexes or the names of specific subpatterns to return.</p> <p>The predefined sets of subpatterns are:</p> <taglist> <tag><c>all</c></tag> <item>All captured subpatterns including the complete matching string. This is the default.</item> + <tag><c>all_names</c></tag> + <item>All <em>named</em> subpatterns in the regular expression, as if a <c>list()</c> + of all the names <em>in alphabetical order</em> was given. The list of all names can also be retrieved with the <seealso marker="#inspect/2">inspect/2</seealso> function.</item> <tag><c>first</c></tag> <item>Only the first captured subpattern, which is always the complete matching part of the subject. All explicitly captured subpatterns are discarded.</item> <tag><c>all_but_first</c></tag> @@ -437,7 +578,7 @@ This option makes it possible to include comments inside complicated patterns. N </taglist> <p>The value list is a list of indexes for the subpatterns to return, where index 0 is for all of the pattern, and 1 is for the first explicit capturing subpattern in the regular expression, and so forth. When using named captured subpatterns (see below) in the regular expression, one can use <c>atom()</c>s or <c>string()</c>s to specify the subpatterns to be returned. For example, consider the regular expression:</p> <code> ".*(abcd).*"</code> - <p>matched against the string ""ABCabcdABC", capturing only the "abcd" part (the first explicit subpattern):</p> + <p>matched against the string "ABCabcdABC", capturing only the "abcd" part (the first explicit subpattern):</p> <code> re:run("ABCabcdABC",".*(abcd).*",[{capture,[1]}]).</code> <p>The call will yield the following result:</p> <code> {match,[{3,4}]}</code> @@ -460,8 +601,8 @@ This option makes it possible to include comments inside complicated patterns. N or list respectively.</p> </item> - <tag><c>Type</c></tag> - <item><p>Optionally specifies how captured substrings are to be returned. If omitted, the default of <c>index</c> is used. The <c>Type</c> can be one of the following:</p> + <tag><c><anno>Type</anno></c></tag> + <item><p>Optionally specifies how captured substrings are to be returned. If omitted, the default of <c>index</c> is used. The <c><anno>Type</anno></c> can be one of the following:</p> <taglist> <tag><c>index</c></tag> <item>Return captured substrings as pairs of byte indexes into the subject string and length of the matching string in the subject (as if the subject string was flattened with <c>iolist_to_binary/1</c> or <c>unicode:characters_to_binary/2</c> prior to matching). Note that the <c>unicode</c> option results in <em>byte-oriented</em> indexes in a (possibly virtual) <em>UTF-8 encoded</em> binary. A byte index tuple <c>{0,2}</c> might therefore represent one or two characters when <c>unicode</c> is in effect. This might seem counter-intuitive, but has been deemed the most effective and useful way to way to do it. To return lists instead might result in simpler code if that is desired. This return type is the default.</item> @@ -478,7 +619,7 @@ This option makes it possible to include comments inside complicated patterns. N <code> "ABCabcdABC"</code> <p>the subpattern at index 2 won't match, as "abdd" is not present in the string, but the complete pattern matches (due to the alternative <c>a(..d)</c>. The subpattern at index 2 is therefore unassigned and the default return value will be:</p> <code> {match,[{0,10},{3,4},{-1,0},{4,3}]}</code> - <p>Setting the capture <c>Type</c> to <c>binary</c> would give the following:</p> + <p>Setting the capture <c><anno>Type</anno></c> to <c>binary</c> would give the following:</p> <code> {match,[<<"ABCabcdABC">>,<<"abcd">>,<<>>,<<"bcd">>]}</code> <p>where the empty binary (<c><<>></c>) represents the unassigned subpattern. In the <c>binary</c> case, some information about the matching is therefore lost, the <c><<>></c> might just as well be an empty string captured.</p> <p>If differentiation between empty matches and non existing subpatterns is necessary, use the <c>type</c> <c>index</c> @@ -512,7 +653,7 @@ This option makes it possible to include comments inside complicated patterns. N <p>Replaces the matched part of the <c><anno>Subject</anno></c> string with the contents of <c><anno>Replacement</anno></c>.</p> <p>The permissible options are the same as for <c>re:run/3</c>, except that the <c>capture</c> option is not allowed. Instead a <c>{return, <anno>ReturnType</anno>}</c> is present. The default return type is <c>iodata</c>, constructed in a - way to minimize copying. The <c>iodata</c> result can be used directly in many i/o-operations. If a flat <c>list()</c> is + way to minimize copying. The <c>iodata</c> result can be used directly in many I/O-operations. If a flat <c>list()</c> is desired, specify <c>{return, list}</c> and if a binary is preferred, specify <c>{return, binary}</c>.</p> <p>As in the <c>re:run/3</c> function, an <c>mp()</c> compiled @@ -524,8 +665,8 @@ This option makes it possible to include comments inside complicated patterns. N <p>The replacement string can contain the special character <c>&</c>, which inserts the whole matching expression in the - result, and the special sequence <c>\</c>N (where N is an - integer > 0), resulting in the subexpression number N will be + result, and the special sequence <c>\</c>N (where N is an integer > 0), + <c>\g</c>N or <c>\g{</c>N<c>}</c> resulting in the subexpression number N will be inserted in the result. If no subexpression with that number is generated by the regular expression, nothing is inserted.</p> <p>To insert an <c>&</c> or <c>\</c> in the result, precede it @@ -736,7 +877,7 @@ This option makes it possible to include comments inside complicated patterns. N </func> </funcs> - + <marker id="regexp_syntax"></marker> <section> <title>PERL LIKE REGULAR EXPRESSIONS SYNTAX</title> <p>The following sections contain reference material for the @@ -755,12 +896,12 @@ published by O'Reilly, covers regular expressions in great detail. This description of PCRE's regular expressions is intended as reference material.</p> <p>The reference material is divided into the following sections:</p> <list> -<item><seealso marker="#sect1">Newline conventions</seealso></item> +<item><seealso marker="#sect1">Special start-of-pattern items</seealso></item> <item><seealso marker="#sect2">Characters and metacharacters</seealso></item> <item><seealso marker="#sect3">Backslash</seealso></item> <item><seealso marker="#sect4">Circumflex and dollar</seealso></item> -<item><seealso marker="#sect5">Full stop (period, dot)</seealso></item> -<item><seealso marker="#sect6">Matching a single byte</seealso></item> +<item><seealso marker="#sect5">Full stop (period, dot) and \N</seealso></item> +<item><seealso marker="#sect6">Matching a single data unit</seealso></item> <item><seealso marker="#sect7">Square brackets and character classes</seealso></item> <item><seealso marker="#sect8">POSIX character classes</seealso></item> <item><seealso marker="#sect9">Vertical bar</seealso></item> @@ -776,6 +917,7 @@ description of PCRE's regular expressions is intended as reference material.</p> <item><seealso marker="#sect19">Comments</seealso></item> <item><seealso marker="#sect20">Recursive patterns</seealso></item> <item><seealso marker="#sect21">Subpatterns as subroutines</seealso></item> +<item><seealso marker="#sect22">Oniguruma subroutine syntax</seealso></item> <!-- XXX C Interface <item><seealso marker="#sect22">Callouts</seealso></item> --> @@ -785,7 +927,55 @@ description of PCRE's regular expressions is intended as reference material.</p> </section> -<section><marker id="sect1"></marker><title>Newline conventions</title> +<section><marker id="sect1"></marker><title>Special start-of-pattern items</title> + +<p>A number of options that can be passed to <c>re:compile/2</c> can also be set +by special items at the start of a pattern. These are not Perl-compatible, but +are provided to make these options accessible to pattern writers who are not +able to change the program that processes the pattern. Any number of these +items may appear, but they must all be together right at the start of the +pattern string, and the letters must be in upper case.</p> + +<p><em>UTF support</em></p> +<p> +Unicode support is basically UTF-8 based. To use Unicode characters, you either +call <c>re:compile/2</c>/<c>re:run/3</c> with the <c>unicode</c> option, or the + pattern must start with one of these special sequences:</p> +<quote> +<p> (*UTF8)</p> +<p> (*UTF)</p> +</quote> + +<p>Both options give the same effect, the input string is interpreted +as UTF-8. Note that with these instructions, the automatic conversion +of lists to UTF-8 is not performed by the <c>re</c> functions, why +using these options is not recommended. Add the <c>unicode</c> option +when running <c>re:compile/2</c> instead.</p> + +<p> +Some applications that allow their users to supply patterns may wish to +restrict them to non-UTF data for security reasons. If the <c>never_utf</c> +option is set at compile time, (*UTF) etc. are not allowed, and their +appearance causes an error. +</p> + +<p><em>Unicode property support</em></p> +<p>Another special sequence that may appear at the start of a pattern is</p> +<quote> +<p> (*UCP)</p> +</quote> +<p>This has the same effect as setting the <c>ucp</c> option: it causes sequences +such as \d and \w to use Unicode properties to determine character types, +instead of recognizing only characters with codes less than 128 via a lookup +table. +</p> + +<p><em>Disabling start-up optimizations</em></p> +<p> +If a pattern starts with (*NO_START_OPT), it has the same effect as setting the +<c>no_Start_optimize</c> option at compile time.</p> + +<p><em>Newline conventions</em></p> <p>PCRE supports five @@ -814,23 +1004,37 @@ example, the pattern:</p> </quote> <p>changes the convention to CR. That pattern matches "a\nb" because LF is no -longer a newline. Note that these special settings, which are not -Perl-compatible, are recognized only at the very start of a pattern, and that -they must be in upper case. If more than one of them is present, the last one +longer a newline. If more than one of them is present, the last one is used.</p> -<p>The newline convention does not affect what the \R escape sequence matches. By -default, this is any Unicode newline sequence, for Perl compatibility. However, -this can be changed; see the description of \R in the section entitled +<p>The newline convention affects where the circumflex and dollar assertions are +true. It also affects the interpretation of the dot metacharacter when +<c>dotall</c> is not set, and the behaviour of \N. However, it does not affect +what the \R escape sequence matches. By default, this is any Unicode newline +sequence, for Perl compatibility. However, this can be changed; see the +description of \R in the section entitled -"Newline sequences" +<em>"Newline sequences"</em> below. A change of \R setting can be combined with a change of newline convention.</p> +<p><em>Setting match and recursion limits</em></p> + +<p>The caller of <c>re:run/3</c> can set a limit on the number of times the internal match() function is called and on the maximum depth of recursive calls. These facilities are provided to catch runaway matches that are provoked by patterns with huge matching trees (a typical example is a pattern with nested unlimited repeats) and to avoid running out of system stack by too much recursion. When one of these limits is reached, pcre_exec() gives an error return. The limits can also be set by items at the start of the pattern of the form</p> +<quote> +<p> (*LIMIT_MATCH=d)</p> +<p> (*LIMIT_RECURSION=d)</p> +</quote> +<p>where d is any number of decimal digits. However, the value of the setting must be less than the value set by the caller of <c>re:run/3</c> for it to have any effect. In other words, the pattern writer can lower the limit set by the programmer, but not raise it. If there is more than one setting of one of these limits, the lower value is used.</p> + +<p>The current default value for both the limits are 10000000 in the Erlang +VM. Note that the recursion limit does not actually affect the stack +depth of the VM, as PCRE for Erlang is compiled in such a way that the +match function never does recursion on the "C-stack".</p> + </section> - <section><marker id="sect2"></marker><title>Characters and metacharacters</title> <!-- .rs --> @@ -896,7 +1100,7 @@ a character class the only metacharacters are:</p> <p>The backslash character has several uses. Firstly, if it is followed by a -non-alphanumeric character, it takes away any special meaning that character +character that is not a number or a letter, it takes away any special meaning that character may have. This use of backslash as an escape character applies both inside and outside character classes.</p> @@ -906,10 +1110,14 @@ otherwise be interpreted as a metacharacter, so it is always safe to precede a non-alphanumeric with backslash to specify that it stands for itself. In particular, if you want to match a backslash, you write \\.</p> -<p>If a pattern is compiled with the <c>extended</c> option, whitespace in the +<p>In <c>unicode</c> mode, only ASCII numbers and letters have any special meaning after a +backslash. All other characters (in particular, those whose codepoints are +greater than 127) are treated as literals.</p> + +<p>If a pattern is compiled with the <c>extended</c> option, white space in the pattern (other than in a character class) and characters between a # outside a character class and the next newline are ignored. An escaping backslash can -be used to include a whitespace or # character as part of the pattern.</p> +be used to include a white space or # character as part of the pattern.</p> <p>If you want to remove the special meaning from a sequence of characters, you can do so by putting them between \Q and \E. This is different from Perl in @@ -923,42 +1131,54 @@ Perl, $ and @ cause variable interpolation. Note the following examples:</p> \Qabc\E\$\Qxyz\E abc$xyz abc$xyz</code> -<p>The \Q...\E sequence is recognized both inside and outside character classes.</p> - +<p>The \Q...\E sequence is recognized both inside and outside +character classes. An isolated \E that is not preceded by \Q is +ignored. If \Q is not followed by \E later in the pattern, the literal +interpretation continues to the end of the pattern (that is, \E is +assumed at the end). If the isolated \Q is inside a character class, +this causes an error, because the character class is not +terminated.</p> <p><em>Non-printing characters</em></p> <p>A second use of backslash provides a way of encoding non-printing characters in patterns in a visible manner. There is no restriction on the appearance of non-printing characters, apart from the binary zero that terminates a pattern, -but when a pattern is being prepared by text editing, it is usually easier to -use one of the following escape sequences than the binary character it -represents:</p> +but when a pattern is being prepared by text editing, it is often easier to use +one of the following escape sequences than the binary character it represents:</p> <taglist> <tag>\a</tag> <item>alarm, that is, the BEL character (hex 07)</item> - <tag>\cx</tag> <item>"control-x", where x is any character</item> + <tag>\cx</tag> <item>"control-x", where x is any ASCII character</item> <tag>\e </tag> <item>escape (hex 1B)</item> - <tag>\f</tag> <item>formfeed (hex 0C)</item> + <tag>\f</tag> <item>form feed (hex 0C)</item> <tag>\n</tag> <item>linefeed (hex 0A)</item> <tag>\r</tag> <item>carriage return (hex 0D)</item> <tag>\t </tag> <item>tab (hex 09)</item> - <tag>\ddd</tag> <item>character with octal code ddd, or backreference</item> + <tag>\ddd</tag> <item>character with octal code ddd, or back reference</item> <tag>\xhh </tag> <item>character with hex code hh</item> <tag>\x{hhh..}</tag> <item>character with hex code hhh..</item> </taglist> -<p>The precise effect of \cx is as follows: if x is a lower case letter, it -is converted to upper case. Then bit 6 of the character (hex 40) is inverted. -Thus \cz becomes hex 1A, but \c{ becomes hex 3B, while \c; becomes hex -7B.</p> +<p>The precise effect of \cx on ASCII characters is as follows: if x is a lower +case letter, it is converted to upper case. Then bit 6 of the character (hex +40) is inverted. Thus \cA to \cZ become hex 01 to hex 1A (A is 41, Z is 5A), +but \c{ becomes hex 3B ({ is 7B), and \c; becomes hex 7B (; is 3B). If the +data item (byte or 16-bit value) following \c has a value greater than 127, a +compile-time error occurs. This locks out non-ASCII characters in all modes.</p> -<p>After \x, from zero to two hexadecimal digits are read (letters can be in -upper or lower case). Any number of hexadecimal digits may appear between \x{ -and }, but the value of the character code must be less than 256 in non-UTF-8 -mode, and less than 2**31 in UTF-8 mode. That is, the maximum value in -hexadecimal is 7FFFFFFF. Note that this is bigger than the largest Unicode code -point, which is 10FFFF.</p> +<p>The \c facility was designed for use with ASCII characters, but with the +extension to Unicode it is even less useful than it once was.</p> + +<p>By default, after \x, from zero to two hexadecimal digits are read (letters +can be in upper or lower case). Any number of hexadecimal digits may appear +between \x{ and }, but the character code is constrained as follows:</p> +<taglist> + <tag>8-bit non-Unicode mode</tag> <item>less than 0x100</item> + <tag>8-bit UTF-8 mode</tag> <item>less than 0x10ffff and a valid codepoint</item> +</taglist> +<p>Invalid Unicode codepoints are the range 0xd800 to 0xdfff (the so-called +"surrogate" codepoints), and 0xffef.</p> <p>If characters other than hexadecimal digits appear between \x{ and }, or if there is no terminating }, this form of escape is not recognized. Instead, the @@ -986,17 +1206,12 @@ later, following the discussion of parenthesized subpatterns.</p> <p>Inside a character class, or if the decimal number is greater than 9 and there have not been that many capturing subpatterns, PCRE re-reads up to three octal digits following the backslash, and uses them to generate a data character. Any -subsequent digits stand for themselves. -The value of a -character specified in octal must be less than \400. -In non-UTF-8 mode, the value of a -character specified in octal must be less than \400. In UTF-8 mode, values up -to \777 are permitted. - +subsequent digits stand for themselves. The value of the character is +constrained in the same way as characters specified in hexadecimal. For example:</p> <taglist> - <tag>\040</tag> <item>is another way of writing a space</item> + <tag>\040</tag> <item>is another way of writing a ASCII space</item> <tag>\40</tag> <item>is the same, provided there are fewer than 40 previous capturing subpatterns</item> @@ -1011,7 +1226,7 @@ For example:</p> character with octal code 113</item> <tag>\377</tag> <item>might be a back reference, otherwise - the byte consisting entirely of 1 bits</item> + the value 255 (decimal)</item> <tag>\81</tag> <item>is either a back reference, or a binary zero followed by the two characters "8" and "1"</item> @@ -1021,12 +1236,19 @@ For example:</p> a leading zero, because no more than three octal digits are ever read.</p> -<p>All the sequences that define a single character value can be used -both inside and outside character classes. In addition, inside a -character class, the sequence \b is interpreted as the backspace -character (hex 08), and the sequences \R and \X are interpreted as -the characters "R" and "X", respectively. Outside a character class, -these sequences have different meanings (see below).</p> +<p>All the sequences that define a single character value can be used both inside +and outside character classes. In addition, inside a character class, \b is +interpreted as the backspace character (hex 08).</p> +<p>\N is not allowed in a character class. \B, \R, and \X are not special +inside a character class. Like other unrecognized escape sequences, they are +treated as the literal characters "B", "R", and "X". Outside a character class, these +sequences have different meanings.</p> + +<p><em>Unsupported escape sequences</em></p> + +<p>In Perl, the sequences \l, \L, \u, and \U are recognized by its string +handler and used to modify the case of following characters. PCRE +does not support these escape sequences.</p> <p><em>Absolute and relative back references</em></p> @@ -1036,30 +1258,42 @@ reference. A named back reference can be coded as \g{name}. Back references are discussed later, following the discussion of parenthesized subpatterns.</p> +<p><em>Absolute and relative subroutine calls</em></p> +<p>For compatibility with Oniguruma, the non-Perl syntax \g followed by a name or +a number enclosed either in angle brackets or single quotes, is an alternative +syntax for referencing a subpattern as a "subroutine". Details are discussed +later. +Note that \g{...} (Perl syntax) and \g<...> (Oniguruma syntax) are <em>not</em> +synonymous. The former is a back reference; the latter is a +subroutine call.</p> + <p><em>Generic character types</em></p> -<p>Another use of backslash is for specifying generic character types. The -following are always recognized:</p> +<p>Another use of backslash is for specifying generic character types:</p> <taglist> <tag>\d</tag> <item>any decimal digit</item> <tag>\D</tag> <item>any character that is not a decimal digit</item> - <tag>\h</tag> <item>any horizontal whitespace character</item> - <tag>\H</tag> <item>any character that is not a horizontal whitespace character</item> - <tag>\s</tag> <item>any whitespace character</item> - <tag>\S</tag> <item>any character that is not a whitespace character</item> - <tag>\v</tag> <item>any vertical whitespace character</item> - <tag>\V</tag> <item>any character that is not a vertical whitespace character</item> + <tag>\h</tag> <item>any horizontal white space character</item> + <tag>\H</tag> <item>any character that is not a horizontal white space character</item> + <tag>\s</tag> <item>any white space character</item> + <tag>\S</tag> <item>any character that is not a white space character</item> + <tag>\v</tag> <item>any vertical white space character</item> + <tag>\V</tag> <item>any character that is not a vertical white space character</item> <tag>\w</tag> <item>any "word" character</item> <tag>\W</tag> <item>any "non-word" character</item> </taglist> -<p>Each pair of escape sequences partitions the complete set of characters into -two disjoint sets. Any given character matches one, and only one, of each pair.</p> +<p>There is also the single sequence \N, which matches a non-newline character. +This is the same as the "." metacharacter +when <c>dotall</c> is not set. Perl also uses \N to match characters by name; +PCRE does not support this.</p> -<p>These character type sequences can appear both inside and outside character +<p>Each pair of lower and upper case escape sequences partitions the complete set +of characters into two disjoint sets. Any given character matches one, and only +one, of each pair. The sequences can appear both inside and outside character classes. They each match one character of the appropriate type. If the current -matching point is at the end of the subject string, all of them fail, since +matching point is at the end of the subject string, all of them fail, because there is no character to match.</p> <p>For compatibility with Perl, \s does not match the VT character (code 11). @@ -1068,18 +1302,34 @@ are HT (9), LF (10), FF (12), CR (13), and space (32). If "use locale;" is included in a Perl script, \s may match the VT character. In PCRE, it never does.</p> -<p>In UTF-8 mode, characters with values greater than 128 never match \d, \s, or -\w, and always match \D, \S, and \W. This is true even when Unicode -character property support is available. These sequences retain their original -meanings from before UTF-8 support was available, mainly for efficiency -reasons.</p> +<p>A "word" character is an underscore or any character that is a letter or digit. +By default, the definition of letters and digits is controlled by PCRE's +low-valued character tables, in Erlang's case (and without the <c>unicode</c> option), +the ISO-Latin-1 character set.</p> + +<p>By default, in <c>unicode</c> mode, characters with values greater than 128 never match +\d, \s, or \w, and always match \D, \S, and \W. These sequences retain +their original meanings from before UTF support was available, mainly for +efficiency reasons. However, if the <c>ucp</c> option is set, the behaviour is changed so that Unicode +properties are used to determine character types, as follows:</p> +<taglist> + <tag>\d</tag> <item>any character that \p{Nd} matches (decimal digit)</item> + <tag>\s</tag> <item>any character that \p{Z} matches, plus HT, LF, FF, CR)</item> + <tag> \w</tag> <item>any character that \p{L} or \p{N} matches, plus underscore)</item> +</taglist> +<p>The upper case escapes match the inverse sets of characters. Note that \d +matches only decimal digits, whereas \w matches any Unicode digit, as well as +any Unicode letter, and underscore. Note also that <c>ucp</c> affects \b, and +\B because they are defined in terms of \w and \W. Matching these sequences +is noticeably slower when <c>ucp</c> is set.</p> -<p>The sequences \h, \H, \v, and \V are Perl 5.10 features. In contrast to the -other sequences, these do match certain high-valued codepoints in UTF-8 mode. -The horizontal space characters are:</p> +<p>The sequences \h, \H, \v, and \V are features that were added to Perl at +release 5.10. In contrast to the other sequences, which match only ASCII +characters by default, these always match certain high-valued codepoints, +whether or not <c>ucp</c> is set. The horizontal space characters are:</p> <taglist> - <tag>U+0009</tag> <item>Horizontal tab</item> + <tag>U+0009</tag> <item>Horizontal tab (HT)</item> <tag>U+0020</tag> <item>Space</item> <tag>U+00A0</tag> <item>Non-break space</item> <tag>U+1680</tag> <item>Ogham space mark</item> @@ -1103,23 +1353,22 @@ The horizontal space characters are:</p> <p>The vertical space characters are:</p> <taglist> - <tag>U+000A</tag> <item>Linefeed</item> - <tag>U+000B</tag> <item>Vertical tab</item> - <tag>U+000C</tag> <item>Formfeed</item> - <tag>U+000D</tag> <item>Carriage return</item> - <tag>U+0085</tag> <item>Next line</item> + <tag>U+000A</tag> <item>Linefeed (LF)</item> + <tag>U+000B</tag> <item>Vertical tab (VT)</item> + <tag>U+000C</tag> <item>Form feed (FF)</item> + <tag>U+000D</tag> <item>Carriage return (CR)</item> + <tag>U+0085</tag> <item>Next line (NEL)</item> <tag>U+2028</tag> <item>Line separator</item> <tag>U+2029</tag> <item>Paragraph separator</item> </taglist> -<p>A "word" character is an underscore or any character less than 256 that is a -letter or digit. The definition of letters and digits is controlled by PCRE's -low-valued character tables, which are always ISO-8859-1.</p> +<p>In 8-bit, non-UTF-8 mode, only the characters with codepoints less than 256 are +relevant.</p> <p><em>Newline sequences</em></p> <p>Outside a character class, by default, the escape sequence \R matches any -Unicode newline sequence. This is a Perl 5.10 feature. In non-UTF-8 mode \R is +Unicode newline sequence. In non-UTF-8 mode \R is equivalent to the following:</p> <quote><p> (?>\r\n|\n|\x0b|\f|\r|\x85)</p></quote> @@ -1128,11 +1377,11 @@ equivalent to the following:</p> <p>This particular group matches either the two-character sequence CR followed by LF, or one of the single characters LF (linefeed, U+000A), VT (vertical tab, -U+000B), FF (formfeed, U+000C), CR (carriage return, U+000D), or NEL (next +U+000B), FF (form feed, U+000C), CR (carriage return, U+000D), or NEL (next line, U+0085). The two-character sequence is treated as a single unit that cannot be split.</p> -<p>In UTF-8 mode, two additional characters whose codepoints are greater than 255 +<p>In Unicode mode, two additional characters whose codepoints are greater than 255 are added: LS (line separator, U+2028) and PS (paragraph separator, U+2029). Unicode character property support is not needed for these characters to be recognized.</p> @@ -1149,35 +1398,39 @@ one of the following sequences:</p> <p> (*BSR_ANYCRLF) CR, LF, or CRLF only (*BSR_UNICODE) any Unicode newline sequence</p> -<p>These override the default and the options given to <c>re:compile/2</c>, but -they can be overridden by options given to <c>re:run/3</c>. Note that these -special settings, which are not Perl-compatible, are recognized only at the -very start of a pattern, and that they must be in upper case. If more than one -of them is present, the last one is used. They can be combined with a change of -newline convention, for example, a pattern can start with:</p> +<p>These override the default and the options given to the compiling function, but +they can themselves be overridden by options given to a matching function. Note +that these special settings, which are not Perl-compatible, are recognized only +at the very start of a pattern, and that they must be in upper case. If more +than one of them is present, the last one is used. They can be combined with a +change of newline convention; for example, a pattern can start with:</p> <p> (*ANY)(*BSR_ANYCRLF)</p> -<p>Inside a character class, \R matches the letter "R".</p> - +<p>They can also be combined with the (*UTF8), (*UTF) or +(*UCP) special sequences. Inside a character class, \R is treated as an +unrecognized escape sequence, and so matches the letter "R" by default.</p> <p><em>Unicode character properties</em></p> -<p>When PCRE is built with Unicode character property support, three additional +<p>Three additional escape sequences that match characters with specific properties are available. -When not in UTF-8 mode, these sequences are of course limited to testing +When in 8-bit non-UTF-8 mode, these sequences are of course limited to testing characters whose codepoints are less than 256, but they do work in this mode. The extra escape sequences are:</p> +<taglist> +<tag>\p{<em>xx</em>}</tag> <item>a character with the <em>xx</em> property</item> +<tag>\P{<em>xx</em>}</tag> <item>a character without the <em>xx</em> property</item> +<tag>\X</tag> <item>a Unicode extended grapheme cluster</item> +</taglist> -<p> \p{<em>xx</em>} a character with the <em>xx</em> property - \P{<em>xx</em>} a character without the <em>xx</em> property - \X an extended Unicode sequence</p> - -<p>The property names represented by <em>xx</em> above are limited to the Unicode -script names, the general category properties, and "Any", which matches any -character (including newline). Other properties such as "InMusicalSymbols" are -not currently supported by PCRE. Note that \P{Any} does not match any -characters, so always causes a match failure.</p> +<p>The property names represented by <i>xx</i> above are limited to the Unicode +script names, the general category properties, "Any", which matches any +character (including newline), and some special PCRE properties (described +in the next section). +Other Perl properties such as "InMusicalSymbols" are not currently supported by +PCRE. Note that \P{Any} does not match any characters, so always causes a +match failure.</p> <p>Sets of Unicode characters are defined as belonging to certain scripts. A character from one of these sets can be matched using a script name. For @@ -1192,13 +1445,19 @@ example:</p> <list> <item>Arabic</item> <item>Armenian</item> +<item>Avestan</item> <item>Balinese</item> +<item>Bamum</item> +<item>Batak</item> <item>Bengali</item> <item>Bopomofo</item> <item>Braille</item> <item>Buginese</item> <item>Buhid</item> <item>Canadian_Aboriginal</item> +<item>Carian</item> +<item>Chakma</item> +<item>Cham</item> <item>Cherokee</item> <item>Common</item> <item>Coptic</item> @@ -1207,6 +1466,7 @@ example:</p> <item>Cyrillic</item> <item>Deseret</item> <item>Devanagari</item> +<item>Egyptian_Hieroglyphs</item> <item>Ethiopic</item> <item>Georgian</item> <item>Glagolitic</item> @@ -1219,16 +1479,31 @@ example:</p> <item>Hanunoo</item> <item>Hebrew</item> <item>Hiragana</item> +<item>Imperial_Aramaic</item> <item>Inherited</item> +<item>Inscriptional_Pahlavi</item> +<item>Inscriptional_Parthian</item> +<item>Javanese</item> +<item>Kaithi</item> <item>Kannada</item> <item>Katakana</item> +<item>Kayah_Li</item> <item>Kharoshthi</item> <item>Khmer</item> <item>Lao</item> <item>Latin</item> +<item>Lepcha</item> <item>Limbu</item> <item>Linear_B</item> +<item>Lisu</item> +<item>Lycian</item> +<item>Lydian</item> <item>Malayalam</item> +<item>Mandaic</item> +<item>Meetei_Mayek</item> +<item>Meroitic_Cursive</item> +<item>Meroitic_Hieroglyphs</item> +<item>Miao</item> <item>Mongolian</item> <item>Myanmar</item> <item>New_Tai_Lue</item> @@ -1237,17 +1512,29 @@ example:</p> <item>Old_Italic</item> <item>Old_Persian</item> <item>Oriya</item> +<item>Old_South_Arabian</item> +<item>Old_Turkic</item> +<item>Ol_Chiki</item> <item>Osmanya</item> <item>Phags_Pa</item> <item>Phoenician</item> +<item>Rejang</item> <item>Runic</item> +<item>Samaritan</item> +<item>Saurashtra</item> +<item>Sharada</item> <item>Shavian</item> <item>Sinhala</item> +<item>Sora_Sompeng</item> +<item>Sundanese</item> <item>Syloti_Nagri</item> <item>Syriac</item> <item>Tagalog</item> <item>Tagbanwa</item> <item>Tai_Le</item> +<item>Tai_Tham</item> +<item>Tai_Viet</item> +<item>Takri</item> <item>Tamil</item> <item>Telugu</item> <item>Thaana</item> @@ -1255,13 +1542,14 @@ example:</p> <item>Tibetan</item> <item>Tifinagh</item> <item>Ugaritic</item> +<item>Vai</item> <item>Yi</item> </list> -<p>Each character has exactly one general category property, specified by a -two-letter abbreviation. For compatibility with Perl, negation can be specified -by including a circumflex between the opening brace and the property name. For -example, \p{^Lu} is the same as \P{Lu}.</p> +<p>Each character has exactly one Unicode general category property, specified by +a two-letter abbreviation. For compatibility with Perl, negation can be +specified by including a circumflex between the opening brace and the property +name. For example, \p{^Lu} is the same as \P{Lu}.</p> <p>If only one letter is specified with \p or \P, it includes all the general category properties that start with that letter. In this case, in the absence @@ -1337,13 +1625,10 @@ the Lu, Ll, or Lt property, in other words, a letter that is not classified as a modifier or "other".</p> <p>The Cs (Surrogate) property applies only to characters in the range U+D800 to -U+DFFF. Such characters are not valid in UTF-8 strings (see RFC 3629) and so -cannot be tested by PCRE, unless UTF-8 validity checking has been turned off -(see the discussion of <c>no_utf8_check</c> in the -<em>pcreapi</em> -page).</p> +U+DFFF. Such characters are not valid in Unicode strings and so +cannot be tested by PCRE. Perl does not support the Cs property</p> -<p>The long synonyms for these properties that Perl supports (such as \p{Letter}) +<p>The long synonyms for property names that Perl supports (such as \p{Letter}) are not supported by PCRE, nor is it permitted to prefix any of these properties with "Is".</p> @@ -1352,31 +1637,79 @@ Instead, this property is assumed for any code point that is not in the Unicode table.</p> <p>Specifying caseless matching does not affect these escape sequences. For -example, \p{Lu} always matches only upper case letters.</p> - -<p>The \X escape matches any number of Unicode characters that form an extended -Unicode sequence. \X is equivalent to</p> +example, \p{Lu} always matches only upper case letters. This is different from +the behaviour of current versions of Perl.</p> +<p>Matching characters by Unicode property is not fast, because PCRE has to do a +multistage table lookup in order to find a character's property. That is why +the traditional escape sequences such as \d and \w do not use Unicode +properties in PCRE by default, though you can make them do so by setting the +<c>ucp</c> option or by starting the pattern with (*UCP).</p> + +<p><em>Extended grapheme clusters</em></p> +<p>The \X escape matches any number of Unicode characters that form an "extended +grapheme cluster", and treats the sequence as an atomic group (see below). +Up to and including release 8.31, PCRE matched an earlier, simpler definition +that was equivalent to</p> <quote><p> (?>\PM\pM*)</p></quote> -<p>That is, it matches a character without the "mark" property, followed by zero -or more characters with the "mark" property, and treats the sequence as an -atomic group -(see below). -Characters with the "mark" property are typically accents that affect the -preceding character. None of them have codepoints less than 256, so in -non-UTF-8 mode \X matches any one character.</p> +<p>That is, it matched a character without the "mark" property, followed by zero +or more characters with the "mark" property. Characters with the "mark" +property are typically non-spacing accents that affect the preceding character.</p> -<p>Matching characters by Unicode property is not fast, because PCRE has to search -a structure that contains data for over fifteen thousand characters. That is -why the traditional escape sequences such as \d and \w do not use Unicode -properties in PCRE.</p> +<p>This simple definition was extended in Unicode to include more complicated +kinds of composite character by giving each character a grapheme breaking +property, and creating rules that use these properties to define the boundaries +of extended grapheme clusters. In releases of PCRE later than 8.31, \X matches +one of these clusters.</p> + +<p>\X always matches at least one character. Then it decides whether to add +additional characters according to the following rules for ending a cluster:</p> +<taglist> +<tag>1.</tag> <item>End at the end of the subject string.</item> +<tag>2.</tag> <item>Do not end between CR and LF; otherwise end after any control character.</item> +<tag>3.</tag> <item>Do not break Hangul (a Korean script) syllable sequences. Hangul characters +are of five types: L, V, T, LV, and LVT. An L character may be followed by an +L, V, LV, or LVT character; an LV or V character may be followed by a V or T +character; an LVT or T character may be follwed only by a T character.</item> +<tag>4.</tag> <item>Do not end before extending characters or spacing marks. Characters with +the "mark" property always have the "extend" grapheme breaking property.</item> +<tag>5.</tag> <item>Do not end after prepend characters.</item> +<tag>6.</tag> <item>Otherwise, end the cluster.</item> +</taglist> + +<p><em>PCRE's additional properties</em></p> + +<p>As well as the standard Unicode properties described above, PCRE supports four +more that make it possible to convert traditional escape sequences such as \w +and \s and POSIX character classes to use Unicode properties. PCRE uses these +non-standard, non-Perl properties internally when PCRE_UCP is set. However, +they may also be used explicitly. These properties are:</p> +<taglist> + <tag>Xan</tag> <item>Any alphanumeric character</item> + <tag>Xps</tag> <item>Any POSIX space character</item> + <tag>Xsp</tag> <item>Any Perl space character</item> + <tag>Xwd</tag> <item>Any Perl "word" character</item> +</taglist> +<p>Xan matches characters that have either the L (letter) or the N (number) +property. Xps matches the characters tab, linefeed, vertical tab, form feed, or +carriage return, and any other character that has the Z (separator) property. +Xsp is the same as Xps, except that vertical tab is excluded. Xwd matches the +same characters as Xan, plus underscore.</p> + +<p>There is another non-standard property, Xuc, which matches any character that +can be represented by a Universal Character Name in C++ and other programming +languages. These are the characters $, @, ` (grave accent), and all characters +with Unicode code points greater than or equal to U+00A0, except for the +surrogates U+D800 to U+DFFF. Note that most base (ASCII) characters are +excluded. (Universal Character Names are of the form \uHHHH or \UHHHHHHHH +where H is a hexadecimal digit. Note that the Xuc property does not match these +sequences but the characters that they represent.)</p> <p><em>Resetting the match start</em></p> -<p>The escape sequence \K, which is a Perl 5.10 feature, causes any previously -matched characters not to be included in the final matched sequence. For -example, the pattern:</p> +<p>The escape sequence \K causes any previously matched characters not to be +included in the final matched sequence. For example, the pattern:</p> <quote><p> foo\Kbar</p></quote> @@ -1396,6 +1729,10 @@ For example, when the pattern</p> <p>matches "foobar", the first substring is still set to "foo".</p> +<p>Perl documents that the use of \K within assertions is "not well defined". In +PCRE, \K is acted upon when it occurs inside positive assertions, but is +ignored in negative assertions.</p> + <p><em>Simple assertions</em></p> <p>The final use of backslash is for certain simple assertions. An @@ -1416,13 +1753,20 @@ described below. The backslashed assertions are:</p> subject</item> </taglist> -<p>These assertions may not appear in character classes (but note that \b has a -different meaning, namely the backspace character, inside a character class).</p> +<p>Inside a character class, \b has a different meaning; it matches the backspace +character. If any other of these assertions appears in a character class, by +default it matches the corresponding literal character (for example, \B +matches the letter B). </p> <p>A word boundary is a position in the subject string where the current character and the previous character do not both match \w or \W (i.e. one matches \w and the other matches \W), or the start or end of the string if the -first or last character matches \w, respectively.</p> +first or last character matches \w, respectively. In a UTF mode, the meanings +of \w and \W can be changed by setting the <c>ucp</c> option. When this is +done, it also affects \b and \B. Neither PCRE nor Perl has a separate "start +of word" or "end of word" metasequence. However, whatever follows \b normally +determines which it is. For example, the fragment \ba matches "a" at the start +of a word.</p> <p>The \A, \Z, and \z assertions differ from the traditional circumflex and dollar (described in the next section) in that they only ever match at the very @@ -1456,9 +1800,13 @@ regular expression.</p> <section><marker id="sect4"></marker><title>Circumflex and dollar</title> +<p>The circumflex and dollar metacharacters are zero-width assertions. That is, +they test for a particular condition being true without consuming any +characters from the subject string.</p> + <p>Outside a character class, in the default matching mode, the circumflex -character is an assertion that is true only if the current matching point is -at the start of the subject string. If the <em>startoffset</em> argument of +character is an assertion that is true only if the current matching point is at +the start of the subject string. If the <i>startoffset</i> argument of <c>re:run/3</c> is non-zero, circumflex can never match if the <c>multiline</c> option is unset. Inside a character class, circumflex has an entirely different meaning (see below).</p> @@ -1471,12 +1819,12 @@ constrained to match only at the start of the subject, it is said to be an "anchored" pattern. (There are also other constructs that can cause a pattern to be anchored.)</p> -<p>A dollar character is an assertion that is true only if the current matching -point is at the end of the subject string, or immediately before a newline -at the end of the string (by default). Dollar need not be the last character of -the pattern if a number of alternatives are involved, but it should be the last -item in any branch in which it appears. Dollar has no special meaning in a -character class.</p> +<p>The dollar character is an assertion that is true only if the current matching +point is at the end of the subject string, or immediately before a newline at +the end of the string (by default). Note, however, that it does not actually +match the newline. Dollar need not be the last character of the pattern if a +number of alternatives are involved, but it should be the last item in any +branch in which it appears. Dollar has no special meaning in a character class.</p> <p>The meaning of dollar can be changed so that it matches only at the very end of the string, by setting the <c>dollar_endonly</c> option at @@ -1505,12 +1853,11 @@ end of the subject in both modes, and if all branches of a pattern start with </section> -<section><marker id="sect5"></marker><title>Full stop (period, dot)</title> +<section><marker id="sect5"></marker><title>Full stop (period, dot) and \N</title> <p>Outside a character class, a dot in the pattern matches any one character in the subject string except (by default) a character that signifies the end of a line. - In UTF-8 mode, the matched character may be more than one byte long. </p> <p>When a line ending is defined as a single character, dot never matches that @@ -1531,111 +1878,138 @@ the subject string, it takes two dots to match it.</p> circumflex and dollar, the only relationship being that they both involve newlines. Dot has no special meaning in a character class.</p> +<p>The escape sequence \N behaves like a dot, except that it is not affected by +the PCRE_DOTALL option. In other words, it matches any character except one +that signifies the end of a line. Perl also uses \N to match characters by +name; PCRE does not support this.</p> + </section> -<section><marker id="sect6"></marker><title>Matching a single byte</title> +<section><marker id="sect6"></marker><title>Matching a single data unit</title> -<p>Outside a character class, the escape sequence \C matches any one byte, both -in and out of UTF-8 mode. Unlike a dot, it always matches any line-ending -characters. The feature is provided in Perl in order to match individual bytes -in UTF-8 mode. Because it breaks up UTF-8 characters into individual bytes, -what remains in the string may be a malformed UTF-8 string. For this reason, -the \C escape sequence is best avoided.</p> +<p>Outside a character class, the escape sequence \C matches any one data unit, +whether or not a UTF mode is set. One data unit is one +byte. Unlike a dot, \C always +matches line-ending characters. The feature is provided in Perl in order to +match individual bytes in UTF-8 mode, but it is unclear how it can usefully be +used. Because \C breaks up characters into individual data units, matching one +unit with \C in a UTF mode means that the rest of the string may start with a +malformed UTF character. This has undefined results, because PCRE assumes that +it is dealing with valid UTF strings.</p> -<p>PCRE does not allow \C to appear in lookbehind assertions (described below), -because in UTF-8 mode this would make it impossible to calculate the length of +<p>PCRE does not allow \C to appear in lookbehind assertions (described below) +in a UTF mode, because this would make it impossible to calculate the length of the lookbehind.</p> +<p>In general, the \C escape sequence is best avoided. However, one +way of using it that avoids the problem of malformed UTF characters is to use a +lookahead to check the length of the next character, as in this pattern, which +could be used with a UTF-8 string (ignore white space and line breaks):</p> + +<code type="none"> + (?| (?=[\x00-\x7f])(\C) | + (?=[\x80-\x{7ff}])(\C)(\C) | + (?=[\x{800}-\x{ffff}])(\C)(\C)(\C) | + (?=[\x{10000}-\x{1fffff}])(\C)(\C)(\C)(\C))</code> + +<p>A group that starts with (?| resets the capturing parentheses numbers in each +alternative (see "Duplicate Subpattern Numbers" +below). The assertions at the start of each branch check the next UTF-8 +character for values whose encoding uses 1, 2, 3, or 4 bytes, respectively. The +character's individual bytes are then captured by the appropriate number of +groups.</p> + </section> <section><marker id="sect7"></marker><title>Square brackets and character classes</title> -<p>An opening square bracket introduces a character class, terminated -by a closing square bracket. A closing square bracket on its own is -not special. If a closing square bracket is required as a member of -the class, it should be the first data character in the class (after -an initial circumflex, if present) or escaped with a backslash.</p> - -<p>A character class matches a single character in the subject. -In -UTF-8 mode, the character may occupy more than one byte. -A matched -character must be in the set of characters defined by the class, -unless the first character in the class definition is a circumflex, in -which case the subject character must not be in the set defined by the -class. If a circumflex is actually required as a member of the class, -ensure it is not the first character, or escape it with a +<p>An opening square bracket introduces a character class, terminated by a closing +square bracket. A closing square bracket on its own is not special by default. +However, if the PCRE_JAVASCRIPT_COMPAT option is set, a lone closing square +bracket causes a compile-time error. If a closing square bracket is required as +a member of the class, it should be the first data character in the class +(after an initial circumflex, if present) or escaped with a backslash.</p> + +<p>A character class matches a single character in the subject. In a UTF mode, the +character may be more than one data unit long. A matched character must be in +the set of characters defined by the class, unless the first character in the +class definition is a circumflex, in which case the subject character must not +be in the set defined by the class. If a circumflex is actually required as a +member of the class, ensure it is not the first character, or escape it with a backslash.</p> <p>For example, the character class [aeiou] matches any lower case vowel, while [^aeiou] matches any character that is not a lower case vowel. Note that a circumflex is just a convenient notation for specifying the characters that are in the class by enumerating those that are not. A class that starts with a -circumflex is not an assertion: it still consumes a character from the subject +circumflex is not an assertion; it still consumes a character from the subject string, and therefore it fails if the current pointer is at the end of the string.</p> -<p>In UTF-8 mode, characters with values greater than 255 can be included in a -class as a literal string of bytes, or by using the \x{ escaping mechanism.</p> +<p>In UTF-8 mode, characters with values greater than 255 (0xffff) +can be included in a class as a literal string of data units, or by using the +\x{ escaping mechanism.</p> <p>When caseless matching is set, any letters in a class represent both their upper case and lower case versions, so for example, a caseless [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not match "A", whereas a -caseful version would. -In UTF-8 mode, PCRE always understands the concept of +caseful version would. In a UTF mode, PCRE always understands the concept of case for characters whose values are less than 128, so caseless matching is always possible. For characters with higher values, the concept of case is supported if PCRE is compiled with Unicode property support, but not otherwise. -If you want to use caseless matching for characters 128 and above, you must -ensure that PCRE is compiled with Unicode property support as well as with -UTF-8 support. -</p> - -<p>Characters that might indicate line breaks are never treated in any -special way when matching character classes, whatever line-ending -sequence is in use, and whatever setting of the <c>dotall</c> and -<c>multiline</c> options is used. A class such as [^a] always matches -one of these characters.</p> - -<p>The minus (hyphen) character can be used to specify a range of -characters in a character class. For example, [d-m] matches any letter -between d and m, inclusive. If a minus character is required in a -class, it must be escaped with a backslash or appear in a position -where it cannot be interpreted as indicating a range, typically as the -first or last character in the class.</p> - -<p>It is not possible to have the literal character "]" as the end -character of a range. A pattern such as [W-]46] is interpreted as a -class of two characters ("W" and "-") followed by a literal string -"46]", so it would match "W46]" or "-46]". However, if the "]" is -escaped with a backslash it is interpreted as the end of range, so -[W-\]46] is interpreted as a class containing a range followed by two -other characters. The octal or hexadecimal representation of "]" can -also be used to end a range.</p> +If you want to use caseless matching in a UTF mode for characters 128 and +above, you must ensure that PCRE is compiled with Unicode property support as +well as with UTF support.</p> + +<p>Characters that might indicate line breaks are never treated in any special way +when matching character classes, whatever line-ending sequence is in use, and +whatever setting of the PCRE_DOTALL and PCRE_MULTILINE options is used. A class +such as [^a] always matches one of these characters.</p> + +<p>The minus (hyphen) character can be used to specify a range of characters in a +character class. For example, [d-m] matches any letter between d and m, +inclusive. If a minus character is required in a class, it must be escaped with +a backslash or appear in a position where it cannot be interpreted as +indicating a range, typically as the first or last character in the class.</p> + +<p>It is not possible to have the literal character "]" as the end character of a +range. A pattern such as [W-]46] is interpreted as a class of two characters +("W" and "-") followed by a literal string "46]", so it would match "W46]" or +"-46]". However, if the "]" is escaped with a backslash it is interpreted as +the end of range, so [W-\]46] is interpreted as a class containing a range +followed by two other characters. The octal or hexadecimal representation of +"]" can also be used to end a range.</p> <p>Ranges operate in the collating sequence of character values. They can also be -used for characters specified numerically, for example [\000-\037]. -In UTF-8 -mode, ranges can include characters whose values are greater than 255, for -example [\x{100}-\x{2ff}]. -</p> +used for characters specified numerically, for example [\000-\037]. Ranges +can include any characters that are valid for the current mode.</p> <p>If a range that includes letters is used when caseless matching is set, it matches the letters in either case. For example, [W-c] is equivalent to -[][\\^_`wxyzabc], matched caselessly -, and in non-UTF-8 mode, if character +[][\\^_`wxyzabc], matched caselessly, and in a non-UTF mode, if character tables for a French locale are in use, [\xc8-\xcb] matches accented E -characters in both cases. In UTF-8 mode, PCRE supports the concept of case for +characters in both cases. In UTF modes, PCRE supports the concept of case for characters with values greater than 128 only when it is compiled with Unicode property support.</p> -<p>The character types \d, \D, \p, \P, \s, \S, \w, and \W may -also appear in a character class, and add the characters that they -match to the class. For example, [\dABCDEF] matches any hexadecimal -digit. A circumflex can conveniently be used with the upper case -character types to specify a more restricted set of characters than -the matching lower case type. For example, the class [^\W_] matches -any letter or digit, but not underscore.</p> +<p>The character escape sequences \d, \D, \h, \H, \p, \P, \s, \S, \v, +\V, \w, and \W may appear in a character class, and add the characters that +they match to the class. For example, [\dABCDEF] matches any hexadecimal +digit. In UTF modes, the <c>ucp</c> option affects the meanings of \d, \s, \w +and their upper case partners, just as it does when they appear outside a +character class, as described in the section entitled +"Generic character types" +above. The escape sequence \b has a different meaning inside a character +class; it matches the backspace character. The sequences \B, \N, \R, and \X +are not special inside a character class. Like any other unrecognized escape +sequences, they are treated as the literal characters "B", "N", "R", and "X".</p> + +<p>A circumflex can conveniently be used with the upper case character types to +specify a more restricted set of characters than the matching lower case type. +For example, the class [^\W_] matches any letter or digit, but not underscore, +whereas [\w] includes underscore. A positive character class should be read as +"something OR something OR ..." and a negative class as "NOT something AND NOT +something AND NOT ...".</p> <p>The only metacharacters that are recognized in character classes are backslash, hyphen (only where it can be interpreted as specifying @@ -1645,7 +2019,6 @@ next section), and the terminating closing square bracket. However, escaping other non-alphanumeric characters does no harm.</p> </section> - <section><marker id="sect8"></marker><title>POSIX character classes</title> <p>Perl supports the POSIX notation for character classes. This uses names @@ -1655,7 +2028,7 @@ this notation. For example,</p> <quote><p> [01[:alpha:]%]</p></quote> <p>matches "0", "1", any alphabetic character, or "%". The supported class names -are</p> +are:</p> <taglist> <tag>alnum</tag> <item>letters and digits</item> @@ -1667,7 +2040,7 @@ are</p> <tag>graph</tag> <item>printing characters, excluding space</item> <tag>lower</tag> <item>lower case letters</item> <tag>print</tag> <item>printing characters, including space</item> - <tag>punct</tag> <item>printing characters, excluding letters and digits</item> + <tag>punct</tag> <item>printing characters, excluding letters and digits and space</item> <tag>space</tag> <item>whitespace (not quite the same as \s)</item> <tag>upper</tag> <item>upper case letters</item> <tag>word</tag> <item>"word" characters (same as \w)</item> @@ -1689,8 +2062,26 @@ by a ^ character after the colon. For example,</p> syntax [.ch.] and [=ch=] where "ch" is a "collating element", but these are not supported, and an error is given if they are encountered.</p> -<p>In UTF-8 mode, characters with values greater than 128 do not match any of -the POSIX character classes.</p> +<p>By default, in UTF modes, characters with values greater than 128 do not match +any of the POSIX character classes. However, if the PCRE_UCP option is passed +to <b>pcre_compile()</b>, some of the classes are changed so that Unicode +character properties are used. This is achieved by replacing the POSIX classes +by other sequences, as follows:</p> + +<taglist> + <tag>[:alnum:]</tag> <item>becomes <em>\p{Xan}</em></item> + <tag>[:alpha:]</tag> <item>becomes <em>\p{L}</em></item> + <tag>[:blank:]</tag> <item>becomes <em>\h</em></item> + <tag>[:digit:</tag>] <item>becomes <em>\p{Nd}</em></item> + <tag>[:lower:]</tag> <item>becomes <em>\p{Ll}</em></item> + <tag>[:space:]</tag> <item>becomes <em>\p{Xps}</em></item> + <tag>[:upper:</tag>] <item>becomes <em>\p{Lu}</em></item> + <tag>[:word:]</tag> <item>becomes <em>\p{Xwd}</em></item> +</taglist> + +<p>Negated versions, such as [:^alpha:] use \P instead of \p. The other POSIX +classes are unchanged, and match only characters with code points less than +128.</p> </section> @@ -1737,19 +2128,13 @@ unset.</p> <c>extra</c> can be changed in the same way as the Perl-compatible options by using the characters J, U and X respectively.</p> -<p>When an option change occurs at top level (that is, not inside subpattern -parentheses), the change applies to the remainder of the pattern that follows. -If the change is placed right at the start of a pattern, PCRE extracts it into -the global options -<!-- XXX C Interface -(and it will therefore show up in data extracted by the -<c>pcre_fullinfo()</c> function). ---> -</p> +<p>When one of these option changes occurs at top level (that is, not inside +subpattern parentheses), the change applies to the remainder of the pattern +that follows. If the change is placed right at the start of a pattern, PCRE +extracts it into the global options.</p> -<p>An option change within a subpattern (see below for a description -of subpatterns) affects only that part of the current pattern that -follows it, so</p> +<p>An option change within a subpattern (see below for a description of +subpatterns) affects only that part of the subpattern that follows it, so</p> <quote><p> (a(?i)b)c</p></quote> @@ -1767,11 +2152,16 @@ option settings happen at compile time. There would be some very weird behaviour otherwise.</p> <p><em>Note:</em> There are other PCRE-specific options that can be set by the -application when the compile or match functions are called. In some cases the -pattern can contain special leading sequences to override what the application -has set or what has been defaulted. Details are given in the section entitled -"Newline sequences" above.</p> - +application when the compiling or matching functions are called. In some cases +the pattern can contain special leading sequences such as (*CRLF) to override +what the application has set or what has been defaulted. Details are given in +the section entitled "Newline sequences" +above. There are also the (*UTF8) and (*UCP) leading +sequences that can be used to set UTF and Unicode property modes; they are +equivalent to setting the <c>unicode</c> and the <c>ucp</c> +options, respectively. The (*UTF) sequence is a generic version that can be +used with any of the libraries. However, the application can set the +<c>never_utf</c> option, which locks out the use of the (*UTF) sequences.</p> </section> @@ -1785,16 +2175,17 @@ things:</p> <quote><p> cat(aract|erpillar|)</p></quote> -<p>matches one of the words "cat", "cataract", or "caterpillar". Without the -parentheses, it would match "cataract", "erpillar" or an empty string.</p> +<p>matches "cataract", "caterpillar", or "cat". Without the parentheses, it would +match "cataract", "erpillar" or an empty string.</p> <p>2. It sets up the subpattern as a capturing subpattern. This means that, when the complete pattern matches, that portion of the subject string that matched the subpattern is passed back to the caller via the return value of -<c>re:run/3</c>. Opening parentheses are counted from left to right (starting -from 1) to obtain numbers for the capturing subpatterns.</p> - -<p>For example, if the string "the red king" is matched against the pattern</p> +<c>re:run/3</c>.</p> + +<p>Opening parentheses are counted from left to right (starting +from 1) to obtain numbers for the capturing subpatterns.For example, if the string +"the red king" is matched against the pattern</p> <quote><p> the ((red|white) (king|queen))</p></quote> @@ -1827,7 +2218,6 @@ from left to right, and options are not reset until the end of the subpattern is reached, an option setting in one branch does affect subsequent branches, so the above patterns match "SUNDAY" as well as "Saturday".</p> - </section> <section><marker id="sect12"></marker><title>Duplicate subpattern numbers</title> @@ -1845,18 +2235,30 @@ at captured substring number one, whichever alternative matched. This construct is useful when you want to capture part, but not all, of one of a number of alternatives. Inside a (?| group, parentheses are numbered as usual, but the number is reset at the start of each branch. The numbers of any capturing -buffers that follow the subpattern start after the highest number used in any -branch. The following example is taken from the Perl documentation. -The numbers underneath show in which buffer the captured content will be -stored.</p> +parentheses that follow the subpattern start after the highest number used in +any branch. The following example is taken from the Perl documentation. The +numbers underneath show in which buffer the captured content will be stored.</p> <code type="none"> # before ---------------branch-reset----------- after / ( a ) (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x # 1 2 2 3 2 3 4</code> -<p>A backreference or a recursive call to a numbered subpattern always -refers to the first one in the pattern with the given number.</p> +<p>A back reference to a numbered subpattern uses the most recent value that is +set for that number by any subpattern. The following pattern matches "abcabc" +or "defdef":</p> + +<quote><p> /(?|(abc)|(def))\1/</p></quote> + +<p>In contrast, a subroutine call to a numbered subpattern always refers to the +first one in the pattern with the given number. The following pattern matches +"abcabc" or "defabc":</p> + +<quote><p> /(?|(abc)|(def))(?1)/</p></quote> + +<p>If a condition test +for a subpattern's having matched refers to a non-unique number, the test is +true if any of the subpatterns of that number have matched.</p> <p>An alternative approach to using this "branch reset" feature is to use duplicate named subpatterns, as described in the next section.</p> @@ -1871,12 +2273,13 @@ if an expression is modified, the numbers may change. To help with this difficulty, PCRE supports the naming of subpatterns. This feature was not added to Perl until release 5.10. Python had the feature earlier, and PCRE introduced it at release 4.0, using the Python syntax. PCRE now supports both -the Perl and the Python syntax.</p> +the Perl and the Python syntax. Perl allows identically numbered subpatterns to +have different names, but PCRE does not.</p> <p>In PCRE, a subpattern can be named in one of three ways: (?<name>...) or (?'name'...) as in Perl, or (?P<name>...) as in Python. References to capturing parentheses from other parts of -the pattern, such as backreferences, recursion, and conditions, can be +the pattern, such as back references, recursion, and conditions, can be made by name as well as by number.</p> <p>Names consist of up to 32 alphanumeric characters and underscores. Named @@ -1891,11 +2294,13 @@ The <c>capture</c> specification to <c>re:run/3</c> can use named values if they </p> <p>By default, a name must be unique within a pattern, but it is possible to relax -this constraint by setting the <c>dupnames</c> option at compile time. This can -be useful for patterns where only one instance of the named parentheses can -match. Suppose you want to match the name of a weekday, either as a 3-letter -abbreviation or as the full name, and in both cases you want to extract the -abbreviation. This pattern (ignoring the line breaks) does the job:</p> +this constraint by setting the <c>dupnames</c> option at compile time. (Duplicate +names are also always permitted for subpatterns with the same number, set up as +described in the previous section.) Duplicate names can be useful for patterns +where only one instance of the named parentheses can match. Suppose you want to +match the name of a weekday, either as a 3-letter abbreviation or as the full +name, and in both cases you want to extract the abbreviation. This pattern +(ignoring the line breaks) does the job:</p> <code type="none"> (?<DN>Mon|Fri|Sun)(?:day)?| @@ -1921,7 +2326,13 @@ details of the interfaces for handling named subpatterns, see the documentation.</p> --> -<p>In case of capturing named subpatterns which are not unique, the first occurrence is returned from <c>re:exec/3</c>, if the name is specified int the <c>values</c> part of the <c>capture</c> statement.</p> +<p>In case of capturing named subpatterns which names are not unique, the first matching occurrence (counted from left to right in the subject) is returned from <c>re:exec/3</c>, if the name is specified in the <c>values</c> part of the <c>capture</c> statement. The <c>all_names</c> capturing value will match all of the names in the same way.</p> + +<p><em>Warning:</em> You cannot use different names to distinguish between two +subpatterns with the same number because PCRE uses only the numbers when +matching. For this reason, an error is given at compile time if different names +are given to subpatterns with the same number. However, you can give the same +name to subpatterns with the same number, even when <c>dupnames</c> is not set.</p> </section> @@ -1934,14 +2345,13 @@ following items:</p> <item>a literal data character</item> <item>the dot metacharacter</item> <item>the \C escape sequence</item> - <item>the \X escape sequence -(in UTF-8 mode with Unicode properties) - </item> + <item>the \X escape sequence</item> <item>the \R escape sequence</item> - <item>an escape such as \d that matches a single character</item> + <item>an escape such as \d or \pL that matches a single character</item> <item>a character class</item> <item>a back reference (see next section)</item> - <item>a parenthesized subpattern (unless it is an assertion)</item> + <item>a parenthesized subpattern (including assertions)</item> + <item>a subroutine call to a subpattern (recursive or otherwise)</item> </list> <p>The general repetition quantifier specifies a minimum and maximum number of @@ -1967,14 +2377,18 @@ where a quantifier is not allowed, or one that does not match the syntax of a quantifier, is taken as a literal character. For example, {,6} is not a quantifier, but a literal string of four characters.</p> -<p>In UTF-8 mode, quantifiers apply to UTF-8 characters rather than to individual -bytes. Thus, for example, \x{100}{2} matches two UTF-8 characters, each of -which is represented by a two-byte sequence. Similarly, when Unicode property -support is available, \X{3} matches three Unicode extended sequences, each of -which may be several bytes long (and they may be of different lengths).</p> - +<p>In Unicode mode, quantifiers apply to characters rather than to individual data +units. Thus, for example, \x{100}{2} matches two characters, each of +which is represented by a two-byte sequence in a UTF-8 string. Similarly, +\X{3} matches three Unicode extended grapheme clusters, each of which may be +several data units long (and they may be of different lengths).</p> <p>The quantifier {0} is permitted, causing the expression to behave as if the -previous item and the quantifier were not present.</p> +previous item and the quantifier were not present. This may be useful for +subpatterns that are referenced as subroutines +from elsewhere in the pattern (but see also the section entitled +"Defining subpatterns for use by reference only" +below). Items other than subpatterns that have a {0} quantifier are omitted +from the compiled pattern.</p> <p>For convenience, the three most common quantifiers have single-character abbreviations:</p> @@ -2048,8 +2462,8 @@ pattern as though it were preceded by \A.</p> worth setting <c>dotall</c> in order to obtain this optimization, or alternatively using ^ to indicate anchoring explicitly.</p> -<p>However, there is one situation where the optimization cannot be used. When .* -is inside capturing parentheses that are the subject of a backreference +<p>However, there are some cases where the optimization cannot be used. When .* +is inside capturing parentheses that are the subject of a back reference elsewhere in the pattern, a match at the start may fail where a later one succeeds. Consider, for example:</p> @@ -2058,6 +2472,15 @@ succeeds. Consider, for example:</p> <p>If the subject is "xyz123abc123" the match point is the fourth character. For this reason, such a pattern is not implicitly anchored.</p> +<p>Another case where implicit anchoring is not applied is when the leading .* is +inside an atomic group. Once again, a match at the start may fail where a later +one succeeds. Consider this pattern:</p> + +<quote><p> (?>.*?a)b</p></quote> + +<p>It matches "ab" in the subject "aab". The use of the backtracking control verbs +(*PRUNE) and (*SKIP) also disable this optimization.</p> + <p>When a capturing subpattern is repeated, the value captured is the substring that matched the final iteration. For example, after</p> @@ -2196,11 +2619,10 @@ further details of the handling of digits following a backslash. There is no such problem when named parentheses are used. A back reference to any subpattern is possible using named parentheses (see below).</p> -<p>Another way of avoiding the ambiguity inherent in the use of digits -following a backslash is to use the \g escape sequence, which is a -feature introduced in Perl 5.10. This escape must be followed by an -unsigned number or a negative number, optionally enclosed in -braces. These examples are all identical:</p> +<p>Another way of avoiding the ambiguity inherent in the use of digits following a +backslash is to use the \g escape sequence. This escape must be followed by an +unsigned number or a negative number, optionally enclosed in braces. These +examples are all identical:</p> <list> <item>(ring), \1</item> @@ -2216,10 +2638,10 @@ reference. Consider this example:</p> <quote><p> (abc(def)ghi)\g{-1}</p></quote> <p>The sequence \g{-1} is a reference to the most recently started capturing -subpattern before \g, that is, is it equivalent to \2. Similarly, \g{-2} -would be equivalent to \1. The use of relative references can be helpful in -long patterns, and also in patterns that are created by joining together -fragments that contain references within themselves.</p> +subpattern before \g, that is, is it equivalent to \2 in this example. +Similarly, \g{-2} would be equivalent to \1. The use of relative references +can be helpful in long patterns, and also in patterns that are created by +joining together fragments that contain references within themselves.</p> <p>A back reference matches whatever actually matched the capturing subpattern in the current subject string, rather than anything @@ -2268,6 +2690,8 @@ some delimiter must be used to terminate the back reference. If the <c>extended</c> option is set, this can be whitespace. Otherwise an empty comment (see "Comments" below) can be used.</p> +<p><em>Recursive back references</em></p> + <p>A back reference that occurs inside the parentheses to which it refers fails when the subpattern is first used, so, for example, (a\1) never matches. However, such references can be useful inside repeated subpatterns. For @@ -2282,6 +2706,11 @@ that the first iteration does not need to match the back reference. This can be done using alternation, as in the example above, or by a quantifier with a minimum of zero.</p> +<p>Back references of this type cause the group that they reference to be treated +as an atomic group. +Once the whole group has been matched, a subsequent matching failure cannot +cause backtracking into the middle of the group.</p> + </section> <section><marker id="sect17"></marker><title>Assertions</title> @@ -2297,12 +2726,27 @@ those that look ahead of the current position in the subject string, and those that look behind it. An assertion subpattern is matched in the normal way, except that it does not cause the current matching position to be changed.</p> -<p>Assertion subpatterns are not capturing subpatterns, and may not be repeated, -because it makes no sense to assert the same thing several times. If any kind -of assertion contains capturing subpatterns within it, these are counted for -the purposes of numbering the capturing subpatterns in the whole pattern. -However, substring capturing is carried out only for positive assertions, -because it does not make sense for negative assertions.</p> +<p>Assertion subpatterns are not capturing subpatterns. If such an assertion +contains capturing subpatterns within it, these are counted for the purposes of +numbering the capturing subpatterns in the whole pattern. However, substring +capturing is carried out only for positive assertions. (Perl sometimes, but not +always, does do capturing in negative assertions.)</p> + +<p>For compatibility with Perl, assertion subpatterns may be repeated; though +it makes no sense to assert the same thing several times, the side effect of +capturing parentheses may occasionally be useful. In practice, there only three +cases:</p> + +<taglist> +<tag>(1)</tag> <item>If the quantifier is {0}, the assertion is never obeyed during matching. +However, it may contain internal capturing parenthesized groups that are called +from elsewhere via the subroutine mechanism.</item> +<tag>(2)</tag> <item>If quantifier is {0,n} where n is greater than zero, it is treated as if it +were {0,1}. At run time, the rest of the pattern match is tried with and +without the assertion, the order depending on the greediness of the quantifier.</item> +<tag>(3)</tag> <item>If the minimum repetition is greater than zero, the quantifier is ignored. +The assertion is obeyed just once when encountered during matching.</item> +</taglist> <p><em>Lookahead assertions</em></p> @@ -2328,7 +2772,8 @@ lookbehind assertion is needed to achieve the other effect.</p> <p>If you want to force a matching failure at some point in a pattern, the most convenient way to do it is with (?!) because an empty string always matches, so -an assertion that requires there not to be an empty string must always fail.</p> +an assertion that requires there not to be an empty string must always fail. +The backtracking control verb (*FAIL) or (*F) is a synonym for (?!).</p> <p><em>Lookbehind assertions</em></p> @@ -2351,33 +2796,38 @@ do not all have to have the same fixed length. Thus</p> <p>causes an error at compile time. Branches that match different length strings are permitted only at the top level of a lookbehind assertion. This is an -extension compared with Perl (at least for 5.8), which requires all branches to +extension compared with Perl, which requires all branches to match the same length of string. An assertion such as</p> <quote><p> (?<=ab(c|de))</p></quote> <p>is not permitted, because its single top-level branch can match two different -lengths, but it is acceptable if rewritten to use two top-level branches:</p> +lengths, but it is acceptable to PCRE if rewritten to use two top-level +branches:</p> <quote><p> (?<=abc|abde)</p></quote> -<p>In some cases, the Perl 5.10 escape sequence \K (see above) can be -used instead of a lookbehind assertion; this is not restricted to a -fixed-length.</p> +<p>In some cases, the escape sequence \K (see above) can be +used instead of a lookbehind assertion to get round the fixed-length +restriction.</p> <p>The implementation of lookbehind assertions is, for each alternative, to temporarily move the current position back by the fixed length and then try to match. If there are insufficient characters before the current position, the assertion fails.</p> -<p>PCRE does not allow the \C escape (which matches a single byte in UTF-8 mode) -to appear in lookbehind assertions, because it makes it impossible to calculate -the length of the lookbehind. The \X and \R escapes, which can match -different numbers of bytes, are also not permitted.</p> +<p>In a UTF mode, PCRE does not allow the \C escape (which matches a single data +unit even in a UTF mode) to appear in lookbehind assertions, because it makes +it impossible to calculate the length of the lookbehind. The \X and \R +escapes, which can match different numbers of data units, are also not +permitted.</p> +<p>"Subroutine" calls (see below) such as (?2) or (?&X) are permitted in lookbehinds, as long +as the subpattern matches a fixed-length string. Recursion, +however, is not supported.</p> <p>Possessive quantifiers can be used in conjunction with lookbehind assertions to -specify efficient matching at the end of the subject string. Consider a simple -pattern such as</p> +specify efficient matching of fixed-length strings at the end of subject +strings. Consider a simple pattern such as</p> <quote><p> abcd$</p></quote> @@ -2440,8 +2890,8 @@ characters that are not "999".</p> <p>It is possible to cause the matching process to obey a subpattern conditionally or to choose between two alternative subpatterns, depending on -the result of an assertion, or whether a previous capturing subpattern matched -or not. The two possible forms of conditional subpattern are</p> +the result of an assertion, or whether a specific capturing subpattern has +already been matched. The two possible forms of conditional subpattern are:</p> <list> <item>(?(condition)yes-pattern)</item> @@ -2450,7 +2900,13 @@ or not. The two possible forms of conditional subpattern are</p> <p>If the condition is satisfied, the yes-pattern is used; otherwise the no-pattern (if present) is used. If there are more than two alternatives in the -subpattern, a compile-time error occurs.</p> +subpattern, a compile-time error occurs. Each of the two alternatives may +itself contain nested subpatterns of any form, including conditional +subpatterns; the restriction to two alternatives applies only at the level of +the condition. This pattern fragment is an example where the alternatives are +complex:</p> + +<quote><p> (?(1) (A|B|C) | (D | (?(2)E|F) | E) )</p></quote> <p>There are four kinds of condition: references to subpatterns, references to recursion, a pseudo-condition called DEFINE, and assertions.</p> @@ -2459,13 +2915,16 @@ recursion, a pseudo-condition called DEFINE, and assertions.</p> <p><em>Checking for a used subpattern by number</em></p> <p>If the text between the parentheses consists of a sequence of -digits, the condition is true if the capturing subpattern of that -number has previously matched. An alternative notation is to precede -the digits with a plus or minus sign. In this case, the subpattern -number is relative rather than absolute. The most recently opened -parentheses can be referenced by (?(-1), the next most recent by -(?(-2), and so on. In looping constructs it can also make sense to -refer to subsequent groups with constructs such as (?(+2).</p> +digits, the condition is true if a capturing subpattern of that number has previously +matched. If there is more than one capturing subpattern with the same number +(see the earlier section about duplicate subpattern numbers), +the condition is true if any of them have matched. An alternative notation is +to precede the digits with a plus or minus sign. In this case, the subpattern +number is relative rather than absolute. The most recently opened parentheses +can be referenced by (?(-1), the next most recent by (?(-2), and so on. Inside +loops it can also make sense to refer to subsequent groups. The next +parentheses to be opened can be referenced as (?(+1), and so on. (The value +zero in any of these forms is not used; it provokes a compile-time error.)</p> <p>Consider the following pattern, which contains non-significant whitespace to make it more readable (assume the <c>extended</c> @@ -2476,7 +2935,7 @@ option) and to divide it into three parts for ease of discussion:</p> <p>The first part matches an optional opening parenthesis, and if that character is present, sets it as the first captured substring. The second part matches one or more characters that are not parentheses. The third part is a -conditional subpattern that tests whether the first set of parentheses matched +conditional subpattern that tests whether or not the first set of parentheses matched or not. If they did, that is, if subject started with an opening parenthesis, the condition is true, and so the yes-pattern is executed and a closing parenthesis is required. Otherwise, since no-pattern is not present, the @@ -2506,6 +2965,10 @@ consist entirely of digits is not recommended.</p> <quote><p> (?<OPEN> \( )? [^()]+ (?(<OPEN>) \) )</p></quote> +<p>If the name used in a condition of this kind is a duplicate, the test is +applied to all subpatterns of the same name, and is true if any one of them has +matched.</p> + <p><em>Checking for pattern recursion</em></p> <p>If the condition is the string (R), and there is no subpattern with @@ -2515,12 +2978,14 @@ by ampersand follow the letter R, for example:</p> <quote><p> (?(R3)...) or (?(R&name)...)</p></quote> -<p>the condition is true if the most recent recursion is into the +<p>the condition is true if the most recent recursion is into a subpattern whose number or name is given. This condition does not -check the entire recursion stack.</p> +check the entire recursion stack. If the name used in a condition of this kind is a duplicate, the test is +applied to all subpatterns of the same name, and is true if any one of them is +the most recent recursion.</p> -<p>At "top level", all these recursion test conditions are false. Recursive -patterns are described below.</p> +<p>At "top level", all these recursion test conditions are false. The syntax for recursive +patterns is described below.</p> <p><em>Defining subpatterns for use by reference only</em></p> @@ -2528,21 +2993,21 @@ patterns are described below.</p> name DEFINE, the condition is always false. In this case, there may be only one alternative in the subpattern. It is always skipped if control reaches this point in the pattern; the idea of DEFINE is that it can be used to define -"subroutines" that can be referenced from elsewhere. (The use of "subroutines" -is described below.) For example, a pattern to match an IPv4 address could be +"subroutines" that can be referenced from elsewhere. (The use of subroutines +is described below.) For example, a pattern to match an IPv4 address such as +"192.168.23.245" could be written like this (ignore whitespace and line breaks):</p> <quote><p> (?(DEFINE) (?<byte> 2[0-4]\d | 25[0-5] | 1\d\d | [1-9]?\d) ) \b (?&byte) (\.(?&byte)){3} \b</p></quote> -<p>The first part of the pattern is a DEFINE group inside which a another group -named "byte" is defined. This matches an individual component of an IPv4 -address (a number less than 256). When matching takes place, this part of the -pattern is skipped because DEFINE acts like a false condition.</p> - -<p>The rest of the pattern uses references to the named group to match the four -dot-separated components of an IPv4 address, insisting on a word boundary at -each end.</p> +<p>The first part of the pattern is a DEFINE group inside which a +another group named "byte" is defined. This matches an individual +component of an IPv4 address (a number less than 256). When matching +takes place, this part of the pattern is skipped because DEFINE acts +like a false condition. The rest of the pattern uses references to the +named group to match the four dot-separated components of an IPv4 +address, insisting on a word boundary at each end.</p> <p><em>Assertion conditions</em></p> @@ -2567,14 +3032,31 @@ dd-aaa-dd or dd-dd-dd, where aaa are letters and dd are digits.</p> <section><marker id="sect19"></marker><title>Comments</title> -<p>The sequence (?# marks the start of a comment that continues up to the next -closing parenthesis. Nested parentheses are not permitted. The characters -that make up a comment play no part in the pattern matching at all.</p> - -<p>If the <c>extended</c> option is set, an unescaped # character outside a -character class introduces a comment that continues to immediately after the -next newline in the pattern.</p> +<p>There are two ways of including comments in patterns that are processed by +PCRE. In both cases, the start of the comment must not be in a character class, +nor in the middle of any other sequence of related characters such as (?: or a +subpattern name or number. The characters that make up a comment play no part +in the pattern matching.</p> +<p>The sequence (?# marks the start of a comment that continues up to the next +closing parenthesis. Nested parentheses are not permitted. If the PCRE_EXTENDED +option is set, an unescaped # character also introduces a comment, which in +this case continues to immediately after the next newline character or +character sequence in the pattern. Which characters are interpreted as newlines +is controlled by the options passed to a compiling function or by a special +sequence at the start of the pattern, as described in the section entitled +"Newline conventions" +above. Note that the end of this type of comment is a literal newline sequence +in the pattern; escape sequences that happen to represent a newline do not +count. For example, consider this pattern when <c>extended</c> is set, and the +default newline convention is in force:</p> + +<quote><p> abc #comment \n still comment</p></quote> + +<p>On encountering the # character, <b>pcre_compile()</b> skips along, looking for +a newline in the pattern. The sequence \n is still literal at this stage, so +it does not terminate the comment. Only an actual character with the code value +0x0a (the default newline) does so.</p> </section> @@ -2600,51 +3082,45 @@ case refers recursively to the pattern in which it appears.</p> <p>Obviously, PCRE cannot support the interpolation of Perl code. Instead, it supports special syntax for recursion of the entire pattern, and also for individual subpattern recursion. After its introduction in PCRE and Python, -this kind of recursion was introduced into Perl at release 5.10.</p> +this kind of recursion was subsequently introduced into Perl at release 5.10.</p> <p>A special item that consists of (? followed by a number greater -than zero and a closing parenthesis is a recursive call of the +than zero and a closing parenthesis is a recursive subroutine call of the subpattern of the given number, provided that it occurs inside that -subpattern. (If not, it is a "subroutine" call, which is described in +subpattern. (If not, it is a non-recursive subroutine call, which is described in the next section.) The special item (?R) or (?0) is a recursive call of the entire regular expression.</p> -<p>In PCRE (like Python, but unlike Perl), a recursive subpattern call -is always treated as an atomic group. That is, once it has matched -some of the subject string, it is never re-entered, even if it -contains untried alternatives and there is a subsequent matching -failure.</p> - <p>This PCRE pattern solves the nested parentheses problem (assume the <c>extended</c> option is set so that whitespace is ignored):</p> -<quote><p> \( ( (?>[^()]+) | (?R) )* \)</p></quote> +<quote><p> \( ( [^()]++ | (?R) )* \)</p></quote> <p>First it matches an opening parenthesis. Then it matches any number of substrings which can either be a sequence of non-parentheses, or a recursive match of the pattern itself (that is, a correctly -parenthesized substring). Finally there is a closing parenthesis.</p> +parenthesized substring). Finally there is a closing +parenthesis. Note the use of a possessive quantifier to avoid +backtracking into sequences of non-parentheses.</p> <p>If this were part of a larger pattern, you would not want to recurse the entire pattern, so instead you could use this:</p> -<quote><p> ( \( ( (?>[^()]+) | (?1) )* \) )</p></quote> +<quote><p> ( \( ( [^()]++ | (?1) )* \) )</p></quote> <p>We have put the pattern into parentheses, and caused the recursion to refer to them instead of the whole pattern.</p> -<p>In a larger pattern, keeping track of parenthesis numbers can be -tricky. This is made easier by the use of relative references. (A Perl -5.10 feature.) Instead of (?1) in the pattern above you can write -(?-2) to refer to the second most recently opened parentheses -preceding the recursion. In other words, a negative number counts -capturing parentheses leftwards from the point at which it is -encountered.</p> +<p>In a larger pattern, keeping track of parenthesis numbers can be tricky. This +is made easier by the use of relative references. Instead of (?1) in the +pattern above you can write (?-2) to refer to the second most recently opened +parentheses preceding the recursion. In other words, a negative number counts +capturing parentheses leftwards from the point at which it is encountered.</p> <p>It is also possible to refer to subsequently opened parentheses, by writing references such as (?+2). However, these cannot be recursive because the reference is not inside the parentheses that are -referenced. They are always "subroutine" calls, as described in the +referenced. They are always non-recursive subroutine calls, as described in the next section.</p> <p>An alternative approach is to use named parentheses instead. The @@ -2652,75 +3128,136 @@ Perl syntax for this is (?&name); PCRE's earlier syntax (?P>name) is also supported. We could rewrite the above example as follows:</p> -<quote><p> (?<pn> \( ( (?>[^()]+) | (?&pn) )* \) )</p></quote> +<quote><p> (?<pn> \( ( [^()]++ | (?&pn) )* \) )</p></quote> <p>If there is more than one subpattern with the same name, the earliest one is used.</p> <p>This particular example pattern that we have been looking at contains nested -unlimited repeats, and so the use of atomic grouping for matching strings of -non-parentheses is important when applying the pattern to strings that do not -match. For example, when this pattern is applied to</p> +unlimited repeats, and so the use of a possessive quantifier for matching +strings of non-parentheses is important when applying the pattern to strings +that do not match. For example, when this pattern is applied to</p> <quote><p> (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()</p></quote> -<p>it yields "no match" quickly. However, if atomic grouping is not used, +<p>it yields "no match" quickly. However, if a possessive quantifier is not used, the match runs for a very long time indeed because there are so many different ways the + and * repeats can carve up the subject, and all have to be tested before failure can be reported.</p> -<p>At the end of a match, the values set for any capturing subpatterns are those -from the outermost level of the recursion at which the subpattern value is set. +<p>At the end of a match, the values of capturing parentheses are those from +the outermost level. If the pattern above is matched against</p> -<!-- XXX C Interface -If you want to obtain intermediate values, a callout function can be used (see -below and the +<quote><p> (ab(cd)ef)</p></quote> -<em>pcrecallout</em> +<p>the value for the inner capturing parentheses (numbered 2) is "ef", which is +the last value taken on at the top level. If a capturing subpattern is not +matched at the top level, its final captured value is unset, even if it was +(temporarily) set at a deeper level during the matching process.</p> -documentation). ---> -If the pattern above is matched against</p> +<p>Do not confuse the (?R) item with the condition (R), which tests for recursion. +Consider this pattern, which matches text in angle brackets, allowing for +arbitrary nesting. Only digits are allowed in nested brackets (that is, when +recursing), whereas any characters are permitted at the outer level.</p> -<quote><p> (ab(cd)ef)</p></quote> +<quote><p> < (?: (?(R) \d++ | [^<>]*+) | (?R)) * ></p></quote> -<p>the value for the capturing parentheses is "ef", which is the last value taken -on at the top level. If additional parentheses are added, giving</p> +<p>In this pattern, (?(R) is the start of a conditional subpattern, with two +different alternatives for the recursive and non-recursive cases. The (?R) item +is the actual recursive call.</p> + +<p><em>Differences in recursion processing between PCRE and Perl</em></p> + +<p>Recursion processing in PCRE differs from Perl in two important ways. In PCRE +(like Python, but unlike Perl), a recursive subpattern call is always treated +as an atomic group. That is, once it has matched some of the subject string, it +is never re-entered, even if it contains untried alternatives and there is a +subsequent matching failure. This can be illustrated by the following pattern, +which purports to match a palindromic string that contains an odd number of +characters (for example, "a", "aba", "abcba", "abcdcba"):</p> + +<quote><p> ^(.|(.)(?1)\2)$</p></quote> + +<p>The idea is that it either matches a single character, or two identical +characters surrounding a sub-palindrome. In Perl, this pattern works; in PCRE +it does not if the pattern is longer than three characters. Consider the +subject string "abcba":</p> + +<p>At the top level, the first character is matched, but as it is not at the end +of the string, the first alternative fails; the second alternative is taken +and the recursion kicks in. The recursive call to subpattern 1 successfully +matches the next character ("b"). (Note that the beginning and end of line +tests are not part of the recursion).</p> + +<p>Back at the top level, the next character ("c") is compared with what +subpattern 2 matched, which was "a". This fails. Because the recursion is +treated as an atomic group, there are now no backtracking points, and so the +entire match fails. (Perl is able, at this point, to re-enter the recursion and +try the second alternative.) However, if the pattern is written with the +alternatives in the other order, things are different:</p> + +<quote><p> ^((.)(?1)\2|.)$</p></quote> + +<p>This time, the recursing alternative is tried first, and continues to recurse +until it runs out of characters, at which point the recursion fails. But this +time we do have another alternative to try at the higher level. That is the big +difference: in the previous case the remaining alternative is at a deeper +recursion level, which PCRE cannot use.</p> + +<p>To change the pattern so that it matches all palindromic strings, not just +those with an odd number of characters, it is tempting to change the pattern to +this:</p> -<code type="none"> - \( ( ( (?>[^()]+) | (?R) )* ) \) - ^ ^ - ^ ^</code> +<quote><p> ^((.)(?1)\2|.?)$</p></quote> -<p>the string they capture is "ab(cd)ef", the contents of the top level -parentheses. -<!-- XXX C interface -If there are more than 15 capturing parentheses in a pattern, PCRE -has to obtain extra memory to store data during a recursion, which it does by -using <em>pcre_malloc</em>, freeing it via <em>pcre_free</em> afterwards. If no -memory can be obtained, the match fails with the <c>error_nomemory</c> error.</p> ---> -</p> +<p>Again, this works in Perl, but not in PCRE, and for the same reason. When a +deeper recursion has matched a single character, it cannot be entered again in +order to match an empty string. The solution is to separate the two cases, and +write out the odd and even cases as alternatives at the higher level:</p> -<p>Do not confuse the (?R) item with the condition (R), which tests -for recursion. Consider this pattern, which matches text in angle -brackets, allowing for arbitrary nesting. Only digits are allowed in -nested brackets (that is, when recursing), whereas any characters are -permitted at the outer level.</p> +<quote><p> ^(?:((.)(?1)\2|)|((.)(?3)\4|.))</p></quote> -<quote><p> < (?: (?(R) \d++ | [^<>]*+) | (?R)) * ></p></quote> +<p>If you want to match typical palindromic phrases, the pattern has to ignore all +non-word characters, which can be done like this:</p> + + <quote><p> ^\W*+(?:((.)\W*+(?1)\W*+\2|)|((.)\W*+(?3)\W*+\4|\W*+.\W*+))\W*+$</p></quote> + +<p>If run with the <c>caseless</c> option, this pattern matches phrases such as "A +man, a plan, a canal: Panama!" and it works well in both PCRE and Perl. Note +the use of the possessive quantifier *+ to avoid backtracking into sequences of +non-word characters. Without this, PCRE takes a great deal longer (ten times or +more) to match typical phrases, and Perl takes so long that you think it has +gone into a loop.</p> + +<p><em>WARNING</em>: The palindrome-matching patterns above work only if the subject +string does not start with a palindrome that is shorter than the entire string. +For example, although "abcba" is correctly matched, if the subject is "ababa", +PCRE finds the palindrome "aba" at the start, then fails at top level because +the end of the string does not follow. Once again, it cannot jump back into the +recursion to try other alternatives, so the entire match fails.</p> -<p>In this pattern, (?(R) is the start of a conditional subpattern, -with two different alternatives for the recursive and non-recursive -cases. The (?R) item is the actual recursive call.</p> +<p>The second way in which PCRE and Perl differ in their recursion processing is +in the handling of captured values. In Perl, when a subpattern is called +recursively or as a subpattern (see the next section), it has no access to any +values that were captured outside the recursion, whereas in PCRE these values +can be referenced. Consider this pattern:</p> + +<quote><p> ^(.)(\1|a(?2))</p></quote> + +<p>In PCRE, this pattern matches "bab". The first capturing parentheses match "b", +then in the second group, when the back reference \1 fails to match "b", the +second alternative matches "a" and then recurses. In the recursion, \1 does +now match "b" and so the whole match succeeds. In Perl, the pattern fails to +match because inside the recursive call \1 cannot access the externally set +value.</p> </section> <section><marker id="sect21"></marker><title>Subpatterns as subroutines</title> -<p>If the syntax for a recursive subpattern reference (either by number or by +<p>If the syntax for a recursive subpattern call (either by number or by name) is used outside the parentheses to which it refers, it operates like a -subroutine in a programming language. The "called" subpattern may be defined +subroutine in a programming language. The called subpattern may be defined before or after the reference. A numbered reference can be absolute or relative, as in these examples:</p> @@ -2742,23 +3279,40 @@ relative, as in these examples:</p> <p>is used, it does match "sense and responsibility" as well as the other two strings. Another example is given in the discussion of DEFINE above.</p> -<p>Like recursive subpatterns, a "subroutine" call is always treated -as an atomic group. That is, once it has matched some of the subject -string, it is never re-entered, even if it contains untried -alternatives and there is a subsequent matching failure.</p> - -<p>When a subpattern is used as a subroutine, processing options such as -case-independence are fixed when the subpattern is defined. They cannot be -changed for different calls. For example, consider this pattern:</p> +<p>All subroutine calls, whether recursive or not, are always treated as atomic +groups. That is, once a subroutine has matched some of the subject string, it +is never re-entered, even if it contains untried alternatives and there is a +subsequent matching failure. Any capturing parentheses that are set during the +subroutine call revert to their previous values afterwards.</p> +<p>Processing options such as case-independence are fixed when a subpattern is +defined, so if it is used as a subroutine, such options cannot be changed for +different calls. For example, consider this pattern:</p> <quote><p> (abc)(?i:(?-1))</p></quote> <p>It matches "abcabc". It does not match "abcABC" because the change of processing option does not affect the called subpattern.</p> - </section> +<section><marker id="sect22"></marker><title>Oniguruma subroutine syntax</title> +<p>For compatibility with Oniguruma, the non-Perl syntax \g followed by a name or +a number enclosed either in angle brackets or single quotes, is an alternative +syntax for referencing a subpattern as a subroutine, possibly recursively. Here +are two of the examples used above, rewritten using this syntax:</p> +<quote> + <p> (?<pn> \( ( (?>[^()]+) | \g<pn> )* \) )</p> + <p> (sens|respons)e and \g'1'ibility</p> +</quote> +<p>PCRE supports an extension to Oniguruma: if a number is preceded by a +plus or a minus sign it is taken as a relative reference. For example:</p> + + <quote><p> (abc)(?i:\g<-1>)</p></quote> + +<p>Note that \g{...} (Perl syntax) and \g<...> (Oniguruma syntax) are <i>not</i> +synonymous. The former is a back reference; the latter is a subroutine call.</p> + +</section> <!-- XXX C interface <section> <marker id="sect22"><title>Callouts</title></marker> @@ -2801,116 +3355,387 @@ documentation.</p> <section><marker id="sect23"></marker><title>Backtracking control</title> <p>Perl 5.10 introduced a number of "Special Backtracking Control Verbs", which -are described in the Perl documentation as "experimental and subject to change -or removal in a future version of Perl". It goes on to say: "Their usage in -production code should be noted to avoid problems during upgrades." The same +are still described in the Perl documentation as "experimental and subject to +change or removal in a future version of Perl". It goes on to say: "Their usage +in production code should be noted to avoid problems during upgrades." The same remarks apply to the PCRE features described in this section.</p> +<p>The new verbs make use of what was previously invalid syntax: an opening +parenthesis followed by an asterisk. They are generally of the form +(*VERB) or (*VERB:NAME). Some may take either form, possibly behaving +differently depending on whether or not a name is present. A name is any +sequence of characters that does not include a closing parenthesis. The maximum +length of name is 255 in the 8-bit library and 65535 in the 16-bit and 32-bit +libraries. If the name is empty, that is, if the closing parenthesis +immediately follows the colon, the effect is as if the colon were not there. +Any number of these verbs may occur in a pattern.</p> + <!-- XXX C interface -<p>Since these verbs are specifically related to backtracking, they can be used -only when the pattern is to be matched using <c>re:run/3</c>, which uses a -backtracking algorithm. They cause an error if encountered by -<c>pcre_dfa_exec()</c>.</p> +<p>Since these verbs are specifically related to backtracking, most of them can be +used only when the pattern is to be matched using one of the traditional +matching functions, because these use a backtracking algorithm. With the +exception of (*FAIL), which behaves like a failing negative assertion, the +backtracking control verbs cause an error if encountered by a DFA matching +function.</p> --> +<p>The behaviour of these verbs in +repeated groups, assertions, +and in subpatterns called as subroutines +(whether or not recursively) is documented below.</p> -<p>The new verbs make use of what was previously invalid syntax: an opening -parenthesis followed by an asterisk. In Perl, they are generally of the form -(*VERB:ARG) but PCRE does not support the use of arguments, so its general -form is just (*VERB). Any number of these verbs may occur in a pattern. There -are two kinds:</p> +<p><em>Optimizations that affect backtracking verbs</em></p> + +<p>PCRE contains some optimizations that are used to speed up matching by running +some checks at the start of each match attempt. For example, it may know the +minimum length of matching subject, or that a particular character must be +present. When one of these optimizations bypasses the running of a match, any +included backtracking verbs will not, of course, be processed. You can suppress +the start-of-match optimizations by setting the <c>no_start_optimize</c> option +when calling <c>re:compile/2</c> or <c>re:run/3</c>, or by starting the +pattern with (*NO_START_OPT).</p> +<p>Experiments with Perl suggest that it too has similar optimizations, sometimes +leading to anomalous results.</p> <p><em>Verbs that act immediately</em></p> -<p>The following verbs act as soon as they are encountered:</p> +<p>The following verbs act as soon as they are encountered. They may not be +followed by a name.</p> -<quote><p> (*ACCEPT)</p></quote> +<quote><p> (*ACCEPT)</p></quote> <p>This verb causes the match to end successfully, skipping the remainder of the -pattern. When inside a recursion, only the innermost pattern is ended -immediately. PCRE differs from Perl in what happens if the (*ACCEPT) is inside -capturing parentheses. In Perl, the data so far is captured: in PCRE no data is -captured. For example:</p> +pattern. However, when it is inside a subpattern that is called as a +subroutine, only that subpattern is ended successfully. Matching then continues +at the outer level. If (*ACCEPT) in triggered in a positive assertion, the +assertion succeeds; in a negative assertion, the assertion fails.</p> + +<p>If (*ACCEPT) is inside capturing parentheses, the data so far is captured. For +example:</p> -<quote><p> A(A|B(*ACCEPT)|C)D</p></quote> +<quote><p> A((?:A|B(*ACCEPT)|C)D)</p></quote> -<p>This matches "AB", "AAD", or "ACD", but when it matches "AB", no data is -captured.</p> +<p>This matches "AB", "AAD", or "ACD"; when it matches "AB", "B" is captured by +the outer parentheses.</p> -<quote><p> (*FAIL) or (*F)</p></quote> +<quote><p> (*FAIL) or (*F)</p></quote> -<p>This verb causes the match to fail, forcing backtracking to occur. It is +<p>This verb causes a matching failure, forcing backtracking to occur. It is equivalent to (?!) but easier to read. The Perl documentation notes that it is probably useful only when combined with (?{}) or (??{}). Those are, of course, Perl features that are not present in PCRE. The nearest equivalent is the callout feature, as for example in this pattern:</p> -<quote><p> a+(?C)(*FAIL)</p></quote> +<quote><p> a+(?C)(*FAIL)</p></quote> <p>A match with the string "aaaa" always fails, but the callout is taken before each backtrack happens (in this example, 10 times).</p> - +<p><em>Recording which path was taken</em></p> + +<p>There is one verb whose main purpose is to track how a match was arrived at, +though it also has a secondary use in conjunction with advancing the match +starting point (see (*SKIP) below).</p> + +<warning> +<p>In Erlang, there is no interface to retrieve a mark with <c>re:run/{2,3]</c>, +so only the secondary purpose is relevant to the Erlang programmer!</p> +<p>The rest of this section is therefore deliberately not adapted for reading +by the Erlang programmer, however the examples might help in understanding NAMES as +they can be used by (*SKIP).</p> +</warning> + +<quote><p> (*MARK:NAME) or (*:NAME)</p></quote> + +<p>A name is always required with this verb. There may be as many instances of +(*MARK) as you like in a pattern, and their names do not have to be unique.</p> + +<p>When a match succeeds, the name of the last-encountered (*MARK:NAME), +(*PRUNE:NAME), or (*THEN:NAME) on the matching path is passed back to the +caller as described in the section entitled "Extra data for <c>pcre_exec()</c>" +in the <c>pcreapi</c> +documentation. Here is an example of <c>pcretest</c> output, where the /K +modifier requests the retrieval and outputting of (*MARK) data:</p> +<code> + re> /X(*MARK:A)Y|X(*MARK:B)Z/K + data> XY + 0: XY + MK: A + XZ + 0: XZ + MK: B</code> + +<p>The (*MARK) name is tagged with "MK:" in this output, and in this example it +indicates which of the two alternatives matched. This is a more efficient way +of obtaining this information than putting each alternative in its own +capturing parentheses.</p> + +<p>If a verb with a name is encountered in a positive assertion that is true, the +name is recorded and passed back if it is the last-encountered. This does not +happen for negative assertions or failing positive assertions.</p> + +<p>After a partial match or a failed match, the last encountered name in the +entire match process is returned. For example:</p> +<code> + re> /X(*MARK:A)Y|X(*MARK:B)Z/K + data> XP + No match, mark = B</code> + +<p>Note that in this unanchored example the mark is retained from the match +attempt that started at the letter "X" in the subject. Subsequent match +attempts starting at "P" and then with an empty string do not get as far as the +(*MARK) item, but nevertheless do not reset it.</p> + +<!-- +<p>If you are interested in (*MARK) values after failed matches, you should +probably set the PCRE_NO_START_OPTIMIZE option +(see above) +to ensure that the match is always attempted.</p> +--> <p><em>Verbs that act after backtracking</em></p> <p>The following verbs do nothing when they are encountered. Matching continues -with what follows, but if there is no subsequent match, a failure is forced. -The verbs differ in exactly what kind of failure occurs.</p> - -<quote><p> (*COMMIT)</p></quote> - -<p>This verb causes the whole match to fail outright if the rest of the pattern -does not match. Even if the pattern is unanchored, no further attempts to find -a match by advancing the start point take place. Once (*COMMIT) has been -passed, <c>re:run/3</c> is committed to finding a match at the current -starting point, or not at all. For example:</p> +with what follows, but if there is no subsequent match, causing a backtrack to +the verb, a failure is forced. That is, backtracking cannot pass to the left of +the verb. However, when one of these verbs appears inside an atomic group or an +assertion that is true, its effect is confined to that group, because once the +group has been matched, there is never any backtracking into it. In this +situation, backtracking can "jump back" to the left of the entire atomic group +or assertion. (Remember also, as stated above, that this localization also +applies in subroutine calls.)</p> + +<p>These verbs differ in exactly what kind of failure occurs when backtracking +reaches them. The behaviour described below is what happens when the verb is +not in a subroutine or an assertion. Subsequent sections cover these special +cases.</p> + +<quote><p> (*COMMIT)</p></quote> + +<p>This verb, which may not be followed by a name, causes the whole match to fail +outright if there is a later matching failure that causes backtracking to reach +it. Even if the pattern is unanchored, no further attempts to find a match by +advancing the starting point take place. If (*COMMIT) is the only backtracking +verb that is encountered, once it has been passed <c>re:run/{2,3}</c> is +committed to finding a match at the current starting point, or not at all. For +example:</p> -<quote><p> a+(*COMMIT)b</p></quote> +<quote><p> a+(*COMMIT)b</p></quote> <p>This matches "xxaab" but not "aacaab". It can be thought of as a kind of -dynamic anchor, or "I've started, so I must finish."</p> +dynamic anchor, or "I've started, so I must finish." The name of the most +recently passed (*MARK) in the path is passed back when (*COMMIT) forces a +match failure.</p> -<quote><p> (*PRUNE)</p></quote> +<p>If there is more than one backtracking verb in a pattern, a different one that +follows (*COMMIT) may be triggered first, so merely passing (*COMMIT) during a +match does not always guarantee that a match must be at this starting point.</p> -<p>This verb causes the match to fail at the current position if the rest of the -pattern does not match. If the pattern is unanchored, the normal "bumpalong" -advance to the next starting character then happens. Backtracking can occur as -usual to the left of (*PRUNE), or when matching to the right of (*PRUNE), but -if there is no match to the right, backtracking cannot cross (*PRUNE). -In simple cases, the use of (*PRUNE) is just an alternative to an atomic -group or possessive quantifier, but there are some uses of (*PRUNE) that cannot -be expressed in any other way.</p> - -<quote><p> (*SKIP)</p></quote> - -<p>This verb is like (*PRUNE), except that if the pattern is unanchored, the -"bumpalong" advance is not to the next character, but to the position in the -subject where (*SKIP) was encountered. (*SKIP) signifies that whatever text -was matched leading up to it cannot be part of a successful match. Consider:</p> - -<quote><p> a+(*SKIP)b</p></quote> +<p>Note that (*COMMIT) at the start of a pattern is not the same as an anchor, +unless PCRE's start-of-match optimizations are turned off, as shown in this + example:</p> +<code type="none"> + 1> re:run("xyzabc","(*COMMIT)abc",[{capture,all,list}]). + {match,["abc"]} + 2> re:run("xyzabc","(*COMMIT)abc",[{capture,all,list},no_start_optimize]). + nomatch</code> + +<p>PCRE knows that any match must start with "a", so the optimization skips along +the subject to "a" before running the first match attempt, which succeeds. When +the optimization is disabled by the <c>no_start_optimize</c> option, the match +starts at "x" and so the (*COMMIT) causes it to fail without trying any other +starting points.</p> + +<quote><p> (*PRUNE) or (*PRUNE:NAME)</p></quote> + +<p>This verb causes the match to fail at the current starting position in the +subject if there is a later matching failure that causes backtracking to reach +it. If the pattern is unanchored, the normal "bumpalong" advance to the next +starting character then happens. Backtracking can occur as usual to the left of +(*PRUNE), before it is reached, or when matching to the right of (*PRUNE), but +if there is no match to the right, backtracking cannot cross (*PRUNE). In +simple cases, the use of (*PRUNE) is just an alternative to an atomic group or +possessive quantifier, but there are some uses of (*PRUNE) that cannot be +expressed in any other way. In an anchored pattern (*PRUNE) has the same effect +as (*COMMIT).</p> + +<p>The behaviour of (*PRUNE:NAME) is the not the same as (*MARK:NAME)(*PRUNE). +It is like (*MARK:NAME) in that the name is remembered for passing back to the +caller. However, (*SKIP:NAME) searches only for names set with (*MARK).</p> + +<warning> +<p>The fact that (*PRUNE:NAME) remembers the name is useless to the Erlang programmer, +as names can not be retrieved.</p> +</warning> + +<quote><p> (*SKIP)</p></quote> + +<p>This verb, when given without a name, is like (*PRUNE), except that if the +pattern is unanchored, the "bumpalong" advance is not to the next character, +but to the position in the subject where (*SKIP) was encountered. (*SKIP) +signifies that whatever text was matched leading up to it cannot be part of a +successful match. Consider:</p> + +<quote><p> a+(*SKIP)b</p></quote> <p>If the subject is "aaaac...", after the first match attempt fails (starting at the first character in the string), the starting point skips on to start the -next attempt at "c". Note that a possessive quantifier does not have the same -effect in this example; although it would suppress backtracking during the +next attempt at "c". Note that a possessive quantifer does not have the same +effect as this example; although it would suppress backtracking during the first match attempt, the second attempt would start at the second character instead of skipping on to "c".</p> -<quote><p> (*THEN)</p></quote> +<quote><p> (*SKIP:NAME)</p></quote> + +<p>When (*SKIP) has an associated name, its behaviour is modified. When it is +triggered, the previous path through the pattern is searched for the most +recent (*MARK) that has the same name. If one is found, the "bumpalong" advance +is to the subject position that corresponds to that (*MARK) instead of to where +(*SKIP) was encountered. If no (*MARK) with a matching name is found, the +(*SKIP) is ignored.</p> -<p>This verb causes a skip to the next alternation if the rest of the pattern does -not match. That is, it cancels pending backtracking, but only within the -current alternation. Its name comes from the observation that it can be used -for a pattern-based if-then-else block:</p> +<p>Note that (*SKIP:NAME) searches only for names set by (*MARK:NAME). It ignores +names that are set by (*PRUNE:NAME) or (*THEN:NAME).</p> -<quote><p> ( COND1 (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ ) ...</p></quote> +<quote><p> (*THEN) or (*THEN:NAME)</p></quote> + +<p>This verb causes a skip to the next innermost alternative when backtracking +reaches it. That is, it cancels any further backtracking within the current +alternative. Its name comes from the observation that it can be used for a +pattern-based if-then-else block:</p> + +<quote><p> ( COND1 (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ ) ...</p></quote> <p>If the COND1 pattern matches, FOO is tried (and possibly further items after -the end of the group if FOO succeeds); on failure the matcher skips to the -second alternative and tries COND2, without backtracking into COND1. If (*THEN) -is used outside of any alternation, it acts exactly like (*PRUNE).</p> +the end of the group if FOO succeeds); on failure, the matcher skips to the +second alternative and tries COND2, without backtracking into COND1. If that +succeeds and BAR fails, COND3 is tried. If subsequently BAZ fails, there are no +more alternatives, so there is a backtrack to whatever came before the entire +group. If (*THEN) is not inside an alternation, it acts like (*PRUNE).</p> + +<p>The behaviour of (*THEN:NAME) is the not the same as (*MARK:NAME)(*THEN). +It is like (*MARK:NAME) in that the name is remembered for passing back to the +caller. However, (*SKIP:NAME) searches only for names set with (*MARK).</p> + +<warning> +<p>The fact that (*THEN:NAME) remembers the name is useless to the Erlang programmer, +as names can not be retrieved.</p> +</warning> + +<p>A subpattern that does not contain a | character is just a part of the +enclosing alternative; it is not a nested alternation with only one +alternative. The effect of (*THEN) extends beyond such a subpattern to the +enclosing alternative. Consider this pattern, where A, B, etc. are complex +pattern fragments that do not contain any | characters at this level:</p> + +<quote><p> A (B(*THEN)C) | D</p></quote> + +<p>If A and B are matched, but there is a failure in C, matching does not +backtrack into A; instead it moves to the next alternative, that is, D. +However, if the subpattern containing (*THEN) is given an alternative, it +behaves differently:</p> + +<quote><p> A (B(*THEN)C | (*FAIL)) | D</p></quote> + +<p>The effect of (*THEN) is now confined to the inner subpattern. After a failure +in C, matching moves to (*FAIL), which causes the whole subpattern to fail +because there are no more alternatives to try. In this case, matching does now +backtrack into A.</p> + +<p>Note that a conditional subpattern is not considered as having two +alternatives, because only one is ever used. In other words, the | character in +a conditional subpattern has a different meaning. Ignoring white space, +consider:</p> + +<quote><p> ^.*? (?(?=a) a | b(*THEN)c )</p></quote> + +<p>If the subject is "ba", this pattern does not match. Because .*? is ungreedy, +it initially matches zero characters. The condition (?=a) then fails, the +character "b" is matched, but "c" is not. At this point, matching does not +backtrack to .*? as might perhaps be expected from the presence of the | +character. The conditional subpattern is part of the single alternative that +comprises the whole pattern, and so the match fails. (If there was a backtrack +into .*?, allowing it to match "b", the match would succeed.)</p> + +<p>The verbs just described provide four different "strengths" of control when +subsequent matching fails. (*THEN) is the weakest, carrying on the match at the +next alternative. (*PRUNE) comes next, failing the match at the current +starting position, but allowing an advance to the next character (for an +unanchored pattern). (*SKIP) is similar, except that the advance may be more +than one character. (*COMMIT) is the strongest, causing the entire match to +fail.</p> + + +<p><em>More than one backtracking verb</em></p> + +<p>If more than one backtracking verb is present in a pattern, the one that is +backtracked onto first acts. For example, consider this pattern, where A, B, +etc. are complex pattern fragments:</p> + +<quote><p> (A(*COMMIT)B(*THEN)C|ABD)</p></quote> + +<p>If A matches but B fails, the backtrack to (*COMMIT) causes the entire match to +fail. However, if A and B match, but C fails, the backtrack to (*THEN) causes +the next alternative (ABD) to be tried. This behaviour is consistent, but is +not always the same as Perl's. It means that if two or more backtracking verbs +appear in succession, all the the last of them has no effect. Consider this +example:</p> + +<quote><p> ...(*COMMIT)(*PRUNE)...</p></quote> + +<p>If there is a matching failure to the right, backtracking onto (*PRUNE) cases +it to be triggered, and its action is taken. There can never be a backtrack +onto (*COMMIT).</p> + +<p><em>Backtracking verbs in repeated groups</em></p> + +<p>PCRE differs from Perl in its handling of backtracking verbs in repeated +groups. For example, consider:</p> + +<quote><p> /(a(*COMMIT)b)+ac/</p></quote> + +<p>If the subject is "abac", Perl matches, but PCRE fails because the (*COMMIT) in +the second repeat of the group acts.</p> + +<p><em>Backtracking verbs in assertions</em></p> + +<p>(*FAIL) in an assertion has its normal effect: it forces an immediate backtrack.</p> + +<p>(*ACCEPT) in a positive assertion causes the assertion to succeed without any +further processing. In a negative assertion, (*ACCEPT) causes the assertion to +fail without any further processing.</p> + +<p>The other backtracking verbs are not treated specially if they appear in a +positive assertion. In particular, (*THEN) skips to the next alternative in the +innermost enclosing group that has alternations, whether or not this is within +the assertion.</p> + +<p>Negative assertions are, however, different, in order to ensure that changing a +positive assertion into a negative assertion changes its result. Backtracking +into (*COMMIT), (*SKIP), or (*PRUNE) causes a negative assertion to be true, +without considering any further alternative branches in the assertion. +Backtracking into (*THEN) causes it to skip to the next enclosing alternative +within the assertion (the normal behaviour), but if the assertion does not have +such an alternative, (*THEN) behaves like (*PRUNE).</p> + +<p><em>Backtracking verbs in subroutines</em></p> + +<p>These behaviours occur whether or not the subpattern is called recursively. +Perl's treatment of subroutines is different in some cases.</p> + +<p>(*FAIL) in a subpattern called as a subroutine has its normal effect: it forces +an immediate backtrack.</p> + +<p>(*ACCEPT) in a subpattern called as a subroutine causes the subroutine match to +succeed without any further processing. Matching then continues after the +subroutine call.</p> + +<p>(*COMMIT), (*SKIP), and (*PRUNE) in a subpattern called as a subroutine cause +the subroutine match to fail.</p> + +<p>(*THEN) skips to the next alternative in the innermost enclosing group within +the subpattern that has alternatives. If there is no such group within the +subpattern, (*THEN) causes the subroutine match to fail.</p> </section> diff --git a/lib/stdlib/doc/src/ref_man.xml b/lib/stdlib/doc/src/ref_man.xml index 0f277f6c5e..6c35578bdf 100644 --- a/lib/stdlib/doc/src/ref_man.xml +++ b/lib/stdlib/doc/src/ref_man.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE application SYSTEM "application.dtd"> <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -68,6 +68,7 @@ <xi:include href="lib.xml"/> <xi:include href="lists.xml"/> <xi:include href="log_mf_h.xml"/> + <xi:include href="maps.xml"/> <xi:include href="math.xml"/> <xi:include href="ms_transform.xml"/> <xi:include href="orddict.xml"/> diff --git a/lib/stdlib/doc/src/sets.xml b/lib/stdlib/doc/src/sets.xml index 071ee437cb..c5b8dce4b7 100644 --- a/lib/stdlib/doc/src/sets.xml +++ b/lib/stdlib/doc/src/sets.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2000</year><year>2011</year> + <year>2000</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -45,9 +45,15 @@ <datatypes> <datatype> - <name><marker id="type-dict">set()</marker></name> + <name name="set" n_vars="1"/> <desc><p>As returned by <c>new/0</c>.</p></desc> </datatype> + <datatype> + <name name="set" n_vars="0"/> + <desc> + <p><c>set()</c> is equivalent to <c>set(term())</c>.</p> + </desc> + </datatype> </datatypes> <funcs> <func> diff --git a/lib/stdlib/doc/src/shell.xml b/lib/stdlib/doc/src/shell.xml index bc2120c37d..3ca80ed900 100644 --- a/lib/stdlib/doc/src/shell.xml +++ b/lib/stdlib/doc/src/shell.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -781,7 +781,7 @@ loop(N) -> </desc> </func> <func> - <name>catch_exception(Bool) -> Bool</name> + <name>catch_exception(Bool) -> boolean()</name> <fsummary>Sets the exception handling of the shell</fsummary> <type> <v>Bool = boolean()</v> @@ -801,8 +801,8 @@ loop(N) -> <name name="prompt_func" arity="1"/> <fsummary>Sets the shell prompt</fsummary> <desc> - <p>Sets the shell prompt function to <c>PromptFunc</c>. The - previous prompt function is returned.</p> + <p>Sets the shell prompt function to <c><anno>PromptFunc</anno></c>. + The previous prompt function is returned.</p> </desc> </func> <func> @@ -827,6 +827,20 @@ loop(N) -> is meant to be called from the shell.</p> </desc> </func> + <func> + <name name="strings" arity="1"/> + <fsummary>Sets the shell's string recognition flag.</fsummary> + <desc> + <p>Sets pretty printing of lists to <c><anno>Strings</anno></c>. + The previous value of the flag is returned.</p> + <p>The flag can also be set by the STDLIB application variable + <c>shell_strings</c>. The default is + <c>true</c> which means that lists of integers will be + printed using the string syntax, when possible. The value + <c>false</c> means that no lists will be printed using the + string syntax.</p> + </desc> + </func> </funcs> </erlref> diff --git a/lib/stdlib/doc/src/shell_default.xml b/lib/stdlib/doc/src/shell_default.xml index f7e7d5388a..2355ba92f9 100644 --- a/lib/stdlib/doc/src/shell_default.xml +++ b/lib/stdlib/doc/src/shell_default.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/slave.xml b/lib/stdlib/doc/src/slave.xml index 15b6711731..f5d0436a20 100644 --- a/lib/stdlib/doc/src/slave.xml +++ b/lib/stdlib/doc/src/slave.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/sofs.xml b/lib/stdlib/doc/src/sofs.xml index 37c41501ae..6c97fd0bc0 100644 --- a/lib/stdlib/doc/src/sofs.xml +++ b/lib/stdlib/doc/src/sofs.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2001</year><year>2012</year> + <year>2001</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/specs.xml b/lib/stdlib/doc/src/specs.xml index 49c60529d2..60a04ed5e7 100644 --- a/lib/stdlib/doc/src/specs.xml +++ b/lib/stdlib/doc/src/specs.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <specs xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="../specs/specs_array.xml"/> <xi:include href="../specs/specs_base64.xml"/> @@ -34,6 +34,7 @@ <xi:include href="../specs/specs_lib.xml"/> <xi:include href="../specs/specs_lists.xml"/> <xi:include href="../specs/specs_log_mf_h.xml"/> + <xi:include href="../specs/specs_maps.xml"/> <xi:include href="../specs/specs_math.xml"/> <xi:include href="../specs/specs_ms_transform.xml"/> <xi:include href="../specs/specs_orddict.xml"/> diff --git a/lib/stdlib/doc/src/stdlib_app.xml b/lib/stdlib/doc/src/stdlib_app.xml index a615c1bf88..de4cc65396 100644 --- a/lib/stdlib/doc/src/stdlib_app.xml +++ b/lib/stdlib/doc/src/stdlib_app.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE appref SYSTEM "appref.dtd"> <appref> <header> <copyright> - <year>2005</year><year>2010</year> + <year>2005</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -51,7 +51,7 @@ <p>This parameter can be used to run the Erlang shell in restricted mode.</p> </item> - <tag><c>shell_catch_exception = bool()</c></tag> + <tag><c>shell_catch_exception = boolean()</c></tag> <item> <p>This parameter can be used to set the exception handling of the Erlang shell's evaluator process.</p> @@ -76,6 +76,11 @@ <p>This parameter can be used to determine how many results are saved by the Erlang shell.</p> </item> + <tag><c>shell_strings = boolean()</c></tag> + <item> + <p>This parameter can be used to determine how the Erlang + shell outputs lists of integers.</p> + </item> </taglist> </section> diff --git a/lib/stdlib/doc/src/string.xml b/lib/stdlib/doc/src/string.xml index 48867ffe72..c96cc95a44 100644 --- a/lib/stdlib/doc/src/string.xml +++ b/lib/stdlib/doc/src/string.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -255,18 +255,12 @@ sub_string("Hello World", 4, 8). </desc> </func> <func> - <name>to_float(String) -> {Float,Rest} | {error,Reason} </name> + <name name="to_float" arity="1"/> <fsummary>Returns a float whose text representation is the integers (ASCII values) in String.</fsummary> - <type> - <v>String = string()</v> - <v>Float = float()</v> - <v>Rest = string()</v> - <v>Reason = no_float | not_a_list</v> - </type> <desc> - <p>Argument <c>String</c> is expected to start with a valid text + <p>Argument <c><anno>String</anno></c> is expected to start with a valid text represented float (the digits being ASCII values). Remaining characters - in the string after the float are returned in <c>Rest</c>.</p> + in the string after the float are returned in <c><anno>Rest</anno></c>.</p> <p>Example:</p> <code type="none"> > {F1,Fs} = string:to_float("1.0-1.0e-1"), @@ -280,18 +274,12 @@ sub_string("Hello World", 4, 8). </desc> </func> <func> - <name>to_integer(String) -> {Int,Rest} | {error,Reason} </name> + <name name="to_integer" arity="1"/> <fsummary>Returns an integer whose text representation is the integers (ASCII values) in String.</fsummary> - <type> - <v>String = string()</v> - <v>Int = integer()</v> - <v>Rest = string()</v> - <v>Reason = no_integer | not_a_list</v> - </type> <desc> - <p>Argument <c>String</c> is expected to start with a valid text + <p>Argument <c><anno>String</anno></c> is expected to start with a valid text represented integer (the digits being ASCII values). Remaining characters - in the string after the integer are returned in <c>Rest</c>.</p> + in the string after the integer are returned in <c><anno>Rest</anno></c>.</p> <p>Example:</p> <code type="none"> > {I1,Is} = string:to_integer("33+22"), diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index f9a5e245b4..3a5027d595 100644 --- a/lib/stdlib/doc/src/supervisor.xml +++ b/lib/stdlib/doc/src/supervisor.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2012</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -177,12 +177,6 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} child process, it must be implemented in a safe way and its cleanup procedure must always return.</p> </warning> - <p><em>Important note on simple-one-for-one supervisors:</em> - The dynamically created child processes of a - simple-one-for-one supervisor are not explicitly killed, - regardless of shutdown strategy, but are expected to terminate - when the supervisor does (that is, when an exit signal from - the parent process is received).</p> <p>Note that all child processes implemented using the standard OTP behavior modules automatically adhere to the shutdown protocol.</p> @@ -268,12 +262,12 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} locally as <c>Name</c> using <c>register/2</c>. If <c><anno>SupName</anno>={global,Name}</c> the supervisor is registered globally as <c>Name</c> using <c>global:register_name/2</c>. If - <c><anno>SupName</anno>={via,Module,Name}</c> the supervisor + <c><anno>SupName</anno>={via,<anno>Module</anno>,<anno>Name</anno>}</c> the supervisor is registered as <c>Name</c> using the registry represented by <c>Module</c>. The <c>Module</c> callback should export the functions <c>register_name/2</c>, <c>unregister_name/1</c> and <c>send/2</c>, which should behave like the corresponding functions in <c>global</c>. - Thus, <c>{via,global,Name}</c> is a valid reference.</p> + Thus, <c>{via,global,<anno>Name</anno>}</c> is a valid reference.</p> <p>If no name is provided, the supervisor is not registered.</p> <p><c><anno>Module</anno></c> is the name of the callback module.</p> <p><c><anno>Args</anno></c> is an arbitrary term which is passed as @@ -294,10 +288,10 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} is a term with information about the error, and the supervisor terminates with reason <c>Term</c>.</p> <p>If any child process start function fails or returns an error - tuple or an erroneous value, the function returns - <c>{error,shutdown}</c> and the supervisor terminates all - started child processes and then itself with reason - <c>shutdown</c>.</p> + tuple or an erroneous value, the supervisor will first terminate + all already started child processes with reason <c>shutdown</c> + and then terminate itself and return + <c>{error, {shutdown, Reason}}</c>.</p> </desc> </func> <func> @@ -377,7 +371,7 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} children.</p> <p>If the supervisor is <c>simple_one_for_one</c>, <c><anno>Id</anno></c> - must be the child process' <c>pid()</c>. I the specified + must be the child process' <c>pid()</c>. If the specified process is alive, but is not a child of the given supervisor, the function will return <c>{error,not_found}</c>. If the child specification diff --git a/lib/stdlib/doc/src/supervisor_bridge.xml b/lib/stdlib/doc/src/supervisor_bridge.xml index f6712d6c1d..d16b258b6c 100644 --- a/lib/stdlib/doc/src/supervisor_bridge.xml +++ b/lib/stdlib/doc/src/supervisor_bridge.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 073faf2df2..19605f325b 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -115,6 +115,9 @@ <datatype> <name name="dbg_fun"/> </datatype> + <datatype> + <name name="format_fun"/> + </datatype> </datatypes> <funcs> <func> @@ -211,18 +214,125 @@ <p>Gets the status of the process.</p> <p>The value of <c><anno>Misc</anno></c> varies for different types of processes. For example, a <c>gen_server</c> process returns - the callback module's state, and a <c>gen_fsm</c> process - returns information such as its current state name. Callback - modules for <c>gen_server</c> and <c>gen_fsm</c> can also - customise the value of <c><anno>Misc</anno></c> by exporting - a <c>format_status/2</c> function that contributes - module-specific information; - see <seealso marker="gen_server#Module:format_status/2">gen_server:format_status/2</seealso> - and <seealso marker="gen_fsm#Module:format_status/2">gen_fsm:format_status/2</seealso> + the callback module's state, a <c>gen_fsm</c> process + returns information such as its current state name and state data, + and a <c>gen_event</c> process returns information about each of its + registered handlers. Callback modules for <c>gen_server</c>, + <c>gen_fsm</c>, and <c>gen_event</c> can also customise the value + of <c><anno>Misc</anno></c> by exporting a <c>format_status/2</c> + function that contributes module-specific information; + see <seealso marker="gen_server#Module:format_status/2">gen_server:format_status/2</seealso>, + <seealso marker="gen_fsm#Module:format_status/2">gen_fsm:format_status/2</seealso>, and + <seealso marker="gen_event#Module:format_status/2">gen_event:format_status/2</seealso> for more details.</p> </desc> </func> <func> + <name name="get_state" arity="1"/> + <name name="get_state" arity="2"/> + <fsummary>Get the state of the process</fsummary> + <desc> + <p>Gets the state of the process.</p> + <note> + <p>These functions are intended only to help with debugging. They are provided for + convenience, allowing developers to avoid having to create their own state extraction + functions and also avoid having to interactively extract state from the return values of + <c><seealso marker="#get_status-1">get_status/1</seealso></c> or + <c><seealso marker="#get_status-2">get_status/2</seealso></c> while debugging.</p> + </note> + <p>The value of <c><anno>State</anno></c> varies for different types of + processes. For a <c>gen_server</c> process, the returned <c><anno>State</anno></c> + is simply the callback module's state. For a <c>gen_fsm</c> process, + <c><anno>State</anno></c> is the tuple <c>{CurrentStateName, CurrentStateData}</c>. + For a <c>gen_event</c> process, <c><anno>State</anno></c> a list of tuples, + where each tuple corresponds to an event handler registered in the process and contains + <c>{Module, Id, HandlerState}</c>, where <c>Module</c> is the event handler's module name, + <c>Id</c> is the handler's ID (which is the value <c>false</c> if it was registered without + an ID), and <c>HandlerState</c> is the handler's state.</p> + <p>If the callback module exports a <c>system_get_state/1</c> function, it will be called in the + target process to get its state. Its argument is the same as the <c>Misc</c> value returned by + <seealso marker="#get_status-1">get_status/1,2</seealso>, and the <c>system_get_state/1</c> + function is expected to extract the callback module's state from it. The <c>system_get_state/1</c> + function must return <c>{ok, State}</c> where <c>State</c> is the callback module's state.</p> + <p>If the callback module does not export a <c>system_get_state/1</c> function, <c>get_state/1,2</c> + assumes the <c>Misc</c> value is the callback module's state and returns it directly instead.</p> + <p>If the callback module's <c>system_get_state/1</c> function crashes or throws an exception, the + caller exits with error <c>{callback_failed, {Module, system_get_state}, {Class, Reason}}</c> where + <c>Module</c> is the name of the callback module and <c>Class</c> and <c>Reason</c> indicate + details of the exception.</p> + <p>The <c>system_get_state/1</c> function is primarily useful for user-defined + behaviours and modules that implement OTP <seealso marker="#special_process">special + processes</seealso>. The <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_event</c> OTP + behaviour modules export this function, and so callback modules for those behaviours + need not supply their own.</p> + <p>To obtain more information about a process, including its state, see + <seealso marker="#get_status-1">get_status/1</seealso> and + <seealso marker="#get_status-2">get_status/2</seealso>.</p> + </desc> + </func> + <func> + <name name="replace_state" arity="2"/> + <name name="replace_state" arity="3"/> + <fsummary>Replace the state of the process</fsummary> + <desc> + <p>Replaces the state of the process, and returns the new state.</p> + <note> + <p>These functions are intended only to help with debugging, and they should not be + be called from normal code. They are provided for convenience, allowing developers + to avoid having to create their own custom state replacement functions.</p> + </note> + <p>The <c><anno>StateFun</anno></c> function provides a new state for the process. + The <c><anno>State</anno></c> argument and <c><anno>NewState</anno></c> return value + of <c><anno>StateFun</anno></c> vary for different types of processes. For a + <c>gen_server</c> process, <c><anno>State</anno></c> is simply the callback module's + state, and <c><anno>NewState</anno></c> is a new instance of that state. For a + <c>gen_fsm</c> process, <c><anno>State</anno></c> is the tuple + <c>{CurrentStateName, CurrentStateData}</c>, and <c><anno>NewState</anno></c> + is a similar tuple that may contain a new state name, new state data, or both. + For a <c>gen_event</c> process, <c><anno>State</anno></c> is the tuple + <c>{Module, Id, HandlerState}</c> where <c>Module</c> is the event handler's module name, + <c>Id</c> is the handler's ID (which is the value <c>false</c> if it was registered without + an ID), and <c>HandlerState</c> is the handler's state. <c><anno>NewState</anno></c> is a + similar tuple where <c>Module</c> and <c>Id</c> shall have the same values as in + <c><anno>State</anno></c> but the value of <c>HandlerState</c> may be different. Returning + a <c><anno>NewState</anno></c> whose <c>Module</c> or <c>Id</c> values differ from those of + <c><anno>State</anno></c> will result in the event handler's state remaining unchanged. For a + <c>gen_event</c> process, <c><anno>StateFun</anno></c> is called once for each event handler + registered in the <c>gen_event</c> process.</p> + <p>If a <c><anno>StateFun</anno></c> function decides not to effect any change in process + state, then regardless of process type, it may simply return its <c><anno>State</anno></c> + argument.</p> + <p>If a <c><anno>StateFun</anno></c> function crashes or throws an exception, then + for <c>gen_server</c> and <c>gen_fsm</c> processes, the original state of the process is + unchanged. For <c>gen_event</c> processes, a crashing or failing <c><anno>StateFun</anno></c> + function means that only the state of the particular event handler it was working on when it + failed or crashed is unchanged; it can still succeed in changing the states of other event + handlers registered in the same <c>gen_event</c> process.</p> + <p>If the callback module exports a <c>system_replace_state/2</c> function, it will be called in the + target process to replace its state using <c>StateFun</c>. Its two arguments are <c>StateFun</c> + and <c>Misc</c>, where <c>Misc</c> is the same as the <c>Misc</c> value returned by + <seealso marker="#get_status-1">get_status/1,2</seealso>. A <c>system_replace_state/2</c> function + is expected to return <c>{ok, NewState, NewMisc}</c> where <c>NewState</c> is the callback module's + new state obtained by calling <c>StateFun</c>, and <c>NewMisc</c> is a possibly new value used to + replace the original <c>Misc</c> (required since <c>Misc</c> often contains the callback + module's state within it).</p> + <p>If the callback module does not export a <c>system_replace_state/2</c> function, + <c>replace_state/2,3</c> assumes the <c>Misc</c> value is the callback module's state, passes it + to <c>StateFun</c> and uses the return value as both the new state and as the new value of + <c>Misc</c>.</p> + <p>If the callback module's <c>system_replace_state/2</c> function crashes or throws an exception, + the caller exits with error <c>{callback_failed, {Module, system_replace_state}, {Class, Reason}}</c> + where <c>Module</c> is the name of the callback module and <c>Class</c> and <c>Reason</c> indicate details + of the exception. If the callback module does not provide a <c>system_replace_state/2</c> function and + <c>StateFun</c> crashes or throws an exception, the caller exits with error + <c>{callback_failed, StateFun, {Class, Reason}}</c>.</p> + <p>The <c>system_replace_state/2</c> function is primarily useful for user-defined behaviours and + modules that implement OTP <seealso marker="#special_process">special processes</seealso>. The + <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_event</c> OTP behaviour modules export this function, + and so callback modules for those behaviours need not supply their own.</p> + </desc> + </func> + <func> <name name="install" arity="2"/> <name name="install" arity="3"/> <fsummary>Install a debug function in the process</fsummary> @@ -253,7 +363,7 @@ <section> <title>Process Implementation Functions</title> - <p>The following functions are used when implementing a + <p><marker id="special_process"/>The following functions are used when implementing a special process. This is an ordinary process which does not use a standard behaviour, but a process which understands the standard system messages.</p> </section> @@ -306,8 +416,9 @@ process continues the execution, or <c><anno>Module</anno>:system_terminate(Reason, <anno>Parent</anno>, <anno>Debug</anno>, <anno>Misc</anno>)</c> if the process should terminate. The <c><anno>Module</anno></c> must export - <c>system_continue/3</c>, <c>system_terminate/4</c>, and - <c>system_code_change/4</c> (see below). + <c>system_continue/3</c>, <c>system_terminate/4</c>, + <c>system_code_change/4</c>, <c>system_get_state/1</c> and + <c>system_replace_state/2</c> (see below). </p> <p>The <c><anno>Misc</anno></c> argument can be used to save internal data in a process, for example its state. It is sent to @@ -375,6 +486,34 @@ defined, the atom <c>undefined</c> is sent.</p> </desc> </func> + <func> + <name>Mod:system_get_state(Misc) -> {ok, State}</name> + <fsummary>Called when the process should return its current state</fsummary> + <type> + <v>Misc = term()</v> + <v>State = term()</v> + </type> + <desc> + <p>This function is called from <c>sys:handle_system_msg/6</c> when the process + should return a term that reflects its current state. <c>State</c> is the + value returned by <c>sys:get_state/2</c>.</p> + </desc> + </func> + <func> + <name>Mod:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}</name> + <fsummary>Called when the process should replace its current state</fsummary> + <type> + <v>StateFun = fun((State :: term()) -> NState)</v> + <v>Misc = term()</v> + <v>NState = term()</v> + <v>NMisc = term()</v> + </type> + <desc> + <p>This function is called from <c>sys:handle_system_msg/6</c> when the process + should replace its current state. <c>NState</c> is the value returned by + <c>sys:replace_state/3</c>.</p> + </desc> + </func> </funcs> </erlref> diff --git a/lib/stdlib/doc/src/timer.xml b/lib/stdlib/doc/src/timer.xml index 0c1e398dc4..eca9a72d36 100644 --- a/lib/stdlib/doc/src/timer.xml +++ b/lib/stdlib/doc/src/timer.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/unicode.xml b/lib/stdlib/doc/src/unicode.xml index 1001ebbae4..6f8a289432 100644 --- a/lib/stdlib/doc/src/unicode.xml +++ b/lib/stdlib/doc/src/unicode.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -32,9 +32,9 @@ <module>unicode</module> <modulesummary>Functions for converting Unicode characters</modulesummary> <description> - <p>This module contains functions for converting between different character representations. Basically it converts between iso-latin-1 characters and Unicode ditto, but it can also convert between different Unicode encodings (like UTF-8, UTF-16 and UTF-32).</p> + <p>This module contains functions for converting between different character representations. Basically it converts between ISO-latin-1 characters and Unicode ditto, but it can also convert between different Unicode encodings (like UTF-8, UTF-16 and UTF-32).</p> <p>The default Unicode encoding in Erlang is in binaries UTF-8, which is also the format in which built in functions and libraries in OTP expect to find binary Unicode data. In lists, Unicode data is encoded as integers, each integer representing one character and encoded simply as the Unicode codepoint for the character.</p> - <p>Other Unicode encodings than integers representing codepoints or UTF-8 in binaries are referred to as "external encodings". The iso-latin-1 encoding is in binaries and lists referred to as latin1-encoding.</p> + <p>Other Unicode encodings than integers representing codepoints or UTF-8 in binaries are referred to as "external encodings". The ISO-latin-1 encoding is in binaries and lists referred to as latin1-encoding.</p> <p>It is recommended to only use external encodings for communication with external entities where this is required. When working inside the Erlang/OTP environment, it is recommended to keep binaries in UTF-8 when representing Unicode characters. Latin1 encoding is supported both for backward compatibility and for communication with external entities not supporting Unicode character sets.</p> </description> @@ -48,13 +48,7 @@ <datatype> <name name="unicode_binary"/> <desc> - <p>A binary() with characters encoded in the UTF-8 coding standard.</p> - </desc> - </datatype> - <datatype> - <name name="unicode_char"/> - <desc> - <p>An integer() representing a valid unicode codepoint.</p> + <p>A <c>binary()</c> with characters encoded in the UTF-8 coding standard.</p> </desc> </datatype> <datatype> @@ -62,9 +56,6 @@ </datatype> <datatype> <name name="charlist"/> - <desc> - <p>A unicode_binary is allowed as the tail of the list.</p> - </desc> </datatype> <datatype> <name name="external_unicode_binary"/> @@ -78,14 +69,10 @@ </datatype> <datatype> <name name="external_charlist"/> - <desc> - <p>An <c>external_unicode_binary()</c> is allowed as the tail - of the list.</p> - </desc> </datatype> <datatype> <name name="latin1_binary"/> - <desc><p>A <c>binary()</c> with characters coded in iso-latin-1.</p> + <desc><p>A <c>binary()</c> with characters coded in ISO-latin-1.</p> </desc> </datatype> <datatype> @@ -96,11 +83,12 @@ </datatype> <datatype> <name name="latin1_chardata"/> + <desc><p>The same as <c>iodata()</c>.</p> + </desc> </datatype> <datatype> <name name="latin1_charlist"/> - <desc><p>A <c>latin1_binary()</c> is allowed as the tail of - the list.</p> + <desc><p>The same as <c>iolist()</c>.</p> </desc> </datatype> </datatypes> @@ -110,7 +98,9 @@ <name name="bom_to_encoding" arity="1"/> <fsummary>Identify UTF byte order marks in a binary.</fsummary> <type name="endian"/> - <type_desc variable="Bin">A binary() of byte_size 4 or more.</type_desc> + <type_desc variable="Bin"> + A <c>binary()</c> such that <c>byte_size(<anno>Bin</anno>) >= 4</c>. + </type_desc> <desc> <p>Check for a UTF byte order mark (BOM) in the beginning of a @@ -126,50 +116,40 @@ <name name="characters_to_list" arity="1"/> <fsummary>Convert a collection of characters to list of Unicode characters</fsummary> <desc> - <p>Same as characters_to_list(<anno>Data</anno>,unicode).</p> + <p>Same as <c>characters_to_list(<anno>Data</anno>, unicode)</c>.</p> </desc> </func> <func> - <name>characters_to_list(Data, InEncoding) -> Result</name> + <name name="characters_to_list" arity="2"/> <fsummary>Convert a collection of characters to list of Unicode characters</fsummary> - <type> - <v>Data = <seealso marker="#type-latin1_chardata">latin1_chardata()</seealso> - | <seealso marker="#type-chardata">chardata()</seealso> - | <seealso marker="#type-external_chardata">external_chardata()</seealso></v> - <v>Result = list() | {error, list(), RestData} | {incomplete, list(), binary()}</v> - <v>RestData = <seealso marker="#type-latin1_chardata">latin1_chardata()</seealso> - | <seealso marker="#type-chardata">chardata()</seealso> - | <seealso marker="#type-external_chardata">external_chardata()</seealso></v> - <v>InEncoding = <seealso marker="#type-encoding">encoding()</seealso></v> - </type> <desc> - <p>This function converts a possibly deep list of integers and - binaries into a list of integers representing unicode + <p>Converts a possibly deep list of integers and + binaries into a list of integers representing Unicode characters. The binaries in the input may have characters encoded as latin1 (0 - 255, one character per byte), in which - case the <c>InEncoding</c> parameter should be given as + case the <c><anno>InEncoding</anno></c> parameter should be given as <c>latin1</c>, or have characters encoded as one of the - UTF-encodings, which is given as the <c>InEncoding</c> - parameter. Only when the <c>InEncoding</c> is one of the UTF + UTF-encodings, which is given as the <c><anno>InEncoding</anno></c> + parameter. Only when the <c><anno>InEncoding</anno></c> is one of the UTF encodings, integers in the list are allowed to be grater than 255.</p> - <p>If <c>InEncoding</c> is <c>latin1</c>, the <c>Data</c> parameter + <p>If <c><anno>InEncoding</anno></c> is <c>latin1</c>, the <c><anno>Data</anno></c> parameter corresponds to the <c>iodata()</c> type, but for <c>unicode</c>, - the <c>Data</c> parameter can contain integers greater than 255 - (unicode characters beyond the iso-latin-1 range), which would + the <c><anno>Data</anno></c> parameter can contain integers greater than 255 + (Unicode characters beyond the ISO-latin-1 range), which would make it invalid as <c>iodata()</c>.</p> <p>The purpose of the function is mainly to be able to convert - combinations of unicode characters into a pure unicode + combinations of Unicode characters into a pure Unicode string in list representation for further processing. For writing the data to an external entity, the reverse function <seealso - marker="#characters_to_binary/3">characters_to_binary/3</seealso> + marker="#characters_to_binary/3"><c>characters_to_binary/3</c></seealso> comes in handy.</p> - <p>The option <c>unicode</c> is an alias for <c>utf8</c>, as this is the + <p>The option <c>unicode</c> is an alias for <c>utf8</c>, as this is the preferred encoding for Unicode characters in binaries. <c>utf16</c> is an alias for <c>{utf16,big}</c> and <c>utf32</c> is an alias for <c>{utf32,big}</c>. The <c>big</c> @@ -177,7 +157,7 @@ encoding.</p> <p>If for some reason, the data cannot be converted, either - because of illegal unicode/latin1 characters in the list, or + because of illegal Unicode/latin1 characters in the list, or because of invalid UTF encoding in any binaries, an error tuple is returned. The error tuple contains the tag <c>error</c>, a list representing the characters that could be @@ -186,43 +166,43 @@ last part is mostly for debugging as it still constitutes a possibly deep and/or mixed list, not necessarily of the same depth as the original data. The error occurs when traversing the - list and whatever's left to decode is simply returned as is.</p> + list and whatever is left to decode is simply returned as is.</p> - <p>However, if the input <c>Data</c> is a pure binary, the third + <p>However, if the input <c><anno>Data</anno></c> is a pure binary, the third part of the error tuple is guaranteed to be a binary as well.</p> <p>Errors occur for the following reasons:</p> <list type="bulleted"> - <item>Integers out of range - If <c>InEncoding</c> is + <item>Integers out of range - If <c><anno>InEncoding</anno></c> is <c>latin1</c>, an error occurs whenever an integer greater - than 255 is found in the lists. If <c>InEncoding</c> is + than 255 is found in the lists. If <c><anno>InEncoding</anno></c> is of a Unicode type, an error occurs whenever an integer <list type="bulleted"> <item>greater than <c>16#10FFFF</c> - (the maximum unicode character),</item> + (the maximum Unicode character),</item> <item>in the range <c>16#D800</c> to <c>16#DFFF</c> (invalid range reserved for UTF-16 surrogate pairs)</item> </list> is found. </item> - <item>UTF encoding incorrect - If <c>InEncoding</c> is + <item>UTF encoding incorrect - If <c><anno>InEncoding</anno></c> is one of the UTF types, the bytes in any binaries have to be valid in that encoding. Errors can occur for various reasons, including "pure" decoding errors (like the upper bits of the bytes being wrong), the bytes are decoded to a too large number, the bytes are decoded to a code-point in the - invalid unicode - range or encoding is "overlong", meaning that a + invalid Unicode + range, or encoding is "overlong", meaning that a number should have been encoded in fewer bytes. The case of a truncated UTF is handled specially, see the paragraph about incomplete binaries below. If - <c>InEncoding</c> is <c>latin1</c>, binaries are always valid + <c><anno>InEncoding</anno></c> is <c>latin1</c>, binaries are always valid as long as they contain whole bytes, - as each byte falls into the valid iso-latin-1 range.</item> + as each byte falls into the valid ISO-latin-1 range.</item> </list> @@ -238,7 +218,7 @@ the first part of a (so far) valid UTF character.</p> <p>If one UTF characters is split over two consecutive - binaries in the <c>Data</c>, the conversion succeeds. This means + binaries in the <c><anno>Data</anno></c>, the conversion succeeds. This means that a character can be decoded from a range of binaries as long as the whole range is given as input without errors occurring. Example:</p> @@ -260,7 +240,7 @@ ever be decoded.</p> <p>If any parameters are of the wrong type, the list structure - is invalid (a number as tail) or the binaries does not contain + is invalid (a number as tail) or the binaries do not contain whole bytes (bit-strings), a <c>badarg</c> exception is thrown.</p> @@ -268,38 +248,27 @@ </func> <func> <name name="characters_to_binary" arity="1"/> - <fsummary>Convert a collection of characters to an UTF-8 binary</fsummary> + <fsummary>Convert a collection of characters to a UTF-8 binary</fsummary> <desc> - <p>Same as characters_to_binary(Data, unicode, unicode).</p> + <p>Same as <c>characters_to_binary(<anno>Data</anno>, unicode, unicode)</c>.</p> </desc> </func> <func> - <name>characters_to_binary(Data,InEncoding) -> Result</name> - <fsummary>Convert a collection of characters to an UTF-8 binary</fsummary> + <name name="characters_to_binary" arity="2"/> + <fsummary>Convert a collection of characters to a UTF-8 binary</fsummary> - <type> - <v>Data = <seealso marker="#type-latin1_chardata">latin1_chardata()</seealso> - | <seealso marker="#type-chardata">chardata()</seealso> - | <seealso marker="#type-external_chardata">external_chardata()</seealso></v> - <v>Result = binary() | {error, binary(), RestData} | {incomplete, binary(), binary()}</v> - <v>RestData = <seealso marker="#type-latin1_chardata">latin1_chardata()</seealso> - | <seealso marker="#type-chardata">chardata()</seealso> - | <seealso marker="#type-external_chardata">external_chardata()</seealso></v> - <v>InEncoding = <seealso marker="#type-encoding">encoding()</seealso></v> - </type> <desc> - <p>Same as characters_to_binary(Data, InEncoding, unicode).</p> + <p>Same as <c>characters_to_binary(<anno>Data</anno>, <anno>InEncoding</anno>, unicode)</c>.</p> </desc> </func> <func> <name name="characters_to_binary" arity="3"/> - <fsummary>Convert a collection of characters to an UTF-8 binary</fsummary> + <fsummary>Convert a collection of characters to a UTF-8 binary</fsummary> <desc> - <p>This function behaves as <seealso - marker="#characters_to_list/2"> - characters_to_list/2</seealso>, but produces an binary - instead of a unicode list. The + <p>Behaves as <seealso marker="#characters_to_list/2"> + <c>characters_to_list/2</c></seealso>, but produces an binary + instead of a Unicode list. The <c><anno>InEncoding</anno></c> defines how input is to be interpreted if binaries are present in the <c>Data</c>, while <c><anno>OutEncoding</anno></c> defines in what format output is to be @@ -314,7 +283,7 @@ <p>Errors and exceptions occur as in <seealso marker="#characters_to_list/2"> - characters_to_list/2</seealso>, but the second element + <c>characters_to_list/2</c></seealso>, but the second element in the <c>error</c> or <c>incomplete</c> tuple will be a <c>binary()</c> and not a <c>list()</c>.</p> @@ -324,16 +293,18 @@ <func> <name name="encoding_to_bom" arity="1"/> <fsummary>Create a binary UTF byte order mark from encoding.</fsummary> - <type_desc variable="Bin">A binary() of byte_size 4 or more.</type_desc> + <type_desc variable="Bin"> + A <c>binary()</c> such that <c>byte_size(<anno>Bin</anno>) >= 4</c>. + </type_desc> <desc> - <p>Create an UTF byte order mark (BOM) as a binary from the + <p>Create a UTF byte order mark (BOM) as a binary from the supplied <c><anno>InEncoding</anno></c>. The BOM is, if supported at all, expected to be placed first in UTF encoded files or messages.</p> <p>The function returns <c><<>></c> for the - <c>latin1</c> encoding, there is no BOM for ISO-latin-1.</p> + <c>latin1</c> encoding as there is no BOM for ISO-latin-1.</p> <p>It can be noted that the BOM for UTF-8 is seldom used, and it is really not a <em>byte order</em> mark. There are obviously no diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index bbcd49a934..bebfbd4514 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -1,11 +1,11 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> <header> <copyright> <year>1999</year> - <year>2012</year> + <year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,226 +32,1090 @@ <rev>PA1</rev> <file>unicode_usage.xml</file> </header> -<p>Implementing support for Unicode character sets is an ongoing process. The Erlang Enhancement Proposal (EEP) 10 outlines the basics of Unicode support and also specifies a default encoding in binaries that all Unicode-aware modules should handle in the future.</p> -<p>The functionality described in EEP10 is implemented in Erlang/OTP as of R13A, but that's by no means the end of it. More functionality will be needed in the future and more OTP-libraries might need updating to cope with Unicode data. One example of future development is obvious when reading this manual, our documentation format is limited to the ISO-latin-1 character range, why no Unicode characters beyond that range will occur in this document.</p> -<p>This guide outlines the current Unicode support and gives a couple of recipes for working with Unicode data.</p> <section> -<title>What Unicode is</title> -<p>Unicode is a standard defining codepoints (numbers) for all known, living or dead, scripts. In principle, every known symbol used in any language has a Unicode codepoint.</p> -<p>Unicode codepoints are defined and published by the <em>Unicode Consortium</em>, which is a non profit organization.</p> -<p>Support for Unicode is increasing throughout the world of computing, as the benefits of one common character set are overwhelming when programs are used in a global environment.</p> -<p>Along with the base of the standard, the codepoints for all the scripts, there are a couple of encoding standards available. Different operating systems and tools support different encodings. For example Linux and MacOS X has chosen the UTF-8 encoding, which is backwards compatible with 7-bit ASCII and therefore affects programs written in plain English the least. Windows® on the other hand supports a limited version of UTF-16, namely all the code planes where the characters can be stored in one single 16-bit entity, which includes most living languages.</p> -<p>The most widely spread encodings are:</p> -<taglist> -<tag>UTF-8</tag> -<item>Each character is stored in one to four bytes depending on codepoint. The encoding is backwards compatible with 7-bit ASCII as all 7-bit characters are stored in one single byte as is. The characters beyond codepoint 127 are stored in more bytes, letting the most significant bit in the first character indicate a multi-byte character. For details on the encoding, the RFC is publicly available.</item> -<tag>UTF-16</tag> -<item>This encoding has many similarities to UTF-8, but the basic unit is a 16-bit number. This means that all characters occupy at least two bytes, some high numbers even four bytes. Some programs and operating systems claiming to use UTF-16 only allows for characters that can be stored in one 16-bit entity, which is usually sufficient to handle living languages. As the basic unit is more than one byte, byte-order issues occur, why UTF-16 exists in both a big-endian and little-endian variant.</item> -<tag>UTF-32</tag> -<item>The most straight forward representation, each character is stored in one single 32-bit number. There is no need for escapes or any variable amount of entities for one character, all Unicode codepoints can be stored in one single 32-bit entity. As with UTF-16, there are byte-order issues, UTF-32 can be both big- and little-endian.</item> -<tag>UCS-4</tag> -<item>Basically the same as UTF-32, but without some Unicode semantics, defined by IEEE and has little use as a separate encoding standard. For all normal (and possibly abnormal) usages, UTF-32 and UCS-4 are interchangeable.</item> -</taglist> -<p>Certain ranges of characters are left unused and certain ranges are even deemed invalid. The most notable invalid range is 16#D800 - 16#DFFF, as the UTF-16 encoding does not allow for encoding of these numbers. It can be speculated that the UTF-16 encoding standard was, from the beginning, expected to be able to hold all Unicode characters in one 16-bit entity, but then had to be extended, leaving a hole in the Unicode range to cope with backward compatibility.</p> -<p>Additionally, the codepoint 16#FEFF is used for byte order marks (BOM's) and use of that character is not encouraged in other contexts than that. It actually is valid though, as the character "ZWNBS" (Zero Width Non Breaking Space). BOM's are used to identify encodings and byte order for programs where such parameters are not known in advance. Byte order marks are more seldom used than one could expect, but their use is becoming more widely spread as they provide the means for programs to make educated guesses about the Unicode format of a certain file.</p> +<title>Unicode Implementation</title> + <p>Implementing support for Unicode character sets is an ongoing + process. The Erlang Enhancement Proposal (EEP) 10 outlined the + basics of Unicode support and also specified a default encoding in + binaries that all Unicode-aware modules should handle in the + future.</p> + + <p>The functionality described in EEP10 was implemented in Erlang/OTP + R13A, but that was by no means the end of it. In Erlang/OTP R14B01 support + for Unicode file names was added, although it was in no way complete + and was by default disabled on platforms where no guarantee was given + for the file name encoding. With Erlang/OTP R16A came support for UTF-8 encoded + source code, among with enhancements to many of the applications to + support both Unicode encoded file names as well as support for UTF-8 + encoded files in several circumstances. Most notable is the support + for UTF-8 in files read by <c>file:consult/1</c>, release handler support + for UTF-8 and more support for Unicode character sets in the + I/O-system.</p> + + <p>In Erlang/OTP 17.0, the encoding default for Erlang source files was + switched to UTF-8 and in Erlang/OTP 18.0 Erlang will support atoms in the full + Unicode range, meaning full Unicode function and module + names</p> + + <p>This guide outlines the current Unicode support and gives a couple + of recipes for working with Unicode data.</p> +</section> +<section> +<title>Understanding Unicode</title> + <p>Experience with the Unicode support in Erlang has made it + painfully clear that understanding Unicode characters and encodings + is not as easy as one would expect. The complexity of the field as + well as the implications of the standard requires thorough + understanding of concepts rarely before thought of.</p> + + <p>Furthermore the Erlang implementation requires understanding of + concepts that never were an issue for many (Erlang) programmers. To + understand and use Unicode characters requires that you study the + subject thoroughly, even if you're an experienced programmer.</p> + + <p>As an example, one could contemplate the issue of converting + between upper and lower case letters. Reading the standard will make + you realize that, to begin with, there's not a simple one to one + mapping in all scripts. Take German as an example, where there's a + letter "ß" (Sharp s) in lower case, but the uppercase equivalent is + "SS". Or Greek, where "Σ" has two different lowercase forms: "ς" in + word-final position and "σ" elsewhere. Or Turkish where dotted and + dot-less "i" both exist in lower case and upper case forms, or + Cyrillic "I" which usually has no lowercase form. Or of course + languages that have no concept of upper case (or lower case). So, a + conversion function will need to know not only one character at a + time, but possibly the whole sentence, maybe the natural language + the translation should be in and also take into account differences + in input and output string length and so on. There is at the time of + writing no Unicode to_upper/to_lower functionality in Erlang/OTP, but + there are publicly available libraries that address these issues.</p> + + <p>Another example is the accented characters where the same glyph + has two different representations. Let's look at the Swedish + "ö". There's a code point for that in the Unicode standard, but you + can also write it as "o" followed by U+0308 (Combining Diaeresis, + with the simplified meaning that the last letter should have a "¨" + above). They have exactly the same glyph. They are for most + purposes the same, but they have completely different + representations. For example MacOS X converts all file names to use + Combining Diaeresis, while most other programs (including Erlang) + try to hide that by doing the opposite when for example listing + directories. However it's done, it's usually important to normalize + such characters to avoid utter confusion.</p> + + <p>The list of examples can be made as long as the Unicode standard, I + suspect. The point is that one need a kind of knowledge that was + never needed when programs only took one or two languages into + account. The complexity of human languages and scripts, certainly + has made this a challenge when constructing a universal + standard. Supporting Unicode properly in your program <em>will</em> require + effort.</p> + </section> <section> -<title>Standard Unicode representation in Erlang</title> -<p>In Erlang, strings are actually lists of integers. A string is defined to be encoded in the ISO-latin-1 (ISO8859-1) character set, which is, codepoint by codepoint, a sub-range of the Unicode character set.</p> -<p>The standard list encoding for strings is therefore easily extendible to cope with the whole Unicode range: A Unicode string in Erlang is simply a list containing integers, each integer being a valid Unicode codepoint and representing one character in the Unicode character set.</p> -<p>Regular Erlang strings in ISO-latin-1 are a subset of their Unicode strings.</p> +<title>What Unicode Is</title> + <p>Unicode is a standard defining code points (numbers) for all + known, living or dead, scripts. In principle, every known symbol + used in any language has a Unicode code point.</p> + <p>Unicode code points are defined and published by the <em>Unicode + Consortium</em>, which is a non profit organization.</p> + <p>Support for Unicode is increasing throughout the world of + computing, as the benefits of one common character set are + overwhelming when programs are used in a global environment.</p> + <p>Along with the base of the standard: the code points for all the + scripts, there are a couple of <em>encoding standards</em> available.</p> + <p>It is vital to understand the difference between encodings and + Unicode characters. Unicode characters are code points according to + the Unicode standard, while the encodings are ways to represent such + code points. An encoding is just a standard for representation, + UTF-8 can for example be used to represent a very limited part of + the Unicode character set (e.g. ISO-Latin-1), or the full Unicode + range. It's just an encoding format.</p> + <p>As long as all character sets were limited to 256 characters, + each character could be stored in one single byte, so there was more + or less only one practical encoding for the characters. Encoding + each character in one byte was so common that the encoding wasn't + even named. When we now, with the Unicode system, have a lot more + than 256 characters, we need a common way to represent these. The + common ways of representing the code points are the encodings. This + means a whole new concept to the programmer, the concept of + character representation, which was before a non-issue.</p> -<p>Binaries on the other hand are more troublesome. For performance reasons, programs often store textual data in binaries instead of lists, mainly because they are more compact (one byte per character instead of two words per character, as is the case with lists). Using erlang:list_to_binary/1, an regular Erlang string can be converted into a binary, effectively using the ISO-latin-1 encoding in the binary - one byte per character. This is very convenient for those regular Erlang strings, but cannot be done for Unicode lists.</p> -<p>As the UTF-8 encoding is widely spread and provides the most compact storage, it is selected as the standard encoding of Unicode characters in binaries for Erlang.</p> -<p>The standard binary encoding is used whenever a library function in Erlang should cope with Unicode data in binaries, but is of course not enforced when communicating externally. Functions and bit-syntax exist to encode and decode both UTF-8, UTF-16 and UTF-32 in binaries. Library functions dealing with binaries and Unicode in general, however, only deal with the default encoding.</p> + <p>Different operating systems and tools support different + encodings. For example Linux and MacOS X has chosen the UTF-8 + encoding, which is backwards compatible with 7-bit ASCII and + therefore affects programs written in plain English the + least. Windows on the other hand supports a limited version of + UTF-16, namely all the code planes where the characters can be + stored in one single 16-bit entity, which includes most living + languages.</p> -<p>Character data may be combined from several sources, sometimes available in a mix of strings and binaries. Erlang has for long had the concept of iodata or iolists, where binaries and lists can be combined to represent a sequence of bytes. In the same way, the Unicode aware modules often allow for combinations of binaries and lists where the binaries have characters encoded in UTF-8 and the lists contain such binaries or numbers representing Unicode codepoints:</p> -<code type="none"> + <p>The most widely spread encodings are:</p> + <taglist> + <tag>Bytewise representation</tag> + <item>This is not a proper Unicode representation, but the + representation used for characters before the Unicode standard. It + can still be used to represent character code points in the Unicode + standard that have numbers below 256, which corresponds exactly to + the ISO-Latin-1 character set. In Erlang, this is commonly denoted + <c>latin1</c> encoding, which is slightly misleading as ISO-Latin-1 is + a character code range, not an encoding.</item> + <tag>UTF-8</tag> + <item>Each character is stored in one to four bytes depending on + code point. The encoding is backwards compatible with bytewise + representation of 7-bit ASCII as all 7-bit characters are stored + in one single byte in UTF-8. The characters beyond code point 127 + are stored in more bytes, letting the most significant bit in the + first character indicate a multi-byte character. For details on + the encoding, the RFC is publicly available. Note that UTF-8 is + <em>not</em> compatible with bytewise representation for + code points between 128 and 255, so a ISO-Latin-1 bytewise + representation is not generally compatible with UTF-8.</item> + <tag>UTF-16</tag> + <item>This encoding has many similarities to UTF-8, but the basic + unit is a 16-bit number. This means that all characters occupy at + least two bytes, some high numbers even four bytes. Some programs, + libraries and operating systems claiming to use UTF-16 only allows + for characters that can be stored in one 16-bit entity, which is + usually sufficient to handle living languages. As the basic unit + is more than one byte, byte-order issues occur, why UTF-16 exists + in both a big-endian and little-endian variant. In Erlang, the + full UTF-16 range is supported when applicable, like in the + <c>unicode</c> module and in the bit syntax.</item> + <tag>UTF-32</tag> + <item>The most straight forward representation. Each character is + stored in one single 32-bit number. There is no need for escapes + or any variable amount of entities for one character, all Unicode + code points can be stored in one single 32-bit entity. As with + UTF-16, there are byte-order issues, UTF-32 can be both big- and + little-endian.</item> + <tag>UCS-4</tag> + <item>Basically the same as UTF-32, but without some Unicode + semantics, defined by IEEE and has little use as a separate + encoding standard. For all normal (and possibly abnormal) usages, + UTF-32 and UCS-4 are interchangeable.</item> + </taglist> + <p>Certain ranges of numbers are left unused in the Unicode standard + and certain ranges are even deemed invalid. The most notable invalid + range is 16#D800 - 16#DFFF, as the UTF-16 encoding does not allow + for encoding of these numbers. It can be speculated that the UTF-16 + encoding standard was, from the beginning, expected to be able to + hold all Unicode characters in one 16-bit entity, but then had to be + extended, leaving a hole in the Unicode range to cope with backward + compatibility.</p> + <p>Additionally, the code point 16#FEFF is used for byte order marks + (BOM's) and use of that character is not encouraged in other + contexts than that. It actually is valid though, as the character + "ZWNBS" (Zero Width Non Breaking Space). BOM's are used to identify + encodings and byte order for programs where such parameters are not + known in advance. Byte order marks are more seldom used than one + could expect, but their use might become more widely spread as they + provide the means for programs to make educated guesses about the + Unicode format of a certain file.</p> +</section> +<section> + <title>Areas of Unicode Support</title> + <p>To support Unicode in Erlang, problems in several areas have been + addressed. Each area is described briefly in this section and more + thoroughly further down in this document:</p> + <taglist> + <tag>Representation</tag> + <item>To handle Unicode characters in Erlang, we have to have a + common representation both in lists and binaries. The EEP (10) and + the subsequent initial implementation in Erlang/OTP R13A settled a standard + representation of Unicode characters in Erlang.</item> + <tag>Manipulation</tag> + <item>The Unicode characters need to be processed by the Erlang + program, why library functions need to be able to handle them. In + some cases functionality was added to already existing interfaces + (as the string module now can handle lists with arbitrary code points), + in some cases new functionality or options need to be added (as in + the <c>io</c>-module, the file handling, the <c>unicode</c> module + and the bit syntax). Today most modules in kernel and STDLIB, as + well as the VM are Unicode aware.</item> + <tag>File I/O</tag> + <item>I/O is by far the most problematic area for Unicode. A file + is an entity where bytes are stored and the lore of programming + has been to treat characters and bytes as interchangeable. With + Unicode characters, you need to decide on an encoding as soon as + you want to store the data in a file. In Erlang you can open a + text file with an encoding option, so that you can read characters + from it rather than bytes, but you can also open a file for + bytewise I/O. The I/O-system of Erlang has been designed (or at + least used) in a way where you expect any I/O-server to be + able to cope with any string data, but that is no longer the case + when you work with Unicode characters. Handling the fact that you + need to know the capabilities of the device where your data ends + up is something new to the Erlang programmer. Furthermore, ports + in Erlang are byte oriented, so an arbitrary string of (Unicode) + characters can not be sent to a port without first converting it + to an encoding of choice.</item> + <tag>Terminal I/O</tag> + <item>Terminal I/O is slightly easier than file I/O. The output is + meant for human reading and is usually Erlang syntax (e.g. in the + shell). There exists syntactic representation of any Unicode + character without actually displaying the glyph (instead written + as <c>\x{</c>HHH<c>}</c>), so Unicode data can usually be displayed + even if the terminal as such do not support the whole Unicode + range.</item> + <tag>File names</tag> + <item>File names can be stored as Unicode strings, in different + ways depending on the underlying OS and file system. This can be + handled fairly easy by a program. The problems arise when the file + system is not consistent in it's encodings, like for example + Linux. Linux allows files to be named with any sequence of bytes, + leaving to each program to interpret those bytes. On systems where + these "transparent" file names are used, Erlang has to be informed + about the file name encoding by a startup flag. The default is + bytewise interpretation, which is actually usually wrong, but + allows for interpretation of <em>all</em> file names. The concept + of "raw file names" can be used to handle wrongly encoded + file names if one enables Unicode file name translation + (<c>+fnu</c>) on platforms where this is not the default.</item> + <tag>Source code encoding</tag> + <item>When it comes to the Erlang source code, there is support + for the UTF-8 encoding and bytewise encoding. The default in + Erlang/OTP R16B was bytewise (or latin1) encoding; in Erlang/OTP 17.0 + it was changed to UTF-8. You can control the encoding by a comment like: +<code> +%% -*- coding: utf-8 -*- +</code> + in the beginning of the file. This of course requires your editor to + support UTF-8 as well. The same comment is also interpreted by + functions like <c>file:consult/1</c>, the release handler etc, so that + you can have all text files in your source directories in UTF-8 + encoding. + </item> + <tag>The language</tag> + <item>Having the source code in UTF-8 also allows you to write + string literals containing Unicode characters with code points > + 255, although atoms, module names and function names will be + restricted to the ISO-Latin-1 range until the Erlang/OTP 18.0 release. Binary + literals where you use the <c>/utf8</c> type, can also be + expressed using Unicode characters > 255. Having module names + using characters other than 7-bit ASCII can cause trouble on + operating systems with inconsistent file naming schemes, and might + also hurt portability, so it's not really recommended. It is + suggested in EEP 40 that the language should also allow for + Unicode characters > 255 in variable names. Whether to + implement that EEP or not is yet to be decided.</item> + </taglist> +</section> +<section> + <title>Standard Unicode Representation</title> + <p>In Erlang, strings are actually lists of integers. A string was + up until Erlang/OTP R13 defined to be encoded in the ISO-latin-1 (ISO8859-1) + character set, which is, code point by code point, a sub-range of + the Unicode character set.</p> + <p>The standard list encoding for strings was therefore easily + extended to cope with the whole Unicode range: A Unicode string in + Erlang is simply a list containing integers, each integer being a + valid Unicode code point and representing one character in the + Unicode character set.</p> + <p>Erlang strings in ISO-latin-1 are a subset of Unicode + strings.</p> + <p>Only if a string contains code points < 256, can it be + directly converted to a binary by using + i.e. <c>erlang:iolist_to_binary/1</c> or can be sent directly to a + port. If the string contains Unicode characters > 255, an + encoding has to be decided upon and the string should be converted + to a binary in the preferred encoding using + <c>unicode:characters_to_binary/{1,2,3}</c>. Strings are not + generally lists of bytes, as they were before Erlang/OTP R13. They are lists of + characters. Characters are not generally bytes, they are Unicode + code points.</p> + + <p>Binaries are more troublesome. For performance reasons, programs + often store textual data in binaries instead of lists, mainly + because they are more compact (one byte per character instead of two + words per character, as is the case with lists). Using + <c>erlang:list_to_binary/1</c>, an ISO-Latin-1 Erlang string could + be converted into a binary, effectively using bytewise encoding - + one byte per character. This was very convenient for those limited + Erlang strings, but cannot be done for arbitrary Unicode lists.</p> + <p>As the UTF-8 encoding is widely spread and provides some backward + compatibility in the 7-bit ASCII range, it is selected as the + standard encoding for Unicode characters in binaries for Erlang.</p> + <p>The standard binary encoding is used whenever a library function + in Erlang should cope with Unicode data in binaries, but is of + course not enforced when communicating externally. Functions and + bit-syntax exist to encode and decode both UTF-8, UTF-16 and UTF-32 + in binaries. Library functions dealing with binaries and Unicode in + general, however, only deal with the default encoding.</p> + + <p>Character data may be combined from several sources, sometimes + available in a mix of strings and binaries. Erlang has for long had + the concept of <c>iodata</c> or <c>iolist</c>s, where binaries and + lists can be combined to represent a sequence of bytes. In the same + way, the Unicode aware modules often allow for combinations of + binaries and lists where the binaries have characters encoded in + UTF-8 and the lists contain such binaries or numbers representing + Unicode code points:</p> + <code type="none"> unicode_binary() = binary() with characters encoded in UTF-8 coding standard -unicode_char() = integer() representing valid unicode codepoint chardata() = charlist() | unicode_binary() -charlist() = [unicode_char() | unicode_binary() | charlist()] - a unicode_binary is allowed as the tail of the list</code> -<p>The module <c>unicode</c> in stdlib even supports similar mixes with binaries containing other encodings than UTF-8, but that is a special case to allow for conversions to and from external data:</p> - <code type="none"> -external_unicode_binary() = binary() with characters coded in a user specified Unicode - encoding other than UTF-8 (UTF-16 or UTF-32) +charlist() = maybe_improper_list(char() | unicode_binary() | charlist(), + unicode_binary() | nil())</code> + <p>The module <seealso + marker="stdlib:unicode"><c>unicode</c></seealso> in STDLIB even + supports similar mixes with binaries containing other encodings than + UTF-8, but that is a special case to allow for conversions to and + from external data:</p> + <code type="none"> +external_unicode_binary() = binary() with characters coded in + a user specified Unicode encoding other than UTF-8 (UTF-16 or UTF-32) external_chardata() = external_charlist() | external_unicode_binary() -external_charlist() = [unicode_char() | external_unicode_binary() | external_charlist()] - an external_unicode_binary is allowed as the tail of the list</code> +external_charlist() = maybe_improper_list(char() | + external_unicode_binary() | + external_charlist(), + external_unicode_binary() | nil())</code> </section> <section> -<title>Basic language support for Unicode</title> -<p>First of all, Erlang is still defined to be written in the ISO-latin-1 character set. Functions have to be named in that character set, atoms are restricted to ISO-latin-1 and regular strings are still lists of characters 0..255 in the ISO-latin-1 encoding. This has not (yet) changed, but the language has been slightly extended to cope with Unicode characters and encodings.</p> - -<section> -<title>Bit-syntax</title> -<p>The bit-syntax contains types for coping with binary data in the three main encodings. The types are named <c>utf8</c>, <c>utf16</c> and <c>utf32</c> respectively. The <c>utf16</c> and <c>utf32</c> types can be in a big- or little-endian variant:</p> -<code> + <title>Basic Language Support</title> + <p><marker id="unicode_in_erlang"/>As of Erlang/OTP R16 Erlang + source files can be written in either UTF-8 or bytewise encoding + (a.k.a. <c>latin1</c> encoding). The details on how to state the encoding + of an Erlang source file can be found in + <seealso marker="stdlib:epp#encoding"><c>epp(3)</c></seealso>. Strings and comments + can be written using Unicode, but functions still have to be named + using characters from the ISO-latin-1 character set and atoms are + restricted to the same ISO-latin-1 range. These restrictions in the + language are of course independent of the encoding of the source + file. Erlang/OTP 18.0 is expected to handle functions named in + Unicode as well as Unicode atoms.</p> + <section> + <title>Bit-syntax</title> + <p>The bit-syntax contains types for coping with binary data in the + three main encodings. The types are named <c>utf8</c>, <c>utf16</c> + and <c>utf32</c> respectively. The <c>utf16</c> and <c>utf32</c> types + can be in a big- or little-endian variant:</p> + <code> <<Ch/utf8,_/binary>> = Bin1, <<Ch/utf16-little,_/binary>> = Bin2, Bin3 = <<$H/utf32-little, $e/utf32-little, $l/utf32-little, $l/utf32-little, - $o/utf32-little>>,</code> -<p>For convenience, literal strings can be encoded with a Unicode encoding in binaries using the following (or similar) syntax:</p> -<code> +$o/utf32-little>>,</code> + <p>For convenience, literal strings can be encoded with a Unicode + encoding in binaries using the following (or similar) syntax:</p> + <code> Bin4 = <<"Hello"/utf16>>,</code> -</section> -<section> -<title>String- and character-literals</title> -<warning> -<p>The literal syntax described here may be subject to change in R13B, it has not yet passed the usual process for language changes approval.</p> -</warning> -<p>It is convenient to be able to write a list of Unicode characters in the string syntax. However, the language specifies strings as being in the ISO-latin-1 character set which the compiler tool chain as well as many other tools expect.</p> -<p>Also the source code is (for now) still expected to be written using the ISO-latin-1 character set, why Unicode characters beyond that range cannot be entered in string literals.</p> -<p>To make it easier to enter Unicode characters in the shell, it allows strings with Unicode characters on input, immediately converting them to regular lists of integers. They will, by the evaluator etc be viewed as if they were input using the regular list syntax, which is - in the end - how the language actually treats them. They will in the same way not be output as strings by i.e <c>io:write/2</c> or <c>io:format/3</c> unless the format string supplied to <c>io:format</c> uses the Unicode translation modifier (which we will talk about later).</p> -<p>For source code, there is an extension to the \OOO (backslash followed by three octal numbers) and \xHH (backslash followed by 'x', followed by two hexadecimal characters) syntax, namely \x{H ...} (a backslash followed by an 'x', followed by left curly bracket, any number of hexadecimal digits and a terminating right curly bracket). This allows for entering characters of any codepoint literally in a string. The string is immediately converted into a list by the scanner however, which is obvious when calling it directly:</p> + </section> + <section> + <title>String and Character Literals</title> + <p>For source code, there is an extension to the <c>\</c>OOO + (backslash followed by three octal numbers) and <c>\x</c>HH + (backslash followed by <c>x</c>, followed by two hexadecimal + characters) syntax, namely <c>\x{</c>H ...<c>}</c> (a backslash + followed by an <c>x</c>, followed by left curly bracket, any + number of hexadecimal digits and a terminating right curly + bracket). This allows for entering characters of any code point + literally in a string even when the encoding of the source file is + bytewise (<c>latin1</c>).</p> + <p>In the shell, if using a Unicode input device, or in source + code stored in UTF-8, <c>$</c> can be followed directly by a + Unicode character producing an integer. In the following example + the code point of a Cyrillic <c>с</c> is output:</p> + <pre> +7> <input>$с.</input> +1089</pre> + </section> + <section> + <title>Heuristic String Detection</title> + <p>In certain output functions and in the output of return values + in the shell, Erlang tries to heuristically detect string data in + lists and binaries. Typically you will see heuristic detection in + a situation like this:</p> + <pre> +1> <input>[97,98,99].</input> +"abc" +2> <input><<97,98,99>>.</input> +<<"abc">> +3> <input><<195,165,195,164,195,182>>.</input> +<<"åäö"/utf8>></pre> + <p>Here the shell will detect lists containing printable + characters or binaries containing printable characters either in + bytewise or UTF-8 encoding. The question here is: what is a + printable character? One view would be that anything the Unicode + standard thinks is printable, will also be printable according to + the heuristic detection. The result would be that almost any list + of integers will be deemed a string, resulting in all sorts of + characters being printed, maybe even characters your terminal does + not have in its font set (resulting in some generic output you + probably will not appreciate). Another way is to keep it backwards + compatible so that only the ISO-Latin-1 character set is used to + detect a string. A third way would be to let the user decide + exactly what Unicode ranges are to be viewed as characters. Since + Erlang/OTP R16B you can select either the whole Unicode range or the + ISO-Latin-1 range by supplying the startup flag <c>+pc + </c><i>Range</i>, where <i>Range</i> is either <c>latin1</c> or + <c>unicode</c>. For backwards compatibility, the default is + <c>latin1</c>. This only controls how heuristic string detection + is done. In the future, more ranges are expected to be added, so + that one can tailor the heuristics to the language and region + relevant to the user.</p> + <p>Lets look at an example with the two different startup options:</p> <pre> -1> <input>erl_scan:string("\"X\".").</input> -{ok,[{string,1,"X"},{dot,1}],1} -2> <input>erl_scan:string("\"\x{400}\".").</input> -{ok,[{'[',1},{integer,1,1024},{']',1},{dot,1}],1}</pre> -<p>Character literals, or rather integers representing Unicode codepoints can be expressed in a similar way using $\x{H ...}:</p> +$ <input>erl +pc latin1</input> +Erlang R16B (erts-5.10.1) [source] [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.10.1 (abort with ^G) +1> <input>[1024].</input> +[1024] +2> <input>[1070,1085,1080,1082,1086,1076].</input> +[1070,1085,1080,1082,1086,1076] +3> <input>[229,228,246].</input> +"åäö" +4> <input><<208,174,208,189,208,184,208,186,208,190,208,180>>.</input> +<<208,174,208,189,208,184,208,186,208,190,208,180>> +5> <input><<229/utf8,228/utf8,246/utf8>>.</input> +<<"åäö"/utf8>> +</pre> <pre> -4> <input>$\x{400}.</input> -1024</pre> -<p>This also is a translation by the scanner:</p> +$ <input>erl +pc unicode</input> +Erlang R16B (erts-5.10.1) [source] [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.10.1 (abort with ^G) +1> <input>[1024].</input> +"Ѐ" +2> <input>[1070,1085,1080,1082,1086,1076].</input> +"Юникод" +3> <input>[229,228,246].</input> +"åäö" +4> <input><<208,174,208,189,208,184,208,186,208,190,208,180>>.</input> +<<"Юникод"/utf8>> +5> <input><<229/utf8,228/utf8,246/utf8>>.</input> +<<"åäö"/utf8>> +</pre> + <p>In the examples, we can see that the default Erlang shell will + only interpret characters from the ISO-Latin1 range as printable + and will only detect lists or binaries with those "printable" + characters as containing string data. The valid UTF-8 binary + containing "Юникод", will not be printed as a string. When, on the + other hand, started with all Unicode characters printable (<c>+pc + unicode</c>), the shell will output anything containing printable + Unicode data (in binaries either UTF-8 or bytewise encoded) as + string data.</p> + + <p>These heuristics are also used by + <c>io</c>(<c>_lib</c>)<c>:format/2</c> and friends when the + <c>t</c> modifier is used in conjunction with <c>~p</c> or + <c>~P</c>:</p> <pre> -5> <input>erl_scan:string("$Y.").</input> -{ok,[{char,1,89},{dot,1}],1} -6> <input>erl_scan:string("$\x{400}.").</input> -{ok,[{integer,1,1024},{dot,1}],1}</pre> -<p>In the shell, if using a Unicode input device, '$' can be followed directly by a Unicode character producing an integer. In the following example, let's imagine the character 'c' is actually a Cyrillic 's' (looking fairly similar):</p> +$ <input>erl +pc latin1</input> +Erlang R16B (erts-5.10.1) [source] [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.10.1 (abort with ^G) +1> <input>io:format("~tp~n",[{<<"åäö">>, <<"åäö"/utf8>>, <<208,174,208,189,208,184,208,186,208,190,208,180>>}]).</input> +{<<"åäö">>,<<"åäö"/utf8>>,<<208,174,208,189,208,184,208,186,208,190,208,180>>} +ok +</pre> <pre> -7> <input>$c.</input> -1089</pre> +$ <input>erl +pc unicode</input> +Erlang R16B (erts-5.10.1) [source] [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.10.1 (abort with ^G) +1> <input>io:format("~tp~n",[{<<"åäö">>, <<"åäö"/utf8>>, <<208,174,208,189,208,184,208,186,208,190,208,180>>}]).</input> +{<<"åäö">>,<<"åäö"/utf8>>,<<"Юникод"/utf8>>} +ok +</pre> + <p>Please observe that this only affects <i>heuristic</i> interpretation + of lists and binaries on output. For example the <c>~ts</c> format + sequence does always output a valid lists of characters, + regardless of the <c>+pc</c> setting, as the programmer has + explicitly requested string output.</p> + </section> </section> -<p>The literal syntax allowing Unicode characters is to be viewed as "syntactic sugar", but is, as such, fairly useful.</p> -</section> <section> -<title>The interactive shell</title> -<p>The interactive Erlang shell, when started towards a terminal or started using the <c>werl</c> command on windows, can support Unicode input and output.</p> -<p>On Windows®, proper operation requires that a suitable font is installed and selected for the Erlang application to use. If no suitable font is available on your system, try installing the DejaVu fonts (dejavu-fonts.org), which are freely available and then select that font in the Erlang shell application.</p> -<p>On Unix®-like operating systems, the terminal should be able to handle UTF-8 on input and output (modern versions of XTerm, KDE konsole and the Gnome terminal do for example) and your locale settings have to be proper. As an example, my LANG environment variable is set as this:</p> -<pre> + <title>The Interactive Shell</title> + <p>The interactive Erlang shell, when started towards a terminal or + started using the <c>werl</c> command on windows, can support + Unicode input and output.</p> + <p>On Windows, proper operation requires that a suitable font + is installed and selected for the Erlang application to use. If no + suitable font is available on your system, try installing the DejaVu + fonts (<c>dejavu-fonts.org</c>), which are freely available and then + select that font in the Erlang shell application.</p> + <p>On Unix-like operating systems, the terminal should be able + to handle UTF-8 on input and output (modern versions of XTerm, KDE + konsole and the Gnome terminal do for example) and your locale + settings have to be proper. As an example, my <c>LANG</c> + environment variable is set as this:</p> + <pre> $ <input>echo $LANG</input> en_US.UTF-8</pre> -<p>Actually, most systems handle the LC_CTYPE variable before LANG, so if that is set, it has to be set to UTF-8:</p> -<pre> + <p>Actually, most systems handle the <c>LC_CTYPE</c> variable before + <c>LANG</c>, so if that is set, it has to be set to + <c>UTF-8</c>:</p> + <pre> $ echo <input>$LC_CTYPE</input> en_US.UTF-8</pre> -<p>The LANG or LC_CTYPE setting should be consistent with what the terminal is capable of, there is no portable way for Erlang to ask the actual terminal about its UTF-8 capacity, we have to rely on the language and character type settings.</p> -<p>To investigate what Erlang thinks about the terminal, the <c>io:getopts()</c> call can be used when the shell is started:</p> -<pre> + <p>The <c>LANG</c> or <c>LC_CTYPE</c> setting should be consistent + with what the terminal is capable of, there is no portable way for + Erlang to ask the actual terminal about its UTF-8 capacity, we have + to rely on the language and character type settings.</p> + <p>To investigate what Erlang thinks about the terminal, the + <c>io:getopts()</c> call can be used when the shell is started:</p> + <pre> $ <input>LC_CTYPE=en_US.ISO-8859-1 erl</input> -Erlang R13A (erts-5.7) [source] [64-bit] [smp:4:4] [rq:4] [async-threads:0] [kernel-poll:false] +Erlang R16B (erts-5.10.1) [source] [async-threads:0] [hipe] [kernel-poll:false] -Eshell V5.7 (abort with ^G) -1> <input>lists:keyfind(encoding,1,io:getopts()).</input> +Eshell V5.10.1 (abort with ^G) +1> <input>lists:keyfind(encoding, 1, io:getopts()).</input> {encoding,latin1} 2> <input>q().</input> ok $ <input>LC_CTYPE=en_US.UTF-8 erl</input> -Erlang R13A (erts-5.7) [source] [64-bit] [smp:4:4] [rq:4] [async-threads:0] [kernel-poll:false] +Erlang R16B (erts-5.10.1) [source] [async-threads:0] [hipe] [kernel-poll:false] -Eshell V5.7 (abort with ^G) -1> <input>lists:keyfind(encoding,1,io:getopts()).</input> +Eshell V5.10.1 (abort with ^G) +1> <input>lists:keyfind(encoding, 1, io:getopts()).</input> {encoding,unicode} 2></pre> -<p>When (finally?) everything is in order with the locale settings, fonts and the terminal emulator, you probably also have discovered a way to input characters in the script you desire. For testing, the simplest way is to add some keyboard mappings for other languages, usually done with some applet in your desktop environment. In my KDE environment, I start the KDE Control Center (Personal Settings), select "Regional and Accessibility" and then "Keyboard Layout". On Windows XP®, I start Control Panel->Regional and Language Options, select the Language tab and click the Details... button in the square named "Text services and input Languages". Your environment probably provides similar means of changing the keyboard layout. Make sure you have a way to easily switch back and forth between keyboards if you are not used to this, entering commands using a Cyrillic character set is, as an example, not easily done in the Erlang shell.</p> -<p>Now you are set up for some Unicode input and output. The simplest thing to do is of course to enter a string in the shell:</p> -<image file="ushell1.gif"><icaption>Cyrillic characters in an Erlang shell</icaption></image> -<p>While strings can be input as Unicode characters, the language elements are still limited to the ISO-latin-1 character set. Only character constants and strings are allowed to be beyond that range:</p> -<image file="ushell2.gif"><icaption>Unicode characters in allowed and disallowed context</icaption></image> + + <p>When (finally?) everything is in order with the locale settings, + fonts and the terminal emulator, you probably also have discovered a + way to input characters in the script you desire. For testing, the + simplest way is to add some keyboard mappings for other languages, + usually done with some applet in your desktop environment. In my KDE + environment, I start the KDE Control Center (Personal Settings), + select "Regional and Accessibility" and then "Keyboard Layout". On + Windows XP, I start Control Panel->Regional and Language + Options, select the Language tab and click the Details... button in + the square named "Text services and input Languages". Your + environment probably provides similar means of changing the keyboard + layout. Make sure you have a way to easily switch back and forth + between keyboards if you are not used to this, entering commands + using a Cyrillic character set is, as an example, not easily done in + the Erlang shell.</p> + + <p>Now you are set up for some Unicode input and output. The + simplest thing to do is of course to enter a string in the + shell:</p> + + <pre> +$ <input>erl</input> +Erlang R16B (erts-5.10.1) [source] [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.10.1 (abort with ^G) +1> <input>lists:keyfind(encoding, 1, io:getopts()).</input> +{encoding,unicode} +2> <input>"Юникод".</input> +"Юникод" +3> <input>io:format("~ts~n", [v(2)]).</input> +Юникод +ok +4> </pre> + <p>While strings can be input as Unicode characters, the language + elements are still limited to the ISO-latin-1 character set. Only + character constants and strings are allowed to be beyond that + range:</p> + <pre> +$ <input>erl</input> +Erlang R16B (erts-5.10.1) [source] [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.10.1 (abort with ^G) +1> <input>$ξ.</input> +958 +2> <input>Юникод.</input> +* 1: illegal character +2> </pre> </section> <section> -<title>Unicode file names</title> -<p>Most modern operating systems support Unicode file names in some way or another. There are several different ways to do this and Erlang by default treats the different approaches differently:</p> -<taglist> -<tag>Mandatory Unicode file naming</tag> -<item> -<p>Windows and, for most common uses, MacOSX enforces Unicode support for file names. All files created in the filesystem have names that can consistently be interpreted. In MacOSX, all file names are retrieved in UTF-8 encoding, while Windows has selected an approach where each system call handling file names has a special Unicode aware variant, giving much the same effect. There are no file names on these systems that are not Unicode file names, why the default behavior of the Erlang VM is to work in "Unicode file name translation mode", meaning that a file name can be given as a Unicode list and that will be automatically translated to the proper name encoding for the underlying operating and file system.</p> -<p>Doing i.e. a <c>file:list_dir/1</c> on one of these systems may return Unicode lists with codepoints beyond 255, depending on the content of the actual filesystem.</p> -<p>As the feature is fairly new, you may still stumble upon non core applications that cannot handle being provided with file names containing characters with codepoints larger than 255, but the core Erlang system should have no problems with Unicode file names.</p> -</item> -<tag>Transparent file naming</tag> -<item> -<p>Most Unix operating systems have adopted a simpler approach, namely that Unicode file naming is not enforced, but by convention. Those systems usually use UTF-8 encoding for Unicode file names, but do not enforce it. On such a system, a file name containing characters having codepoints between 128 and 255 may be named either as plain ISO-latin-1 or using UTF-8 encoding. As no consistency is enforced, the Erlang VM can do no consistent translation of all file names. If the VM would automatically select encoding based on heuristics, one could get unexpected behavior on these systems, therefore file names not being encoded in UTF-8 are returned as "raw file names" if Unicode file naming support is turned on.</p> -<p>A raw file name is not a list, but a binary. Many non core applications still do not handle file names given as binaries, why such raw names are avoided by default. This means that systems having implemented Unicode file naming through transparent file systems and an UTF-8 convention, do not by default have Unicode file naming turned on. Explicitly turning Unicode file name handling on for these types of systems is considered experimental.</p> -</item> -</taglist> -<p>The Unicode file naming support was introduced with OTP release R14B01. A VM operating in Unicode file mode can work with files having names in any language or character set (as long as it's supported by the underlying OS and file system). The Unicode character list is used to denote file or directory names and if the file system content is listed, you will also be able to get Unicode lists as return value. The support lies in the kernel and stdlib modules, why most applications (that does not explicitly require the file names to be in the ISO-latin-1 range) will benefit from the Unicode support without change.</p> + <title>Unicode File Names</title> + <marker id="unicode_file_names"/> + <p>Most modern operating systems support Unicode file names in some + way or another. There are several different ways to do this and + Erlang by default treats the different approaches differently:</p> + <taglist> + <tag>Mandatory Unicode file naming</tag> + <item> + <p>Windows and, for most common uses, MacOS X enforces Unicode + support for file names. All files created in the file system have + names that can consistently be interpreted. In MacOS X, all file + names are retrieved in UTF-8 encoding, while Windows has + selected an approach where each system call handling file names + has a special Unicode aware variant, giving much the same + effect. There are no file names on these systems that are not + Unicode file names, why the default behavior of the Erlang VM is + to work in "Unicode file name translation mode", + meaning that a file name can be given as a Unicode list and that + will be automatically translated to the proper name encoding for + the underlying operating and file system.</p> + <p>Doing i.e. a <c>file:list_dir/1</c> on one of these systems + may return Unicode lists with code points beyond 255, depending + on the content of the actual file system.</p> + <p>As the feature is fairly new, you may still stumble upon non + core applications that cannot handle being provided with file + names containing characters with code points larger than 255, but + the core Erlang system should have no problems with Unicode file + names.</p> + </item> + <tag>Transparent file naming</tag> + <item> + <p>Most Unix operating systems have adopted a simpler approach, + namely that Unicode file naming is not enforced, but by + convention. Those systems usually use UTF-8 encoding for Unicode + file names, but do not enforce it. On such a system, a file name + containing characters having code points between 128 and 255 may + be named either as plain ISO-latin-1 or using UTF-8 encoding. As + no consistency is enforced, the Erlang VM can do no consistent + translation of all file names.</p> -<p>On Operating systems with mandatory Unicode file names, this means that you more easily conform to the file names of other (non Erlang) applications, and you can also process file names that, at least on Windows, were completely inaccessible (due to having names that could not be represented in ISO-latin-1). Also you will avoid creating incomprehensible file names on MacOSX as the vfs layer of the OS will accept all your file names as UTF-8 and will not rewrite them.</p> + <p>By default on such systems, Erlang starts in <c>utf8</c> file + name mode if the terminal supports UTF-8, otherwise in + <c>latin1</c> mode.</p> -<p>For most systems, turning on Unicode file name translation is no problem even if it uses transparent file naming. Very few systems have mixed file name encodings. A consistent UTF-8 named system will work perfectly in Unicode file name mode. It is still however considered experimental in R14B01. Unicode file name translation is turned on with the <c>+fnu</c> switch to the <c>erl</c> program. If the VM is started in Unicode file name translation mode, <c>file:native_name_encoding/0</c> will return the atom <c>utf8</c>.</p> + <p>In the <c>latin1</c> mode, file names are bytewise endcoded. + This allows for list representation of all file names in + the system, but, for example, a file named "Östersund.txt", will + appear in <c>file:list_dir/1</c> as either "Östersund.txt" (if + the file name was encoded in bytewise ISO-Latin-1 by the program + creating the file, or more probably as + <c>[195,150,115,116,101,114,115,117,110,100]</c>, which is a + list containing UTF-8 bytes - not what you would want... If you + on the other hand use Unicode file name translation on such a + system, non-UTF-8 file names will simply be ignored by functions + like <c>file:list_dir/1</c>. They can be retrieved with + <c>file:list_dir_all/1</c>, but wrongly encoded file names will + appear as "raw file names".</p> -<p>In Unicode file name mode, file names given to the BIF <c>open_port/2</c> with the option <c>{spawn_executable,...}</c> are also interpreted as Unicode. So is the parameter list given in the <c>args</c> option available when using <c>spawn_executable</c>. The UTF-8 translation of arguments can be avoided using binaries, see the discussion about raw file names below.</p> + </item> + </taglist> -<p>It is worth noting that the file <c>encoding</c> options given when opening a file has nothing to do with the file <em>name</em> encoding convention. You can very well open files containing UTF-8 but having file names in ISO-latin-1 or vice versa.</p> + <p>The Unicode file naming support was introduced with Erlang/OTP + R14B01. A VM operating in Unicode file name translation mode can + work with files having names in any language or character set (as + long as it is supported by the underlying OS and file system). The + Unicode character list is used to denote file or directory names and + if the file system content is listed, you will also get + Unicode lists as return value. The support lies in the Kernel and + STDLIB modules, why most applications (that does not explicitly + require the file names to be in the ISO-latin-1 range) will benefit + from the Unicode support without change.</p> -<note>Erlang drivers and NIF shared objects still can not be named with names containing codepoints beyond 127. This is a known limitation to be removed in a future release. Erlang modules however can, but it is definitely not a good idea and is still considered experimental.</note> + <p>On operating systems with mandatory Unicode file names, this + means that you more easily conform to the file names of other (non + Erlang) applications, and you can also process file names that, at + least on Windows, were completely inaccessible (due to having names + that could not be represented in ISO-latin-1). Also you will avoid + creating incomprehensible file names on MacOS X as the vfs layer of + the OS will accept all your file names as UTF-8 and will not rewrite + them.</p> + + <p>For most systems, turning on Unicode file name translation is no + problem even if it uses transparent file naming. Very few systems + have mixed file name encodings. A consistent UTF-8 named system will + work perfectly in Unicode file name mode. It was still however + considered experimental in Erlang/OTP R14B01 and is still not the default on + such systems. Unicode file name translation is turned on with the + <c>+fnu</c> switch to the On Linux, a VM started without explicitly + stating the file name translation mode will default to <c>latin1</c> + as the native file name encoding. On Windows and MacOS X, the + default behavior is that of Unicode file name translation, why the + <c>file:native_name_encoding/0</c> by default returns <c>utf8</c> on + those systems (the fact that Windows actually does not use UTF-8 on + the file system level can safely be ignored by the Erlang + programmer). The default behavior can, as stated before, be + changed using the <c>+fnu</c> or <c>+fnl</c> options to the VM, see + the <seealso marker="erts:erl"><c>erl</c></seealso> program. If the + VM is started in Unicode file name translation mode, + <c>file:native_name_encoding/0</c> will return the atom + <c>utf8</c>. The <c>+fnu</c> switch can be followed by <c>w</c>, + <c>i</c> or <c>e</c>, to control how wrongly encoded file names are + to be reported. <c>w</c> means that a warning is sent to the + <c>error_logger</c> whenever a wrongly encoded file name is + "skipped" in directory listings, <c>i</c> means that those wrongly + encoded file names are silently ignored and <c>e</c> means that the + API function will return an error whenever a wrongly encoded file + (or directory) name is encountered. <c>w</c> is the default. Note + that <c>file:read_link/1</c> will always return an error if the link + points to an invalid file name.</p> + + <p>In Unicode file name mode, file names given to the BIF + <c>open_port/2</c> with the option <c>{spawn_executable,...}</c> are + also interpreted as Unicode. So is the parameter list given in the + <c>args</c> option available when using <c>spawn_executable</c>. The + UTF-8 translation of arguments can be avoided using binaries, see + the discussion about raw file names below.</p> + + <p>It is worth noting that the file <c>encoding</c> options given + when opening a file has nothing to do with the file <em>name</em> + encoding convention. You can very well open files containing data + encoded in UTF-8 but having file names in bytewise (<c>latin1</c>) encoding + or vice versa.</p> + + <note><p>Erlang drivers and NIF shared objects still can not be + named with names containing code points beyond 127. This is a known + limitation to be removed in a future release. Erlang modules however + can, but it is definitely not a good idea and is still considered + experimental.</p></note> <section> -<title>Notes about raw file names and automatic file name conversion</title> -<p>Raw file names is introduced together with Unicode file name support in erts-5.8.2 (OTP R14B01). The reason "raw file names" is introduced in the system is to be able to consistently represent file names given in different encodings on the same system. Having the VM automatically translate a file name that is not in UTF-8 to a list of Unicode characters might seem practical, but this would open up for both duplicate file names and other inconsistent behavior. Consider a directory containing a file named "bj�rn" in ISO-latin-1, while the Erlang VM is operating in Unicode file name mode (and therefore expecting UTF-8 file naming). The ISO-latin-1 name is not valid UTF-8 and one could be tempted to think that automatic conversion in for example <c>file:list_dir/1</c> is a good idea. But what would happen if we later tried to open the file and have the name as a Unicode list (magically converted from the ISO-latin-1 file name)? The VM will convert the file name given to UTF-8, as this is the encoding expected. Effectively this means trying to open the file named <<"bj�rn"/utf8>>. This file does not exist, and even if it existed it would not be the same file as the one that was listed. We could even create two files named "bj�rn", one named in the UTF-8 encoding and one not. If <c>file:list_dir/1</c> would automatically convert the ISO-latin-1 file name to a list, we would get two identical file names as the result. To avoid this, we need to differentiate between file names being properly encoded according to the Unicode file naming convention (i.e. UTF-8) and file names being invalid under the encoding. This is done by representing invalid encoding as "raw" file names, i.e. as binaries.</p> -<p>The core system of Erlang (kernel and stdlib) accepts raw file names except for loadable drivers and executables invoked using <c>open_port({spawn, ...} ...)</c>. <c>open_port({spawn_executable, ...} ...)</c> however does accept them. As mentioned earlier, the arguments given in the option list to <c>open_port({spawn_executable, ...} ...)</c> undergo the same conversion as the file names, meaning that the executable will be provided with arguments in UTF-8 as well. This translation is avoided consistently with how the file names are treated, by giving the argument as a binary.</p> -<p>To force Unicode file name translation mode on systems where this is not the default is considered experimental in OTP R14B01 due to the raw file names possibly being a new experience to the programmer and that the non core applications of OTP are not tested for compliance with raw file names yet. Unicode file name translation is expected to be default in future releases.</p> -<p>If working with raw file names, one can still conform to the encoding convention of the Erlang VM by using the <c>file:native_name_encoding/0</c> function, which returns either the atom <c>latin1</c> or the atom <c>utf8</c> depending on the file name translation mode. On Linux, a VM started without explicitly stating the file name translation mode will default to <c>latin1</c> as the native file name encoding, why file names on the disk encoded as UTF-8 will be returned as a list of the names interpreted as ISO-latin-1. The "UTF-8 list" is not a practical type for displaying or operating on in Erlang, but it is backward compatible and usable in all functions requiring a file name. On Windows and MacOSX, the default behavior is that of file name translation, why the <c>file:native_name_encoding/0</c> by default returns <c>utf8</c> on those systems (the fact that Windows actually does not use UTF-8 on the file system level can safely be ignored by the Erlang programmer). The default behavior can be changed using the <c>+fnu</c> or <c>+fnl</c> options to the VM, see the <c>erl</c> command manual page.</p> -<p>Even if you are operating without Unicode file naming translation automatically done by the VM, you can access and create files with names in UTF-8 encoding by using raw file names encoded as UTF-8. Enforcing the UTF-8 encoding regardless of the mode the Erlang VM is started in might, in some circumstances be a good idea, as the convention of using UTF-8 file names is spreading.</p> + <title>Notes About Raw File Names</title> + <marker id="notes-about-raw-filenames"/> + <p>Raw file names were introduced together with Unicode file name + support in erts-5.8.2 (Erlang/OTP R14B01). The reason "raw file + names" was introduced in the system was to be able to + consistently represent file names given in different encodings on + the same system. Having the VM automatically translate a file name + that is not in UTF-8 to a list of Unicode characters might seem + practical, but this would open up for both duplicate file names and + other inconsistent behavior. Consider a directory containing a file + named "björn" in ISO-latin-1, while the Erlang VM is + operating in Unicode file name mode (and therefore expecting UTF-8 + file naming). The ISO-latin-1 name is not valid UTF-8 and one could + be tempted to think that automatic conversion in for example + <c>file:list_dir/1</c> is a good idea. But what would happen if we + later tried to open the file and have the name as a Unicode list + (magically converted from the ISO-latin-1 file name)? The VM will + convert the file name given to UTF-8, as this is the encoding + expected. Effectively this means trying to open the file named + <<"björn"/utf8>>. This file does not exist, + and even if it existed it would not be the same file as the one that + was listed. We could even create two files named "björn", + one named in the UTF-8 encoding and one not. If + <c>file:list_dir/1</c> would automatically convert the ISO-latin-1 + file name to a list, we would get two identical file names as the + result. To avoid this, we need to differentiate between file names + being properly encoded according to the Unicode file naming + convention (i.e. UTF-8) and file names being invalid under the + encoding. By the common <c>file:list_dir/1</c> function, the wrongly + encoded file names are simply ignored in Unicode file name + translation mode, but by the <c>file:list_dir_all/1</c> function, + the file names with invalid encoding are returned as "raw" + file names, i.e. as binaries.</p> + + <p>The Erlang <c>file</c> module accepts raw file names as + input. <c>open_port({spawn_executable, ...} ...)</c> also accepts + them. As mentioned earlier, the arguments given in the option list + to <c>open_port({spawn_executable, ...} ...)</c> undergo the same + conversion as the file names, meaning that the executable will be + provided with arguments in UTF-8 as well. This translation is + avoided consistently with how the file names are treated, by giving + the argument as a binary.</p> + + <p>To force Unicode file name translation mode on systems where this + is not the default was considered experimental in Erlang/OTP R14B01 due to + the fact that the initial implementation did not ignore wrongly + encoded file names, so that raw file names could spread unexpectedly + throughout the system. Beginning with Erlang/OTP R16B, the wrongly encoded file + names are only retrieved by special functions + (e.g. <c>file:list_dir_all/1</c>), so the impact on existing code is + much lower, why it is now supported. Unicode file name translation + is expected to be default in future releases.</p> + + <p>Even if you are operating without Unicode file naming translation + automatically done by the VM, you can access and create files with + names in UTF-8 encoding by using raw file names encoded as + UTF-8. Enforcing the UTF-8 encoding regardless of the mode the + Erlang VM is started in might, in some circumstances be a good idea, + as the convention of using UTF-8 file names is spreading.</p> </section> <section> -<title>Notes about MacOSX</title> -<p>MacOSXs vfs layer enforces UTF-8 file names in a quite aggressive way. Older versions did this by simply refusing to create non UTF-8 conforming file names, while newer versions replace offending bytes with the sequence "%HH", where HH is the original character in hexadecimal notation. As Unicode translation is enabled by default on MacOSX, the only way to come up against this is to either start the VM with the <c>+fnl</c> flag or to use a raw file name in <c>latin1</c> encoding. In that case, the file can not be opened with the same name as the one used to create this. The problem is by design in newer versions of MacOSX.</p> -<p>MacOSX also reorganizes the names of files so that the representation of accents etc is denormalized, i.e. the character <c>�</c> is represented as the codepoints [111,776], where 111 is the character <c>o</c> and 776 is a special accent character. This type of denormalized Unicode is otherwise very seldom used and Erlang normalizes those file names on retrieval, so that denormalized file names is not passed up to the Erlang application. In Erlang the file name "bj�rn" is retrieved as [98,106,246,114,110], not as [98,106,117,776,114,110], even though the file system might think differently.</p> + <title>Notes About MacOS X</title> + <p>MacOS X's vfs layer enforces UTF-8 file names in a quite + aggressive way. Older versions did this by simply refusing to create + non UTF-8 conforming file names, while newer versions replace + offending bytes with the sequence "%HH", where HH is the + original character in hexadecimal notation. As Unicode translation + is enabled by default on MacOS X, the only way to come up against + this is to either start the VM with the <c>+fnl</c> flag or to use a + raw file name in bytewise (<c>latin1</c>) encoding. If using a raw + filename, with a bytewise encoding containing characters between 127 + and 255, to create a file, the file can not be opened using the same + name as the one used to create it. There is no remedy for this + behaviour, other than keeping the file names in the right + encoding.</p> + + <p>MacOS X also reorganizes the names of files so that the + representation of accents etc is using the "combining characters", + i.e. the character <c>ö</c> is represented as the code points + [111,776], where 111 is the character <c>o</c> and 776 is the + special accent character "combining diaeresis". This way of + normalizing Unicode is otherwise very seldom used and Erlang + normalizes those file names in the opposite way upon retrieval, so + that file names using combining accents are not passed up to the + Erlang application. In Erlang the file name "björn" is + retrieved as [98,106,246,114,110], not as [98,106,117,776,114,110], + even though the file system might think differently. The + normalization into combining accents are redone when actually + accessing files, so this can usually be ignored by the Erlang + programmer.</p> </section> </section> <section> -<title>Unicode in environment variables and parameters</title> -<p>Environment variables and their interpretation is handled much in the same way as file names. If Unicode file names are enabled, environment variables as well as parameters to the Erlang VM are expected to be in Unicode.</p> -<p>If Unicode file names are enabled, the calls to <seealso marker="kernel:os#getenv/0"><c>os:getenv/0</c></seealso>, <seealso marker="kernel:os#getenv/1"><c>os:getenv/1</c></seealso> and <seealso marker="kernel:os#putenv/2"><c>os:putenv/2</c></seealso> will handle Unicode strings. On Unix-like platforms, the built-in functions will translate environment variables in UTF-8 to/from Unicode strings, possibly with codepoints > 255. On Windows the Unicode versions of the environment system API will be used, also allowing for codepoints > 255.</p> -<p>On Unix-like operating systems, parameters are expected to be UTF-8 without translation if Unicode file names are enabled.</p> + <title>Unicode in Environment and Parameters</title> + <marker id="unicode_in_environment_and_parameters"/> + <p>Environment variables and their interpretation is handled much in + the same way as file names. If Unicode file names are enabled, + environment variables as well as parameters to the Erlang VM are + expected to be in Unicode.</p> + <p>If Unicode file names are enabled, the calls to + <seealso marker="kernel:os#getenv/0"><c>os:getenv/0</c></seealso>, + <seealso marker="kernel:os#getenv/1"><c>os:getenv/1</c></seealso> and + <seealso marker="kernel:os#putenv/2"><c>os:putenv/2</c></seealso> + will handle Unicode strings. On Unix-like platforms, the built-in + functions will translate environment variables in UTF-8 to/from + Unicode strings, possibly with code points > 255. On Windows the + Unicode versions of the environment system API will be used, also + allowing for code points > 255.</p> + <p>On Unix-like operating systems, parameters are expected to be + UTF-8 without translation if Unicode file names are enabled.</p> </section> <section> -<title>Unicode-aware modules</title> -<p>Most of the modules in Erlang/OTP are of course Unicode-unaware in the sense that they have no notion of Unicode and really shouldn't have. Typically they handle non-textual or byte-oriented data (like <c>gen_tcp</c> etc).</p> -<p>Modules that actually handle textual data (like <c>io_lib</c>, <c>string</c> etc) are sometimes subject to conversion or extension to be able to handle Unicode characters.</p> -<p>Fortunately, most textual data has been stored in lists and range checking has been sparse, why modules like <c>string</c> works well for Unicode lists with little need for conversion or extension.</p> -<p>Some modules are however changed to be explicitly Unicode-aware. These modules include:</p> -<taglist> -<tag><c>unicode</c></tag> -<item> -<p>The module <seealso marker="stdlib:unicode">unicode</seealso> is obviously Unicode-aware. It contains functions for conversion between different Unicode formats as well as some utilities for identifying byte order marks. Few programs handling Unicode data will survive without this module.</p> -</item> -<tag><c>io</c></tag> -<item> -<p>The <seealso marker="stdlib:io">io</seealso> module has been extended along with the actual I/O-protocol to handle Unicode data. This means that several functions require binaries to be in UTF-8 and there are modifiers to formatting control sequences to allow for outputting of Unicode strings.</p> -</item> -<tag><c>file</c>, <c>group</c> and <c>user</c></tag> -<item> -<p>I/O-servers throughout the system are able both to handle Unicode data and has options for converting data upon actual output or input to/from the device. As shown earlier, the <seealso marker="stdlib:shell">shell</seealso> has support for Unicode terminals and the <seealso marker="kernel:file">file</seealso> module allows for translation to and from various Unicode formats on disk.</p> -<p>The actual reading and writing of files with Unicode data is however not best done with the <c>file</c> module as its interface is byte oriented. A file opened with a Unicode encoding (like UTF-8), is then best read or written using the <seealso marker="stdlib:io">io</seealso> module.</p> -</item> -<tag><c>re</c></tag> -<item> -<p>The <seealso marker="stdlib:re">re</seealso> module allows for matching Unicode strings as a special option. As the library is actually centered on matching in binaries, the Unicode support is UTF-8-centered.</p> -</item> -<tag><c>wx</c></tag> -<item> -<p>The <seealso marker="wx:wx">wx</seealso> graphical library has extensive support for Unicode text</p> -</item> -</taglist> -<p>The module <seealso marker="stdlib:string">string</seealso> works perfect for Unicode strings as well as for ISO-latin-1 strings with the exception of the language-dependent <seealso marker="stdlib:string#to_upper/1">to_upper</seealso> and <seealso marker="stdlib:string#to_lower/1">to_lower</seealso> functions, which are only correct for the ISO-latin-1 character set. Actually they can never function correctly for Unicode characters in their current form, there are language and locale issues as well as multi-character mappings to consider when conversion text between cases. Converting case in an international environment is a big subject not yet addressed in OTP.</p> + <title>Unicode-aware Modules</title> + <p>Most of the modules in Erlang/OTP are of course Unicode-unaware + in the sense that they have no notion of Unicode and really should + not have. Typically they handle non-textual or byte-oriented data + (like <c>gen_tcp</c> etc).</p> + <p>Modules that actually handle textual data (like <c>io_lib</c>, + <c>string</c> etc) are sometimes subject to conversion or extension + to be able to handle Unicode characters.</p> + <p>Fortunately, most textual data has been stored in lists and range + checking has been sparse, why modules like <c>string</c> works well + for Unicode lists with little need for conversion or extension.</p> + <p>Some modules are however changed to be explicitly + Unicode-aware. These modules include:</p> + <taglist> + <tag><c>unicode</c></tag> + <item> + <p>The module <seealso marker="stdlib:unicode"><c>unicode</c></seealso> + is obviously Unicode-aware. It contains functions for conversion + between different Unicode formats as well as some utilities for + identifying byte order marks. Few programs handling Unicode data + will survive without this module.</p> + </item> + <tag><c>io</c></tag> + <item> + <p>The <seealso marker="stdlib:io"><c>io</c></seealso> module has been + extended along with the actual I/O-protocol to handle Unicode + data. This means that several functions require binaries to be + in UTF-8 and there are modifiers to formatting control sequences + to allow for outputting of Unicode strings.</p> + </item> + <tag><c>file</c>, <c>group</c>, <c>user</c></tag> + <item> + <p>I/O-servers throughout the system are able to handle + Unicode data and has options for converting data upon actual + output or input to/from the device. As shown earlier, the + <seealso marker="stdlib:shell"><c>shell</c></seealso> has support for + Unicode terminals and the <seealso + marker="kernel:file"><c>file</c></seealso> module allows for + translation to and from various Unicode formats on disk.</p> + <p>The actual reading and writing of files with Unicode data is + however not best done with the <c>file</c> module as its + interface is byte oriented. A file opened with a Unicode + encoding (like UTF-8), is then best read or written using the + <seealso marker="stdlib:io"><c>io</c></seealso> module.</p> + </item> + <tag><c>re</c></tag> + <item> + <p>The <seealso marker="stdlib:re"><c>re</c></seealso> module allows + for matching Unicode strings as a special option. As the library + is actually centered on matching in binaries, the Unicode + support is UTF-8-centered.</p> + </item> + <tag><c>wx</c></tag> + <item> + <p>The <seealso marker="wx:wx"><c>wx</c></seealso> graphical library + has extensive support for Unicode text</p> + </item> + </taglist> + <p>The module <seealso + marker="stdlib:string"><c>string</c></seealso> works perfectly for + Unicode strings as well as for ISO-latin-1 strings with the + exception of the language-dependent <seealso + marker="stdlib:string#to_upper/1"><c>to_upper</c></seealso> and + <seealso marker="stdlib:string#to_lower/1"><c>to_lower</c></seealso> + functions, which are only correct for the ISO-latin-1 character + set. Actually they can never function correctly for Unicode + characters in their current form, as there are language and locale + issues as well as multi-character mappings to consider when + converting text between cases. Converting case in an international + environment is a big subject not yet addressed in OTP.</p> </section> <section> -<title>Unicode recipes</title> -<p>When starting with Unicode, one often stumbles over some common issues. I try to outline some methods of dealing with Unicode data in this section.</p> + <title>Unicode Data in Files</title> + <p>The fact that Erlang as such can handle Unicode data in many forms + does not automatically mean that the content of any file can be + Unicode text. The external entities such as ports or I/O-servers are + not generally Unicode capable.</p> + <p>Ports are always byte oriented, so before sending data that you + are not sure is bytewise encoded to a port, make sure to encode it + in a proper Unicode encoding. Sometimes this will mean that only + part of the data shall be encoded as e.g. UTF-8, some parts may be + binary data (like a length indicator) or something else that shall + not undergo character encoding, so no automatic translation is + present.</p> + <p>I/O-servers behave a little differently. The I/O-servers connected + to terminals (or stdout) can usually cope with Unicode data + regardless of the <c>encoding</c> option. This is convenient when + one expects a modern environment but do not want to crash when + writing to a archaic terminal or pipe. Files on the other hand are + more picky. A file can have an encoding option which makes it + generally usable by the io-module (e.g. <c>{encoding,utf8}</c>), but + is by default opened as a byte oriented file. The <seealso + marker="kernel:file"><c>file</c></seealso> module is byte oriented, why only + ISO-Latin-1 characters can be written using that module. The + <seealso marker="stdlib:io"><c>io</c></seealso> module is the one to use if + Unicode data is to be output to a file with other <c>encoding</c> + than <c>latin1</c> (a.k.a. bytewise encoding). It is slightly + confusing that a file opened with + e.g. <c>file:open(Name,[read,{encoding,utf8}])</c>, cannot be + properly read using <c>file:read(File,N)</c> but you have to use the + <c>io</c> module to retrieve the Unicode data from it. The reason is + that <c>file:read</c> and <c>file:write</c> (and friends) are purely + byte oriented, and should so be, as that is the way to access + files other than text files - byte by byte. Just as with ports, you + can of course write encoded data into a file by "manually" converting + the data to the encoding of choice (using the <seealso + marker="stdlib:unicode"><c>unicode</c></seealso> module or the bit syntax) + and then output it on a bytewise encoded (<c>latin1</c>) file.</p> + <p>The rule of thumb is that the <seealso + marker="kernel:file"><c>file</c></seealso> module should be used for files + opened for bytewise access (<c>{encoding,latin1}</c>) and the + <seealso marker="stdlib:io"><c>io</c></seealso> module should be used when + accessing files with any other encoding + (e.g. <c>{encoding,uf8}</c>).</p> + + <p>Functions reading Erlang syntax from files generally recognize + the <c>coding:</c> comment and can therefore handle Unicode data on + input. When writing Erlang Terms to a file, you should insert + such comments when applicable:</p> + <pre> +$ <input>erl +fna +pc unicode</input> +Erlang R16B (erts-5.10.1) [source] [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.10.1 (abort with ^G) +1> <input>file:write_file("test.term",<<"%% coding: utf-8\n[{\"Юникод\",4711}].\n"/utf8>>).</input> +ok +2> <input>file:consult("test.term").</input> +{ok,[[{"Юникод",4711}]]} + </pre> +</section> +<section> + <title>Summary of Options</title> + <marker id="unicode_options_summary"/> + <p>The Unicode support is controlled by both command line switches, + some standard environment variables and the version of OTP you are + using. Most options affect mainly the way Unicode data is displayed, + not the actual functionality of the API's in the standard + libraries. This means that Erlang programs usually do not + need to concern themselves with these options, they are more for the + development environment. An Erlang program can be written so that it + works well regardless of the type of system or the Unicode options + that are in effect.</p> + + <p>Here follows a summary of the settings affecting Unicode:</p> + <taglist> + <tag>The <c>LANG</c> and <c>LC_CTYPE</c> environment variables</tag> + <item> + <p>The language setting in the OS mainly affects the shell. The + terminal (i.e. the group leader) will operate with <c>{encoding, + unicode}</c> only if the environment tells it that UTF-8 is + allowed. This setting should correspond to the actual terminal + you are using.</p> + <p>The environment can also affect file name interpretation, if + Erlang is started with the <c>+fna</c> flag (which is default from + Erlang/OTP 17.0).</p> + <p>You can check the setting of this by calling + <c>io:getopts()</c>, which will give you an option list + containing <c>{encoding,unicode}</c> or + <c>{encoding,latin1}</c>.</p> + </item> + <tag>The <c>+pc </c>{<c>unicode</c>|<c>latin1</c>} flag to + <seealso marker="erts:erl"><c>erl(1)</c></seealso></tag> + <item> + <p>This flag affects what is interpreted as string data when + doing heuristic string detection in the shell and in + <c>io</c>/<c>io_lib:format</c> with the <c>"~tp"</c> and + <c>~tP</c> formatting instructions, as described above.</p> + <p>You can check this option by calling io:printable_range/0, + which will return <c>unicode</c> or <c>latin1</c>. To be + compatible with future (expected) extensions to the settings, + one should rather use <c>io_lib:printable_list/1</c> to check if + a list is printable according to the setting. That function will + take into account new possible settings returned from + <c>io:printable_range/0</c>.</p> + </item> + <tag>The <c>+fn</c>{<c>l</c>|<c>a</c>|<c>u</c>} + [{<c>w</c>|<c>i</c>|<c>e</c>}] + flag to <seealso marker="erts:erl"><c>erl(1)</c></seealso></tag> + <item> + <p>This flag affects how the file names are to be interpreted. On + operating systems with transparent file naming, this has to be + specified to allow for file naming in Unicode characters (and + for correct interpretation of file names containing characters + > 255.</p> + <p><c>+fnl</c> means bytewise interpretation of file names, which + was the usual way to represent ISO-Latin-1 file names before + UTF-8 file naming got widespread.</p> + <p><c>+fnu</c> means that file names are encoded in UTF-8, which + is nowadays the common scheme (although not enforced).</p> + <p><c>+fna</c> means that you automatically select between + <c>+fnl</c> and <c>+fnu</c>, based on the <c>LANG</c> and + <c>LC_CTYPE</c> environment variables. This is optimistic + heuristics indeed, nothing enforces a user to have a terminal + with the same encoding as the file system, but usually, this is + the case. This is the default on all Unix-like operating + systems except MacOS X.</p> + + <p>The file name translation mode can be read with the + <c>file:native_name_encoding/0</c> function, which returns + <c>latin1</c> (meaning bytewise encoding) or <c>utf8</c>.</p> + </item> + <tag><seealso marker="stdlib:epp#default_encoding/0"> + <c>epp:default_encoding/0</c></seealso></tag> + <item> + <p>This function returns the default encoding for Erlang source + files (if no encoding comment is present) in the currently + running release. In Erlang/OTP R16B <c>latin1</c> was returned (meaning + bytewise encoding). In Erlang/OTP 17.0 and forward it returns + <c>utf8</c>.</p> + <p>The encoding of each file can be specified using comments as + described in + <seealso marker="stdlib:epp#encoding"><c>epp(3)</c></seealso>.</p> + </item> + <tag><seealso marker="stdlib:io#setopts/1"><c>io:setopts/</c>{<c>1</c>,<c>2</c>}</seealso> and the <c>-oldshell</c>/<c>-noshell</c> flags.</tag> + <item> + <p>When Erlang is started with <c>-oldshell</c> or + <c>-noshell</c>, the I/O-server for <c>standard_io</c> is default + set to bytewise encoding, while an interactive shell defaults to + what the environment variables says.</p> + <p>With the <c>io:setopts/2</c> function you can set the + encoding of a file or other I/O-server. This can also be set when + opening a file. Setting the terminal (or other + <c>standard_io</c> server) unconditionally to the option + <c>{encoding,utf8}</c> will for example make UTF-8 encoded characters + being written to the device regardless of how Erlang was started or + the users environment.</p> + <p>Opening files with <c>encoding</c> option is convenient when + writing or reading text files in a known encoding.</p> + <p>You can retrieve the <c>encoding</c> setting for an I/O-server + using <seealso + marker="stdlib:io#getopts/1"><c>io:getopts()</c></seealso>.</p> + </item> + </taglist> +</section> <section> -<title>Byte order marks</title> -<p>A common method of identifying encoding in text-files is to put a byte order mark (BOM) first in the file. The BOM is the codepoint 16#FEFF encoded in the same way as the rest of the file. If such a file is to be read, the first few bytes (depending on encoding) is not part of the actual text. This code outlines how to open a file which is believed to have a BOM and set the files encoding and position for further sequential reading (preferably using the <seealso marker="stdlib:io">io</seealso> module). Note that error handling is omitted from the code:</p> + <title>Recipes</title> + <p>When starting with Unicode, one often stumbles over some common + issues. I try to outline some methods of dealing with Unicode data + in this section.</p> + <section> + <title>Byte Order Marks</title> + <p>A common method of identifying encoding in text-files is to put + a byte order mark (BOM) first in the file. The BOM is the + code point 16#FEFF encoded in the same way as the rest of the + file. If such a file is to be read, the first few bytes (depending + on encoding) is not part of the actual text. This code outlines + how to open a file which is believed to have a BOM and set the + files encoding and position for further sequential reading + (preferably using the <seealso marker="stdlib:io"><c>io</c></seealso> + module). Note that error handling is omitted from the code:</p> <code> open_bom_file_for_reading(File) -> {ok,F} = file:open(File,[read,binary]), @@ -261,8 +1125,15 @@ open_bom_file_for_reading(File) -> io:setopts(F,[{encoding,Type}]), {ok,F}. </code> -<p>The <c>unicode:bom_to_encoding/1</c> function identifies the encoding from a binary of at least four bytes. It returns, along with an term suitable for setting the encoding of the file, the actual length of the BOM, so that the file position can be set accordingly. Note that <c>file:position</c> always works on byte-offsets, so that the actual byte-length of the BOM is needed.</p> -<p>To open a file for writing and putting the BOM first is even simpler:</p> + <p>The <c>unicode:bom_to_encoding/1</c> function identifies the + encoding from a binary of at least four bytes. It returns, along + with an term suitable for setting the encoding of the file, the + actual length of the BOM, so that the file position can be set + accordingly. Note that <c>file:position/2</c> always works on + byte-offsets, so that the actual byte-length of the BOM is + needed.</p> + <p>To open a file for writing and putting the BOM first is even + simpler:</p> <code> open_bom_file_for_writing(File,Encoding) -> {ok,F} = file:open(File,[write,binary]), @@ -270,29 +1141,95 @@ open_bom_file_for_writing(File,Encoding) -> io:setopts(F,[{encoding,Encoding}]), {ok,F}. </code> -<p>In both cases the file is then best processed using the <c>io</c> module, as the functions in <c>io</c> can handle codepoints beyond the ISO-latin-1 range.</p> -</section> -<section> -<title>Formatted input and output</title> -<p>When reading and writing to Unicode-aware entities, like the User or a file opened for Unicode translation, you will probably want to format text strings using the functions in <seealso marker="stdlib:io">io</seealso> or <seealso marker="stdlib:io_lib">io_lib</seealso>. For backward compatibility reasons, these functions don't accept just any list as a string, but require e special "translation modifier" when working with Unicode texts. The modifier is "t". When applied to the "s" control character in a formatting string, it accepts all Unicode codepoints and expect binaries to be in UTF-8:</p> -<pre> -1> <input>io:format("~ts~n",[<<"���"/utf8>>]).</input> -��� -ok -2> <input>io:format("~s~n",[<<"���"/utf8>>]).</input> + <p>In both cases the file is then best processed using the + <c>io</c> module, as the functions in <c>io</c> can handle code + points beyond the ISO-latin-1 range.</p> + </section> + <section> + <title>Formatted I/O</title> + <p>When reading and writing to Unicode-aware entities, like the + User or a file opened for Unicode translation, you will probably + want to format text strings using the functions in <seealso + marker="stdlib:io"><c>io</c></seealso> or <seealso + marker="stdlib:io_lib"><c>io_lib</c></seealso>. For backward + compatibility reasons, these functions do not accept just any list + as a string, but require a special <em>translation modifier</em> + when working with Unicode texts. The modifier is <c>t</c>. When + applied to the <c>s</c> control character in a formatting string, + it accepts all Unicode code points and expect binaries to be in + UTF-8:</p> + <pre> +1> <input>io:format("~ts~n",[<<"åäö"/utf8>>]).</input> åäö +ok +2> <input>io:format("~s~n",[<<"åäö"/utf8>>]).</input> +åäö ok</pre> -<p>Obviously the second <c>io:format</c> gives undesired output because the UTF-8 binary is not in latin1. Because ISO-latin-1 is still the defined character set of Erlang, the non prefixed "s" control character expects ISO-latin-1 in binaries as well as lists.</p> -<p>As long as the data is always lists, the "t" modifier can be used for any string, but when binary data is involved, care must be taken to make the tight choice of formatting characters.</p> -<p>The function <c>format</c> in <c>io_lib</c> behaves similarly. This function is defined to return a deep list of characters and the output could easily be converted to binary data for outputting on a device of any kind by a simple <c>erlang:list_to_binary</c>. When the translation modifier is used, the list can however contain characters that cannot be stored in one byte. The call to <c>erlang:list_to_binary</c> will in that case fail. However, if the io_server you want to communicate with is Unicode-aware, the list returned can still be used directly:</p> -<image file="ushell3.gif"><icaption>io_lib:format with Unicode translation</icaption></image> -<p>The Unicode string is returned as a Unicode list, why the return value of <c>io_lib:format</c> no longer qualifies as a regular Erlang string (the function <seealso marker="stdlib:io_lib#deep_char_list/1">io_lib:deep_char_list</seealso> will, as an example, return <c>false</c>). The Unicode list is however valid input to the <seealso marker="stdlib:io#put_chars/2">io:put_chars</seealso> function, so data can be output on any Unicode capable device anyway. If the device is a terminal, characters will be output in the \x{H ...} format if encoding is <c>latin1</c> otherwise in UTF-8 (for the non-interactive terminal - "oldshell" or "noshell") or whatever is suitable to show the character properly (for an interactive terminal - the regular shell). The bottom line is that you can always send Unicode data to the <c>standard_io</c> device. Files will however only accept Unicode codepoints beyond ISO-latin-1 if <c>encoding</c> is set to something else than <c>latin1</c>.</p> -</section> -<section> -<title>Heuristic identification of UTF-8</title> -<p>While it's strongly encouraged that the actual encoding of characters in binary data is known prior to processing, that is not always possible. On a typical Linux® system, there is a mix of UTF-8 and ISO-latin-1 text files and there are seldom any BOM's in the files to identify them.</p> -<p>UTF-8 is designed in such a way that ISO-latin-1 characters with numbers beyond the 7-bit ASCII range are seldom considered valid when decoded as UTF-8. Therefore one can usually use heuristics to determine if a file is in UTF-8 or if it is encoded in ISO-latin-1 (one byte per character) encoding. The <c>unicode</c> module can be used to determine if data can be interpreted as UTF-8:</p> -<code> + <p>Obviously the second <c>io:format/2</c> gives undesired output + because the UTF-8 binary is not in latin1. For backward + compatibility, the non prefixed <c>s</c> control character expects + bytewise encoded ISO-latin-1 characters in binaries and lists + containing only code points < 256.</p> + <p>As long as the data is always lists, the <c>t</c> modifier can + be used for any string, but when binary data is involved, care + must be taken to make the right choice of formatting characters. A + bytewise encoded binary will also be interpreted as a string and + printed even when using <c>~ts</c>, but it might be mistaken for a + valid UTF-8 string and one should therefore avoid using the + <c>~ts</c> control if the binary contains bytewise encoded + characters and not UTF-8.</p> + <p>The function <c>format/2</c> in <c>io_lib</c> behaves + similarly. This function is defined to return a deep list of + characters and the output could easily be converted to binary data + for outputting on a device of any kind by a simple + <c>erlang:list_to_binary/1</c>. When the translation modifier is + used, the list can however contain characters that cannot be + stored in one byte. The call to <c>erlang:list_to_binary/1</c> + will in that case fail. However, if the I/O server you want to + communicate with is Unicode-aware, the list returned can still be + used directly:</p> +<pre> +$ <input>erl +pc unicode</input> +Erlang R16B (erts-5.10.1) [source] [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.10.1 (abort with ^G) +1> <input>io_lib:format("~ts~n", ["Γιούνικοντ"]).</input> +["Γιούνικοντ","\n"] +2> <input>io:put_chars(io_lib:format("~ts~n", ["Γιούνικοντ"])).</input> +Γιούνικοντ +ok</pre> + <p>The Unicode string is returned as a Unicode list, which is + recognized as such since the Erlang shell uses the Unicode + encoding (and is started with all Unicode characters considered + printable). The Unicode list is valid input to the <seealso + marker="stdlib:io#put_chars/2"><c>io:put_chars/2</c></seealso> function, + so data can be output on any Unicode capable device. If the device + is a terminal, characters will be output in the <c>\x{</c>H + ...<c>}</c> format if encoding is <c>latin1</c> otherwise in UTF-8 + (for the non-interactive terminal - "oldshell" or "noshell") or + whatever is suitable to show the character properly (for an + interactive terminal - the regular shell). The bottom line is that + you can always send Unicode data to the <c>standard_io</c> + device. Files will however only accept Unicode code points beyond + ISO-latin-1 if <c>encoding</c> is set to something else than + <c>latin1</c>.</p> + </section> + <section> + <title>Heuristic Identification of UTF-8</title> + <p>While it is + strongly encouraged that the actual encoding of characters in + binary data is known prior to processing, that is not always + possible. On a typical Linux system, there is a mix of UTF-8 + and ISO-latin-1 text files and there are seldom any BOM's in the + files to identify them.</p> + <p>UTF-8 is designed in such a way that ISO-latin-1 characters + with numbers beyond the 7-bit ASCII range are seldom considered + valid when decoded as UTF-8. Therefore one can usually use + heuristics to determine if a file is in UTF-8 or if it is encoded + in ISO-latin-1 (one byte per character) encoding. The + <c>unicode</c> module can be used to determine if data can be + interpreted as UTF-8:</p> + <code> heuristic_encoding_bin(Bin) when is_binary(Bin) -> case unicode:characters_to_binary(Bin,utf8,utf8) of Bin -> @@ -300,9 +1237,16 @@ heuristic_encoding_bin(Bin) when is_binary(Bin) -> _ -> latin1 end. -</code> -<p>If one does not have a complete binary of the file content, one could instead chunk through the file and check part by part. The return-tuple <c>{incomplete,Decoded,Rest}</c> from <c>unicode:characters_to_binary/{1,2,3}</c> comes in handy. The incomplete rest from one chunk of data read from the file is prepended to the next chunk and we therefore circumvent the problem of character boundaries when reading chunks of bytes in UTF-8 encoding:</p> -<code> + </code> + <p>If one does not have a complete binary of the file content, one + could instead chunk through the file and check part by part. The + return-tuple <c>{incomplete,Decoded,Rest}</c> from + <c>unicode:characters_to_binary/{1,2,3}</c> comes in handy. The + incomplete rest from one chunk of data read from the file is + prepended to the next chunk and we therefore circumvent the + problem of character boundaries when reading chunks of bytes in + UTF-8 encoding:</p> + <code> heuristic_encoding_file(FileName) -> {ok,F} = file:open(FileName,[read,binary]), loop_through_file(F,<<>>,file:read(F,1024)). @@ -320,9 +1264,12 @@ loop_through_file(F,Acc,{ok,Bin}) when is_binary(Bin) -> Res when is_binary(Res) -> loop_through_file(F,<<>>,file:read(F,1024)) end. -</code> -<p>Another option is to try to read the whole file in utf8 encoding and see if it fails. Here we need to read the file using <c>io:get_chars/3</c>, as we have to succeed in reading characters with a codepoint over 255:</p> -<code> + </code> + <p>Another option is to try to read the whole file in UTF-8 + encoding and see if it fails. Here we need to read the file using + <c>io:get_chars/3</c>, as we have to succeed in reading characters + with a code point over 255:</p> + <code> heuristic_encoding_file2(FileName) -> {ok,F} = file:open(FileName,[read,binary,{encoding,utf8}]), loop_through_file2(F,io:get_chars(F,'',1024)). @@ -333,7 +1280,68 @@ loop_through_file2(_,{error,_Err}) -> latin1; loop_through_file2(F,Bin) when is_binary(Bin) -> loop_through_file2(F,io:get_chars(F,'',1024)). -</code> -</section> + </code> + </section> + <section> + <title>Lists of UTF-8 Bytes</title> + <p>For various reasons, you may find yourself having a list of + UTF-8 bytes. This is not a regular string of Unicode characters as + each element in the list does not contain one character. Instead + you get the "raw" UTF-8 encoding that you have in binaries. This + is easily converted to a proper Unicode string by first converting + byte per byte into a binary and then converting the binary of + UTF-8 encoded characters back to a Unicode string:</p> + <code> + utf8_list_to_string(StrangeList) -> + unicode:characters_to_list(list_to_binary(StrangeList)). + </code> + </section> + <section> + <title>Double UTF-8 Encoding</title> + <p>When working with binaries, you may get the horrible "double + UTF-8 encoding", where strange characters are encoded in your + binaries or files that you did not expect. What you may have got, + is a UTF-8 encoded binary that is for the second time encoded as + UTF-8. A common situation is where you read a file, byte by byte, + but the actual content is already UTF-8. If you then convert the + bytes to UTF-8, using i.e. the <c>unicode</c> module or by + writing to a file opened with the <c>{encoding,utf8}</c> + option. You will have each <i>byte</i> in the in the input file + encoded as UTF-8, not each character of the original text (one + character may have been encoded in several bytes). There is no + real remedy for this other than being very sure of which data is + actually encoded in which format, and never convert UTF-8 data + (possibly read byte by byte from a file) into UTF-8 again.</p> + <p>The by far most common situation where this happens, is when + you get lists of UTF-8 instead of proper Unicode strings, and then + convert them to UTF-8 in a binary or on a file:</p> + <code> + wrong_thing_to_do() -> + {ok,Bin} = file:read_file("an_utf8_encoded_file.txt"), + MyList = binary_to_list(Bin), %% Wrong! It is an utf8 binary! + {ok,C} = file:open("catastrophe.txt",[write,{encoding,utf8}]), + io:put_chars(C,MyList), %% Expects a Unicode string, but get UTF-8 + %% bytes in a list! + file:close(C). %% The file catastrophe.txt contains more or less unreadable + %% garbage! + </code> + <p>Make very sure you know what a binary contains before + converting it to a string. If no other option exists, try + heuristics:</p> + <code> + if_you_can_not_know() -> + {ok,Bin} = file:read_file("maybe_utf8_encoded_file.txt"), + MyList = case unicode:characters_to_list(Bin) of + L when is_list(L) -> + L; + _ -> + binary_to_list(Bin) %% The file was bytewise encoded + end, + %% Now we know that the list is a Unicode string, not a list of UTF-8 bytes + {ok,G} = file:open("greatness.txt",[write,{encoding,utf8}]), + io:put_chars(G,MyList), %% Expects a Unicode string, which is what it gets! + file:close(G). %% The file contains valid UTF-8 encoded Unicode characters! + </code> + </section> </section> </chapter> diff --git a/lib/stdlib/doc/src/ushell1.gif b/lib/stdlib/doc/src/ushell1.gif Binary files differdeleted file mode 100644 index 7c46464fd2..0000000000 --- a/lib/stdlib/doc/src/ushell1.gif +++ /dev/null diff --git a/lib/stdlib/doc/src/ushell1.ps b/lib/stdlib/doc/src/ushell1.ps deleted file mode 100644 index 95bfebf194..0000000000 --- a/lib/stdlib/doc/src/ushell1.ps +++ /dev/null @@ -1,1196 +0,0 @@ -%!PS-Adobe-3.0 -%%Creator: GIMP PostScript file plugin V 1.17 by Peter Kirchgessner -%%Title: ushell1.ps -%%CreationDate: Mon Mar 16 09:53:27 2009 -%%DocumentData: Clean7Bit -%%LanguageLevel: 2 -%%Pages: 1 -%%BoundingBox: 14 14 468 142 -%%EndComments -%%BeginProlog -% Use own dictionary to avoid conflicts -10 dict begin -%%EndProlog -%%Page: 1 1 -% Translate for offset -14.173228346456694 14.173228346456694 translate -% Translate to begin of first scanline -0 127.55905511811024 translate -453.54330708661422 -127.55905511811024 scale -% Image geometry -640 180 8 -% Transformation matrix -[ 640 0 0 180 0 0 ] -% Strings to hold RGB-samples per scanline -/rstr 640 string def -/gstr 640 string def -/bstr 640 string def -{currentfile /ASCII85Decode filter /RunLengthDecode filter rstr readstring pop} -{currentfile /ASCII85Decode filter /RunLengthDecode filter gstr readstring pop} -{currentfile /ASCII85Decode filter /RunLengthDecode filter bstr readstring pop} -true 3 -%%BeginData: 67571 ASCII Bytes -colorimage -JP1PeJP1PeJP1L~> -JP1PeJP1PeJP1L~> -JP1PeJP1PeJP1L~> -!!e'9JNA?CJNABDJ,~> -!!e'9JNA?CJNABDJ,~> -!!e'9JNA?CJNABDJ,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$2%<!Lr-2rr]6=Dt\b^JcC<$JcD\KJ,~> -!$2%<!Lr-2rr]6=Dt\b^JcC<$JcD\KJ,~> -!$2%<!Lr-2rr]6=Dt\b^JcC<$JcD\KJ,~> -#9EjEY>Q6)=6BMbc`J;XJcC<$JcC<$W;hA~> -#9EjEY>Q6)=6BMbc`J;XJcC<$JcC<$W;hA~> -#9EjEY>Q6)=6BMbc`J;XJcC<$JcC<$W;hA~> -#T`rUH-/@H`Dbmu!A3bks+13$s+13Ks*t~> -#T`rUH-/@H`Dbmu!A3bks+13$s+13Ks*t~> -#T`rUH-/@H`Dbmu!A3bks+13$s+13Ks*t~> -#T`rEG5Y4]rp0@Z!W@cP*=4P!s-oDP9H?1krVlmMmt(Lis+13$s/>sJ~> -#T`rEG5Y4]rp0@Z!W@cP*=4P!s-oDP9H?1krVlmMmt(Lis+13$s/>sJ~> -#T`rEG5Y4]rp0@Z!W@cP*=4P!s-oDP9H?1krVlmMmt(Lis+13$s/>sJ~> -#9EjER>jY@r:g3lQA5D=$0F2Hs)Ak%s4op<rrF_?JcC<$JcC<$W;hA~> -#9EjER>jY@r:g3lQA5D=$0F2Hs)Ak%s4op<rrF_?JcC<$JcC<$W;hA~> -#9EjER>jY@r:g3lQA5D=$0F2Hs)Ak%s4op<rrF_?JcC<$JcC<$W;hA~> -!$2(="-F9Q\G-"(Q=^'2$*?/ds)G.?s5e.srrF_?JcC<$JcC<$W;hA~> -!$2(="-F9Q\G-"(Q=^'2$*?/ds)G.?s5e.srrF_?JcC<$JcC<$W;hA~> -!$2(="-F9Q\G-"(Q=^'2$*?/ds)G.?s5e.srrF_?JcC<$JcC<$W;hA~> -!$2%<"&I0WZ2">"Q8&8B"FpIOENK!9!A3bks+13$s+13Ks*t~> -!$2%<"&I0WZ2">"Q8&8B"FpIOENK!9!A3bks+13$s+13Ks*t~> -!$2%<"&I0WZ2">"Q8&8B"FpIOENK!9!A3bks+13$s+13Ks*t~> -#T`rq^Ah!RpEo\8!LAK:rrI,@q>UIImt(Lis+13$s/>sJ~> -#T`rq^Ah!RpEo\8!LAK:rrI,@q>UIImt(Lis+13$s/>sJ~> -#T`rq^Ah!RpEo\8!LAK:rrI,@q>UIImt(Lis+13$s/>sJ~> -#T`s"JSH?.CSgh+!RuStC&iMXrrI,@qu6esC(k*/JcC<$JcC<$WW.J~> -#T`s"JSH?.CSgh+!RuStC&iMXrrI,@qu6esC(k*/JcC<$JcC<$WW.J~> -#T`s"JSH?.CSgh+!RuStC&iMXrrI,@qu6esC(k*/JcC<$JcC<$WW.J~> -#9EjEgp/o#[J'V#fD`&U])M^1eE6Z.!7LkP!5F*bJcC<$JcD_LJ,~> -#9EjEgp/o#[J'V#fD`&U])M^1eE6Z.!7LkP!5F*bJcC<$JcD_LJ,~> -#9EjEgp/o#[J'V#fD`&U])M^1eE6Z.!7LkP!5F*bJcC<$JcD_LJ,~> -!$2%<!T*O$s+13$s+13+s*t~> -!$2%<!T*O$s+13$s+13+s*t~> -!$2%<!T*O$s+13$s+13+s*t~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$.X1!VbZgrrMcToD\g]rn%5Fci4"4rn%5Kp&>-Vf\#!)rr_95f\lE%"5DJ\kK!T&r;P=KmIgJZ -p&<SDo\]ZKoD[ABp@\Fcm/GW;rJ1CTgXt0Ap&>$hrn%5=kPp&~> -!$.X1!VbZgrrMcToD\g]rn%5Fci4"4rn%5Kp&>-Vf\#!)rr_95f\lE%"5DJ\kK!T&r;P=KmIgJZ -p&<SDo\]ZKoD[ABp@\Fcm/GW;rJ1CTgXt0Ap&>$hrn%5=kPp&~> -!$.X1!VbZgrrMcToD\g]rn%5Fci4"4rn%5Kp&>-Vf\#!)rr_95f\lE%"5DJ\kK!T&r;P=KmIgJZ -p&<SDo\]ZKoD[ABp@\Fcm/GW;rJ1CTgXt0Ap&>$hrn%5=kPp&~> -!Zh=)r4;sJp\t?M]=[dnrrC^M])^+RrrBt8rrCOG])^O`rrN,;oD\mfUOUkp!5JHD!:K[_!<2l- -"nM]nb];P3rrf;C6q#_Srrf>i6k8JSrrZO_6rs9d"4Ffn`;BQ8r5SL2!SZc5rrL6To`##66p3I# -rrWs'7#p%%s5ESL#i+SBs6i?D-]@Zt"M5R?7*O]k#gN&Bs2.5m(WQ.J"Fqsi7/+e&!SceorrM<; -mf3=!!7LiG"&[email protected])jpjdIXT/=<lMlA~> -!Zh=)r4;sJp\t?M]=[dnrrC^M])^+RrrBt8rrCOG])^O`rrN,;oD\mfUOUkp!5JHD!:K[_!<2l- -"nM]nb];P3rrf;C6q#_Srrf>i6k8JSrrZO_6rs9d"4Ffn`;BQ8r5SL2!SZc5rrL6To`##66p3I# -rrWs'7#p%%s5ESL#i+SBs6i?D-]@Zt"M5R?7*O]k#gN&Bs2.5m(WQ.J"Fqsi7/+e&!SceorrM<; -mf3=!!7LiG"&[email protected])jpjdIXT/=<lMlA~> -!Zh=)r4;sJp\t?M]=[dnrrC^M])^+RrrBt8rrCOG])^O`rrN,;oD\mfUOUkp!5JHD!:K[_!<2l- -"nM]nb];P3rrf;C6q#_Srrf>i6k8JSrrZO_6rs9d"4Ffn`;BQ8r5SL2!SZc5rrL6To`##66p3I# -rrWs'7#p%%s5ESL#i+SBs6i?D-]@Zt"M5R?7*O]k#gN&Bs2.5m(WQ.J"Fqsi7/+e&!SceorrM<; -mf3=!!7LiG"&[email protected])jpjdIXT/=<lMlA~> -"!.E>/H&uWGk_4?XC2t&hZ!Um6iLKpEPqeU!Nm==rrAJc@0&Z7rr3%sBt![6!U2E,rrMo!m/I&" -r*]TWq>UHor*]UHci3qFSUgA4!NC.^rrFq?p&>%u_#438a`V$#Fo21>SLO=5!Hk=9rrIX^qu6]" -qYL3mju2l3!$0bm!oI+@o`#!G9q_Fa!Ki<5rrK`?iVrtr.,4\"!ER55rrIY@bPqUQnGW@fGGa6s -!Mju/rrf?1@<TfkrrKf@p&>'T2Z3RT*U<ZT~> -"!.E>/H&uWGk_4?XC2t&hZ!Um6iLKpEPqeU!Nm==rrAJc@0&Z7rr3%sBt![6!U2E,rrMo!m/I&" -r*]TWq>UHor*]UHci3qFSUgA4!NC.^rrFq?p&>%u_#438a`V$#Fo21>SLO=5!Hk=9rrIX^qu6]" -qYL3mju2l3!$0bm!oI+@o`#!G9q_Fa!Ki<5rrK`?iVrtr.,4\"!ER55rrIY@bPqUQnGW@fGGa6s -!Mju/rrf?1@<TfkrrKf@p&>'T2Z3RT*U<ZT~> -"!.E>/H&uWGk_4?XC2t&hZ!Um6iLKpEPqeU!Nm==rrAJc@0&Z7rr3%sBt![6!U2E,rrMo!m/I&" -r*]TWq>UHor*]UHci3qFSUgA4!NC.^rrFq?p&>%u_#438a`V$#Fo21>SLO=5!Hk=9rrIX^qu6]" -qYL3mju2l3!$0bm!oI+@o`#!G9q_Fa!Ki<5rrK`?iVrtr.,4\"!ER55rrIY@bPqUQnGW@fGGa6s -!Mju/rrf?1@<TfkrrKf@p&>'T2Z3RT*U<ZT~> -"!.E>Fn#D352P/r!Go">rs$)Ds8SmD(]"(;jFF`>s."Z-J$8PF!JQp-rrML@m/I&+mf*?sJ*6h2 -!mQ8Ap&>&lF34F_1[4T4!F<M>rrU8keG9+GR!:(SrrI8?nc&V>o(r@eju2l3!$0en"6=u%O7iMT -gjhP\r;Qe[MtR)N]4'_!"297-g\h'P<lXh4!J$`arrGO?rVlnBVV_=RUj2D/#+pAEs3lJ>rVlo3 [email protected]#ju3/;!$1A)J,~> -"!.E>Fn#D352P/r!Go">rs$)Ds8SmD(]"(;jFF`>s."Z-J$8PF!JQp-rrML@m/I&+mf*?sJ*6h2 -!mQ8Ap&>&lF34F_1[4T4!F<M>rrU8keG9+GR!:(SrrI8?nc&V>o(r@eju2l3!$0en"6=u%O7iMT -gjhP\r;Qe[MtR)N]4'_!"297-g\h'P<lXh4!J$`arrGO?rVlnBVV_=RUj2D/#+pAEs3lJ>rVlo3 [email protected]#ju3/;!$1A)J,~> -"!.E>Fn#D352P/r!Go">rs$)Ds8SmD(]"(;jFF`>s."Z-J$8PF!JQp-rrML@m/I&+mf*?sJ*6h2 -!mQ8Ap&>&lF34F_1[4T4!F<M>rrU8keG9+GR!:(SrrI8?nc&V>o(r@eju2l3!$0en"6=u%O7iMT -gjhP\r;Qe[MtR)N]4'_!"297-g\h'P<lXh4!J$`arrGO?rVlnBVV_=RUj2D/#+pAEs3lJ>rVlo3 [email protected]#ju3/;!$1A)J,~> -"!.E>Fo21B`NfH(A8hDG!C#B=rrB%tA-dJ\s0]Y*A7U/grro!)A9-Unq#:A2Yl=Y,]4(`5N:.e` -rsS:7]`8"tO7rV9LTgFO!$1t:!-S9O&?Pp3K(J/9A?l17I9dLsA@MR<!+u4@!5/(+!?L;$A,sX@ -rrHo@r;QeISb<!`WH8";!8%0["6KR_df!\YlMob-rr3C]n,M+2s.s7:o`+s/rF?$+s8Th3A,uW, -rrFq?p&>%u_#=96O,`u8"-Sf5.JNiGFf1%+A;L6b!gR;1rVm%pA.`0ZP5P=\ju2l3!$1t:!.4]U% -&a.*Lh(\`A?>h2KC/YK!3uM&!omgerVm#hE4h0krVlrPA?Pn2"QaaBIA$N<!Ki<5rrK`?rVm2rJ -cEJqAD7(`h>Updc%Y]errTT=df'1K_1:6*g\h'P<lXh4!J$a=rrBe3A-;i2s1/,>"DIi8`ioCA# -^67J_6fbDA97bM!36$/!-n8<'sV9g<Fg^]s*(>sA7UJqs/40BEb(..rrA/[A,qbkrr@uVA,qqpr -s4?iA;[1-s8RZLA,r>%rrVe&PlC[`45p2=!K3->rrKf@p&>'T2Z3RT*W?!?Us]5;rF?8Ss8R9Bc -X^S/s8RT~> -"!.E>Fo21B`NfH(A8hDG!C#B=rrB%tA-dJ\s0]Y*A7U/grro!)A9-Unq#:A2Yl=Y,]4(`5N:.e` -rsS:7]`8"tO7rV9LTgFO!$1t:!-S9O&?Pp3K(J/9A?l17I9dLsA@MR<!+u4@!5/(+!?L;$A,sX@ -rrHo@r;QeISb<!`WH8";!8%0["6KR_df!\YlMob-rr3C]n,M+2s.s7:o`+s/rF?$+s8Th3A,uW, -rrFq?p&>%u_#=96O,`u8"-Sf5.JNiGFf1%+A;L6b!gR;1rVm%pA.`0ZP5P=\ju2l3!$1t:!.4]U% -&a.*Lh(\`A?>h2KC/YK!3uM&!omgerVm#hE4h0krVlrPA?Pn2"QaaBIA$N<!Ki<5rrK`?rVm2rJ -cEJqAD7(`h>Updc%Y]errTT=df'1K_1:6*g\h'P<lXh4!J$a=rrBe3A-;i2s1/,>"DIi8`ioCA# -^67J_6fbDA97bM!36$/!-n8<'sV9g<Fg^]s*(>sA7UJqs/40BEb(..rrA/[A,qbkrr@uVA,qqpr -s4?iA;[1-s8RZLA,r>%rrVe&PlC[`45p2=!K3->rrKf@p&>'T2Z3RT*W?!?Us]5;rF?8Ss8R9Bc -X^S/s8RT~> -"!.E>Fo21B`NfH(A8hDG!C#B=rrB%tA-dJ\s0]Y*A7U/grro!)A9-Unq#:A2Yl=Y,]4(`5N:.e` -rsS:7]`8"tO7rV9LTgFO!$1t:!-S9O&?Pp3K(J/9A?l17I9dLsA@MR<!+u4@!5/(+!?L;$A,sX@ -rrHo@r;QeISb<!`WH8";!8%0["6KR_df!\YlMob-rr3C]n,M+2s.s7:o`+s/rF?$+s8Th3A,uW, -rrFq?p&>%u_#=96O,`u8"-Sf5.JNiGFf1%+A;L6b!gR;1rVm%pA.`0ZP5P=\ju2l3!$1t:!.4]U% -&a.*Lh(\`A?>h2KC/YK!3uM&!omgerVm#hE4h0krVlrPA?Pn2"QaaBIA$N<!Ki<5rrK`?rVm2rJ -cEJqAD7(`h>Updc%Y]errTT=df'1K_1:6*g\h'P<lXh4!J$a=rrBe3A-;i2s1/,>"DIi8`ioCA# -^67J_6fbDA97bM!36$/!-n8<'sV9g<Fg^]s*(>sA7UJqs/40BEb(..rrA/[A,qbkrr@uVA,qqpr -s4?iA;[1-s8RZLA,r>%rrVe&PlC[`45p2=!K3->rrKf@p&>'T2Z3RT*W?!?Us]5;rF?8Ss8R9Bc -X^S/s8RT~> -"!.E>+oY"=nGiOLJ4Q':Y\F(9!C#B=rrC[M[h5T^s+Mqh\$r2\s.PF]\#s&_q#:A21B'fKA^g\. -li/"%rrth%K`D'Nb5VDAU3cP5!$2";!HG1>[hOJ#s2@f;\$pmts21i\\$t2ns'E/5[fL`lq#:@. ->Q2)4ER=CY!i_%@r;QeISb<!`WH8%<!Tdkj[f]k-he;tt"'>BB;Z?\)39C2.O@Y5;[oi[TF8`QM ->5uWerO2c3r;QdRl1P&W?,6F="cnXr84[+erreOOo(+=)rsNs&T!u2#L]@D"[ho#C"k:"&Y.)XQ -rrM7?o`"n3r;QeBVuF.6Lo^P:UT.b3KX(P47fKjtJ@GOX!mgp]rVm"#a8_-[rVlr7!.+YE"nc'C -s*^R<rrJ7?p&>')@K$34qP-T)\$ol2lsTh%!c/D1rr3%Q!4Dh+"j;#Cs$>E;rrH0?p&>&CSc&Kf -iVg4f>lVWdrjN$<@K3$Jrr3BIs8SH4NjlL"D?$enrjMp-F85bQgUAo,\&JCIG;#Mr\"8?Sen[gZ -\!r?VOdQ-W"IG;Os2k8L%$R(YKV,`_S1]'dI\ZnO!K<iRrrVKd:]C@p45p2=!K3->rrKf@p&>'T -2Z3R\*WQ/Q8;ZX3=oGf:EmOcj88>WCDUnc;~> -"!.E>+oY"=nGiOLJ4Q':Y\F(9!C#B=rrC[M[h5T^s+Mqh\$r2\s.PF]\#s&_q#:A21B'fKA^g\. -li/"%rrth%K`D'Nb5VDAU3cP5!$2";!HG1>[hOJ#s2@f;\$pmts21i\\$t2ns'E/5[fL`lq#:@. ->Q2)4ER=CY!i_%@r;QeISb<!`WH8%<!Tdkj[f]k-he;tt"'>BB;Z?\)39C2.O@Y5;[oi[TF8`QM ->5uWerO2c3r;QdRl1P&W?,6F="cnXr84[+erreOOo(+=)rsNs&T!u2#L]@D"[ho#C"k:"&Y.)XQ -rrM7?o`"n3r;QeBVuF.6Lo^P:UT.b3KX(P47fKjtJ@GOX!mgp]rVm"#a8_-[rVlr7!.+YE"nc'C -s*^R<rrJ7?p&>')@K$34qP-T)\$ol2lsTh%!c/D1rr3%Q!4Dh+"j;#Cs$>E;rrH0?p&>&CSc&Kf -iVg4f>lVWdrjN$<@K3$Jrr3BIs8SH4NjlL"D?$enrjMp-F85bQgUAo,\&JCIG;#Mr\"8?Sen[gZ -\!r?VOdQ-W"IG;Os2k8L%$R(YKV,`_S1]'dI\ZnO!K<iRrrVKd:]C@p45p2=!K3->rrKf@p&>'T -2Z3R\*WQ/Q8;ZX3=oGf:EmOcj88>WCDUnc;~> -"!.E>+oY"=nGiOLJ4Q':Y\F(9!C#B=rrC[M[h5T^s+Mqh\$r2\s.PF]\#s&_q#:A21B'fKA^g\. -li/"%rrth%K`D'Nb5VDAU3cP5!$2";!HG1>[hOJ#s2@f;\$pmts21i\\$t2ns'E/5[fL`lq#:@. ->Q2)4ER=CY!i_%@r;QeISb<!`WH8%<!Tdkj[f]k-he;tt"'>BB;Z?\)39C2.O@Y5;[oi[TF8`QM ->5uWerO2c3r;QdRl1P&W?,6F="cnXr84[+erreOOo(+=)rsNs&T!u2#L]@D"[ho#C"k:"&Y.)XQ -rrM7?o`"n3r;QeBVuF.6Lo^P:UT.b3KX(P47fKjtJ@GOX!mgp]rVm"#a8_-[rVlr7!.+YE"nc'C -s*^R<rrJ7?p&>')@K$34qP-T)\$ol2lsTh%!c/D1rr3%Q!4Dh+"j;#Cs$>E;rrH0?p&>&CSc&Kf -iVg4f>lVWdrjN$<@K3$Jrr3BIs8SH4NjlL"D?$enrjMp-F85bQgUAo,\&JCIG;#Mr\"8?Sen[gZ -\!r?VOdQ-W"IG;Os2k8L%$R(YKV,`_S1]'dI\ZnO!K<iRrrVKd:]C@p45p2=!K3->rrKf@p&>'T -2Z3R\*WQ/Q8;ZX3=oGf:EmOcj88>WCDUnc;~> -"!.E>@K+aVr;Q`rJHPNDmOnJ<!C#B9rt+!Ns+Ppms8UV?s*^O>s62?6rrm5&e/6]nr;Qa;qYpcM -e=;Er;p,+>!MXo6rr=);rrG.?rr3F`PlLb'g].;(SH&WV0`:qO+T;<>"6]4S55Zo5_Z/6Crr3"* -^@hL,Lm7f:!Ip[5rrK*?rVloQ62gfch#5\orVlsEq8uV7rsUmKs8Sm*mJm2,s1)Y<rr^sSZ#'C= -!$2";!Aj!5rrHE@rVmFi(nB+*^0^i/Nq35A.KBF4r$r%hs)j7ms8U&>rVlj<qu6[Ho(r@eju2l3 -!$2";!CPT?rs\;\s#T/u49(2%s"_RmrrI\?rr3&oeE6c1"\.)Cs,E*<rrViBl2L\d6/2G>IA$N< -!Ki<5rrK`?r;R&L5j&+H4l>?\rr3&Z/Ed$4$gQ75s8UhXjo>?Hg\h'P<lXh4!J$a8rrX;AWH8(= -"TI-TTmQe=$m#BJQu;Bms6)??OGs2="8^pTS,=c:AcD]17+hJ<&U0-*s8U)>s8Prqqu=?:s(8b> -rrKN?qu7)+E;rqZs8VbKGlLIarr3#elMgebr7'^)rrG4?rr3"WP5YC]]jUO5!Tl<<rs0Y*.qmH" -s8O,<rsE/Hs6;)ns8Q3>s*t~> -"!.E>@K+aVr;Q`rJHPNDmOnJ<!C#B9rt+!Ns+Ppms8UV?s*^O>s62?6rrm5&e/6]nr;Qa;qYpcM -e=;Er;p,+>!MXo6rr=);rrG.?rr3F`PlLb'g].;(SH&WV0`:qO+T;<>"6]4S55Zo5_Z/6Crr3"* -^@hL,Lm7f:!Ip[5rrK*?rVloQ62gfch#5\orVlsEq8uV7rsUmKs8Sm*mJm2,s1)Y<rr^sSZ#'C= -!$2";!Aj!5rrHE@rVmFi(nB+*^0^i/Nq35A.KBF4r$r%hs)j7ms8U&>rVlj<qu6[Ho(r@eju2l3 -!$2";!CPT?rs\;\s#T/u49(2%s"_RmrrI\?rr3&oeE6c1"\.)Cs,E*<rrViBl2L\d6/2G>IA$N< -!Ki<5rrK`?r;R&L5j&+H4l>?\rr3&Z/Ed$4$gQ75s8UhXjo>?Hg\h'P<lXh4!J$a8rrX;AWH8(= -"TI-TTmQe=$m#BJQu;Bms6)??OGs2="8^pTS,=c:AcD]17+hJ<&U0-*s8U)>s8Prqqu=?:s(8b> -rrKN?qu7)+E;rqZs8VbKGlLIarr3#elMgebr7'^)rrG4?rr3"WP5YC]]jUO5!Tl<<rs0Y*.qmH" -s8O,<rsE/Hs6;)ns8Q3>s*t~> -"!.E>@K+aVr;Q`rJHPNDmOnJ<!C#B9rt+!Ns+Ppms8UV?s*^O>s62?6rrm5&e/6]nr;Qa;qYpcM -e=;Er;p,+>!MXo6rr=);rrG.?rr3F`PlLb'g].;(SH&WV0`:qO+T;<>"6]4S55Zo5_Z/6Crr3"* -^@hL,Lm7f:!Ip[5rrK*?rVloQ62gfch#5\orVlsEq8uV7rsUmKs8Sm*mJm2,s1)Y<rr^sSZ#'C= -!$2";!Aj!5rrHE@rVmFi(nB+*^0^i/Nq35A.KBF4r$r%hs)j7ms8U&>rVlj<qu6[Ho(r@eju2l3 -!$2";!CPT?rs\;\s#T/u49(2%s"_RmrrI\?rr3&oeE6c1"\.)Cs,E*<rrViBl2L\d6/2G>IA$N< -!Ki<5rrK`?r;R&L5j&+H4l>?\rr3&Z/Ed$4$gQ75s8UhXjo>?Hg\h'P<lXh4!J$a8rrX;AWH8(= -"TI-TTmQe=$m#BJQu;Bms6)??OGs2="8^pTS,=c:AcD]17+hJ<&U0-*s8U)>s8Prqqu=?:s(8b> -rrKN?qu7)+E;rqZs8VbKGlLIarr3#elMgebr7'^)rrG4?rr3"WP5YC]]jUO5!Tl<<rs0Y*.qmH" -s8O,<rsE/Hs6;)ns8Q3>s*t~> -"!.E>Fo)+AJXc]>rq-0h!C#B>rrMn@rZ)+Z5Q?G(rr38S8H4C6nF56up\tD5YlF#Po_e^h*VfX; -WcJ,<(]GEU&pj9O!$2";!BD(t*<[.Hs8O,=rrr2os8VI?r;Qfh+9!8_PktFNr:'daqu6\'^@qR. -Wd+@:rrIV?p&>&lF8c+>rO`"K"3gbn9)\bl,PfJ[rr3-]jo>@VGlI^FoDc@2qu6]%%/h1H.fB;I -1[4T4!F<M>rt(6GqZ$TP56$WZ*??+'>Q=KrnH8IaFf56=!QA.=rr=):rrFV?qYpTY2Y@"L*W5p< -ofW3o%!VLH3o]*[s,*$?1@+r>!J-a8rr=\N*WHZN[eTk&+9!8^%MHbZrrJ7?p&>')@Jp-+cqXN> -"82WS3;rjX2<Xf8!S.q`*<HH`q>L<o<lXh4!J$a>rrMt`r>btZs8%lW*<[SWs.Of=rraABs-SK= -rrhOCs,`3:rrDlmnGr7]rrGO?rVlnBVZ-T(``E->;9](?qtC&%(&f3V)0#WK;Z7[>'QF(PaSu2B -Uj2q47/e2-Dts,-!B]9>rrJ%@[email protected]#ju3/;!ua,Xm/?qa')`gR'Ysb61B.:TpAFr@~> -"!.E>Fo)+AJXc]>rq-0h!C#B>rrMn@rZ)+Z5Q?G(rr38S8H4C6nF56up\tD5YlF#Po_e^h*VfX; -WcJ,<(]GEU&pj9O!$2";!BD(t*<[.Hs8O,=rrr2os8VI?r;Qfh+9!8_PktFNr:'daqu6\'^@qR. -Wd+@:rrIV?p&>&lF8c+>rO`"K"3gbn9)\bl,PfJ[rr3-]jo>@VGlI^FoDc@2qu6]%%/h1H.fB;I -1[4T4!F<M>rt(6GqZ$TP56$WZ*??+'>Q=KrnH8IaFf56=!QA.=rr=):rrFV?qYpTY2Y@"L*W5p< -ofW3o%!VLH3o]*[s,*$?1@+r>!J-a8rr=\N*WHZN[eTk&+9!8^%MHbZrrJ7?p&>')@Jp-+cqXN> -"82WS3;rjX2<Xf8!S.q`*<HH`q>L<o<lXh4!J$a>rrMt`r>btZs8%lW*<[SWs.Of=rraABs-SK= -rrhOCs,`3:rrDlmnGr7]rrGO?rVlnBVZ-T(``E->;9](?qtC&%(&f3V)0#WK;Z7[>'QF(PaSu2B -Uj2q47/e2-Dts,-!B]9>rrJ%@[email protected]#ju3/;!ua,Xm/?qa')`gR'Ysb61B.:TpAFr@~> -"!.E>Fo)+AJXc]>rq-0h!C#B>rrMn@rZ)+Z5Q?G(rr38S8H4C6nF56up\tD5YlF#Po_e^h*VfX; -WcJ,<(]GEU&pj9O!$2";!BD(t*<[.Hs8O,=rrr2os8VI?r;Qfh+9!8_PktFNr:'daqu6\'^@qR. -Wd+@:rrIV?p&>&lF8c+>rO`"K"3gbn9)\bl,PfJ[rr3-]jo>@VGlI^FoDc@2qu6]%%/h1H.fB;I -1[4T4!F<M>rt(6GqZ$TP56$WZ*??+'>Q=KrnH8IaFf56=!QA.=rr=):rrFV?qYpTY2Y@"L*W5p< -ofW3o%!VLH3o]*[s,*$?1@+r>!J-a8rr=\N*WHZN[eTk&+9!8^%MHbZrrJ7?p&>')@Jp-+cqXN> -"82WS3;rjX2<Xf8!S.q`*<HH`q>L<o<lXh4!J$a>rrMt`r>btZs8%lW*<[SWs.Of=rraABs-SK= -rrhOCs,`3:rrDlmnGr7]rrGO?rVlnBVZ-T(``E->;9](?qtC&%(&f3V)0#WK;Z7[>'QF(PaSu2B -Uj2q47/e2-Dts,-!B]9>rrJ%@[email protected]#ju3/;!ua,Xm/?qa')`gR'Ysb61B.:TpAFr@~> -"!.E>Fo)+=JXcK8!C#B>s8S,ZrrrD25Q?G(rr35R8H7pi/1a!Yrs!;Ds8UtYjSf)Y*W?!=j7N?N -"KHMB;p,+>!MXo6rrGC?rVlmYj8/cU*W#d@m4eS?kjSQ)rVln:Xn_nrf_tgN?G?F=!qFb*rVlrl -R#h.E!q(Q@p&>&lF8c+>q;2)M""Woj9)\bl,PfJ[rr3-]jo>@VGl7RB\RYU<"5*XYD"mr11[4T4 -!F<M>rrJ1?rr3#U55bE]o-sG6#'Ggrs8U&>rVlj<qu6dKo)J:BrVlo\2Y@"L*W5p<htd9O%$HMJ -3o]*[s,*$?1;s1l!J-a>rrVrDjneuXNK=&<!qat*qYpSET`"fjOc/o4!P;e<rrLJ@r;QfZ3<&pZ -i@O0krrVK7o(r@e6/2>;!ER55rrIY@rVlo(C]=>:fH("]kPkJiq'?!6HiO-#)uor*K`:uSkV`C% -N;ihXqVLrG#=R5EpYc'qVZ-T!``E->;9\t<!G8h<rt/POs8VeRE;rqZs8V_IGlQ^rrr3"hJc>ZN -r6sX(rrucDs8VSDV>^Dp]jUO5!Tl<<rs0Y+/83N"s8O,9rrMC?qu;0~> -"!.E>Fo)+=JXcK8!C#B>s8S,ZrrrD25Q?G(rr35R8H7pi/1a!Yrs!;Ds8UtYjSf)Y*W?!=j7N?N -"KHMB;p,+>!MXo6rrGC?rVlmYj8/cU*W#d@m4eS?kjSQ)rVln:Xn_nrf_tgN?G?F=!qFb*rVlrl -R#h.E!q(Q@p&>&lF8c+>q;2)M""Woj9)\bl,PfJ[rr3-]jo>@VGl7RB\RYU<"5*XYD"mr11[4T4 -!F<M>rrJ1?rr3#U55bE]o-sG6#'Ggrs8U&>rVlj<qu6dKo)J:BrVlo\2Y@"L*W5p<htd9O%$HMJ -3o]*[s,*$?1;s1l!J-a>rrVrDjneuXNK=&<!qat*qYpSET`"fjOc/o4!P;e<rrLJ@r;QfZ3<&pZ -i@O0krrVK7o(r@e6/2>;!ER55rrIY@rVlo(C]=>:fH("]kPkJiq'?!6HiO-#)uor*K`:uSkV`C% -N;ihXqVLrG#=R5EpYc'qVZ-T!``E->;9\t<!G8h<rt/POs8VeRE;rqZs8V_IGlQ^rrr3"hJc>ZN -r6sX(rrucDs8VSDV>^Dp]jUO5!Tl<<rs0Y+/83N"s8O,9rrMC?qu;0~> -"!.E>Fo)+=JXcK8!C#B>s8S,ZrrrD25Q?G(rr35R8H7pi/1a!Yrs!;Ds8UtYjSf)Y*W?!=j7N?N -"KHMB;p,+>!MXo6rrGC?rVlmYj8/cU*W#d@m4eS?kjSQ)rVln:Xn_nrf_tgN?G?F=!qFb*rVlrl -R#h.E!q(Q@p&>&lF8c+>q;2)M""Woj9)\bl,PfJ[rr3-]jo>@VGl7RB\RYU<"5*XYD"mr11[4T4 -!F<M>rrJ1?rr3#U55bE]o-sG6#'Ggrs8U&>rVlj<qu6dKo)J:BrVlo\2Y@"L*W5p<htd9O%$HMJ -3o]*[s,*$?1;s1l!J-a>rrVrDjneuXNK=&<!qat*qYpSET`"fjOc/o4!P;e<rrLJ@r;QfZ3<&pZ -i@O0krrVK7o(r@e6/2>;!ER55rrIY@rVlo(C]=>:fH("]kPkJiq'?!6HiO-#)uor*K`:uSkV`C% -N;ihXqVLrG#=R5EpYc'qVZ-T!``E->;9\t<!G8h<rt/POs8VeRE;rqZs8V_IGlQ^rrr3"hJc>ZN -r6sX(rrucDs8VSDV>^Dp]jUO5!Tl<<rs0Y+/83N"s8O,9rrMC?qu;0~> -"!.E><;j6._>jOdS,<3sfsWK(^&S,8L:4Ot5<o1%Qi@!feO]_7NW-?d`V9B5Cp<p=%(fsJe$c\" -[^O]cMOa[S"Ho5R;p,+>!MXo6rrM@?rVln=WrBF,f`(mN*W#dAnm/]4I)#\h[JmT8GfBIX!*]?0 -!HHNdrrT>'N;`bW_HQg9!M+c5rrK*?rVlo[Ac9%>>P6lerO)f1qq5fb[KU*@s8Sm>r;QfBF8`NL ->Q;`frO2V'!Aj!5rrHE@rVlo%L&SL]W-/%<!V7c7rsa*)S[PttL]@D![M?6mrVm"5Z*os^rVlo\ -2Y@"L*W5p<Gc(JK%#:qa3o]FGs,*$?1.V>P!J%]ZrrUOIC&7i1NK=&<!l+e^qYpSET`"fjOc/o4 -!P;e<rrLJ@r;Qfa@K*\:C_,_.rrRiR[JKn(6/2>;!ER55rrIY@rVlo>GQ,#R<ZM.VHN(>]ZXWsI -I^Z[i'EA*"K`:uSkV`CEL&SL]WH@k6#C<5TTn35fVZ-T!``E->;9\t<!Ki`J[M6pbs,3AT[\#9n -s+R&Q[[]!qs*pdB[K2>`rr3&c!)NRn"CAOFOdu@L!PMn6rrM7?r;R$Cs8Tc(M<Y%DrO)jhs8V@> -qu;0~> -"!.E><;j6._>jOdS,<3sfsWK(^&S,8L:4Ot5<o1%Qi@!feO]_7NW-?d`V9B5Cp<p=%(fsJe$c\" -[^O]cMOa[S"Ho5R;p,+>!MXo6rrM@?rVln=WrBF,f`(mN*W#dAnm/]4I)#\h[JmT8GfBIX!*]?0 -!HHNdrrT>'N;`bW_HQg9!M+c5rrK*?rVlo[Ac9%>>P6lerO)f1qq5fb[KU*@s8Sm>r;QfBF8`NL ->Q;`frO2V'!Aj!5rrHE@rVlo%L&SL]W-/%<!V7c7rsa*)S[PttL]@D![M?6mrVm"5Z*os^rVlo\ -2Y@"L*W5p<Gc(JK%#:qa3o]FGs,*$?1.V>P!J%]ZrrUOIC&7i1NK=&<!l+e^qYpSET`"fjOc/o4 -!P;e<rrLJ@r;Qfa@K*\:C_,_.rrRiR[JKn(6/2>;!ER55rrIY@rVlo>GQ,#R<ZM.VHN(>]ZXWsI -I^Z[i'EA*"K`:uSkV`CEL&SL]WH@k6#C<5TTn35fVZ-T!``E->;9\t<!Ki`J[M6pbs,3AT[\#9n -s+R&Q[[]!qs*pdB[K2>`rr3&c!)NRn"CAOFOdu@L!PMn6rrM7?r;R$Cs8Tc(M<Y%DrO)jhs8V@> -qu;0~> -"!.E><;j6._>jOdS,<3sfsWK(^&S,8L:4Ot5<o1%Qi@!feO]_7NW-?d`V9B5Cp<p=%(fsJe$c\" -[^O]cMOa[S"Ho5R;p,+>!MXo6rrM@?rVln=WrBF,f`(mN*W#dAnm/]4I)#\h[JmT8GfBIX!*]?0 -!HHNdrrT>'N;`bW_HQg9!M+c5rrK*?rVlo[Ac9%>>P6lerO)f1qq5fb[KU*@s8Sm>r;QfBF8`NL ->Q;`frO2V'!Aj!5rrHE@rVlo%L&SL]W-/%<!V7c7rsa*)S[PttL]@D![M?6mrVm"5Z*os^rVlo\ -2Y@"L*W5p<Gc(JK%#:qa3o]FGs,*$?1.V>P!J%]ZrrUOIC&7i1NK=&<!l+e^qYpSET`"fjOc/o4 -!P;e<rrLJ@r;Qfa@K*\:C_,_.rrRiR[JKn(6/2>;!ER55rrIY@rVlo>GQ,#R<ZM.VHN(>]ZXWsI -I^Z[i'EA*"K`:uSkV`CEL&SL]WH@k6#C<5TTn35fVZ-T!``E->;9\t<!Ki`J[M6pbs,3AT[\#9n -s+R&Q[[]!qs*pdB[K2>`rr3&c!)NRn"CAOFOdu@L!PMn6rrM7?r;R$Cs8Tc(M<Y%DrO)jhs8V@> -qu;0~> -!Zh<`r+6(Zs8TIDqu6Z!ral.Qrr38'AnGcCN;p?%rr3,`OoNUMral1M\bQ1*VpPGC"4j.FUASU* -V>pRRral;$s8SGCrr3#>YP.ttno2/<rr@6AAcSt4rr@9=rr_7mB".d>!,):C!5/(+!;?A'!65!; -!mYDhrVloQSGW<fj+Xf2rs,MlR@3@?s4I9^"6KR_e,<k\lMpn0ral>jGQ7]bY5A5!_u40Lq>^K/ -rFQ<6s8UK7R31\drrZPJRA9c]!36$1!."[email protected];Qh8As<5o"1">P -2Y@"O(n$f.rr2tGral;2s8RrDrr3,2^AftMral/8rVlrZAu5A(!P?#CrrUkcYPS8)Z,ZhDp6h=M -MtR)U]/uFKj8]/>Pl(I\hYq*gc8FearrTT?e,'(MNTpKChjKlh`qB?:J6nY3qu?]2ral<"GQ7]S -ral.Frr383AnL-Fs8TpCrr3,kL&_1Rral.Uo`#,DAqU-`Xi^SB"l5XIs-DU?rrA2\AcS"nrt(-$ -AqnR0s8RjdArFa5s8R]MAcSS(rrVe(Q2L[^AcS:urr]!`EFAJ>#Nd.sRF;-8GQ%ODV:,D=rFQ2O -s8VYCqu;0~> -!Zh<`r+6(Zs8TIDqu6Z!ral.Qrr38'AnGcCN;p?%rr3,`OoNUMral1M\bQ1*VpPGC"4j.FUASU* -V>pRRral;$s8SGCrr3#>YP.ttno2/<rr@6AAcSt4rr@9=rr_7mB".d>!,):C!5/(+!;?A'!65!; -!mYDhrVloQSGW<fj+Xf2rs,MlR@3@?s4I9^"6KR_e,<k\lMpn0ral>jGQ7]bY5A5!_u40Lq>^K/ -rFQ<6s8UK7R31\drrZPJRA9c]!36$1!."[email protected];Qh8As<5o"1">P -2Y@"O(n$f.rr2tGral;2s8RrDrr3,2^AftMral/8rVlrZAu5A(!P?#CrrUkcYPS8)Z,ZhDp6h=M -MtR)U]/uFKj8]/>Pl(I\hYq*gc8FearrTT?e,'(MNTpKChjKlh`qB?:J6nY3qu?]2ral<"GQ7]S -ral.Frr383AnL-Fs8TpCrr3,kL&_1Rral.Uo`#,DAqU-`Xi^SB"l5XIs-DU?rrA2\AcS"nrt(-$ -AqnR0s8RjdArFa5s8R]MAcSS(rrVe(Q2L[^AcS:urr]!`EFAJ>#Nd.sRF;-8GQ%ODV:,D=rFQ2O -s8VYCqu;0~> -!Zh<`r+6(Zs8TIDqu6Z!ral.Qrr38'AnGcCN;p?%rr3,`OoNUMral1M\bQ1*VpPGC"4j.FUASU* -V>pRRral;$s8SGCrr3#>YP.ttno2/<rr@6AAcSt4rr@9=rr_7mB".d>!,):C!5/(+!;?A'!65!; -!mYDhrVloQSGW<fj+Xf2rs,MlR@3@?s4I9^"6KR_e,<k\lMpn0ral>jGQ7]bY5A5!_u40Lq>^K/ -rFQ<6s8UK7R31\drrZPJRA9c]!36$1!."[email protected];Qh8As<5o"1">P -2Y@"O(n$f.rr2tGral;2s8RrDrr3,2^AftMral/8rVlrZAu5A(!P?#CrrUkcYPS8)Z,ZhDp6h=M -MtR)U]/uFKj8]/>Pl(I\hYq*gc8FearrTT?e,'(MNTpKChjKlh`qB?:J6nY3qu?]2ral<"GQ7]S -ral.Frr383AnL-Fs8TpCrr3,kL&_1Rral.Uo`#,DAqU-`Xi^SB"l5XIs-DU?rrA2\AcS"nrt(-$ -AqnR0s8RjdArFa5s8R]MAcSS(rrVe(Q2L[^AcS:urr]!`EFAJ>#Nd.sRF;-8GQ%ODV:,D=rFQ2O -s8VYCqu;0~> -!$0_l!I^U>rrL>?c2Rh,WkJE5h6Z_Q!7h($!9VW-!65"j!;,sa"0dE1O3[b-Tn@ugo`##OK7gQ" -rrFn@g]%9Grdt3jp&>$Krdt4,o)A_JkOAKOfD^C&j7WEP_>]&eqXFLccb08W!$.[2"-%qcZ1\+s -oDX@BaQNSR~> -!$0_l!I^U>rrL>?c2Rh,WkJE5h6Z_Q!7h($!9VW-!65"j!;,sa"0dE1O3[b-Tn@ugo`##OK7gQ" -rrFn@g]%9Grdt3jp&>$Krdt4,o)A_JkOAKOfD^C&j7WEP_>]&eqXFLccb08W!$.[2"-%qcZ1\+s -oDX@BaQNSR~> -!$0_l!I^U>rrL>?c2Rh,WkJE5h6Z_Q!7h($!9VW-!65"j!;,sa"0dE1O3[b-Tn@ugo`##OK7gQ" -rrFn@g]%9Grdt3jp&>$Krdt4,o)A_JkOAKOfD^C&j7WEP_>]&eqXFLccb08W!$.[2"-%qcZ1\+s -oDX@BaQNSR~> -!$0_l!R>og?NFuWJcC<$dJj5&laHfo2<W*]!Si8*?N?dNs6ou<~> -!$0_l!R>og?NFuWJcC<$dJj5&laHfo2<W*]!Si8*?N?dNs6ou<~> -!$0_l!R>og?NFuWJcC<$dJj5&laHfo2<W*]!Si8*?N?dNs6ou<~> -!$0\k!7h(]!6TlmJcF*s!Qk2HrrL:<aSu7trk&7.JcG3=J,~> -!$0\k!7h(]!6TlmJcF*s!Qk2HrrL:<aSu7trk&7.JcG3=J,~> -!$0\k!7h(]!6TlmJcF*s!Qk2HrrL:<aSu7trk&7.JcG3=J,~> -!$..#"#_JQH%H!Hs+13$s7lVE~> -!$..#"#_JQH%H!Hs+13$s7lVE~> -!$..#"#_JQH%H!Hs+13$s7lVE~> -!$1P.",Is-hrXk>C)m`\rrQ[N'D)5,m2m?Wo_8@e73")Lrr`#hZsnUdJcC<$JcGNFJ,~> -!$1P.",Is-hrXk>C)m`\rrQ[N'D)5,m2m?Wo_8@e73")Lrr`#hZsnUdJcC<$JcGNFJ,~> -!$1P.",Is-hrXk>C)m`\rrQ[N'D)5,m2m?Wo_8@e73")Lrr`#hZsnUdJcC<$JcGNFJ,~> -!$1J,!C#B#rr=)9rr=)2rraJBs/L,5rrMX?lMgms@Y+Q1s+13$s7lVE~> -!$1J,!C#B#rr=)9rr=)2rraJBs/L,5rrMX?lMgms@Y+Q1s+13$s7lVE~> -!$1J,!C#B#rr=)9rr=)2rraJBs/L,5rrMX?lMgms@Y+Q1s+13$s7lVE~> -#9Ej*e^C_-[/U(*g&A5V[f$.+52Q#5"kqkTZ*D%BrrC@DYlMW<rr=)9rr=)9rrKOBr;R!Er;X^+ -s8Tq7YlN)JrrMX?r;Qc0rilIPrr2u0rilIRr;Qf0@Y+Q1s+13$s7lVE~> -#9Ej*e^C_-[/U(*g&A5V[f$.+52Q#5"kqkTZ*D%BrrC@DYlMW<rr=)9rr=)9rrKOBr;R!Er;X^+ -s8Tq7YlN)JrrMX?r;Qc0rilIPrr2u0rilIRr;Qf0@Y+Q1s+13$s7lVE~> -#9Ej*e^C_-[/U(*g&A5V[f$.+52Q#5"kqkTZ*D%BrrC@DYlMW<rr=)9rr=)9rrKOBr;R!Er;X^+ -s8Tq7YlN)JrrMX?r;Qc0rilIPrr2u0rilIRr;Qf0@Y+Q1s+13$s7lVE~> -$Q]8F7!rccCo%*_JGs<bDQ*O6!C#B6rs=B]GACu7ZN&$mrbDOU[f-4+*W#d9*W#d:$nqPY!?h=< -rr@rUCB8b%rr3#h/,fJKY]9YX"F\VrXDe)R!IiJqrrK`@JcC<$JcC<$q#>j~> -$Q]8F7!rccCo%*_JGs<bDQ*O6!C#B6rs=B]GACu7ZN&$mrbDOU[f-4+*W#d9*W#d:$nqPY!?h=< -rr@rUCB8b%rr3#h/,fJKY]9YX"F\VrXDe)R!IiJqrrK`@JcC<$JcC<$q#>j~> -$Q]8F7!rccCo%*_JGs<bDQ*O6!C#B6rs=B]GACu7ZN&$mrbDOU[f-4+*W#d9*W#d:$nqPY!?h=< -rr@rUCB8b%rr3#h/,fJKY]9YX"F\VrXDe)R!IiJqrrK`@JcC<$JcC<$q#>j~> -$Q]8F50X',pEop4IfB?JmOnJ<!C#B>rrBt7G70i=Ki$S)s4'[?I@pN=!R+C=rr=)9rr=)9rrJ+N -rr3,"G7Sk^q>UJiHN*pFnLOS<!CGQ?rrgQfs#K-=rrIq?rVlo1@Y+Q1s+13$s7lVE~> -$Q]8F50X',pEop4IfB?JmOnJ<!C#B>rrBt7G70i=Ki$S)s4'[?I@pN=!R+C=rr=)9rr=)9rrJ+N -rr3,"G7Sk^q>UJiHN*pFnLOS<!CGQ?rrgQfs#K-=rrIq?rVlo1@Y+Q1s+13$s7lVE~> -$Q]8F50X',pEop4IfB?JmOnJ<!C#B>rrBt7G70i=Ki$S)s4'[?I@pN=!R+C=rr=)9rr=)9rrJ+N -rr3,"G7Sk^q>UJiHN*pFnLOS<!CGQ?rrgQfs#K-=rrIq?rVlo1@Y+Q1s+13$s7lVE~> -"!.E>FoMCDpEop4/cJoS<%e.L!C#B>rrC[KV$"@0KpVf="P$'CI@pN=!R+C=rr=)9rr=)4rrg<; -'r/;;rr@KH=ogX0rr3#h/,fJK]Oh(G"JPkq3DocZ!AKc:rrK`@JcC<$JcC<$q#>j~> -"!.E>FoMCDpEop4/cJoS<%e.L!C#B>rrC[KV$"@0KpVf="P$'CI@pN=!R+C=rr=)9rr=)4rrg<; -'r/;;rr@KH=ogX0rr3#h/,fJK]Oh(G"JPkq3DocZ!AKc:rrK`@JcC<$JcC<$q#>j~> -"!.E>FoMCDpEop4/cJoS<%e.L!C#B>rrC[KV$"@0KpVf="P$'CI@pN=!R+C=rr=)9rr=)4rrg<; -'r/;;rr@KH=ogX0rr3#h/,fJK]Oh(G"JPkq3DocZ!AKc:rrK`@JcC<$JcC<$q#>j~> -"!.E>FoMCDpEop4?i@e@c2IYC52Q#5!JQm>rrgkCs*^O=rrL>?rVlj<qYpO9oD\h6r;HWrI&?nZ -!IK.lrrMX?r;Qc>rkS_oVuJcYrP8KqrVlo1@Y+Q1s+13$s7lVE~> -"!.E>FoMCDpEop4?i@e@c2IYC52Q#5!JQm>rrgkCs*^O=rrL>?rVlj<qYpO9oD\h6r;HWrI&?nZ -!IK.lrrMX?r;Qc>rkS_oVuJcYrP8KqrVlo1@Y+Q1s+13$s7lVE~> -"!.E>FoMCDpEop4?i@e@c2IYC52Q#5!JQm>rrgkCs*^O=rrL>?rVlj<qYpO9oD\h6r;HWrI&?nZ -!IK.lrrMX?r;Qc>rkS_oVuJcYrP8KqrVlo1@Y+Q1s+13$s7lVE~> -"!.E>FoMCDpEop4Ie`pD52Q#5$&'&,s8UV?s*^O=rrL>?rVlj<qYpO9qYpRH9)S\i+T23<##i\E -s2Pk#rr3#h/,fJK>2T>Z"HeWB3TKo7!P;fls+13$s+14Fs*t~> -"!.E>FoMCDpEop4Ie`pD52Q#5$&'&,s8UV?s*^O=rrL>?rVlj<qYpO9qYpRH9)S\i+T23<##i\E -s2Pk#rr3#h/,fJK>2T>Z"HeWB3TKo7!P;fls+13$s+14Fs*t~> -"!.E>FoMCDpEop4Ie`pD52Q#5$&'&,s8UV?s*^O=rrL>?rVlj<qYpO9qYpRH9)S\i+T23<##i\E -s2Pk#rr3#h/,fJK>2T>Z"HeWB3TKo7!P;fls+13$s+14Fs*t~> -"!.EGKDtlRpH/ESNrC%!/H5YPL`IBR1\^nUKp>sb*CB](rG_`V#YFsos(WPm*Duh9"CiGj*Ei=? -!@1&1rrG%UrVmK-9-#$QWJCNR73*9eGQ7^@4oQH)IJs3D2?"TrLAq2TkiSgQJcC<$JcC<$q#>j~> -"!.EGKDtlRpH/ESNrC%!/H5YPL`IBR1\^nUKp>sb*CB](rG_`V#YFsos(WPm*Duh9"CiGj*Ei=? -!@1&1rrG%UrVmK-9-#$QWJCNR73*9eGQ7^@4oQH)IJs3D2?"TrLAq2TkiSgQJcC<$JcC<$q#>j~> -"!.EGKDtlRpH/ESNrC%!/H5YPL`IBR1\^nUKp>sb*CB](rG_`V#YFsos(WPm*Duh9"CiGj*Ei=? -!@1&1rrG%UrVmK-9-#$QWJCNR73*9eGQ7^@4oQH)IJs3D2?"TrLAq2TkiSgQJcC<$JcC<$q#>j~> -!$1"t!JQlGrrY\J2M6S\JcC<$JcGNFJ,~> -!$1"t!JQlGrrY\J2M6S\JcC<$JcGNFJ,~> -!$1"t!JQlGrrY\J2M6S\JcC<$JcGNFJ,~> -!$1"t!JQkks+13$s+13Hs*t~> -!$1"t!JQkks+13$s+13Hs*t~> -!$1"t!JQkks+13$s+13Hs*t~> -!$1"t!P?=%s+13$s+13Hs*t~> -!$1"t!P?=%s+13$s+13Hs*t~> -!$1"t!P?=%s+13$s+13Hs*t~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$.@)!V"X)rrM*>JcC<$JcFU,J,~> -!$.@)!V"X)rrM*>JcC<$JcFU,J,~> -!$.@)!V"X)rrM*>JcC<$JcFU,J,~> -!Zh<ur1X1qq#:BJe+3M@aJ,F)rVlu=U8%SZrrL7$rr3)_`W*sUU&`:0rrBk4U&`O-rrVhUQM1=Z -Z2;uL!p66)pAY0d\+'Cuce\R"!9*mN!;6?k!jdU@JcC<$JcFX-J,~> -!Zh<ur1X1qq#:BJe+3M@aJ,F)rVlu=U8%SZrrL7$rr3)_`W*sUU&`:0rrBk4U&`O-rrVhUQM1=Z -Z2;uL!p66)pAY0d\+'Cuce\R"!9*mN!;6?k!jdU@JcC<$JcFX-J,~> -!Zh<ur1X1qq#:BJe+3M@aJ,F)rVlu=U8%SZrrL7$rr3)_`W*sUU&`:0rrBk4U&`O-rrVhUQM1=Z -Z2;uL!p66)pAY0d\+'Cuce\R"!9*mN!;6?k!jdU@JcC<$JcFX-J,~> -"!.E>3;n.'NqiVTQA4u1"0d(en,<7gXEkNRpAY/0Yl=Y*]4(_L=T*OGZ2">!V>Y]@9mZ7-!T6*5 -rrFP?lMgnMW9aHbgNpR2rrLi`rVloY3V!+Sc@:E's8V55rH\HtrVln5Z@W%,s+14-s*t~> -"!.E>3;n.'NqiVTQA4u1"0d(en,<7gXEkNRpAY/0Yl=Y*]4(_L=T*OGZ2">!V>Y]@9mZ7-!T6*5 -rrFP?lMgnMW9aHbgNpR2rrLi`rVloY3V!+Sc@:E's8V55rH\HtrVln5Z@W%,s+14-s*t~> -"!.E>3;n.'NqiVTQA4u1"0d(en,<7gXEkNRpAY/0Yl=Y*]4(_L=T*OGZ2">!V>Y]@9mZ7-!T6*5 -rrFP?lMgnMW9aHbgNpR2rrLi`rVloY3V!+Sc@:E's8V55rH\HtrVln5Z@W%,s+14-s*t~> -"!.E>Fn>V6QA4o/!A3d;rrFG?pAY/0Yl=Y*]4(_L\aTP"fm1^.rrW1;YP%nr..lg)!RjX#rrKB? -rVloY3V*1UdsK?QFR&nK;Z6UqU](2o_KOsjs+13$s5<p-~> -"!.E>Fn>V6QA4o/!A3d;rrFG?pAY/0Yl=Y*]4(_L\aTP"fm1^.rrW1;YP%nr..lg)!RjX#rrKB? -rVloY3V*1UdsK?QFR&nK;Z6UqU](2o_KOsjs+13$s5<p-~> -"!.E>Fn>V6QA4o/!A3d;rrFG?pAY/0Yl=Y*]4(_L\aTP"fm1^.rrW1;YP%nr..lg)!RjX#rrKB? -rVloY3V*1UdsK?QFR&nK;Z6UqU](2o_KOsjs+13$s5<p-~> -"!.E>Fo)+<VuB<p=9&;dL5\bu?2jj(S,Q%\A,Q?-/arT:!@@L6rsdIoh#HGJd/RUdBM2!LoD\j+ -?1.^nrZD%;!*T:o"Ju.u.-LS&!3?,!!)<Gc&@)98@/nYJ9=Os$<^%9l9>1-#!WHO+rs")2s5QaF -V>gK%nk1e^92!h8j#P!U9*!]@rs@Uudf9?f>5QH?p\t7gd"24Js+14.s*t~> -"!.E>Fo)+<VuB<p=9&;dL5\bu?2jj(S,Q%\A,Q?-/arT:!@@L6rsdIoh#HGJd/RUdBM2!LoD\j+ -?1.^nrZD%;!*T:o"Ju.u.-LS&!3?,!!)<Gc&@)98@/nYJ9=Os$<^%9l9>1-#!WHO+rs")2s5QaF -V>gK%nk1e^92!h8j#P!U9*!]@rs@Uudf9?f>5QH?p\t7gd"24Js+14.s*t~> -"!.E>Fo)+<VuB<p=9&;dL5\bu?2jj(S,Q%\A,Q?-/arT:!@@L6rsdIoh#HGJd/RUdBM2!LoD\j+ -?1.^nrZD%;!*T:o"Ju.u.-LS&!3?,!!)<Gc&@)98@/nYJ9=Os$<^%9l9>1-#!WHO+rs")2s5QaF -V>gK%nk1e^92!h8j#P!U9*!]@rs@Uudf9?f>5QH?p\t7gd"24Js+14.s*t~> -"!.E>(&ffgmf3<kIf@_'``2u((m`Rs^g$i5M>km']41a=!A3d;rrFG?p&>IscMuQcs8QRQ\'`Tr -L%YHIj&b4-rrN*@qu6ZGrm:k!Y5]n0rm:jp[JreDrm;:"]`6A3=4,E7_uJ2f4OMREq#:Bn+8u3D -:!`k7d=?cHrsJ\OO]TrXo`*qYAcC'X:[RuX!VbILrr^mPb#8!6!DUpls+13$s5<p-~> -"!.E>(&ffgmf3<kIf@_'``2u((m`Rs^g$i5M>km']41a=!A3d;rrFG?p&>IscMuQcs8QRQ\'`Tr -L%YHIj&b4-rrN*@qu6ZGrm:k!Y5]n0rm:jp[JreDrm;:"]`6A3=4,E7_uJ2f4OMREq#:Bn+8u3D -:!`k7d=?cHrsJ\OO]TrXo`*qYAcC'X:[RuX!VbILrr^mPb#8!6!DUpls+13$s5<p-~> -"!.E>(&ffgmf3<kIf@_'``2u((m`Rs^g$i5M>km']41a=!A3d;rrFG?p&>IscMuQcs8QRQ\'`Tr -L%YHIj&b4-rrN*@qu6ZGrm:k!Y5]n0rm:jp[JreDrm;:"]`6A3=4,E7_uJ2f4OMREq#:Bn+8u3D -:!`k7d=?cHrsJ\OO]TrXo`*qYAcC'X:[RuX!VbILrr^mPb#8!6!DUpls+13$s5<p-~> -"!.E>D>ro*rr<"nIfAsJoC;jHIJNpCju<=#M#R#Idm*g2!A3d;rrFG?p&>J%a8XI[s8V`Yr;Zf' -C%_K,e4B!,!WF2<rrD`koE9K1s!Zt-rrdSCruh:>rs`nKs7mi/s8QrHs8UP>p&>9q+9/Bms%Ui= -rrJ[@r;Qf&C]487j#-H-rrFt?nc&g9;ZHc1*>SMP!DUpls+13$s5<p-~> -"!.E>D>ro*rr<"nIfAsJoC;jHIJNpCju<=#M#R#Idm*g2!A3d;rrFG?p&>J%a8XI[s8V`Yr;Zf' -C%_K,e4B!,!WF2<rrD`koE9K1s!Zt-rrdSCruh:>rs`nKs7mi/s8QrHs8UP>p&>9q+9/Bms%Ui= -rrJ[@r;Qf&C]487j#-H-rrFt?nc&g9;ZHc1*>SMP!DUpls+13$s5<p-~> -"!.E>D>ro*rr<"nIfAsJoC;jHIJNpCju<=#M#R#Idm*g2!A3d;rrFG?p&>J%a8XI[s8V`Yr;Zf' -C%_K,e4B!,!WF2<rrD`koE9K1s!Zt-rrdSCruh:>rs`nKs7mi/s8QrHs8UP>p&>9q+9/Bms%Ui= -rrJ[@r;Qf&C]487j#-H-rrFt?nc&g9;ZHc1*>SMP!DUpls+13$s5<p-~> -"!.E>Fo)+<Q2W071uA7uLAq2Uju<=#(B#W]?2ad(/arT:!@@L4rrOq7-MdZBZYB.5!W"&-rrN*@ -r;QfS2?#!,'V,1Oo`"jnGbtE_rVlg"Dls'8,PqE@dn064#Q5bEV0Dr6ci3qFSUgY<!O6G=rrM.? -rVlmTkjeZRb#83<!$2";!DUpls+13$s5<p-~> -"!.E>Fo)+<Q2W071uA7uLAq2Uju<=#(B#W]?2ad(/arT:!@@L4rrOq7-MdZBZYB.5!W"&-rrN*@ -r;QfS2?#!,'V,1Oo`"jnGbtE_rVlg"Dls'8,PqE@dn064#Q5bEV0Dr6ci3qFSUgY<!O6G=rrM.? -rVlmTkjeZRb#83<!$2";!DUpls+13$s5<p-~> -"!.E>Fo)+<Q2W071uA7uLAq2Uju<=#(B#W]?2ad(/arT:!@@L4rrOq7-MdZBZYB.5!W"&-rrN*@ -r;QfS2?#!,'V,1Oo`"jnGbtE_rVlg"Dls'8,PqE@dn064#Q5bEV0Dr6ci3qFSUgY<!O6G=rrM.? -rVlmTkjeZRb#83<!$2";!DUpls+13$s5<p-~> -"!.E>Fo21>jkTk8"R[oBQA5D="QhZCNfNo7!A3d;rrFG?o`"tIi[4[)!S-Q9rrKH?rVlo1ao)/> -^0^1+!rc-@rVm0Ym/R+I?(CpC\,QC1GbtE_rVlg"Dls'8,PqEDdn0T>e*Zu2#Q5b5OaQ._ci3qF -SUgY<#I/(Es2t)r3W8sY2!FK0!Qn==rr=)<rrUech1>TWs+14.s*t~> -"!.E>Fo21>jkTk8"R[oBQA5D="QhZCNfNo7!A3d;rrFG?o`"tIi[4[)!S-Q9rrKH?rVlo1ao)/> -^0^1+!rc-@rVm0Ym/R+I?(CpC\,QC1GbtE_rVlg"Dls'8,PqEDdn0T>e*Zu2#Q5b5OaQ._ci3qF -SUgY<#I/(Es2t)r3W8sY2!FK0!Qn==rr=)<rrUech1>TWs+14.s*t~> -"!.E>Fo21>jkTk8"R[oBQA5D="QhZCNfNo7!A3d;rrFG?o`"tIi[4[)!S-Q9rrKH?rVlo1ao)/> -^0^1+!rc-@rVm0Ym/R+I?(CpC\,QC1GbtE_rVlg"Dls'8,PqEDdn0T>e*Zu2#Q5b5OaQ._ci3qF -SUgY<#I/(Es2t)r3W8sY2!FK0!Qn==rr=)<rrUech1>TWs+14.s*t~> -"!.E>8H#(]XT-4grga1[IfG^grr3,`2ugF@rga%hrr3,?SK*iqrr3,<SJRZup&>)DQ?rQ1!M>AN -SH4YDrVlm#2uN[U*U<Y*i&pu<$%SG7SVAkhs!V@USHOD^s)sq3SHO>bs7mo9rrqJ)SXk#Wq>Us( -Boe[jKQQ2Qn=<r_S`TkN#L@afST*rU3W8sY2!FK0!T%ttSH*F'rrHl?JcC<$JcFX-J,~> -"!.E>8H#(]XT-4grga1[IfG^grr3,`2ugF@rga%hrr3,?SK*iqrr3,<SJRZup&>)DQ?rQ1!M>AN -SH4YDrVlm#2uN[U*U<Y*i&pu<$%SG7SVAkhs!V@USHOD^s)sq3SHO>bs7mo9rrqJ)SXk#Wq>Us( -Boe[jKQQ2Qn=<r_S`TkN#L@afST*rU3W8sY2!FK0!T%ttSH*F'rrHl?JcC<$JcFX-J,~> -"!.E>8H#(]XT-4grga1[IfG^grr3,`2ugF@rga%hrr3,?SK*iqrr3,<SJRZup&>)DQ?rQ1!M>AN -SH4YDrVlm#2uN[U*U<Y*i&pu<$%SG7SVAkhs!V@USHOD^s)sq3SHO>bs7mo9rrqJ)SXk#Wq>Us( -Boe[jKQQ2Qn=<r_S`TkN#L@afST*rU3W8sY2!FK0!T%ttSH*F'rrHl?JcC<$JcFX-J,~> -!Zh<ir-ng3s8Tn6IftQ,s2r4Xrrhn]s8TS-IfPT0rrBD)IfP`4rrB8%IfPl.rrA)WrrAemIfQ>C -rrIY>r;QbWlMgqTJ$&\L#`4%\YeSH_POSR$!5ng9!.b&u"NUQBr/pgT"586Sd.dPGn"'LY[+PEY -lhu;5h#76Waa\g!s7)TWrrJP[nG`L>rI4h<rr3&;J(]DQJcC<$huA3~> -!Zh<ir-ng3s8Tn6IftQ,s2r4Xrrhn]s8TS-IfPT0rrBD)IfP`4rrB8%IfPl.rrA)WrrAemIfQ>C -rrIY>r;QbWlMgqTJ$&\L#`4%\YeSH_POSR$!5ng9!.b&u"NUQBr/pgT"586Sd.dPGn"'LY[+PEY -lhu;5h#76Waa\g!s7)TWrrJP[nG`L>rI4h<rr3&;J(]DQJcC<$huA3~> -!Zh<ir-ng3s8Tn6IftQ,s2r4Xrrhn]s8TS-IfPT0rrBD)IfP`4rrB8%IfPl.rrA)WrrAemIfQ>C -rrIY>r;QbWlMgqTJ$&\L#`4%\YeSH_POSR$!5ng9!.b&u"NUQBr/pgT"586Sd.dPGn"'LY[+PEY -lhu;5h#76Waa\g!s7)TWrrJP[nG`L>rI4h<rr3&;J(]DQJcC<$huA3~> -!$.@)!U.7_rrLKtJcC<$JcFU,J,~> -!$.@)!U.7_rrLKtJcC<$JcFU,J,~> -!$.@)!U.7_rrLKtJcC<$JcFU,J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$2%<!VH<grrMlioD\pdn*g5QrrVf\rndYUo_[nQ"9.cXpAP!ln+6&K!VZ?grrW(rKA$8/oDJXg -qX=1=rrMiio`#!en,'Hk!THTHrrG4Kqu6[UnU^^ks2P(h~> -!$2%<!VH<grrMlioD\pdn*g5QrrVf\rndYUo_[nQ"9.cXpAP!ln+6&K!VZ?grrW(rKA$8/oDJXg -qX=1=rrMiio`#!en,'Hk!THTHrrG4Kqu6[UnU^^ks2P(h~> -!$2%<!VH<grrMlioD\pdn*g5QrrVf\rndYUo_[nQ"9.cXpAP!ln+6&K!VZ?grrW(rKA$8/oDJXg -qX=1=rrMiio`#!en,'Hk!THTHrrG4Kqu6[UnU^^ks2P(h~> -!$2(=!p)_mrVlqdOn//E",\Z;k5>5\CG#,LrrLpOmJd2k_<Lt+`@WZ`lMpn`/RS#I!I1I?rrL/? -f`).EfDklc/Y1u&!pa0mo`"uX/]ZZH!TE_;rrLpOo)A\1qYpO9qu6]o,(]cFs2P(h~> -!$2(=!p)_mrVlqdOn//E",\Z;k5>5\CG#,LrrLpOmJd2k_<Lt+`@WZ`lMpn`/RS#I!I1I?rrL/? -f`).EfDklc/Y1u&!pa0mo`"uX/]ZZH!TE_;rrLpOo)A\1qYpO9qu6]o,(]cFs2P(h~> -!$2(=!p)_mrVlqdOn//E",\Z;k5>5\CG#,LrrLpOmJd2k_<Lt+`@WZ`lMpn`/RS#I!I1I?rrL/? -f`).EfDklc/Y1u&!pa0mo`"uX/]ZZH!TE_;rrLpOo)A\1qYpO9qu6]o,(]cFs2P(h~> -"s*aDh09a\r;Qh\Qh0hK!B0*,rrG1?mJd2k_<Lt&*WQ/%MsLBIGbtH?pRR)lrrGR?i;WoBL*<S@ -rrH*?li-uIiUd'M_-?d9!Ed>=rrW+#a+=8As2Y.i~> -"s*aDh09a\r;Qh\Qh0hK!B0*,rrG1?mJd2k_<Lt&*WQ/%MsLBIGbtH?pRR)lrrGR?i;WoBL*<S@ -rrH*?li-uIiUd'M_-?d9!Ed>=rrW+#a+=8As2Y.i~> -"s*aDh09a\r;Qh\Qh0hK!B0*,rrG1?mJd2k_<Lt&*WQ/%MsLBIGbtH?pRR)lrrGR?i;WoBL*<S@ -rrH*?li-uIiUd'M_-?d9!Ed>=rrW+#a+=8As2Y.i~> -"s*a!J\Fq)qu6_[OS\VL!B0*=rr^-*R/$X[!5JN##d+.,a-\'+R'?Si!4`#q!42V'!M-:jrrH?? -rr3,W`rH(Arg3u*s8TOps8V)prVm0Es8TdDs8Sj]Yl4S&XRlFY!6bBA$(RBM_g&$Xs5Z0;rrE#r -Qiu"?s.o&]Qil%As7ZDY"5NqVo)4pXi;`iGrg3rB7G%S*R$c5!rrVhrh#<ZClMpnGrg3cHWqlJj -"R:fBEiSg4"4rp-jSf)YeGYd4rrT]tpAY'lc2O(5o;_ijao7Y5UAt8AQnilQV>gJp_Z#o6WW3"A -fX$s4XT/=@Qm7?QYl=Y&\GhiqZi0n).e<H9!Tl<;rrLq?JcC<$a8^Y~> -"s*a!J\Fq)qu6_[OS\VL!B0*=rr^-*R/$X[!5JN##d+.,a-\'+R'?Si!4`#q!42V'!M-:jrrH?? -rr3,W`rH(Arg3u*s8TOps8V)prVm0Es8TdDs8Sj]Yl4S&XRlFY!6bBA$(RBM_g&$Xs5Z0;rrE#r -Qiu"?s.o&]Qil%As7ZDY"5NqVo)4pXi;`iGrg3rB7G%S*R$c5!rrVhrh#<ZClMpnGrg3cHWqlJj -"R:fBEiSg4"4rp-jSf)YeGYd4rrT]tpAY'lc2O(5o;_ijao7Y5UAt8AQnilQV>gJp_Z#o6WW3"A -fX$s4XT/=@Qm7?QYl=Y&\GhiqZi0n).e<H9!Tl<;rrLq?JcC<$a8^Y~> -"s*a!J\Fq)qu6_[OS\VL!B0*=rr^-*R/$X[!5JN##d+.,a-\'+R'?Si!4`#q!42V'!M-:jrrH?? -rr3,W`rH(Arg3u*s8TOps8V)prVm0Es8TdDs8Sj]Yl4S&XRlFY!6bBA$(RBM_g&$Xs5Z0;rrE#r -Qiu"?s.o&]Qil%As7ZDY"5NqVo)4pXi;`iGrg3rB7G%S*R$c5!rrVhrh#<ZClMpnGrg3cHWqlJj -"R:fBEiSg4"4rp-jSf)YeGYd4rrT]tpAY'lc2O(5o;_ijao7Y5UAt8AQnilQV>gJp_Z#o6WW3"A -fX$s4XT/=@Qm7?QYl=Y&\GhiqZi0n).e<H9!Tl<;rrLq?JcC<$a8^Y~> -"s*`o]`1dPqYpS`K_59F2Wju<"1Ek"n,E=f]Rg'8%"b>U]S%>KKVAGGZ[r+/!J7HPrrEN]rr3:/ -_>j(QI_5WWK)UE/J\(kRdf9?VB)V`0*W,j<O`W_arrFipre(B(bl<e(KEcrfV>pSV3;idVL])l/ -J(ai;IK"m%Ibk$RrIb9%ir4?(KEH\cqL&9q#C[iJs6,,1M#RDUiu<IHKEHYom!\kd!e,arq>UTZ -XT*=@p&>-?KJL1=rrL`$rIb0.rVm'u!9sO`c@>hH"FQ[<aajAD%"joHab23XKTuN:_1;N<'S<"X -IS>?HKS$$"]n@GLKV8AFZ[r+/!J7HQrrFV?qYpTY2Z*LTh*6JjJcEdjJ,~> -"s*`o]`1dPqYpS`K_59F2Wju<"1Ek"n,E=f]Rg'8%"b>U]S%>KKVAGGZ[r+/!J7HPrrEN]rr3:/ -_>j(QI_5WWK)UE/J\(kRdf9?VB)V`0*W,j<O`W_arrFipre(B(bl<e(KEcrfV>pSV3;idVL])l/ -J(ai;IK"m%Ibk$RrIb9%ir4?(KEH\cqL&9q#C[iJs6,,1M#RDUiu<IHKEHYom!\kd!e,arq>UTZ -XT*=@p&>-?KJL1=rrL`$rIb0.rVm'u!9sO`c@>hH"FQ[<aajAD%"joHab23XKTuN:_1;N<'S<"X -IS>?HKS$$"]n@GLKV8AFZ[r+/!J7HQrrFV?qYpTY2Z*LTh*6JjJcEdjJ,~> -"s*`o]`1dPqYpS`K_59F2Wju<"1Ek"n,E=f]Rg'8%"b>U]S%>KKVAGGZ[r+/!J7HPrrEN]rr3:/ -_>j(QI_5WWK)UE/J\(kRdf9?VB)V`0*W,j<O`W_arrFipre(B(bl<e(KEcrfV>pSV3;idVL])l/ -J(ai;IK"m%Ibk$RrIb9%ir4?(KEH\cqL&9q#C[iJs6,,1M#RDUiu<IHKEHYom!\kd!e,arq>UTZ -XT*=@p&>-?KJL1=rrL`$rIb0.rVm'u!9sO`c@>hH"FQ[<aajAD%"joHab23XKTuN:_1;N<'S<"X -IS>?HKS$$"]n@GLKV8AFZ[r+/!J7HQrrFV?qYpTY2Z*LTh*6JjJcEdjJ,~> -!$2%<!Dgu9rr=)3rrG%?qu6[Kn,E=fI@pN=!URQ"rrG1?rVln7Yl=Y'k/I<!!N!+$rs;oGF(M&\ -s8Q$?rr3M'HN-Ucs8TQ?s8Rm]$XStnrrM%?rVlmQR/[*pJ=QWfo`+sD9;V[gj>d);!$2%<"D>1C -(pX)?"(&_A*W?!?_!:k?rVlsoch&XbrrU.ifDbdNP_f>=!okQBrr3'WkhAE&rrG^@p&>&5Wq65k -@CuO=!O6J>rr=)<rs$32p](8dIK'6L*WQ/+L&V)Qk;N>>!E@/=rrIk?rr3;U8,n$Kk5YJ+:]C@p -45p/<!H#%>rrM9#rr3!Ko(r@eju3,:!Sotks+13js*t~> -!$2%<!Dgu9rr=)3rrG%?qu6[Kn,E=fI@pN=!URQ"rrG1?rVln7Yl=Y'k/I<!!N!+$rs;oGF(M&\ -s8Q$?rr3M'HN-Ucs8TQ?s8Rm]$XStnrrM%?rVlmQR/[*pJ=QWfo`+sD9;V[gj>d);!$2%<"D>1C -(pX)?"(&_A*W?!?_!:k?rVlsoch&XbrrU.ifDbdNP_f>=!okQBrr3'WkhAE&rrG^@p&>&5Wq65k -@CuO=!O6J>rr=)<rs$32p](8dIK'6L*WQ/+L&V)Qk;N>>!E@/=rrIk?rr3;U8,n$Kk5YJ+:]C@p -45p/<!H#%>rrM9#rr3!Ko(r@eju3,:!Sotks+13js*t~> -!$2%<!Dgu9rr=)3rrG%?qu6[Kn,E=fI@pN=!URQ"rrG1?rVln7Yl=Y'k/I<!!N!+$rs;oGF(M&\ -s8Q$?rr3M'HN-Ucs8TQ?s8Rm]$XStnrrM%?rVlmQR/[*pJ=QWfo`+sD9;V[gj>d);!$2%<"D>1C -(pX)?"(&_A*W?!?_!:k?rVlsoch&XbrrU.ifDbdNP_f>=!okQBrr3'WkhAE&rrG^@p&>&5Wq65k -@CuO=!O6J>rr=)<rs$32p](8dIK'6L*WQ/+L&V)Qk;N>>!E@/=rrIk?rr3;U8,n$Kk5YJ+:]C@p -45p/<!H#%>rrM9#rr3!Ko(r@eju3,:!Sotks+13js*t~> -!$2%<!Dgu:rrHN?o`"qMk55/Z/ar]=!T%ep5lbQrrrG1?rVloOB`:9tFSGe;>;EA"rVlms2#]cO -.=2"ddf9?VB)hnV^)"H2r;QfU4T59\1$no>"G!$B..mN="aHmDs5Z0;rr<r85m&%6ruM(<"(&_A -*W,j;r?)"<"&7,6./j/H7G%P=!L/E>rrM.?rVlsVkhAE&rrG^@p&>&5Wq65k@CuO=!O6J>rr=)7 -rrJd@rr3*As8SE0r]pQH2ZE^W<65%<!JZp>rrgnCs*gR=rrLA?rr3!\iVicWg1^IO!-A,=!@m[: -rrM7?qu6]Q5Crics2Y.i~> -!$2%<!Dgu:rrHN?o`"qMk55/Z/ar]=!T%ep5lbQrrrG1?rVloOB`:9tFSGe;>;EA"rVlms2#]cO -.=2"ddf9?VB)hnV^)"H2r;QfU4T59\1$no>"G!$B..mN="aHmDs5Z0;rr<r85m&%6ruM(<"(&_A -*W,j;r?)"<"&7,6./j/H7G%P=!L/E>rrM.?rVlsVkhAE&rrG^@p&>&5Wq65k@CuO=!O6J>rr=)7 -rrJd@rr3*As8SE0r]pQH2ZE^W<65%<!JZp>rrgnCs*gR=rrLA?rr3!\iVicWg1^IO!-A,=!@m[: -rrM7?qu6]Q5Crics2Y.i~> -!$2%<!Dgu:rrHN?o`"qMk55/Z/ar]=!T%ep5lbQrrrG1?rVloOB`:9tFSGe;>;EA"rVlms2#]cO -.=2"ddf9?VB)hnV^)"H2r;QfU4T59\1$no>"G!$B..mN="aHmDs5Z0;rr<r85m&%6ruM(<"(&_A -*W,j;r?)"<"&7,6./j/H7G%P=!L/E>rrM.?rVlsVkhAE&rrG^@p&>&5Wq65k@CuO=!O6J>rr=)7 -rrJd@rr3*As8SE0r]pQH2ZE^W<65%<!JZp>rrgnCs*gR=rrLA?rr3!\iVicWg1^IO!-A,=!@m[: -rrM7?qu6]Q5Crics2Y.i~> -!$2%<!Dgu;rrQWBrUg*j2Wjo:!A3d=rrD9^gB"`srr3![ir&fVk5O*9Wd+=="'_Wb48o0[;m$#Q -#OMI_df9?VB)V`0*W#d:i&pu<!AWs?rrdkBs![O=rrmYDs8V.>r;Qa:r7_;GruM(<"(&_A*W,j; -r?)"<"&7,6./j/H7G%P=!L/E>rrM.?rVlsVkk_C[,QXh=p&>&5Wq65k@CuO=!O6J>rr=)7rrMYA -rZhWqs8SF+rS%>3rr3!uaSl,>L6hi="P-*CI\-Q=!R4F>rrG4?r;[email protected]<H9!Tl<; -rrLq?JcC<$a8^Y~> -!$2%<!Dgu;rrQWBrUg*j2Wjo:!A3d=rrD9^gB"`srr3![ir&fVk5O*9Wd+=="'_Wb48o0[;m$#Q -#OMI_df9?VB)V`0*W#d:i&pu<!AWs?rrdkBs![O=rrmYDs8V.>r;Qa:r7_;GruM(<"(&_A*W,j; -r?)"<"&7,6./j/H7G%P=!L/E>rrM.?rVlsVkk_C[,QXh=p&>&5Wq65k@CuO=!O6J>rr=)7rrMYA -rZhWqs8SF+rS%>3rr3!uaSl,>L6hi="P-*CI\-Q=!R4F>rrG4?r;[email protected]<H9!Tl<; -rrLq?JcC<$a8^Y~> -!$2%<!Dgu;rrQWBrUg*j2Wjo:!A3d=rrD9^gB"`srr3![ir&fVk5O*9Wd+=="'_Wb48o0[;m$#Q -#OMI_df9?VB)V`0*W#d:i&pu<!AWs?rrdkBs![O=rrmYDs8V.>r;Qa:r7_;GruM(<"(&_A*W,j; -r?)"<"&7,6./j/H7G%P=!L/E>rrM.?rVlsVkk_C[,QXh=p&>&5Wq65k@CuO=!O6J>rr=)7rrMYA -rZhWqs8SF+rS%>3rr3!uaSl,>L6hi="P-*CI\-Q=!R4F>rrG4?r;[email protected]<H9!Tl<; -rrLq?JcC<$a8^Y~> -%NYTElKUsRlL"WOoPM5>p&>0dl7pcSrr38pl71QUs8S%KrosO!?iL'19%*"9C]Ag_rosNhDZ0S9 -'/fdh$!Y7@i>l@us'`V?l3Qq[s&m;*`t`4brr=):rs7u:2sU&8s"Wm>rsjRLs#T-(lBDdTs8W)9 ->5eI$0`C8=pAb.5rVlt+^Afhal2tM?r@e-7"'3nD2u`(NC^AYmqs&uclMCP@3W8s[2!Egmro*tA -qu-O&IgEmjs82*HBq4JRrVlq:#grYO#l!UeX6T]a[r;61!&4BO#$)#ps8T-Jro+(Hs8SaFrosLM -rVm+4]^!gBs,`ECl3YL3s*bTflKZ/krr33rdH\>Ys*h!Il2e2-rr3#p,l7NA,Ph9;!rFA@r;Qii -#YfmMJcF'rJ,~> -%NYTElKUsRlL"WOoPM5>p&>0dl7pcSrr38pl71QUs8S%KrosO!?iL'19%*"9C]Ag_rosNhDZ0S9 -'/fdh$!Y7@i>l@us'`V?l3Qq[s&m;*`t`4brr=):rs7u:2sU&8s"Wm>rsjRLs#T-(lBDdTs8W)9 ->5eI$0`C8=pAb.5rVlt+^Afhal2tM?r@e-7"'3nD2u`(NC^AYmqs&uclMCP@3W8s[2!Egmro*tA -qu-O&IgEmjs82*HBq4JRrVlq:#grYO#l!UeX6T]a[r;61!&4BO#$)#ps8T-Jro+(Hs8SaFrosLM -rVm+4]^!gBs,`ECl3YL3s*bTflKZ/krr33rdH\>Ys*h!Il2e2-rr3#p,l7NA,Ph9;!rFA@r;Qii -#YfmMJcF'rJ,~> -%NYTElKUsRlL"WOoPM5>p&>0dl7pcSrr38pl71QUs8S%KrosO!?iL'19%*"9C]Ag_rosNhDZ0S9 -'/fdh$!Y7@i>l@us'`V?l3Qq[s&m;*`t`4brr=):rs7u:2sU&8s"Wm>rsjRLs#T-(lBDdTs8W)9 ->5eI$0`C8=pAb.5rVlt+^Afhal2tM?r@e-7"'3nD2u`(NC^AYmqs&uclMCP@3W8s[2!Egmro*tA -qu-O&IgEmjs82*HBq4JRrVlq:#grYO#l!UeX6T]a[r;61!&4BO#$)#ps8T-Jro+(Hs8SaFrosLM -rVm+4]^!gBs,`ECl3YL3s*bTflKZ/krr33rdH\>Ys*h!Il2e2-rr3#p,l7NA,Ph9;!rFA@r;Qii -#YfmMJcF'rJ,~> -!Zh<Nr%\CPs8SOkoD\fMr\=IJrr2tQr\=IQrr2tJr\=IXr;Qgi11L7_!-.un!,;B2!BaK`rrIJk -rr3,5NrT,br\=J%rr3+%10(eqrVljiqu6Xfr\=V=s8Q6jrr3:mYlF_b1,=WJ\,QC/dUqP=rrDoo -1'=ZYs%<7i"+JGnmJSdB])VfmrA"Jks8V!U1'FgqhuD@-1'>l&l!XJi"'k6gV>W.MZMa_%"dK_8 -s8UXI1&s31rrRrdd/O%FYPg3Yp](8mrA"BPrVm(C1@>,Am",-k"?b98s-3L<!(Qnd!a[WVrr2tR -r\=aXs8RP>BJM>Hr;Qgj11C1^!-8&o!,2<1!CkZ<rrLS?qu6]C:&FqloeL<6s+13rs*t~> -!Zh<Nr%\CPs8SOkoD\fMr\=IJrr2tQr\=IQrr2tJr\=IXr;Qgi11L7_!-.un!,;B2!BaK`rrIJk -rr3,5NrT,br\=J%rr3+%10(eqrVljiqu6Xfr\=V=s8Q6jrr3:mYlF_b1,=WJ\,QC/dUqP=rrDoo -1'=ZYs%<7i"+JGnmJSdB])VfmrA"Jks8V!U1'FgqhuD@-1'>l&l!XJi"'k6gV>W.MZMa_%"dK_8 -s8UXI1&s31rrRrdd/O%FYPg3Yp](8mrA"BPrVm(C1@>,Am",-k"?b98s-3L<!(Qnd!a[WVrr2tR -r\=aXs8RP>BJM>Hr;Qgj11C1^!-8&o!,2<1!CkZ<rrLS?qu6]C:&FqloeL<6s+13rs*t~> -!Zh<Nr%\CPs8SOkoD\fMr\=IJrr2tQr\=IQrr2tJr\=IXr;Qgi11L7_!-.un!,;B2!BaK`rrIJk -rr3,5NrT,br\=J%rr3+%10(eqrVljiqu6Xfr\=V=s8Q6jrr3:mYlF_b1,=WJ\,QC/dUqP=rrDoo -1'=ZYs%<7i"+JGnmJSdB])VfmrA"Jks8V!U1'FgqhuD@-1'>l&l!XJi"'k6gV>W.MZMa_%"dK_8 -s8UXI1&s31rrRrdd/O%FYPg3Yp](8mrA"BPrVm(C1@>,Am",-k"?b98s-3L<!(Qnd!a[WVrr2tR -r\=aXs8RP>BJM>Hr;Qgj11C1^!-8&o!,2<1!CkZ<rrLS?qu6]C:&FqloeL<6s+13rs*t~> -!$/$<"ip05s0lUqrrL'0a8Z1p62gfa/+NT<!F<J3rrGj@kPkRUIK'6Imk*c'!IgX(rrMb1r;Qe0 -r;6Ko@tFZ2s2G"g~> -!$/$<"ip05s0lUqrrL'0a8Z1p62gfa/+NT<!F<J3rrGj@kPkRUIK'6Imk*c'!IgX(rrMb1r;Qe0 -r;6Ko@tFZ2s2G"g~> -!$/$<"ip05s0lUqrrL'0a8Z1p62gfa/+NT<!F<J3rrGj@kPkRUIK'6Imk*c'!IgX(rrMb1r;Qe0 -r;6Ko@tFZ2s2G"g~> -!$/$<"db13PDH-0rrMD.rK@8'p\t0oa*QJ3rrTu\jQHODaFF2Q!Ki-#rrIS?JcC<$SH"*~> -!$/$<"db13PDH-0rrMD.rK@8'p\t0oa*QJ3rrTu\jQHODaFF2Q!Ki-#rrIS?JcC<$SH"*~> -!$/$<"db13PDH-0rrMD.rK@8'p\t0oa*QJ3rrTu\jQHODaFF2Q!Ki-#rrIS?JcC<$SH"*~> -!$/!;".k@+Wh04jiVeT5li$ha_US2W!P7(JrrC%;M#`Y#rrL$cJcC<$SH"*~> -!$/!;".k@+Wh04jiVeT5li$ha_US2W!P7(JrrC%;M#`Y#rrL$cJcC<$SH"*~> -!$/!;".k@+Wh04jiVeT5li$ha_US2W!P7(JrrC%;M#`Y#rrL$cJcC<$SH"*~> -!$2";!d\!iJc>iPBN]t=s+13$s,R,0~> -!$2";!d\!iJc>iPBN]t=s+13$s,R,0~> -!$2";!d\!iJc>iPBN]t=s+13$s,R,0~> -!$2%<"*pi_bhN-ufQmJr!GFXFrrGGskl1[N](l:-aMX^)JcC<$JcCf2J,~> -!$2%<"*pi_bhN-ufQmJr!GFXFrrGGskl1[N](l:-aMX^)JcC<$JcCf2J,~> -!$2%<"*pi_bhN-ufQmJr!GFXFrrGGskl1[N](l:-aMX^)JcC<$JcCf2J,~> -!$2%<!DgtnrrL>?rr3#^i7%],i9'8'!I1I7rrKi?JcC<$JcCf2J,~> -!$2%<!DgtnrrL>?rr3#^i7%],i9'8'!I1I7rrKi?JcC<$JcCf2J,~> -!$2%<!DgtnrrL>?rr3#^i7%],i9'8'!I1I7rrKi?JcC<$JcCf2J,~> -!$2%<!b/kArr2uhroFFJs8V`^mcEQnrr2ufroF.Drr2ueroF.Err3>ojlP[L;#gR`jlQI@"n;9O -jlPk.rrqcNjluO/q#:fjq>^Kimf3=RqW?o$n,E=gkiM+-rrD9^jT+iMrrD6]jT+lNrs.]Jjm[Mk -s8W&Z!;-9j!rK6?JcC<$JcCf2J,~> -!$2%<!b/kArr2uhroFFJs8V`^mcEQnrr2ufroF.Drr2ueroF.Err3>ojlP[L;#gR`jlQI@"n;9O -jlPk.rrqcNjluO/q#:fjq>^Kimf3=RqW?o$n,E=gkiM+-rrD9^jT+iMrrD6]jT+lNrs.]Jjm[Mk -s8W&Z!;-9j!rK6?JcC<$JcCf2J,~> -!$2%<!b/kArr2uhroFFJs8V`^mcEQnrr2ufroF.Drr2ueroF.Err3>ojlP[L;#gR`jlQI@"n;9O -jlPk.rrqcNjluO/q#:fjq>^Kimf3=RqW?o$n,E=gkiM+-rrD9^jT+iMrrD6]jT+lNrs.]Jjm[Mk -s8W&Z!;-9j!rK6?JcC<$JcCf2J,~> -!$2(=#N*U%n,NFQJc7S:6.5e!BkoXd7b%J#GQ'N(9%Et'ErJ!-:Y5X,D)XC@TMY[gHoD</rsik& -;`?XAh>c;<2`FX*MYR2b;p,.?^Kpm>8u4d32f[pYs&:a0rVloJ8,bFMHKbCW6N/nPJ*R'\4Z><@ -?D[\J3W:rBM=(?Cj'9[bJcC<$JcCi3J,~> -!$2(=#N*U%n,NFQJc7S:6.5e!BkoXd7b%J#GQ'N(9%Et'ErJ!-:Y5X,D)XC@TMY[gHoD</rsik& -;`?XAh>c;<2`FX*MYR2b;p,.?^Kpm>8u4d32f[pYs&:a0rVloJ8,bFMHKbCW6N/nPJ*R'\4Z><@ -?D[\J3W:rBM=(?Cj'9[bJcC<$JcCi3J,~> -!$2(=#N*U%n,NFQJc7S:6.5e!BkoXd7b%J#GQ'N(9%Et'ErJ!-:Y5X,D)XC@TMY[gHoD</rsik& -;`?XAh>c;<2`FX*MYR2b;p,.?^Kpm>8u4d32f[pYs&:a0rVloJ8,bFMHKbCW6N/nPJ*R'\4Z><@ -?D[\J3W:rBM=(?Cj'9[bJcC<$JcCi3J,~> -!$2(=!c7q^rr3"kIfB?UmOnO*/AhGeju<=#NrK%]k^NPcQi@!keO]^gTE"r]6W!a]!$2%<%;\)^ -s8T]>s'rV>s3OI6rshuMs8Ti>s8P\[p&G&[KDtlOkqi;<!BK3>rrfR8s"Wm>rsXFJs![O>s0sGQ -ruh:>rrI&?rr3&6!.0:sJcC<$OT0h~> -!$2(=!c7q^rr3"kIfB?UmOnO*/AhGeju<=#NrK%]k^NPcQi@!keO]^gTE"r]6W!a]!$2%<%;\)^ -s8T]>s'rV>s3OI6rshuMs8Ti>s8P\[p&G&[KDtlOkqi;<!BK3>rrfR8s"Wm>rsXFJs![O>s0sGQ -ruh:>rrI&?rr3&6!.0:sJcC<$OT0h~> -!$2(=!c7q^rr3"kIfB?UmOnO*/AhGeju<=#NrK%]k^NPcQi@!keO]^gTE"r]6W!a]!$2%<%;\)^ -s8T]>s'rV>s3OI6rshuMs8Ti>s8P\[p&G&[KDtlOkqi;<!BK3>rrfR8s"Wm>rsXFJs![O>s0sGQ -ruh:>rrI&?rr3&6!.0:sJcC<$OT0h~> -!$2(=#Hi'&pAb/b7fJDNKeECkLAq2Uju<=#Nr/hWKpVf="P$'CI@pN=!R+C=rr=)<rrHr?rr389 -@K0iJs8UG>p\tOub5_LV?2spsdf07IR=kM=!U2E=rrG.?qu6[Om/I"fJ=QWfo`"jnGbtE_NW+qC -5-=kbmtYnkJcC<$JcCi3J,~> -!$2(=#Hi'&pAb/b7fJDNKeECkLAq2Uju<=#Nr/hWKpVf="P$'CI@pN=!R+C=rr=)<rrHr?rr389 -@K0iJs8UG>p\tOub5_LV?2spsdf07IR=kM=!U2E=rrG.?qu6[Om/I"fJ=QWfo`"jnGbtE_NW+qC -5-=kbmtYnkJcC<$JcCi3J,~> -!$2(=#Hi'&pAb/b7fJDNKeECkLAq2Uju<=#Nr/hWKpVf="P$'CI@pN=!R+C=rr=)<rrHr?rr389 -@K0iJs8UG>p\tOub5_LV?2spsdf07IR=kM=!U2E=rrG.?qu6[Om/I"fJ=QWfo`"jnGbtE_NW+qC -5-=kbmtYnkJcC<$JcCi3J,~> -!$2%<#+^SDs8S]\rJguSs-AE=rrhICs,N-:rrIh?rr3,O8H4+1rr3#C;#UCo*W?!=Cp<p=#eOOF -\p8:8G-L`@#uf"Hs1_k>s%:`=rrJO?rr3#`1]@=S3TL#:!AWs?rrdkBs![O=rrdSCrud="NWn2; -s6k`>JcC<$JcCf2J,~> -!$2%<#+^SDs8S]\rJguSs-AE=rrhICs,N-:rrIh?rr3,O8H4+1rr3#C;#UCo*W?!=Cp<p=#eOOF -\p8:8G-L`@#uf"Hs1_k>s%:`=rrJO?rr3#`1]@=S3TL#:!AWs?rrdkBs![O=rrdSCrud="NWn2; -s6k`>JcC<$JcCf2J,~> -!$2%<#+^SDs8S]\rJguSs-AE=rrhICs,N-:rrIh?rr3,O8H4+1rr3#C;#UCo*W?!=Cp<p=#eOOF -\p8:8G-L`@#uf"Hs1_k>s%:`=rrJO?rr3#`1]@=S3TL#:!AWs?rrdkBs![O=rrdSCrud="NWn2; -s6k`>JcC<$JcCf2J,~> -!$2%<!Dgu>rrJa@qu6\_LAq2Uju<=#NrK%]k^NPcQi@!keO]^gTE"r]6W!a]!$2%<!Go">rs-/E -s-JqMX1J3.!EOLFrs;WHs8Ti>s8P^>rr3"eKDtlOkqi;<!BK3>rrfR8s"Wm>rsXFJs![O>s0sGQ -ruh:9rrKi?JcC<$JcCf2J,~> -!$2%<!Dgu>rrJa@qu6\_LAq2Uju<=#NrK%]k^NPcQi@!keO]^gTE"r]6W!a]!$2%<!Go">rs-/E -s-JqMX1J3.!EOLFrs;WHs8Ti>s8P^>rr3"eKDtlOkqi;<!BK3>rrfR8s"Wm>rsXFJs![O>s0sGQ -ruh:9rrKi?JcC<$JcCf2J,~> -!$2%<!Dgu>rrJa@qu6\_LAq2Uju<=#NrK%]k^NPcQi@!keO]^gTE"r]6W!a]!$2%<!Go">rs-/E -s-JqMX1J3.!EOLFrs;WHs8Ti>s8P^>rr3"eKDtlOkqi;<!BK3>rrfR8s"Wm>rsXFJs![O>s0sGQ -ruh:9rrKi?JcC<$JcCf2J,~> -!$2%<!Dgu>rrMD9r\jsKs8SC>rr3,`2ui#ar\jsPec4`Or\kNefDjlJ2`F*s;#gQC2[23Qs8Qo> -rr3,[email protected]\jgur;Qd"2u`g`g/U'j>EbER9%*_=%%2bJs&:`]2i[k;e49Ks"FB;3dR*pl%"IRB -coj<HF'b^CcT1t`!3#kr!PVlks+13$s,[21~> -!$2%<!Dgu>rrMD9r\jsKs8SC>rr3,`2ui#ar\jsPec4`Or\kNefDjlJ2`F*s;#gQC2[23Qs8Qo> -rr3,[email protected]\jgur;Qd"2u`g`g/U'j>EbER9%*_=%%2bJs&:`]2i[k;e49Ks"FB;3dR*pl%"IRB -coj<HF'b^CcT1t`!3#kr!PVlks+13$s,[21~> -!$2%<!Dgu>rrMD9r\jsKs8SC>rr3,`2ui#ar\jsPec4`Or\kNefDjlJ2`F*s;#gQC2[23Qs8Qo> -rr3,[email protected]\jgur;Qd"2u`g`g/U'j>EbER9%*_=%%2bJs&:`]2i[k;e49Ks"FB;3dR*pl%"IRB -coj<HF'b^CcT1t`!3#kr!PVlks+13$s,[21~> -!$2%<#44f!56(ZRroF:Fs8V`^rr3-!lMpnRroF.Drr2ueroF.Err38mjlP\%mJm4SroF:Ks8VT_ -rr3,rn,IL3roF0ZH2[aDc8Y_%#jUO5lh0fJm/$_]"SD9bs60ID!:^!f!9jFD!:g'g!9a@C!:p-h -#Nk.0nF?5Ps8D$`o`+qH*Dc*Ss+13$s,[21~> -!$2%<#44f!56(ZRroF:Fs8V`^rr3-!lMpnRroF.Drr2ueroF.Err38mjlP\%mJm4SroF:Ks8VT_ -rr3,rn,IL3roF0ZH2[aDc8Y_%#jUO5lh0fJm/$_]"SD9bs60ID!:^!f!9jFD!:g'g!9a@C!:p-h -#Nk.0nF?5Ps8D$`o`+qH*Dc*Ss+13$s,[21~> -!$2%<#44f!56(ZRroF:Fs8V`^rr3-!lMpnRroF.Drr2ueroF.Err38mjlP\%mJm4SroF:Ks8VT_ -rr3,rn,IL3roF0ZH2[aDc8Y_%#jUO5lh0fJm/$_]"SD9bs60ID!:^!f!9jFD!:g'g!9a@C!:p-h -#Nk.0nF?5Ps8D$`o`+qH*Dc*Ss+13$s,[21~> -!$/lT!I(UDhuT^&rVloB:kAXts+13$s3Udr~> -!$/lT!I(UDhuT^&rVloB:kAXts+13$s3Udr~> -!$/lT!I(UDhuT^&rVloB:kAXts+13$s3Udr~> -!$/iS!-8'$!-\;?!)nIKJcC<$JcF'rJ,~> -!$/iS!-8'$!-\;?!)nIKJcC<$JcF'rJ,~> -!$/iS!-8'$!-\;?!)nIKJcC<$JcF'rJ,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -"!.FAao7+sNW/qY`R48V"0^kcRDo1.QN,gOJcC<$JcC<$iW"E~> -"!.FAao7+sNW/qY`R48V"0^kcRDo1.QN,gOJcC<$JcC<$iW"E~> -"!.FAao7+sNW/qY`R48V"0^kcRDo1.QN,gOJcC<$JcC<$iW"E~> -"!.EcIf>N8P(N`6b'V_2rrZ3AqBEoY"!.ENAqBu5s+13$s5F!.~> -"!.EcIf>N8P(N`6b'V_2rrZ3AqBEoY"!.ENAqBu5s+13$s5F!.~> -"!.EcIf>N8P(N`6b'V_2rrZ3AqBEoY"!.ENAqBu5s+13$s5F!.~> -"!.E>FoMCApEon>!mbW@o`#"land4#rrX;A[q:3kJcC<$JcF^/J,~> -"!.E>FoMCApEon>!mbW@o`#"land4#rrX;A[q:3kJcC<$JcF^/J,~> -"!.E>FoMCApEon>!mbW@o`#"land4#rrX;A[q:3kJcC<$JcF^/J,~> -"!.F0jSo/[8C[V<!o$B@p&>9Qo`!>>s.-4irrh.os-Btirrgnos,aejrs6qrs,"Pks57Vjrr?j6 -1&u7krrYqM13WZs!+#RZ!.FhG"4R;?iIV#[s+13$s5F!.~> -"!.F0jSo/[8C[V<!o$B@p&>9Qo`!>>s.-4irrh.os-Btirrgnos,aejrs6qrs,"Pks57Vjrr?j6 -1&u7krrYqM13WZs!+#RZ!.FhG"4R;?iIV#[s+13$s5F!.~> -"!.F0jSo/[8C[V<!o$B@p&>9Qo`!>>s.-4irrh.os-Btirrgnos,aejrs6qrs,"Pks57Vjrr?j6 -1&u7krrYqM13WZs!+#RZ!.FhG"4R;?iIV#[s+13$s5F!.~> -!$2%<!r>IAqu6]a0CSoAKpVf="P$'CI@pN='[0DRFK#6>hA08oCp<s>fgPl?E3K9+!NL>Brs'\0 -[oNJ.@D2[*!M"jps+13$s+14(s*t~> -!$2%<!r>IAqu6]a0CSoAKpVf="P$'CI@pN='[0DRFK#6>hA08oCp<s>fgPl?E3K9+!NL>Brs'\0 -[oNJ.@D2[*!M"jps+13$s+14(s*t~> -!$2%<!r>IAqu6]a0CSoAKpVf="P$'CI@pN='[0DRFK#6>hA08oCp<s>fgPl?E3K9+!NL>Brs'\0 -[oNJ.@D2[*!M"jps+13$s+14(s*t~> -!$2(=!pX(@qYpTT4R`:NKpVf="P$'CI>RsX'X(@5FK#5r5/^V(Cp<s>fgPl?A%DU=!OHM>rs'\E -aAr9?;m$&R!K28Ts+13$s+14(s*t~> -!$2(=!pX(@qYpTT4R`:NKpVf="P$'CI>RsX'X(@5FK#5r5/^V(Cp<s>fgPl?A%DU=!OHM>rs'\E -aAr9?;m$&R!K28Ts+13$s+14(s*t~> -!$2(=!pX(@qYpTT4R`:NKpVf="P$'CI>RsX'X(@5FK#5r5/^V(Cp<s>fgPl?A%DU=!OHM>rs'\E -aAr9?;m$&R!K28Ts+13$s+14(s*t~> -"WdXCiHE09rrUPJp@&"^KpVf="P$'CI4>.]'JrYdFK!D[s28(?Cp<s>fgPl?A%DU=%'s[Js34F> -aAr9?;`+G=!1\W?JcC<$JcFI(J,~> -"WdXCiHE09rrUPJp@&"^KpVf="P$'CI4>.]'JrYdFK!D[s28(?Cp<s>fgPl?A%DU=%'s[Js34F> -aAr9?;`+G=!1\W?JcC<$JcFI(J,~> -"WdXCiHE09rrUPJp@&"^KpVf="P$'CI4>.]'JrYdFK!D[s28(?Cp<s>fgPl?A%DU=%'s[Js34F> -aAr9?;`+G=!1\W?JcC<$JcFI(J,~> -"<IO"K"LmZ!lf6Amf*TIQiI*^L.M>mTDnj)bY\=]C2NA<`**+VYlFaV70!9s\c2U;ZYBI>52ZC] -<WE(tb45K5pS#?Qs+13$s+146s*t~> -"<IO"K"LmZ!lf6Amf*TIQiI*^L.M>mTDnj)bY\=]C2NA<`**+VYlFaV70!9s\c2U;ZYBI>52ZC] -<WE(tb45K5pS#?Qs+13$s+146s*t~> -"<IO"K"LmZ!lf6Amf*TIQiI*^L.M>mTDnj)bY\=]C2NA<`**+VYlFaV70!9s\c2U;ZYBI>52ZC] -<WE(tb45K5pS#?Qs+13$s+146s*t~> -"!.E>4oL$;QN.!%J(j;i$,D(EKS*o.s*^O=rtN[Rs)_,ss8U#?s(knmKQ&0Bs0%"QKFEF;s0*Ve -KP)jJs/(DIKE/:MrrVEb;1\aus+13$s60K5~> -"!.E>4oL$;QN.!%J(j;i$,D(EKS*o.s*^O=rtN[Rs)_,ss8U#?s(knmKQ&0Bs0%"QKFEF;s0*Ve -KP)jJs/(DIKE/:MrrVEb;1\aus+13$s60K5~> -"!.E>4oL$;QN.!%J(j;i$,D(EKS*o.s*^O=rtN[Rs)_,ss8U#?s(knmKQ&0Bs0%"QKFEF;s0*Ve -KP)jJs/(DIKE/:MrrVEb;1\aus+13$s60K5~> -!Zh<rr0RVbs8U<pli.7-R$aGp8H6ibrr3,d\GsV)rr3)`]`5qKQiqA:s8TJ*Qisnus''RDQiq#A -s8T8$QiOknrrVn]\Ujd3s+13$s60K5~> -!Zh<rr0RVbs8U<pli.7-R$aGp8H6ibrr3,d\GsV)rr3)`]`5qKQiqA:s8TJ*Qisnus''RDQiq#A -s8T8$QiOknrrVn]\Ujd3s+13$s60K5~> -!Zh<rr0RVbs8U<pli.7-R$aGp8H6ibrr3,d\GsV)rr3)`]`5qKQiqA:s8TJ*Qisnus''RDQiq#A -s8T8$QiOknrrVn]\Ujd3s+13$s60K5~> -!$1"t!NEL+rrLY@li.!t@JKj'cgC`3!Tqsas+13$s+13us*t~> -!$1"t!NEL+rrLY@li.!t@JKj'cgC`3!Tqsas+13$s+13us*t~> -!$1"t!NEL+rrLY@li.!t@JKj'cgC`3!Tqsas+13$s+13us*t~> -!$1"t!U4S&/HJH"li."Wj+75]s+13$s2+ed~> -!$1"t!U4S&/HJH"li."Wj+75]s+13$s2+ed~> -!$1"t!U4S&/HJH"li."Wj+75]s+13$s2+ed~> -!$2(="8MHXoB-&Qp&=C[nU^_$rr`#do(.G4JcDABJ,~> -!$2(="8MHXoB-&Qp&=C[nU^_$rr`#do(.G4JcDABJ,~> -!$2(="8MHXoB-&Qp&=C[nU^_$rr`#do(.G4JcDABJ,~> -!$2(=")T&-1&V%PiV<?N"6A%arr2otkl0-5g\h'Ph>HmE!8@>M!oDM`r;QiRf%p?*!9F(/!9j.V -!WCjOrrUg'j8ArWec=e0rr`5Nf&cQ(!VYROrr`)Jf'<87!<)lI!:]mc!U0(HrrMTRr;Qlif%0?h -rr_fBf(/e>!:^!=!;Q6e!U0(Ors%i@f(]4Eo_d8?g&D!Ol2K9+rrM*Rr;Qu_f%0j#s6]a8!oX+E -r72)2s8RBo.2IL7JcDABJ,~> -!$2(=")T&-1&V%PiV<?N"6A%arr2otkl0-5g\h'Ph>HmE!8@>M!oDM`r;QiRf%p?*!9F(/!9j.V -!WCjOrrUg'j8ArWec=e0rr`5Nf&cQ(!VYROrr`)Jf'<87!<)lI!:]mc!U0(HrrMTRr;Qlif%0?h -rr_fBf(/e>!:^!=!;Q6e!U0(Ors%i@f(]4Eo_d8?g&D!Ol2K9+rrM*Rr;Qu_f%0j#s6]a8!oX+E -r72)2s8RBo.2IL7JcDABJ,~> -!$2(=")T&-1&V%PiV<?N"6A%arr2otkl0-5g\h'Ph>HmE!8@>M!oDM`r;QiRf%p?*!9F(/!9j.V -!WCjOrrUg'j8ArWec=e0rr`5Nf&cQ(!VYROrr`)Jf'<87!<)lI!:]mc!U0(HrrMTRr;Qlif%0?h -rr_fBf(/e>!:^!=!;Q6e!U0(Ors%i@f(]4Eo_d8?g&D!Ol2K9+rrM*Rr;Qu_f%0j#s6]a8!oX+E -r72)2s8RBo.2IL7JcDABJ,~> -!$2(=!H#(<rrU\+ec#LRg2BGM^An5kH2^86<m(FA!mMnWo`"s6(&\(7c<Nh@bPqMIbZRD>cN!oK -2>ouERJ-X]ZRbtR"N*i$CY/Rc"MdJrDV>$h"M.&lEnpBg!r.jWrVm0%WCB@+j8].frC-gJmJ[%d -i)?WKrrVP,JGoK[ns2a7ORE/Kmug.0Pk"eRm>h08!9!SN!oR"WrVm,bK18>*qZ"e;7KaM,s5A>( -7KEG]rrU_-eG]CPg2KMN^&S,8rC-lP56%S[7KGS@r;Qa;JcC<$TDsE~> -!$2(=!H#(<rrU\+ec#LRg2BGM^An5kH2^86<m(FA!mMnWo`"s6(&\(7c<Nh@bPqMIbZRD>cN!oK -2>ouERJ-X]ZRbtR"N*i$CY/Rc"MdJrDV>$h"M.&lEnpBg!r.jWrVm0%WCB@+j8].frC-gJmJ[%d -i)?WKrrVP,JGoK[ns2a7ORE/Kmug.0Pk"eRm>h08!9!SN!oR"WrVm,bK18>*qZ"e;7KaM,s5A>( -7KEG]rrU_-eG]CPg2KMN^&S,8rC-lP56%S[7KGS@r;Qa;JcC<$TDsE~> -!$2(=!H#(<rrU\+ec#LRg2BGM^An5kH2^86<m(FA!mMnWo`"s6(&\(7c<Nh@bPqMIbZRD>cN!oK -2>ouERJ-X]ZRbtR"N*i$CY/Rc"MdJrDV>$h"M.&lEnpBg!r.jWrVm0%WCB@+j8].frC-gJmJ[%d -i)?WKrrVP,JGoK[ns2a7ORE/Kmug.0Pk"eRm>h08!9!SN!oR"WrVm,bK18>*qZ"e;7KaM,s5A>( -7KEG]rrU_-eG]CPg2KMN^&S,8rC-lP56%S[7KGS@r;Qa;JcC<$TDsE~> -!$2(=!H#(=rr^Pl*7b&g$.aRGs8Ql>s,N-=rs.@Es8U#Z'(>Mn!krU^rVmJLFlEAaEl.jnF6<M^ -FN+8a_=IU-X^NaYrt`"Xqu=rhdf6Ufs8U/hec2gjs8Tudg%YLJQVCKYrs5BFs8TH[ir:%trrHH? -rr3)XK.X(srr__K4b3P3')7TQs8SOJoCS*2s8S@Gp@4-5oD\pMK.O&%rs%YBXT/<NSGW<iX)\0u -KX^RQ"4)95eGfIPf7(a>s(nt<rrW1aM>[ATqNHs;rr='js+13Bs*t~> -!$2(=!H#(=rr^Pl*7b&g$.aRGs8Ql>s,N-=rs.@Es8U#Z'(>Mn!krU^rVmJLFlEAaEl.jnF6<M^ -FN+8a_=IU-X^NaYrt`"Xqu=rhdf6Ufs8U/hec2gjs8Tudg%YLJQVCKYrs5BFs8TH[ir:%trrHH? -rr3)XK.X(srr__K4b3P3')7TQs8SOJoCS*2s8S@Gp@4-5oD\pMK.O&%rs%YBXT/<NSGW<iX)\0u -KX^RQ"4)95eGfIPf7(a>s(nt<rrW1aM>[ATqNHs;rr='js+13Bs*t~> -!$2(=!H#(=rr^Pl*7b&g$.aRGs8Ql>s,N-=rs.@Es8U#Z'(>Mn!krU^rVmJLFlEAaEl.jnF6<M^ -FN+8a_=IU-X^NaYrt`"Xqu=rhdf6Ufs8U/hec2gjs8Tudg%YLJQVCKYrs5BFs8TH[ir:%trrHH? -rr3)XK.X(srr__K4b3P3')7TQs8SOJoCS*2s8S@Gp@4-5oD\pMK.O&%rs%YBXT/<NSGW<iX)\0u -KX^RQ"4)95eGfIPf7(a>s(nt<rrW1aM>[ATqNHs;rr='js+13Bs*t~> -!$2(=!H#(>rrgYtbt$=`rrJF?rr3,`2uenurr35Z5QATNg+Dderr]f^iZ8!t!Go">rt)eNs0@.> -s6"m>s'*=#It+Hlrr]'Il7;i5!CGQ?rsY$Js.+]?s3cD>s"Wm>rrIY?q#:GWNQ5&trr=)<rrZoB -ruM(<#[Y7Fs5ea>F/es7"T!VCSUg_>!UMN=rsLsInURY>s/:J?gHkH2"QY'BEiT-=!Q&(>rr=): -rra_Bs06D3rrgYtbt-@`rrJI?rr3#^2Z3RUq]Yk:!V7c;rr='js+13Bs*t~> -!$2(=!H#(>rrgYtbt$=`rrJF?rr3,`2uenurr35Z5QATNg+Dderr]f^iZ8!t!Go">rt)eNs0@.> -s6"m>s'*=#It+Hlrr]'Il7;i5!CGQ?rsY$Js.+]?s3cD>s"Wm>rrIY?q#:GWNQ5&trr=)<rrZoB -ruM(<#[Y7Fs5ea>F/es7"T!VCSUg_>!UMN=rsLsInURY>s/:J?gHkH2"QY'BEiT-=!Q&(>rr=): -rra_Bs06D3rrgYtbt-@`rrJI?rr3#^2Z3RUq]Yk:!V7c;rr='js+13Bs*t~> -!$2(=!H#(>rrgYtbt$=`rrJF?rr3,`2uenurr35Z5QATNg+Dderr]f^iZ8!t!Go">rt)eNs0@.> -s6"m>s'*=#It+Hlrr]'Il7;i5!CGQ?rsY$Js.+]?s3cD>s"Wm>rrIY?q#:GWNQ5&trr=)<rrZoB -ruM(<#[Y7Fs5ea>F/es7"T!VCSUg_>!UMN=rsLsInURY>s/:J?gHkH2"QY'BEiT-=!Q&(>rr=): -rra_Bs06D3rrgYtbt-@`rrJI?rr3#^2Z3RUq]Yk:!V7c;rr='js+13Bs*t~> -!$2(=!H#(>rrh'#s$tW=rrJF?rr3Mk2uenus8W!s5QB*^s"3^5rr^F#ruM(<!Go">rt2kOs8TTE -@Vr^Vs'&*]SXkV9q#:H,mdVh+rrGI@rr3ChMuWgT@UaQ)s8Oh?rr3"LSG<*dWW'q<rVlj<rVlt4 -[f7BIrs>hR^Am_@]`3&Pq#:KoXT+iArr3#c0`D"[4Q-8(M.0qOli5^*`Vs<HjS8`Xlb3==WrE#! -_H[!=!$2";#)nfDs06C@raGm,q#:KNc2U>arr3"cL&V)Qk;N8<!HY:<rrI&?qu6X:JcC<$TDsE~> -!$2(=!H#(>rrh'#s$tW=rrJF?rr3Mk2uenus8W!s5QB*^s"3^5rr^F#ruM(<!Go">rt2kOs8TTE -@Vr^Vs'&*]SXkV9q#:H,mdVh+rrGI@rr3ChMuWgT@UaQ)s8Oh?rr3"LSG<*dWW'q<rVlj<rVlt4 -[f7BIrs>hR^Am_@]`3&Pq#:KoXT+iArr3#c0`D"[4Q-8(M.0qOli5^*`Vs<HjS8`Xlb3==WrE#! -_H[!=!$2";#)nfDs06C@raGm,q#:KNc2U>arr3"cL&V)Qk;N8<!HY:<rrI&?qu6X:JcC<$TDsE~> -!$2(=!H#(>rrh'#s$tW=rrJF?rr3Mk2uenus8W!s5QB*^s"3^5rr^F#ruM(<!Go">rt2kOs8TTE -@Vr^Vs'&*]SXkV9q#:H,mdVh+rrGI@rr3ChMuWgT@UaQ)s8Oh?rr3"LSG<*dWW'q<rVlj<rVlt4 -[f7BIrs>hR^Am_@]`3&Pq#:KoXT+iArr3#c0`D"[4Q-8(M.0qOli5^*`Vs<HjS8`Xlb3==WrE#! -_H[!=!$2";#)nfDs06C@raGm,q#:KNc2U>arr3"cL&V)Qk;N8<!HY:<rrI&?qu6X:JcC<$TDsE~> -!$2(=!H#(;rrGX?rr3"bLAq2Zju<=uGst.lTg/MU!A3d3rr=)<rrHr?rr3SB@K6@PVn/[Ps8UQZ -pAb/mEq]M6nLOS<!CGQ?rsY$Js8Q96\riK^s"Wm>rrIY?pAY06<W2pt*W?!?B=@iLr^@-E7DAe$ -aT)9]WV-8lSUg_>!UMN=rsV$Js42%u\n]pugCeK)\cGt,pAY/6WrE#!_H[!=!$2";#"7,Ds03St -rji)5p&>%`eGfIKQ\GG=!TuB=rr=)9rr=)9rr='js+13Bs*t~> -!$2(=!H#(;rrGX?rr3"bLAq2Zju<=uGst.lTg/MU!A3d3rr=)<rrHr?rr3SB@K6@PVn/[Ps8UQZ -pAb/mEq]M6nLOS<!CGQ?rsY$Js8Q96\riK^s"Wm>rrIY?pAY06<W2pt*W?!?B=@iLr^@-E7DAe$ -aT)9]WV-8lSUg_>!UMN=rsV$Js42%u\n]pugCeK)\cGt,pAY/6WrE#!_H[!=!$2";#"7,Ds03St -rji)5p&>%`eGfIKQ\GG=!TuB=rr=)9rr=)9rr='js+13Bs*t~> -!$2(=!H#(;rrGX?rr3"bLAq2Zju<=uGst.lTg/MU!A3d3rr=)<rrHr?rr3SB@K6@PVn/[Ps8UQZ -pAb/mEq]M6nLOS<!CGQ?rsY$Js8Q96\riK^s"Wm>rrIY?pAY06<W2pt*W?!?B=@iLr^@-E7DAe$ -aT)9]WV-8lSUg_>!UMN=rsV$Js42%u\n]pugCeK)\cGt,pAY/6WrE#!_H[!=!$2";#"7,Ds03St -rji)5p&>%`eGfIKQ\GG=!TuB=rr=)9rr=)9rr='js+13Bs*t~> -!$2(=!H#(;rrGX?rr3"bLAq2Zju<>?l.=P>h*:l<!A3d3rr=)<rrHr?rr3;:@K1_Qq>^5bJc#HJ -WcIh5!V%]=rrGI@rr3ChMuQnts8VVDV>i::rr3"LSG)s`a&W*<!$2%<")#(BrVkCOls@F+$N;FT -&f]0jrrJ[@rr3#c0`D"[4Q,F!jT#8@9^LLmk5PA]/+N?5!HP4>rrKu@rVlj<rVm+KW;6JnZ!6So -rr=)4rrG[?rr3"cL&V)Qk;N;=!E[;<rrGp?qYpO9JcC<$TDsE~> -!$2(=!H#(;rrGX?rr3"bLAq2Zju<>?l.=P>h*:l<!A3d3rr=)<rrHr?rr3;:@K1_Qq>^5bJc#HJ -WcIh5!V%]=rrGI@rr3ChMuQnts8VVDV>i::rr3"LSG)s`a&W*<!$2%<")#(BrVkCOls@F+$N;FT -&f]0jrrJ[@rr3#c0`D"[4Q,F!jT#8@9^LLmk5PA]/+N?5!HP4>rrKu@rVlj<rVm+KW;6JnZ!6So -rr=)4rrG[?rr3"cL&V)Qk;N;=!E[;<rrGp?qYpO9JcC<$TDsE~> -!$2(=!H#(;rrGX?rr3"bLAq2Zju<>?l.=P>h*:l<!A3d3rr=)<rrHr?rr3;:@K1_Qq>^5bJc#HJ -WcIh5!V%]=rrGI@rr3ChMuQnts8VVDV>i::rr3"LSG)s`a&W*<!$2%<")#(BrVkCOls@F+$N;FT -&f]0jrrJ[@rr3#c0`D"[4Q,F!jT#8@9^LLmk5PA]/+N?5!HP4>rrKu@rVlj<rVm+KW;6JnZ!6So -rr=)4rrG[?rr3"cL&V)Qk;N;=!E[;<rrGp?qYpO9JcC<$TDsE~> -!$2(=!H#(;rrGX?rr31nL&(cKfL5W:!ROO=rrF_?qu6]dn,*+b*W?!MG,kK?r3L5>DR'->r2b#? -o_\Xf!NL2=rrMNXr;Qff/,fJ`:X9"?q2^a>8(IY>q1kI>5McA>pjf.=rrW,cp&+gja&W*<"t]9D -s7^9?r;QlmA&J?FoE&p)r;Q]tq<dtTrrJ[@rr3St47iLPoL@j%6hC?Xo02Ho62gfa/+NW=!qu$Y -r;Qe<WrE#&`aJN?s7%Z>rrVn+_#F?7Z#'C=!$2%<!qYgXr;QdgeGfIPSqQq>s4Kd=rrVdXkPY>] -o/c@:rr='js+13Bs*t~> -!$2(=!H#(;rrGX?rr31nL&(cKfL5W:!ROO=rrF_?qu6]dn,*+b*W?!MG,kK?r3L5>DR'->r2b#? -o_\Xf!NL2=rrMNXr;Qff/,fJ`:X9"?q2^a>8(IY>q1kI>5McA>pjf.=rrW,cp&+gja&W*<"t]9D -s7^9?r;QlmA&J?FoE&p)r;Q]tq<dtTrrJ[@rr3St47iLPoL@j%6hC?Xo02Ho62gfa/+NW=!qu$Y -r;Qe<WrE#&`aJN?s7%Z>rrVn+_#F?7Z#'C=!$2%<!qYgXr;QdgeGfIPSqQq>s4Kd=rrVdXkPY>] -o/c@:rr='js+13Bs*t~> -!$2(=!H#(;rrGX?rr31nL&(cKfL5W:!ROO=rrF_?qu6]dn,*+b*W?!MG,kK?r3L5>DR'->r2b#? -o_\Xf!NL2=rrMNXr;Qff/,fJ`:X9"?q2^a>8(IY>q1kI>5McA>pjf.=rrW,cp&+gja&W*<"t]9D -s7^9?r;QlmA&J?FoE&p)r;Q]tq<dtTrrJ[@rr3St47iLPoL@j%6hC?Xo02Ho62gfa/+NW=!qu$Y -r;Qe<WrE#&`aJN?s7%Z>rrVn+_#F?7Z#'C=!$2%<!qYgXr;QdgeGfIPSqQq>s4Kd=rrVdXkPY>] -o/c@:rr='js+13Bs*t~> -!$2(=!H#(>rseACd5nGXg&M)7QI4)Lrr3GhdF$63s8V?2d3Z]XhYmHT,o6L[%Hc'c(t$ais8R#B -dC<ffrs3;IdBd]is*:UCd/f_qrr3&r!'pP`%GoLO,LOp&s8Pd:d@H*mrrbg=d?p!orrbd<d?9go -rrULHCB"5Ef$U6^dF%I`qF/fZJueqOr;P(EIBrbM!HY7=ruS!:PlLd^dF!JXdF%ahf3m"RB?pPW -d:L_Q@b(M<=T-VJ9(W&^'70_os8Vc>d9V[XdJs6SHdU58nG`FgJ"HW=!P`^Sd/ZZ7rt8-.l2UeO -dEt%YdFnR"P*XMC7fE>f<64t:!DLl9rr='js+13Bs*t~> -!$2(=!H#(>rseACd5nGXg&M)7QI4)Lrr3GhdF$63s8V?2d3Z]XhYmHT,o6L[%Hc'c(t$ais8R#B -dC<ffrs3;IdBd]is*:UCd/f_qrr3&r!'pP`%GoLO,LOp&s8Pd:d@H*mrrbg=d?p!orrbd<d?9go -rrULHCB"5Ef$U6^dF%I`qF/fZJueqOr;P(EIBrbM!HY7=ruS!:PlLd^dF!JXdF%ahf3m"RB?pPW -d:L_Q@b(M<=T-VJ9(W&^'70_os8Vc>d9V[XdJs6SHdU58nG`FgJ"HW=!P`^Sd/ZZ7rt8-.l2UeO -dEt%YdFnR"P*XMC7fE>f<64t:!DLl9rr='js+13Bs*t~> -!$2(=!H#(>rseACd5nGXg&M)7QI4)Lrr3GhdF$63s8V?2d3Z]XhYmHT,o6L[%Hc'c(t$ais8R#B -dC<ffrs3;IdBd]is*:UCd/f_qrr3&r!'pP`%GoLO,LOp&s8Pd:d@H*mrrbg=d?p!orrbd<d?9go -rrULHCB"5Ef$U6^dF%I`qF/fZJueqOr;P(EIBrbM!HY7=ruS!:PlLd^dF!JXdF%ahf3m"RB?pPW -d:L_Q@b(M<=T-VJ9(W&^'70_os8Vc>d9V[XdJs6SHdU58nG`FgJ"HW=!P`^Sd/ZZ7rt8-.l2UeO -dEt%YdFnR"P*XMC7fE>f<64t:!DLl9rr='js+13Bs*t~> -!$2(=#&Sap[f?B>r(@$+rr3(Z92#3^rr\``92GQe!3,lh!.OnH!G*,IrrAVf9)skKrrR(2B)MZ1 -BM31?rr@9B9)sbGrrW'`5lUc`JG`%?W;ceu:eQK?rr`6n98`]J"8GM^OSo+[h)/sHrr?O+9*WB8 -s5lsIUAk/mp&7SaW;?MpSAY=*"i)ONs8Vlk9*XGVs2[i+_#=98_FmPArr2uGrC[.KrVm%q*5DOR -gAFSD:&b.pX%Q+BrVlnp]);R.Zi*Msrr)j#KFd>Is1J8&!,MT6"-#rHr;HWrLY2M(!J0,*rr^WT -Zl=SrJcDABJ,~> -!$2(=#&Sap[f?B>r(@$+rr3(Z92#3^rr\``92GQe!3,lh!.OnH!G*,IrrAVf9)skKrrR(2B)MZ1 -BM31?rr@9B9)sbGrrW'`5lUc`JG`%?W;ceu:eQK?rr`6n98`]J"8GM^OSo+[h)/sHrr?O+9*WB8 -s5lsIUAk/mp&7SaW;?MpSAY=*"i)ONs8Vlk9*XGVs2[i+_#=98_FmPArr2uGrC[.KrVm%q*5DOR -gAFSD:&b.pX%Q+BrVlnp]);R.Zi*Msrr)j#KFd>Is1J8&!,MT6"-#rHr;HWrLY2M(!J0,*rr^WT -Zl=SrJcDABJ,~> -!$2(=#&Sap[f?B>r(@$+rr3(Z92#3^rr\``92GQe!3,lh!.OnH!G*,IrrAVf9)skKrrR(2B)MZ1 -BM31?rr@9B9)sbGrrW'`5lUc`JG`%?W;ceu:eQK?rr`6n98`]J"8GM^OSo+[h)/sHrr?O+9*WB8 -s5lsIUAk/mp&7SaW;?MpSAY=*"i)ONs8Vlk9*XGVs2[i+_#=98_FmPArr2uGrC[.KrVm%q*5DOR -gAFSD:&b.pX%Q+BrVlnp]);R.Zi*Msrr)j#KFd>Is1J8&!,MT6"-#rHr;HWrLY2M(!J0,*rr^WT -Zl=SrJcDABJ,~> -!$2(="/omHD;5'j*S^Spgd'Wo!O?IprrIq?g]%:[^YAbh1[3cr"/0CAFFjICs.B=A~> -!$2(="/omHD;5'j*S^Spgd'Wo!O?IprrIq?g]%:[^YAbh1[3cr"/0CAFFjICs.B=A~> -!$2(="/omHD;5'j*S^Spgd'Wo!O?IprrIq?g]%:[^YAbh1[3cr"/0CAFFjICs.B=A~> -!$0Vi!KE/qrrW+FUtktOk'abprrUPsbhW4"\q/eprrT!Kon!-os+14Fs*t~> -!$0Vi!KE/qrrW+FUtktOk'abprrUPsbhW4"\q/eprrT!Kon!-os+14Fs*t~> -!$0Vi!KE/qrrW+FUtktOk'abprrUPsbhW4"\q/eprrT!Kon!-os+14Fs*t~> -!$0Vi!O2LWrrN)%g]%<B^>&YghTjmU!RKTVrrKn$JcC<$JcGKEJ,~> -!$0Vi!O2LWrrN)%g]%<B^>&YghTjmU!RKTVrrKn$JcC<$JcGKEJ,~> -!$0Vi!O2LWrrN)%g]%<B^>&YghTjmU!RKTVrrKn$JcC<$JcGKEJ,~> -!$.X1!SDh6rrC7A5QK%#rrJ>#p&>&uU\t,l_>Z\"ec#LKV6GONJcC<$hZ&*~> -!$.X1!SDh6rrC7A5QK%#rrJ>#p&>&uU\t,l_>Z\"ec#LKV6GONJcC<$hZ&*~> -!$.X1!SDh6rrC7A5QK%#rrJ>#p&>&uU\t,l_>Z\"ec#LKV6GONJcC<$hZ&*~> -!Zh<Ir$)>4s8S:^o)Ac,,O4Up!^%].ec,^;8E]sO"TCUbZAJS\"Z/[Js,sDOrs&<E>Q=_N_"[j3 -dV8`9[J'V'\lIP@p@\FeS;d+>rrC+<,66HsrrV_<Y5SA'o\A4na8Q#>mVojjs+13$s53j,~> -!Zh<Ir$)>4s8S:^o)Ac,,O4Up!^%].ec,^;8E]sO"TCUbZAJS\"Z/[Js,sDOrs&<E>Q=_N_"[j3 -dV8`9[J'V'\lIP@p@\FeS;d+>rrC+<,66HsrrV_<Y5SA'o\A4na8Q#>mVojjs+13$s53j,~> -!Zh<Ir$)>4s8S:^o)Ac,,O4Up!^%].ec,^;8E]sO"TCUbZAJS\"Z/[Js,sDOrs&<E>Q=_N_"[j3 -dV8`9[J'V'\lIP@p@\FeS;d+>rrC+<,66HsrrV_<Y5SA'o\A4na8Q#>mVojjs+13$s53j,~> -!Zh=>rV6]S3WK-WF0PQ6rrW)nrp9Xf5Ml4O?/GS],PqE@f1,]<&cNmPVK`(?2WiUik^]N0s6V]9 -rrs_D_.`%J]_DF/b>J:\WV6>m\mk:2!r%S@rr3#S7/co^0_,/B!f!3?qu6[sa8Gr=GH(Ijs+13$ -s5<p-~> -!Zh=>rV6]S3WK-WF0PQ6rrW)nrp9Xf5Ml4O?/GS],PqE@f1,]<&cNmPVK`(?2WiUik^]N0s6V]9 -rrs_D_.`%J]_DF/b>J:\WV6>m\mk:2!r%S@rr3#S7/co^0_,/B!f!3?qu6[sa8Gr=GH(Ijs+13$ -s5<p-~> -!Zh=>rV6]S3WK-WF0PQ6rrW)nrp9Xf5Ml4O?/GS],PqE@f1,]<&cNmPVK`(?2WiUik^]N0s6V]9 -rrs_D_.`%J]_DF/b>J:\WV6>m\mk:2!r%S@rr3#S7/co^0_,/B!f!3?qu6[sa8Gr=GH(Ijs+13$ -s5<p-~> -!$2";!S0d=rrR#CrV$6nilfOArVllVrlY;kr;QfHd/<nK3o^1dHN4$"rlYl+s8V$Is3AgBs8Us! -bPB?;rr2uLrlYT(s8Ufr(X("[rVlj<qu7B09`MVcs8Q9ls2[$bs8UT^-HjTqrr2uBrlY`7s8Pal -s0OVbs8UL?rlY<.rr3,OFoRN7pAY0)@f?<-qpkZF"k`YNs/C)<rrM+mrr3&R:%\Da!F<J;rrH-? -qu6[kd"24Js+14.s*t~> -!$2";!S0d=rrR#CrV$6nilfOArVllVrlY;kr;QfHd/<nK3o^1dHN4$"rlYl+s8V$Is3AgBs8Us! -bPB?;rr2uLrlYT(s8Ufr(X("[rVlj<qu7B09`MVcs8Q9ls2[$bs8UT^-HjTqrr2uBrlY`7s8Pal -s0OVbs8UL?rlY<.rr3,OFoRN7pAY0)@f?<-qpkZF"k`YNs/C)<rrM+mrr3&R:%\Da!F<J;rrH-? -qu6[kd"24Js+14.s*t~> -!$2";!S0d=rrR#CrV$6nilfOArVllVrlY;kr;QfHd/<nK3o^1dHN4$"rlYl+s8V$Is3AgBs8Us! -bPB?;rr2uLrlYT(s8Ufr(X("[rVlj<qu7B09`MVcs8Q9ls2[$bs8UT^-HjTqrr2uBrlY`7s8Pal -s0OVbs8UL?rlY<.rr3,OFoRN7pAY0)@f?<-qpkZF"k`YNs/C)<rrM+mrr3&R:%\Da!F<J;rrH-? -qu6[kd"24Js+14.s*t~> -!$2%<!luR\qu6\6YP.tuSPTp\rr3#PGQ(D>@)`*E!@8NZrrG1?rVloGD>m?GC!H[BQ*41aD:&;e -4]%qNE7=jeFoG2CF4L;C:^KrpQMpg`*UNe4CeG:8:p'ct\P`?&!J]_2rrF"/r_NWSlgOiS\mkX< -!UMN=rrkOCs8T'>q>UNBCZ53k!F<J;rrH-?qu6[kd"24Js+14.s*t~> -!$2%<!luR\qu6\6YP.tuSPTp\rr3#PGQ(D>@)`*E!@8NZrrG1?rVloGD>m?GC!H[BQ*41aD:&;e -4]%qNE7=jeFoG2CF4L;C:^KrpQMpg`*UNe4CeG:8:p'ct\P`?&!J]_2rrF"/r_NWSlgOiS\mkX< -!UMN=rrkOCs8T'>q>UNBCZ53k!F<J;rrH-?qu6[kd"24Js+14.s*t~> -!$2%<!luR\qu6\6YP.tuSPTp\rr3#PGQ(D>@)`*E!@8NZrrG1?rVloGD>m?GC!H[BQ*41aD:&;e -4]%qNE7=jeFoG2CF4L;C:^KrpQMpg`*UNe4CeG:8:p'ct\P`?&!J]_2rrF"/r_NWSlgOiS\mkX< -!UMN=rrkOCs8T'>q>UNBCZ53k!F<J;rrH-?qu6[kd"24Js+14.s*t~> -!$2%<".O.FUAOrj*VB@42Wk#=!JQm>rrLY@rVlnMHN*pI`0)9pTDnikCp<p=&\DKOs$g8gs0HG> ->J^=[s/L,:rrJj?rr2s=qYpO9li."Q0`:qO+T;<>!Nj`DrrEjhrr3"*^@2(&\mkX<$hSPIs8TTP -mJm3cF8Gn<b'_b:rrHE?qu6[sa8>l;:!eIkJcC<$i;\<~> -!$2%<".O.FUAOrj*VB@42Wk#=!JQm>rrLY@rVlnMHN*pI`0)9pTDnikCp<p=&\DKOs$g8gs0HG> ->J^=[s/L,:rrJj?rr2s=qYpO9li."Q0`:qO+T;<>!Nj`DrrEjhrr3"*^@2(&\mkX<$hSPIs8TTP -mJm3cF8Gn<b'_b:rrHE?qu6[sa8>l;:!eIkJcC<$i;\<~> -!$2%<".O.FUAOrj*VB@42Wk#=!JQm>rrLY@rVlnMHN*pI`0)9pTDnikCp<p=&\DKOs$g8gs0HG> ->J^=[s/L,:rrJj?rr2s=qYpO9li."Q0`:qO+T;<>!Nj`DrrEjhrr3"*^@2(&\mkX<$hSPIs8TTP -mJm3cF8Gn<b'_b:rrHE?qu6[sa8>l;:!eIkJcC<$i;\<~> -!$1t:!V[r=rrJ%?o`"qMk5PA]KpVf=!S'a9rrg)o++'CSrrHr?rr3\E@K6?sf)Pd*])Q!NruM-> -ErZ0&rcJ66HN*pE*W#d9*UE_+m4eJ<!1Ee.!5nR2!$2%<!FEM/rrK]?r;QrH:B1>t_uBZ:WH7t: -!mH/@qYpS%^\e$3<QG":!DUpls+13$s5<p-~> -!$1t:!V[r=rrJ%?o`"qMk5PA]KpVf=!S'a9rrg)o++'CSrrHr?rr3\E@K6?sf)Pd*])Q!NruM-> -ErZ0&rcJ66HN*pE*W#d9*UE_+m4eJ<!1Ee.!5nR2!$2%<!FEM/rrK]?r;QrH:B1>t_uBZ:WH7t: -!mH/@qYpS%^\e$3<QG":!DUpls+13$s5<p-~> -!$1t:!V[r=rrJ%?o`"qMk5PA]KpVf=!S'a9rrg)o++'CSrrHr?rr3\E@K6?sf)Pd*])Q!NruM-> -ErZ0&rcJ66HN*pE*W#d9*UE_+m4eJ<!1Ee.!5nR2!$2%<!FEM/rrK]?r;QrH:B1>t_uBZ:WH7t: -!mH/@qYpS%^\e$3<QG":!DUpls+13$s5<p-~> -!$1t:!V[r>rrRqDqt0mh2Wk#=!JQm>[email protected]/lXCp<p="hS4Cs$kT;rs;oGruM->ErV/d -rhfd3HN*pE*W#d9*UE_+m4eG;!3#mp!IDl_rr=)<rrHH?n,EF"@f660mZ3s:MsC<A!NC/<rrU\m -deWnD?,-::!EI2;rrGj@JcC<$JcF[.J,~> -!$1t:!V[r>rrRqDqt0mh2Wk#=!JQm>[email protected]/lXCp<p="hS4Cs$kT;rs;oGruM->ErV/d -rhfd3HN*pE*W#d9*UE_+m4eG;!3#mp!IDl_rr=)<rrHH?n,EF"@f660mZ3s:MsC<A!NC/<rrU\m -deWnD?,-::!EI2;rrGj@JcC<$JcF[.J,~> -!$1t:!V[r>rrRqDqt0mh2Wk#=!JQm>[email protected]/lXCp<p="hS4Cs$kT;rs;oGruM->ErV/d -rhfd3HN*pE*W#d9*UE_+m4eG;!3#mp!IDl_rr=)<rrHH?n,EF"@f660mZ3s:MsC<A!NC/<rrU\m -deWnD?,-::!EI2;rrGj@JcC<$JcF[.J,~> -"!.ESQ2^dapEon>!f3H@oD\hLk5PA]KpVf=!S'a>rrH1pr;QdYir/lXCp<p="hS4Cs$kT;rsi8L -ruM->ErT(\s8U@jHN*pI*WQ/ET`4rl\mt+,#jj>Gs-L=s;uQ^q!H5+8rr=)<rrHH?pAY3*40AJ] -!P2b;rr]NAGGY9<!pbT@rr3&[?J>5T!h#5@qu6[sa8Gr=N19J;rrRp:iIV#[s+146s*t~> -"!.ESQ2^dapEon>!f3H@oD\hLk5PA]KpVf=!S'a>rrH1pr;QdYir/lXCp<p="hS4Cs$kT;rsi8L -ruM->ErT(\s8U@jHN*pI*WQ/ET`4rl\mt+,#jj>Gs-L=s;uQ^q!H5+8rr=)<rrHH?pAY3*40AJ] -!P2b;rr]NAGGY9<!pbT@rr3&[?J>5T!h#5@qu6[sa8Gr=N19J;rrRp:iIV#[s+146s*t~> -"!.ESQ2^dapEon>!f3H@oD\hLk5PA]KpVf=!S'a>rrH1pr;QdYir/lXCp<p="hS4Cs$kT;rsi8L -ruM->ErT(\s8U@jHN*pI*WQ/ET`4rl\mt+,#jj>Gs-L=s;uQ^q!H5+8rr=)<rrHH?pAY3*40AJ] -!P2b;rr]NAGGY9<!pbT@rr3&[?J>5T!h#5@qu6[sa8Gr=N19J;rrRp:iIV#[s+146s*t~> -"!.F7L]/>!-0>1,OHfM3rs4/s"rf])s7("+*W\IhrVlmE(B"153o^,<!Ua.j*X,I.s8PR>r;R72 -_>iTrWcJ.*7ii^IO*^g*"P=b:D".H(!U2E,rs8S9*Zg(.s5bC&*W_5mq#:=7rVln)^@qR.V#ZbY -rrK]?qu6clO,!<)rrJ(@rr3#R#lG_DoD\ajH_UB:!EI2<rrHl?qu6_+!8)l&JcC<$kl6/~> -"!.F7L]/>!-0>1,OHfM3rs4/s"rf])s7("+*W\IhrVlmE(B"153o^,<!Ua.j*X,I.s8PR>r;R72 -_>iTrWcJ.*7ii^IO*^g*"P=b:D".H(!U2E,rs8S9*Zg(.s5bC&*W_5mq#:=7rVln)^@qR.V#ZbY -rrK]?qu6clO,!<)rrJ(@rr3#R#lG_DoD\ajH_UB:!EI2<rrHl?qu6_+!8)l&JcC<$kl6/~> -"!.F7L]/>!-0>1,OHfM3rs4/s"rf])s7("+*W\IhrVlmE(B"153o^,<!Ua.j*X,I.s8PR>r;R72 -_>iTrWcJ.*7ii^IO*^g*"P=b:D".H(!U2E,rs8S9*Zg(.s5bC&*W_5mq#:=7rVln)^@qR.V#ZbY -rrK]?qu6clO,!<)rrJ(@rr3#R#lG_DoD\ajH_UB:!EI2<rrHl?qu6_+!8)l&JcC<$kl6/~> -!Zh=@r;Q]q!<2Qhr;Q]qr;QWos8Mrr!<2lqr;Q]q!<2lq!<2or!ri6"rVcitrr)lrrqucsct2PC -rr2osr;QHj!<2rs!<2Wj!Jcp<rrg.X*?E#qs8W)qrrW1K\,QF)rr2ouUltZU"L]<k*6nH^!L9>S -s8W(Ls+13$s6'E4~> -!Zh=@r;Q]q!<2Qhr;Q]qr;QWos8Mrr!<2lqr;Q]q!<2lq!<2or!ri6"rVcitrr)lrrqucsct2PC -rr2osr;QHj!<2rs!<2Wj!Jcp<rrg.X*?E#qs8W)qrrW1K\,QF)rr2ouUltZU"L]<k*6nH^!L9>S -s8W(Ls+13$s6'E4~> -!Zh=@r;Q]q!<2Qhr;Q]qr;QWos8Mrr!<2lqr;Q]q!<2lq!<2or!ri6"rVcitrr)lrrqucsct2PC -rr2osr;QHj!<2rs!<2Wj!Jcp<rrg.X*?E#qs8W)qrrW1K\,QF)rr2ouUltZU"L]<k*6nH^!L9>S -s8W(Ls+13$s6'E4~> -!$-XjhZ!ZCKWKb)JcC<$W;hA~> -!$-XjhZ!ZCKWKb)JcC<$W;hA~> -!$-XjhZ!ZCKWKb)JcC<$W;hA~> -!$-XjhZ!VoV1JYts+13Js*t~> -!$-XjhZ!VoV1JYts+13Js*t~> -!$-XjhZ!VoV1JYts+13Js*t~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -"!.EGKDtlRpH/DRMZ3VYn3d5LP5bIij\#Q@RfEEb3<0$WGlA]a6N$i_#?;`a8,rVfC&T+R;>l(G -JcC<$JcE=]J,~> -"!.EGKDtlRpH/DRMZ3VYn3d5LP5bIij\#Q@RfEEb3<0$WGlA]a6N$i_#?;`a8,rVfC&T+R;>l(G -JcC<$JcE=]J,~> -"!.EGKDtlRpH/DRMZ3VYn3d5LP5bIij\#Q@RfEEb3<0$WGlA]a6N$i_#?;`a8,rVfC&T+R;>l(G -JcC<$JcE=]J,~> -"!.E>FoMCDpEop4IfB?]mOnO*LB%;6+?0=\NrT.U,6.[sQi@!ceO]]>#=@//1]RJsW;cet`*%Zk -JcC<$JcE=]J,~> -"!.E>FoMCDpEop4IfB?]mOnO*LB%;6+?0=\NrT.U,6.[sQi@!ceO]]>#=@//1]RJsW;cet`*%Zk -JcC<$JcE=]J,~> -"!.E>FoMCDpEop4IfB?]mOnO*LB%;6+?0=\NrT.U,6.[sQi@!ceO]]>#=@//1]RJsW;cet`*%Zk -JcC<$JcE=]J,~> -"!.E>FoMCDpEop4?iIkU[4_KFLB#Xsj#@!uNrT.U,6.[sQi@!ceO]]>#=@//1]RJsJ,[7bPZ`S; -JcC<$JcE=]J,~> -"!.E>FoMCDpEop4?iIkU[4_KFLB#Xsj#@!uNrT.U,6.[sQi@!ceO]]>#=@//1]RJsJ,[7bPZ`S; -JcC<$JcE=]J,~> -"!.E>FoMCDpEop4?iIkU[4_KFLB#Xsj#@!uNrT.U,6.[sQi@!ceO]]>#=@//1]RJsJ,[7bPZ`S; -JcC<$JcE=]J,~> -"!.E>FoMCDpEop4/cJof<%e3:L;e#pju<=#NrT.U,6.[sQi@!neO]`?`bsu(1]RJs4T/F`P_&jc -s+13$s185\~> -"!.E>FoMCDpEop4/cJof<%e3:L;e#pju<=#NrT.U,6.[sQi@!neO]`?`bsu(1]RJs4T/F`P_&jc -s+13$s185\~> -"!.E>FoMCDpEop4/cJof<%e3:L;e#pju<=#NrT.U,6.[sQi@!neO]`?`bsu(1]RJs4T/F`P_&jc -s+13$s185\~> -"!.E>FoMCDN@+[tIfB?]mOnO*7t'7oju<=#NrT.U,6.[sQi@!neO]`?@(lU)1]RJsW.Fu"s+13$ -s0_lW~> -"!.E>FoMCDN@+[tIfB?]mOnO*7t'7oju<=#NrT.U,6.[sQi@!neO]`?@(lU)1]RJsW.Fu"s+13$ -s0_lW~> -"!.E>FoMCDN@+[tIfB?]mOnO*7t'7oju<=#NrT.U,6.[sQi@!neO]`?@(lU)1]RJsW.Fu"s+13$ -s0_lW~> -"!.EqJc9EfN$eRsIfB?]mOnO*:>,[Iju<=#4DS_H%ZgY6I/[miEjG_O-r4Vf'q,*@H2_RZNIh+\ -s+13$s1//[~> -"!.EqJc9EfN$eRsIfB?]mOnO*:>,[Iju<=#4DS_H%ZgY6I/[miEjG_O-r4Vf'q,*@H2_RZNIh+\ -s+13$s1//[~> -"!.EqJc9EfN$eRsIfB?]mOnO*:>,[Iju<=#4DS_H%ZgY6I/[miEjG_O-r4Vf'q,*@H2_RZNIh+\ -s+13$s1//[~> -"!.FAg]"G\n0\1pfDbdQqS3'fgA_*SpVQscrNQKo5QCc2rilU?s8RLcrilTd;#gR>rilI@JcC<$ -JcC<$\c70~> -"!.FAg]"G\n0\1pfDbdQqS3'fgA_*SpVQscrNQKo5QCc2rilU?s8RLcrilTd;#gR>rilI@JcC<$ -JcC<$\c70~> -"!.FAg]"G\n0\1pfDbdQqS3'fgA_*SpVQscrNQKo5QCc2rilU?s8RLcrilTd;#gR>rilI@JcC<$ -JcC<$\c70~> -"!.EOOT,7\pEo5+!Sp!8rrM9Lrr3#lh1>TWs+13$s0DZT~> -"!.EOOT,7\pEo5+!Sp!8rrM9Lrr3#lh1>TWs+13$s0DZT~> -"!.EOOT,7\pEo5+!Sp!8rrM9Lrr3#lh1>TWs+13$s0DZT~> -"!.F:N;agu,jt!u!W;G<s+13$s+13Es*t~> -"!.F:N;agu,jt!u!W;G<s+13$s+13Es*t~> -"!.F:N;agu,jt!u!W;G<s+13$s+13Es*t~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$1k7!Tr3hs+13$s+130s*t~> -!$1k7!Tr3hs+13$s+130s*t~> -!$1k7!Tr3hs+13$s+130s*t~> -!$1k7!M=gls+13$s+130s*t~> -!$1k7!M=gls+13$s+130s*t~> -!$1k7!M=gls+13$s+130s*t~> -!$1k7!M=gls+13$s+130s*t~> -!$1k7!M=gls+13$s+130s*t~> -!$1k7!M=gls+13$s+130s*t~> -"!.FA\c-1DC]FF,IfB?Jon%bpJcC<$JcCo5J,~> -"!.FA\c-1DC]FF,IfB?Jon%bpJcC<$JcCo5J,~> -"!.FA\c-1DC]FF,IfB?Jon%bpJcC<$JcCo5J,~> -"!.EWHiCG[ZXj*.IfKF\:r@kaJcC<$JcCo5J,~> -"!.EWHiCG[ZXj*.IfKF\:r@kaJcC<$JcCo5J,~> -"!.EWHiCG[ZXj*.IfKF\:r@kaJcC<$JcCo5J,~> -"!.E>FoMCHpEop4IX`oYeq*jPs+13$s,m>3~> -"!.E>FoMCHpEop4IX`oYeq*jPs+13$s,m>3~> -"!.E>FoMCHpEop4IX`oYeq*jPs+13$s,m>3~> -"!.E>FoMCGpEop4%[H&MJcC<$JcC<$OT0h~> -"!.E>FoMCGpEop4%[H&MJcC<$JcC<$OT0h~> -"!.E>FoMCGpEop4%[H&MJcC<$JcC<$OT0h~> -"!.E>FoMCHpEop4IXWfXf7EsQs+13$s,m>3~> -"!.E>FoMCHpEop4IXWfXf7EsQs+13$s,m>3~> -"!.E>FoMCHpEop4IXWfXf7EsQs+13$s,m>3~> -"!.EWHiCJ\Zt'-.IfKF[:W.haJcC<$JcCo5J,~> -"!.EWHiCJ\Zt'-.IfKF[:W.haJcC<$JcCo5J,~> -"!.EWHiCJ\Zt'-.IfKF[:W.haJcC<$JcCo5J,~> -"!.FA\Gg"ACB+=QZ2Xb(omhVnJcC<$JcCo5J,~> -"!.FA\Gg"ACB+=QZ2Xb(omhVnJcC<$JcCo5J,~> -"!.FA\Gg"ACB+=QZ2Xb(omhVnJcC<$JcCo5J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$1>(!5\M"!/Q4+JcC<$JcDMFJ,~> -!$1>(!5\M"!/Q4+JcC<$JcDMFJ,~> -!$1>(!5\M"!/Q4+JcC<$JcDMFJ,~> -!$1>(!NTW+fE%aPJcC<$JcC<$U]5i~> -!$1>(!NTW+fE%aPJcC<$JcC<$U]5i~> -!$1>(!NTW+fE%aPJcC<$JcC<$U]5i~> -!$2";!UqE7rrS:OqY'piX)\(;!Phrks+13$s+13Fs*t~> -!$2";!UqE7rrS:OqY'piX)\(;!Phrks+13$s+13Fs*t~> -!$2";!UqE7rrS:OqY'piX)\(;!Phrks+13$s+13Fs*t~> -!$2%<!o?]]rVlqMU\FN_!NU5<rrKo?JcC<$JcC<$U]5i~> -!$2%<!o?]]rVlqMU\FN_!NU5<rrKo?JcC<$JcC<$U]5i~> -!$2%<!o?]]rVlqMU\FN_!NU5<rrKo?JcC<$JcC<$U]5i~> -!$2(="4M)A*W5p=I\Q`7rrK0?r;Qf5>_2p+s+13$s.fUE~> -!$2(="4M)A*W5p=I\Q`7rrK0?r;Qf5>_2p+s+13$s.fUE~> -!$2(="4M)A*W5p=I\Q`7rrK0?r;Qf5>_2p+s+13$s.fUE~> -#9EjEc[=+>*W,j;JsuK7!NU5<rrKo?JcC<$JcC<$U]5i~> -#9EjEc[=+>*W,j;JsuK7!NU5<rrKo?JcC<$JcC<$U]5i~> -#9EjEc[=+>*W,j;JsuK7!NU5<rrKo?JcC<$JcC<$U]5i~> -#9EilJ'@rm*W#d9*VfX8X)\(;!Phrks+13$s+13Fs*t~> -#9EilJ'@rm*W#d9*VfX8X)\(;!Phrks+13$s+13Fs*t~> -#9EilJ'@rm*W#d9*VfX8X)\(;!Phrks+13$s+13Fs*t~> -"!.E>.fNZR$Zu=H!Ht@8rrK0?r;Qf5>_2p+s+13$s.fUE~> -"!.E>.fNZR$Zu=H!Ht@8rrK0?r;Qf5>_2p+s+13$s.fUE~> -"!.E>.fNZR$Zu=H!Ht@8rrK0?r;Qf5>_2p+s+13$s.fUE~> -!Zh=*rP/FLao25@FK>?7rrK0?r;Qf5>_2p+s+13$s.fUE~> -!Zh=*rP/FLao25@FK>?7rrK0?r;Qf5>_2p+s+13$s.fUE~> -!Zh=*rP/FLao25@FK>?7rrK0?r;Qf5>_2p+s+13$s.fUE~> -!$1t:!$2%<!dUd@p\t8pEW#h;^g)HjJcC<$JcDMFJ,~> -!$1t:!$2%<!dUd@p\t8pEW#h;^g)HjJcC<$JcDMFJ,~> -!$1t:!$2%<!dUd@p\t8pEW#h;^g)HjJcC<$JcDMFJ,~> -!$1t:!&FQR!g'2VpAY/oEW#h;^g)HjJcC<$JcDMFJ,~> -!$1t:!&FQR!g'2VpAY/oEW#h;^g)HjJcC<$JcDMFJ,~> -!$1t:!&FQR!g'2VpAY/oEW#h;^g)HjJcC<$JcDMFJ,~> -!$1>(!NU5<rrKo?JcC<$JcC<$U]5i~> -!$1>(!NU5<rrKo?JcC<$JcC<$U]5i~> -!$1>(!NU5<rrKo?JcC<$JcC<$U]5i~> -!$1>(!NSrmXT=#YJcC<$JcC<$U]5i~> -!$1>(!NSrmXT=#YJcC<$JcC<$U]5i~> -!$1>(!NSrmXT=#YJcC<$JcC<$U]5i~> -!$1>(!71L[!2G,FJcC<$JcDMFJ,~> -!$1>(!71L[!2G,FJcC<$JcDMFJ,~> -!$1>(!71L[!2G,FJcC<$JcDMFJ,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -!$-XjJcC<$JcC?%J,~> -%%EndData -showpage -%%Trailer -end -%%EOF diff --git a/lib/stdlib/doc/src/ushell2.gif b/lib/stdlib/doc/src/ushell2.gif Binary files differdeleted file mode 100644 index 273cf2078a..0000000000 --- a/lib/stdlib/doc/src/ushell2.gif +++ /dev/null diff --git a/lib/stdlib/doc/src/ushell2.ps b/lib/stdlib/doc/src/ushell2.ps deleted file mode 100644 index e6db3c2be2..0000000000 --- a/lib/stdlib/doc/src/ushell2.ps +++ /dev/null @@ -1,404 +0,0 @@ -%!PS-Adobe-3.0 -%%Creator: GIMP PostScript file plugin V 1.17 by Peter Kirchgessner -%%Title: ushell2.ps -%%CreationDate: Mon Mar 16 09:52:14 2009 -%%DocumentData: Clean7Bit -%%LanguageLevel: 2 -%%Pages: 1 -%%BoundingBox: 14 14 468 74 -%%EndComments -%%BeginProlog -% Use own dictionary to avoid conflicts -10 dict begin -%%EndProlog -%%Page: 1 1 -% Translate for offset -14.173228346456694 14.173228346456694 translate -% Translate to begin of first scanline -0 59.527559055118118 translate -453.54330708661422 -59.527559055118118 scale -% Image geometry -640 84 8 -% Transformation matrix -[ 640 0 0 84 0 0 ] -% Strings to hold RGB-samples per scanline -/rstr 640 string def -/gstr 640 string def -/bstr 640 string def -{currentfile /ASCII85Decode filter /RunLengthDecode filter rstr readstring pop} -{currentfile /ASCII85Decode filter /RunLengthDecode filter gstr readstring pop} -{currentfile /ASCII85Decode filter /RunLengthDecode filter bstr readstring pop} -true 3 -%%BeginData: 18704 ASCII Bytes -colorimage -J`MCCJ`MCCJ`M=~> -J`MCCJ`MCCJ`M=~> -J`MCCJ`MCCJ`M=~> -!)nG7JO+iQJO+lRJ,~> -!)nG7JO+iQJO+lRJ,~> -!)nG7JO+iQJO+lRJ,~> -!D=/Y=b0_,=b0_.=b$~> -!D=/Y=b0_,=b0_.=b$~> -!D=/Y=b0_,=b0_.=b$~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M>rrKOJQ2^i3JcC<$JcFU,J,~> -!D>M>rrKOJQ2^i3JcC<$JcFU,J,~> -!D>M>rrKOJQ2^i3JcC<$JcFU,J,~> -"%t`UXo(ooJ,'$ES](+!!dROKr;Qh<:2'>#!I!f.rr]@2s).a0!581-!+,Ru!6ss3!kNp@p\t9X -H-uWnOA=s3rrK.0nG`Jtr;QbGr_<HIrVlo/@tFZ2s+14-s*t~> -"%t`UXo(ooJ,'$ES](+!!dROKr;Qh<:2'>#!I!f.rr]@2s).a0!581-!+,Ru!6ss3!kNp@p\t9X -H-uWnOA=s3rrK.0nG`Jtr;QbGr_<HIrVlo/@tFZ2s+14-s*t~> -"%t`UXo(ooJ,'$ES](+!!dROKr;Qh<:2'>#!I!f.rr]@2s).a0!581-!+,Ru!6ss3!kNp@p\t9X -H-uWnOA=s3rrK.0nG`Jtr;QbGr_<HIrVlo/@tFZ2s+14-s*t~> -"A:iVM0T!F!8RAL!HP42rrUp#*W5p=fZ5E4rrG1@rr3+VQ2`JQrQbK2q#:?CrQbLB\*j7sS:L>5 -!T-**rrJOjli.%FchRG<!HlihrrIe?nc&Yn]MJP,!J%!FcN0Vnrr3#u++aHCs+14-s*t~> -"A:iVM0T!F!8RAL!HP42rrUp#*W5p=fZ5E4rrG1@rr3+VQ2`JQrQbK2q#:?CrQbLB\*j7sS:L>5 -!T-**rrJOjli.%FchRG<!HlihrrIe?nc&Yn]MJP,!J%!FcN0Vnrr3#u++aHCs+14-s*t~> -"A:iVM0T!F!8RAL!HP42rrUp#*W5p=fZ5E4rrG1@rr3+VQ2`JQrQbK2q#:?CrQbLB\*j7sS:L>5 -!T-**rrJOjli.%FchRG<!HlihrrIe?nc&Yn]MJP,!J%!FcN0Vnrr3#u++aHCs+14-s*t~> -"A:iVM3Rl:!;QQc#kn;uEiSm+o_8@b!;HKb!;HEk!$;%;!V[r6rs;$Hs8VtORf>#.rq$3eoD\lN -QMU(M!l&CArVllrrU^6ks5-$;rq$<ks8W#qoFLs$rV6Ego^r._r:GB$o^qnX!W2]krs&2ss8)B[ -rVlg+qXdY#o_/=bKUDN+o_/%Z$2J#IrQSC<s'rY>rrMrfrVloH97d+os+14.s*t~> -"A:iVM3Rl:!;QQc#kn;uEiSm+o_8@b!;HKb!;HEk!$;%;!V[r6rs;$Hs8VtORf>#.rq$3eoD\lN -QMU(M!l&CArVllrrU^6ks5-$;rq$<ks8W#qoFLs$rV6Ego^r._r:GB$o^qnX!W2]krs&2ss8)B[ -rVlg+qXdY#o_/=bKUDN+o_/%Z$2J#IrQSC<s'rY>rrMrfrVloH97d+os+14.s*t~> -"A:iVM3Rl:!;QQc#kn;uEiSm+o_8@b!;HKb!;HEk!$;%;!V[r6rs;$Hs8VtORf>#.rq$3eoD\lN -QMU(M!l&CArVllrrU^6ks5-$;rq$<ks8W#qoFLs$rV6Ego^r._r:GB$o^qnX!W2]krs&2ss8)B[ -rVlg+qXdY#o_/=bKUDN+o_/%Z$2J#IrQSC<s'rY>rrMrfrVloH97d+os+14.s*t~> -#>7/YM1+"-g&D!PlY?DI$r#a^Efa$E-rf=.k?@j5!F+acrr=,;rrMj@o`#1<s8Sp?s8O^er[7f! -nFce_n:I\.rrK]@r;QcHr?qfQqqj5tr[7lYrV35f-kO2nd:1^L-n*1:a!_W=-n+farrK!?rr35q -.KBF2-jn]-rsk_N%3R&fs8Rb&=stdhj7rWTKtI?a"NGcfA%MI8!T6+ls+13$s5<p-~> -#>7/YM1+"-g&D!PlY?DI$r#a^Efa$E-rf=.k?@j5!F+acrr=,;rrMj@o`#1<s8Sp?s8O^er[7f! -nFce_n:I\.rrK]@r;QcHr?qfQqqj5tr[7lYrV35f-kO2nd:1^L-n*1:a!_W=-n+farrK!?rr35q -.KBF2-jn]-rsk_N%3R&fs8Rb&=stdhj7rWTKtI?a"NGcfA%MI8!T6+ls+13$s5<p-~> -#>7/YM1+"-g&D!PlY?DI$r#a^Efa$E-rf=.k?@j5!F+acrr=,;rrMj@o`#1<s8Sp?s8O^er[7f! -nFce_n:I\.rrK]@r;QcHr?qfQqqj5tr[7lYrV35f-kO2nd:1^L-n*1:a!_W=-n+farrK!?rr35q -.KBF2-jn]-rsk_N%3R&fs8Rb&=stdhj7rWTKtI?a"NGcfA%MI8!T6+ls+13$s5<p-~> -#>7/YM'th_:B(7oI@pN=%,$43E\H&Es1hq?B=@g>!OQP=rr=,;rrMj@o`#1<s8Sp?s8Qb.rr3"H -U%SEdTmZ8-!P2e8rrb=Bh[t\DrrXkBdn0N<#U90GWZSDDruV1>!J6g6rs#?Ds3C3-.K08I6JDA; -!EI5>rs"-+b5_Li9CVrcA%M^:\[g>jrrM%@JcC<$JcF[.J,~> -#>7/YM'th_:B(7oI@pN=%,$43E\H&Es1hq?B=@g>!OQP=rr=,;rrMj@o`#1<s8Sp?s8Qb.rr3"H -U%SEdTmZ8-!P2e8rrb=Bh[t\DrrXkBdn0N<#U90GWZSDDruV1>!J6g6rs#?Ds3C3-.K08I6JDA; -!EI5>rs"-+b5_Li9CVrcA%M^:\[g>jrrM%@JcC<$JcF[.J,~> -#>7/YM'th_:B(7oI@pN=%,$43E\H&Es1hq?B=@g>!OQP=rr=,;rrMj@o`#1<s8Sp?s8Qb.rr3"H -U%SEdTmZ8-!P2e8rrb=Bh[t\DrrXkBdn0N<#U90GWZSDDruV1>!J6g6rs#?Ds3C3-.K08I6JDA; -!EI5>rs"-+b5_Li9CVrcA%M^:\[g>jrrM%@JcC<$JcF[.J,~> -"A:iVM3Ro;!O.@YS-6(rs)P.=rrg,Cs(?9LS,mM@rVlj=qu6]k-M7<@Ff=JZXSVqtI%g96!p59A -mJd3uA,Q?,li!=U,37WFrVlsOnC'u-rraPCs/L,=rr@3@rrI_@p&>5nG5k:_oI9b=!CGN<rrH-@ -rVlnOR/[*ddS'*0#%P7Eo4(4*rVloV4b<Was+14.s*t~> -"A:iVM3Ro;!O.@YS-6(rs)P.=rrg,Cs(?9LS,mM@rVlj=qu6]k-M7<@Ff=JZXSVqtI%g96!p59A -mJd3uA,Q?,li!=U,37WFrVlsOnC'u-rraPCs/L,=rr@3@rrI_@p&>5nG5k:_oI9b=!CGN<rrH-@ -rVlnOR/[*ddS'*0#%P7Eo4(4*rVloV4b<Was+14.s*t~> -"A:iVM3Ro;!O.@YS-6(rs)P.=rrg,Cs(?9LS,mM@rVlj=qu6]k-M7<@Ff=JZXSVqtI%g96!p59A -mJd3uA,Q?,li!=U,37WFrVlsOnC'u-rraPCs/L,=rr@3@rrI_@p&>5nG5k:_oI9b=!CGN<rrH-@ -rVlnOR/[*ddS'*0#%P7Eo4(4*rVloV4b<Was+14.s*t~> -"A:iVM3Rl:!3lHR"G!EMEiT-="Me=CB3bCd!4;_)!$;%;!V[r5rr`6B_HQd8!IUU7rrKi?m/I*t -A,ZE.oRHgj"!$CZ55kK`/b%4\rVm!Equ<[:qYpSJS+ZdcVKVu6ch&[brrGI?r;QdtaSl,>KUDc= -!RaX1rrHW@rr3#'D#OA7i&uYkJcC<$i;\<~> -"A:iVM3Rl:!3lHR"G!EMEiT-="Me=CB3bCd!4;_)!$;%;!V[r5rr`6B_HQd8!IUU7rrKi?m/I*t -A,ZE.oRHgj"!$CZ55kK`/b%4\rVm!Equ<[:qYpSJS+ZdcVKVu6ch&[brrGI?r;QdtaSl,>KUDc= -!RaX1rrHW@rr3#'D#OA7i&uYkJcC<$i;\<~> -"A:iVM3Rl:!3lHR"G!EMEiT-="Me=CB3bCd!4;_)!$;%;!V[r5rr`6B_HQd8!IUU7rrKi?m/I*t -A,ZE.oRHgj"!$CZ55kK`/b%4\rVm!Equ<[:qYpSJS+ZdcVKVu6ch&[brrGI?r;QdtaSl,>KUDc= -!RaX1rrHW@rr3#'D#OA7i&uYkJcC<$i;\<~> -"A:iVM3Ro;!O'H@rrgMCs)P.=rrg,Cs(Ae8rr=,;rrMj@o`#$m+2V4\rrITArr3"HU&P&nhI3>\ -rrVG(_X.:(jbC#[email protected]($+6gRf<<h/b%4\rVm!Equ<[:qYp\MS,`M0q#:PqG,("4kUHK1 -!CGN<rs)QFs6>F?KUDc=!RaX1rrHW@rr3#'D#XG9rb/]js+13$s5<p-~> -"A:iVM3Ro;!O'H@rrgMCs)P.=rrg,Cs(Ae8rr=,;rrMj@o`#$m+2V4\rrITArr3"HU&P&nhI3>\ -rrVG(_X.:(jbC#[email protected]($+6gRf<<h/b%4\rVm!Equ<[:qYp\MS,`M0q#:PqG,("4kUHK1 -!CGN<rs)QFs6>F?KUDc=!RaX1rrHW@rr3#'D#XG9rb/]js+13$s5<p-~> -"A:iVM3Ro;!O'H@rrgMCs)P.=rrg,Cs(Ae8rr=,;rrMj@o`#$m+2V4\rrITArr3"HU&P&nhI3>\ -rrVG(_X.:(jbC#[email protected]($+6gRf<<h/b%4\rVm!Equ<[:qYp\MS,`M0q#:PqG,("4kUHK1 -!CGN<rs)QFs6>F?KUDc=!RaX1rrHW@rr3#'D#XG9rb/]js+13$s5<p-~> -"A:iVM'r6h"*ae$E;i3->g`RlWrE#$^g6ulB)Y-tHN*pIEC1"!K)YcQBL)tmMtR)OX^KZXrrL26 -r^-^;k5PA^aT->ZrrLn@lMgmTJH#QLq5"!W"d:Fsh_(&j6Na7`oU5YF"K_V&WcIt9"Q"/d6bE-n% -HrJ%lcE#Es8S]Y&NNhhrs-tX6W;80KUDc=!RaX1rrL\]r^-^"f`(mOrZ?^kJcC<$huA3~> -"A:iVM'r6h"*ae$E;i3->g`RlWrE#$^g6ulB)Y-tHN*pIEC1"!K)YcQBL)tmMtR)OX^KZXrrL26 -r^-^;k5PA^aT->ZrrLn@lMgmTJH#QLq5"!W"d:Fsh_(&j6Na7`oU5YF"K_V&WcIt9"Q"/d6bE-n% -HrJ%lcE#Es8S]Y&NNhhrs-tX6W;80KUDc=!RaX1rrL\]r^-^"f`(mOrZ?^kJcC<$huA3~> -"A:iVM'r6h"*ae$E;i3->g`RlWrE#$^g6ulB)Y-tHN*pIEC1"!K)YcQBL)tmMtR)OX^KZXrrL26 -r^-^;k5PA^aT->ZrrLn@lMgmTJH#QLq5"!W"d:Fsh_(&j6Na7`oU5YF"K_V&WcIt9"Q"/d6bE-n% -HrJ%lcE#Es8S]Y&NNhhrs-tX6W;80KUDc=!RaX1rrL\]r^-^"f`(mOrZ?^kJcC<$huA3~> -"%t`Umek`?jT#8Drn.G5s8VBUrr3,pkPtSCrn.;4rr2uYrn.;6rr2uWrn.;8p&>'hir&fVh#>t, -mJ[%dpY"j1rrMuVlMgqTJ#rYL!;QQH"nL[MqW%/Gf`V$Ls7H9C"T&/uoBQ/O"6eFkrV-<pmdL2U -hZ!NTm/GZ<h>I9Win<2gs6]=TrrMoUn,ECKrn.;5rVlm_hLY]Xs+14-s*t~> -"%t`Umek`?jT#8Drn.G5s8VBUrr3,pkPtSCrn.;4rr2uYrn.;6rr2uWrn.;8p&>'hir&fVh#>t, -mJ[%dpY"j1rrMuVlMgqTJ#rYL!;QQH"nL[MqW%/Gf`V$Ls7H9C"T&/uoBQ/O"6eFkrV-<pmdL2U -hZ!NTm/GZ<h>I9Win<2gs6]=TrrMoUn,ECKrn.;5rVlm_hLY]Xs+14-s*t~> -"%t`Umek`?jT#8Drn.G5s8VBUrr3,pkPtSCrn.;4rr2uYrn.;6rr2uWrn.;8p&>'hir&fVh#>t, -mJ[%dpY"j1rrMuVlMgqTJ#rYL!;QQH"nL[MqW%/Gf`V$Ls7H9C"T&/uoBQ/O"6eFkrV-<pmdL2U -hZ!NTm/GZ<h>I9Win<2gs6]=TrrMoUn,ECKrn.;5rVlm_hLY]Xs+14-s*t~> -!D>M>rrN#pQ2^jZJcC<$JcFU,J,~> -!D>M>rrN#pQ2^jZJcC<$JcFU,J,~> -!D>M>rrN#pQ2^jZJcC<$JcFU,J,~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>NQrrK"krVlo0ipm$KT)JZh\GVHh_h%i=s+13$s/Z0M~> -!D>NQrrK"krVlo0ipm$KT)JZh\GVHh_h%i=s+13$s/Z0M~> -!D>NQrrK"krVlo0ipm$KT)JZh\GVHh_h%i=s+13$s/Z0M~> -!D>NRrrSc-mJ[%d[sIB4rsbK>%<J'>s0[duMN!M0JcC<$JcC<$X8d\~> -!D>NRrrSc-mJ[%d[sIB4rsbK>%<J'>s0[duMN!M0JcC<$JcC<$X8d\~> -!D>NRrrSc-mJ[%d[sIB4rsbK>%<J'>s0[duMN!M0JcC<$JcC<$X8d\~> -#>7/Ys.,5omJQtc^LI'5rsP9XW>)=oS,`M<TDjEAJcC<$JcD\KJ,~> -#>7/Ys.,5omJQtc^LI'5rsP9XW>)=oS,`M<TDjEAJcC<$JcD\KJ,~> -#>7/Ys.,5omJQtc^LI'5rsP9XW>)=oS,`M<TDjEAJcC<$JcD\KJ,~> -#>7/YUPnOomJHnacVF36$>6gI*rkZbs8P:?JcC<$JcC<$VuM8~> -#>7/YUPnOomJHnacVF36$>6gI*rkZbs8P:?JcC<$JcC<$VuM8~> -#>7/YUPnOomJHnacVF36$>6gI*rkZbs8P:?JcC<$JcC<$VuM8~> -#>7/YoCW&:mJ?h`dn0<6"RfFC*W>s:"6h]b:P&Oss+13$s/H$K~> -#>7/YoCW&:mJ?h`dn0<6"RfFC*W>s:"6h]b:P&Oss+13$s/H$K~> -#>7/YoCW&:mJ?h`dn0<6"RfFC*W>s:"6h]b:P&Oss+13$s/H$K~> -!D>NQrrFh@qYpTB:A+Vm7Kc'As8V@[j+75]s+13$s/5mI~> -!D>NQrrFh@qYpTB:A+Vm7Kc'As8V@[j+75]s+13$s/5mI~> -!D>NQrrFh@qYpTB:A+Vm7Kc'As8V@[j+75]s+13$s/5mI~> -!D>NQrrFh@qu6]>;Y0nm*o1A]s'3Bks+13$s+13Is*t~> -!D>NQrrFh@qu6]>;Y0nm*o1A]s'3Bks+13$s+13Is*t~> -!D>NQrrFh@qu6]>;Y0nm*o1A]s'3Bks+13$s+13Is*t~> -!D>NQrrFh@r;Qi1B);6$$-D</*riT\s'3D9rrW+o]Rg*6s+13$s0;TS~> -!D>NQrrFh@r;Qi1B);6$$-D</*riT\s'3D9rrW+o]Rg*6s+13$s0;TS~> -!D>NQrrFh@r;Qi1B);6$$-D</*riT\s'3D9rrW+o]Rg*6s+13$s0;TS~> -%SJn`a+f<dI>4^#s0R1?p&>?%JqahkK!>9SKDpT*YPnJ&pAdU4s+13$s+13Ts*t~> -%SJn`a+f<dI>4^#s0R1?p&>?%JqahkK!>9SKDpT*YPnJ&pAdU4s+13$s+13Ts*t~> -%SJn`a+f<dI>4^#s0R1?p&>?%JqahkK!>9SKDpT*YPnJ&pAdU4s+13$s+13Ts*t~> -"%t`UcMWt2ZiC'>jR`BS[$D;i[Jp1+Yl9phLTURU!rS@iJcC<$JcC<$Z2]=~> -"%t`UcMWt2ZiC'>jR`BS[$D;i[Jp1+Yl9phLTURU!rS@iJcC<$JcC<$Z2]=~> -"%t`UcMWt2ZiC'>jR`BS[$D;i[Jp1+Yl9phLTURU!rS@iJcC<$JcC<$Z2]=~> -!D>N9rrBb-rrK*@JcC<$JcC<$X8d\~> -!D>N9rrBb-rrK*@JcC<$JcC<$X8d\~> -!D>N9rrBb-rrK*@JcC<$JcC<$X8d\~> -!D>N1rr_L<A`eRDJcC<$JcDeNJ,~> -!D>N1rr_L<A`eRDJcC<$JcDeNJ,~> -!D>N1rr_L<A`eRDJcC<$JcDeNJ,~> -!D>N1rrW/foR[$ns+13$s/Q*L~> -!D>N1rrW/foR[$ns+13$s/Q*L~> -!D>N1rrW/foR[$ns+13$s/Q*L~> -"A:iVs5s=1"5EkUl29$2ir8rZh:1/0s+13$s+13<s*t~> -"A:iVs5s=1"5EkUl29$2ir8rZh:1/0s+13$s+13<s*t~> -"A:iVs5s=1"5EkUl29$2ir8rZh:1/0s+13$s+13<s*t~> -"A:iVh08ih"Bs"KI4bCg#D<'VcX9:FaasJCs+13$s-it<~> -"A:iVh08ih"Bs"KI4bCg#D<'VcX9:FaasJCs+13$s-it<~> -"A:iVh08ih"Bs"KI4bCg#D<'VcX9:FaasJCs+13$s-it<~> -"A:iVM3S#>"P-'BI@pE:#01rEs6Fa?JcC<$JcC<$S,\!~> -"A:iVM3S#>"P-'BI@pE:#01rEs6Fa?JcC<$JcC<$S,\!~> -"A:iVM3S#>"P-'BI@pE:#01rEs6Fa?JcC<$JcC<$S,\!~> -"A:iVM3S#>&_9GOI@m*XH^=^3]7/f?mX;?ks+13$s+13>s*t~> -"A:iVM3S#>&_9GOI@m*XH^=^3]7/f?mX;?ks+13$s+13>s*t~> -"A:iVM3S#>&_9GOI@m*XH^=^3]7/f?mX;?ks+13$s+13>s*t~> -(eZsjM3S&?peOBZI63OaTp(Z>s1iGWB=NNmJcC<$JcD2=J,~> -(eZsjM3S&?peOBZI63OaTp(Z>s1iGWB=NNmJcC<$JcD2=J,~> -(eZsjM3S&?peOBZI63OaTp(Z>s1iGWB=NNmJcC<$JcD2=J,~> -(eZsjiH7CN7\E6NhS8LYs3"=?s+$lZY&JslJcC<$JcD2=J,~> -(eZsjiH7CN7\E6NhS8LYs3"=?s+$lZY&JslJcC<$JcD2=J,~> -(eZsjiH7CN7\E6NhS8LYs3"=?s+$lZY&JslJcC<$JcD2=J,~> -#tmA[s6JIqhUY0nrs?kHs+R*>s8&m>JcC<$JcC<$S,\!~> -#tmA[s6JIqhUY0nrs?kHs+R*>s8&m>JcC<$JcC<$S,\!~> -#tmA[s6JIqhUY0nrs?kHs+R*>s8&m>JcC<$JcC<$S,\!~> -!D>NPrrrDA=TA!drr3;J;ZD6@qZ$K"Ck;V;s+13$s-s%=~> -!D>NPrrrDA=TA!drr3;J;ZD6@qZ$K"Ck;V;s+13$s-s%=~> -!D>NPrrrDA=TA!drr3;J;ZD6@qZ$K"Ck;V;s+13$s-s%=~> -$qi\^s5;#@_cHg;R?IQk#ci.Ks*1Qc[V16lJcC<$JcD2=J,~> -$qi\^s5;#@_cHg;R?IQk#ci.Ks*1Qc[V16lJcC<$JcD2=J,~> -$qi\^s5;#@_cHg;R?IQk#ci.Ks*1Qc[V16lJcC<$JcD2=J,~> -#>7/Ys-lqc>Q+R%Pl=S]G5_FBGZ/@.s+13$s+13<s*t~> -#>7/Ys-lqc>Q+R%Pl=S]G5_FBGZ/@.s+13$s+13<s*t~> -#>7/Ys-lqc>Q+R%Pl=S]G5_FBGZ/@.s+13$s+13<s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -"A:iVrHeGa#!r.ds)PpSp&>3n>ok%TqqqDSq^h^f!K[21s+13$s+13ns*t~> -"A:iVrHeGa#!r.ds)PpSp&>3n>ok%TqqqDSq^h^f!K[21s+13$s+13ns*t~> -"A:iVrHeGa#!r.ds)PpSp&>3n>ok%TqqqDSq^h^f!K[21s+13$s+13ns*t~> -"A:iVM3S#>!S0a>rrQHBrq??qB=@j?dS&Kt!DCl?rrJ._JcC<$JcC<$bQ!(~> -"A:iVM3S#>!S0a>rrQHBrq??qB=@j?dS&Kt!DCl?rrJ._JcC<$JcC<$bQ!(~> -"A:iVM3S#>!S0a>rrQHBrq??qB=@j?dS&Kt!DCl?rrJ._JcC<$JcC<$bQ!(~> -#tmA[Vm$.#r2Oo<rrHB@pAYG3[f?BU9E5%Cn,E=fl.l:<!64s:$./AAbQ$Y^s8U+<^B!*hrr<u: -^B!3krrBk6^B!;Fs+13$s+13us*t~> -#tmA[Vm$.#r2Oo<rrHB@pAYG3[f?BU9E5%Cn,E=fl.l:<!64s:$./AAbQ$Y^s8U+<^B!*hrr<u: -^B!3krrBk6^B!;Fs+13$s+13us*t~> -#tmA[Vm$.#r2Oo<rrHB@pAYG3[f?BU9E5%Cn,E=fl.l:<!64s:$./AAbQ$Y^s8U+<^B!*hrr<u: -^B!3krrBk6^B!;Fs+13$s+13us*t~> -!D>NPrrJs@qu6\1[.jS,B60c?KhMIG>f$F>!NC2?rr=,<rs;-HlS8F'MZ:+rra#_Uf`/6dra#_X -h#FNara#VXi.:oZs+13$s3q!u~> -!D>NPrrJs@qu6\1[.jS,B60c?KhMIG>f$F>!NC2?rr=,<rs;-HlS8F'MZ:+rra#_Uf`/6dra#_X -h#FNara#VXi.:oZs+13$s3q!u~> -!D>NPrrJs@qu6\1[.jS,B60c?KhMIG>f$F>!NC2?rr=,<rs;-HlS8F'MZ:+rra#_Uf`/6dra#_X -h#FNara#VXi.:oZs+13$s3q!u~> -!D>NQrrJU@qYpT[2#%"[B39M-AkW1(X+Kg?jFOf>rr=,<rs;-HlS8F'MZ5`trr3+VQ2`K)rr3+K -U&QA5rr3#-e:IXNs+13$s3q!u~> -!D>NQrrJU@qYpT[2#%"[B39M-AkW1(X+Kg?jFOf>rr=,<rs;-HlS8F'MZ5`trr3+VQ2`K)rr3+K -U&QA5rr3#-e:IXNs+13$s3q!u~> -!D>NQrrJU@qYpT[2#%"[B39M-AkW1(X+Kg?jFOf>rr=,<rs;-HlS8F'MZ5`trr3+VQ2`K)rr3+K -U&QA5rr3#-e:IXNs+13$s3q!u~> -!D>NRrrSFGq"k!kDm&j7"_Y:Ds3aR>rrbOCs2S1=rr=,<rs;-HlS8F'MZ5`trr3+VQ2`K)rr34N -U&V$'AnJ&os+13$s+13ts*t~> -!D>NRrrSFGq"k!kDm&j7"_Y:Ds3aR>rrbOCs2S1=rr=,<rs;-HlS8F'MZ5`trr3+VQ2`K)rr34N -U&V$'AnJ&os+13$s+13ts*t~> -!D>NRrrSFGq"k!kDm&j7"_Y:Ds3aR>rrbOCs2S1=rr=,<rs;-HlS8F'MZ5`trr3+VQ2`K)rr34N -U&V$'AnJ&os+13$s+13ts*t~> -#"q&Xs-8l>qYpS+](Z.-B=@j?dS'T>"NXX/@F+oP!$;(<#t<M41&mGps#T3>rre+Bs"<a=rs*qF -s'i@E\(?32JcC<$JcF-tJ,~> -#"q&Xs-8l>qYpS+](Z.-B=@j?dS'T>"NXX/@F+oP!$;(<#t<M41&mGps#T3>rre+Bs"<a=rs*qF -s'i@E\(?32JcC<$JcF-tJ,~> -#"q&Xs-8l>qYpS+](Z.-B=@j?dS'T>"NXX/@F+oP!$;(<#t<M41&mGps#T3>rre+Bs"<a=rs*qF -s'i@E\(?32JcC<$JcF-tJ,~> -"\UrWSW34:rrQZBrq??qB=@j?dS'Q=![-G]r;R9Ks2TNes$bT+1&mGps#T3>rre+Bs"<a=rrd_C -s!.@=rrItfrr3&A/!>J`JcC<$JcFF'J,~> -"\UrWSW34:rrQZBrq??qB=@j?dS'Q=![-G]r;R9Ks2TNes$bT+1&mGps#T3>rre+Bs"<a=rrd_C -s!.@=rrItfrr3&A/!>J`JcC<$JcFF'J,~> -"\UrWSW34:rrQZBrq??qB=@j?dS'Q=![-G]r;R9Ks2TNes$bT+1&mGps#T3>rre+Bs"<a=rrd_C -s!.@=rrItfrr3&A/!>J`JcC<$JcFF'J,~> -"A:iVO;Rp;"^M*-EkD;Crrr.#*Zd]BrVlrj2YI"J&*t?<p](9d4rX\IGkqC42?"X"Jbf?</H-[n -MYdAE,5rVaPl(I[!l>M%JcC<$JcC<$g&HR~> -"A:iVO;Rp;"^M*-EkD;Crrr.#*Zd]BrVlrj2YI"J&*t?<p](9d4rX\IGkqC42?"X"Jbf?</H-[n -MYdAE,5rVaPl(I[!l>M%JcC<$JcC<$g&HR~> -"A:iVO;Rp;"^M*-EkD;Crrr.#*Zd]BrVlrj2YI"J&*t?<p](9d4rX\IGkqC42?"X"Jbf?</H-[n -MYdAE,5rVaPl(I[!l>M%JcC<$JcC<$g&HR~> -!D>N"rrMF?JcC<$JcC<$\Gq'~> -!D>N"rrMF?JcC<$JcC<$\Gq'~> -!D>N"rrMF?JcC<$JcC<$\Gq'~> -!D>N"rrMF?JcC<$JcC<$\Gq'~> -!D>N"rrMF?JcC<$JcC<$\Gq'~> -!D>N"rrMF?JcC<$JcC<$\Gq'~> -!D>N"rrM_GJcC<$JcC<$\Gq'~> -!D>N"rrM_GJcC<$JcC<$\Gq'~> -!D>N"rrM_GJcC<$JcC<$\Gq'~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>NQrrIH;oD\f.li.!"FSu.?F^'4jrrR%AK'!"7oNPOlmf*=XI"D<Ks+13$s7QDB~> -!D>NQrrIH;oD\f.li.!"FSu.?F^'4jrrR%AK'!"7oNPOlmf*=XI"D<Ks+13$s7QDB~> -!D>NQrrIH;oD\f.li.!"FSu.?F^'4jrrR%AK'!"7oNPOlmf*=XI"D<Ks+13$s7QDB~> -#tmA[V69hPmGN'ZrrHa>li."*b5D8@bH`l#rrU9A4lu\Gqn\)'mf*=Q1YMd/Qb7nLJcC<$TDsE~> -#tmA[V69hPmGN'ZrrHa>li."*b5D8@bH`l#rrU9A4lu\Gqn\)'mf*=Q1YMd/Qb7nLJcC<$TDsE~> -#tmA[V69hPmGN'ZrrHa>li."*b5D8@bH`l#rrU9A4lu\Gqn\)'mf*=Q1YMd/Qb7nLJcC<$TDsE~> -#tmA[n8Punj$2c%rrQrD)WUhulS8;:!T6-$rrKH@mf*=Q1YMd/G,BijJcC<$TDsE~> -#tmA[n8Punj$2c%rrQrD)WUhulS8;:!T6-$rrKH@mf*=Q1YMd/G,BijJcC<$TDsE~> -#tmA[n8Punj$2c%rrQrD)WUhulS8;:!T6-$rrKH@mf*=Q1YMd/G,BijJcC<$TDsE~> -#YR8Zs6a"o,j+k$"+miX*r>m;&MNhW!_OI]qu6]_1&LtOi'%&=!U2-6*XdYos6(XJ*d)V6s8)[8 -!L<EYrrKH@pAY0m`Vgh\YP[T:VZ%V=\GZBJr>l?_rRb34I3'HPs8TJ)*WsmkpmV.&$f1io*Y&i) -*rl96M#JG%-KtK-K&fcM0C",gJcC<$ZN#F~> -#YR8Zs6a"o,j+k$"+miX*r>m;&MNhW!_OI]qu6]_1&LtOi'%&=!U2-6*XdYos6(XJ*d)V6s8)[8 -!L<EYrrKH@pAY0m`Vgh\YP[T:VZ%V=\GZBJr>l?_rRb34I3'HPs8TJ)*WsmkpmV.&$f1io*Y&i) -*rl96M#JG%-KtK-K&fcM0C",gJcC<$ZN#F~> -#YR8Zs6a"o,j+k$"+miX*r>m;&MNhW!_OI]qu6]_1&LtOi'%&=!U2-6*XdYos6(XJ*d)V6s8)[8 -!L<EYrrKH@pAY0m`Vgh\YP[T:VZ%V=\GZBJr>l?_rRb34I3'HPs8TJ)*WsmkpmV.&$f1io*Y&i) -*rl96M#JG%-KtK-K&fcM0C",gJcC<$ZN#F~> -#tmA[j`JBojA4A"rr=,:rrGJko`"sd-N!fDlS8;:!T6->rrFb?rr37OU&QA5s8S+>qYpS-\,QC. -ZYK46!VIi=rrd2tl3hh8rrG+?qu6sSnGfp5T`>$9qtpBq*rio]rVljnrr3"BVZ$MqVKVt=$1o\H -s*Z-8s6):js+13$s0DZT~> -#tmA[j`JBojA4A"rr=,:rrGJko`"sd-N!fDlS8;:!T6->rrFb?rr37OU&QA5s8S+>qYpS-\,QC. -ZYK46!VIi=rrd2tl3hh8rrG+?qu6sSnGfp5T`>$9qtpBq*rio]rVljnrr3"BVZ$MqVKVt=$1o\H -s*Z-8s6):js+13$s0DZT~> -#tmA[j`JBojA4A"rr=,:rrGJko`"sd-N!fDlS8;:!T6->rrFb?rr37OU&QA5s8S+>qYpS-\,QC. -ZYK46!VIi=rrd2tl3hh8rrG+?qu6sSnGfp5T`>$9qtpBq*rio]rVljnrr3"BVZ$MqVKVt=$1o\H -s*Z-8s6):js+13$s0DZT~> -#tmA[Z+0ffmGruorr=,+rrMj@qu6]_1&LtOi'%&=!A9uCW=)Uts!.@>s,N->s8Dnq!CO?qrrKH@ -pAY0d-i<oEl8/D="$#BAlM[[b*q93<BE%o5D#F=nrM]l7s1Mh9rrI;?rVlnq:B%4!U+--BI@pQ> -n9BNaJcC<$ZN#F~> -#tmA[Z+0ffmGruorr=,+rrMj@qu6]_1&LtOi'%&=!A9uCW=)Uts!.@>s,N->s8Dnq!CO?qrrKH@ -pAY0d-i<oEl8/D="$#BAlM[[b*q93<BE%o5D#F=nrM]l7s1Mh9rrI;?rVlnq:B%4!U+--BI@pQ> -n9BNaJcC<$ZN#F~> -#tmA[Z+0ffmGruorr=,+rrMj@qu6]_1&LtOi'%&=!A9uCW=)Uts!.@>s,N->s8Dnq!CO?qrrKH@ -pAY0d-i<oEl8/D="$#BAlM[[b*q93<BE%o5D#F=nrM]l7s1Mh9rrI;?rVlnq:B%4!U+--BI@pQ> -n9BNaJcC<$ZN#F~> -!D>NQrrJ/QoD\e3li."[-N!fDlS8;:!T6->rrF`grGr=hs+cMkN.JhFs-EV)!A:k\rrKH@pAY0d --i<oEl8/D="$#B2LAc/r'_).2BDhc1k(N\S!tkRH@/9g'G,G6<!N%dREs.C#s*^Mjs+13$s/uBP~> -!D>NQrrJ/QoD\e3li."[-N!fDlS8;:!T6->rrF`grGr=hs+cMkN.JhFs-EV)!A:k\rrKH@pAY0d --i<oEl8/D="$#B2LAc/r'_).2BDhc1k(N\S!tkRH@/9g'G,G6<!N%dREs.C#s*^Mjs+13$s/uBP~> -!D>NQrrJ/QoD\e3li."[-N!fDlS8;:!T6->rrF`grGr=hs+cMkN.JhFs-EV)!A:k\rrKH@pAY0d --i<oEl8/D="$#B2LAc/r'_).2BDhc1k(N\S!tkRH@/9g'G,G6<!N%dREs.C#s*^Mjs+13$s/uBP~> -!D>NArr=,:rrI;!o`"sd-N!fDlS8;:!T6->rrFb?qu6eNOHG[Brr2s>rr3&1/@YWY!OHP7rrMd? -rVltal0:)'rrY7Ah`h&>"dftms0cS<rrL2@rr3+[&c]OPrVlkIrr34HVZ6[Gs/'u9rrIP?JcC<$ -JcDnQJ,~> -!D>NArr=,:rrI;!o`"sd-N!fDlS8;:!T6->rrFb?qu6eNOHG[Brr2s>rr3&1/@YWY!OHP7rrMd? -rVltal0:)'rrY7Ah`h&>"dftms0cS<rrL2@rr3+[&c]OPrVlkIrr34HVZ6[Gs/'u9rrIP?JcC<$ -JcDnQJ,~> -!D>NArr=,:rrI;!o`"sd-N!fDlS8;:!T6->rrFb?qu6eNOHG[Brr2s>rr3&1/@YWY!OHP7rrMd? -rVltal0:)'rrY7Ah`h&>"dftms0cS<rrL2@rr3+[&c]OPrVlkIrr34HVZ6[Gs/'u9rrIP?JcC<$ -JcDnQJ,~> -!D>NDrs#)m;$g)sOT#1[%P@AR"ER<H;3V"Z"Dg[A;4IRb#\6F=;54*j]iY21"KMM%\l8T*"1%t, -[/No/IRUaGo2.Lk;8N&-!W8Vh;$3-Ul8/D="$#B7R/TqdP99;o[V,O<!Uc$J;$<@(s6>O@;#mj" -rs.%n;,Ok'j+I>.!*K7#!I^Sks+13$s/uBP~> -!D>NDrs#)m;$g)sOT#1[%P@AR"ER<H;3V"Z"Dg[A;4IRb#\6F=;54*j]iY21"KMM%\l8T*"1%t, -[/No/IRUaGo2.Lk;8N&-!W8Vh;$3-Ul8/D="$#B7R/TqdP99;o[V,O<!Uc$J;$<@(s6>O@;#mj" -rs.%n;,Ok'j+I>.!*K7#!I^Sks+13$s/uBP~> -!D>NDrs#)m;$g)sOT#1[%P@AR"ER<H;3V"Z"Dg[A;4IRb#\6F=;54*j]iY21"KMM%\l8T*"1%t, -[/No/IRUaGo2.Lk;8N&-!W8Vh;$3-Ul8/D="$#B7R/TqdP99;o[V,O<!Uc$J;$<@(s6>O@;#mj" -rs.%n;,Ok'j+I>.!*K7#!I^Sks+13$s/uBP~> -!D>NDrrD*WbQ-Q!rrLHrp&>$CrlbB"rr2uJrlbB%rr2uHrlbB'rr2uErlbN-s8Pm:rlbIg^&S*2 -bQR%cnc/OcbQ.&)rrDflbQID8qpt`G"5!DLoDZr;nC@I:nDX9E!:Kj1"SL4Cs6T^.!<)lr!oD/F -rr2u]rlbAfrr3#\m",1fs+13Qs*t~> -!D>NDrrD*WbQ-Q!rrLHrp&>$CrlbB"rr2uJrlbB%rr2uHrlbB'rr2uErlbN-s8Pm:rlbIg^&S*2 -bQR%cnc/OcbQ.&)rrDflbQID8qpt`G"5!DLoDZr;nC@I:nDX9E!:Kj1"SL4Cs6T^.!<)lr!oD/F -rr2u]rlbAfrr3#\m",1fs+13Qs*t~> -!D>NDrrD*WbQ-Q!rrLHrp&>$CrlbB"rr2uJrlbB%rr2uHrlbB'rr2uErlbN-s8Pm:rlbIg^&S*2 -bQR%cnc/OcbQ.&)rrDflbQID8qpt`G"5!DLoDZr;nC@I:nDX9E!:Kj1"SL4Cs6T^.!<)lr!oD/F -rr2u]rlbAfrr3#\m",1fs+13Qs*t~> -!D>MarrFV?rq?G6YCZ_)s+13$s3q!u~> -!D>MarrFV?rq?G6YCZ_)s+13$s3q!u~> -!D>MarrFV?rq?G6YCZ_)s+13$s3q!u~> -!D>M`rr=PJ-30Zhs+13$s+13us*t~> -!D>M`rr=PJ-30Zhs+13$s+13us*t~> -!D>M`rr=PJ-30Zhs+13$s+13us*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -"A:iVs2Y,1!3Z>$!Q4&Ns+13$s+132s*t~> -"A:iVs2Y,1!3Z>$!Q4&Ns+13$s+132s*t~> -"A:iVs2Y,1!3Z>$!Q4&Ns+13$s+132s*t~> -"A:iV`..c8#(NHKs0$t?JcC<$JcC<$OT0h~> -"A:iV`..c8#(NHKs0$t?JcC<$JcC<$OT0h~> -"A:iV`..c8#(NHKs0$t?JcC<$JcC<$OT0h~> -"A:iVM3S#>!S0a>rrTTDqgncus+13$s,m>3~> -"A:iVM3S#>!S0a>rrTTDqgncus+13$s,m>3~> -"A:iVM3S#>!S0a>rrTTDqgncus+13$s,m>3~> -#tmA[hr=\9pK5Z<rrL#?JcC<$JcC<$OoKq~> -#tmA[hr=\9pK5Z<rrL#?JcC<$JcC<$OoKq~> -#tmA[hr=\9pK5Z<rrL#?JcC<$JcC<$OoKq~> -!D>NPrrG@?qu6]<<.Y(#s+13$s-!D4~> -!D>NPrrG@?qu6]<<.Y(#s+13$s-!D4~> -!D>NPrrG@?qu6]<<.Y(#s+13$s-!D4~> -!D>NRrrVaZjneuXg-^GkJcC<$JcCo5J,~> -!D>NRrrVaZjneuXg-^GkJcC<$JcCo5J,~> -!D>NRrrVaZjneuXg-^GkJcC<$JcCo5J,~> -#"q&Xs5RM>qYpTI7tL\ks+13$s,m>3~> -#"q&Xs5RM>qYpTI7tL\ks+13$s,m>3~> -#"q&Xs5RM>qYpTI7tL\ks+13$s,m>3~> -"\UrWgN^j:rrU/EqLSZts+13$s,m>3~> -"\UrWgN^j:rrU/EqLSZts+13$s,m>3~> -"\UrWgN^j:rrU/EqLSZts+13$s,m>3~> -"A:iVM,sS>"gS+-]QWRks+13$s+133s*t~> -"A:iVM,sS>"gS+-]QWRks+13$s+133s*t~> -"A:iVM,sS>"gS+-]QWRks+13$s+133s*t~> -"%t`UaS^ktWrN+,i.:oZs+13$s,[21~> -"%t`UaS^ktWrN+,i.:oZs+13$s,[21~> -"%t`UaS^ktWrN+,i.:oZs+13$s,[21~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -!D>M*s+13$s+13&s*t~> -%%EndData -showpage -%%Trailer -end -%%EOF diff --git a/lib/stdlib/doc/src/ushell3.gif b/lib/stdlib/doc/src/ushell3.gif Binary files differdeleted file mode 100644 index 2141268b91..0000000000 --- a/lib/stdlib/doc/src/ushell3.gif +++ /dev/null diff --git a/lib/stdlib/doc/src/ushell3.ps b/lib/stdlib/doc/src/ushell3.ps deleted file mode 100644 index dd64eeab5c..0000000000 --- a/lib/stdlib/doc/src/ushell3.ps +++ /dev/null @@ -1,662 +0,0 @@ -%!PS-Adobe-3.0 -%%Creator: GIMP PostScript file plugin V 1.17 by Peter Kirchgessner -%%Title: ushell3.ps -%%CreationDate: Mon Mar 16 12:15:17 2009 -%%DocumentData: Clean7Bit -%%LanguageLevel: 2 -%%Pages: 1 -%%BoundingBox: 14 14 468 78 -%%EndComments -%%BeginProlog -% Use own dictionary to avoid conflicts -10 dict begin -%%EndProlog -%%Page: 1 1 -% Translate for offset -14.173228346456694 14.173228346456694 translate -% Translate to begin of first scanline -0 63.070866141732289 translate -453.54330708661422 -63.070866141732289 scale -% Image geometry -640 89 8 -% Transformation matrix -[ 640 0 0 89 0 0 ] -% Strings to hold RGB-samples per scanline -/rstr 640 string def -/gstr 640 string def -/bstr 640 string def -{currentfile /ASCII85Decode filter /RunLengthDecode filter rstr readstring pop} -{currentfile /ASCII85Decode filter /RunLengthDecode filter gstr readstring pop} -{currentfile /ASCII85Decode filter /RunLengthDecode filter bstr readstring pop} -true 3 -%%BeginData: 37475 ASCII Bytes -colorimage -!1\W%J`VIEJ`VLFJ,~> -!1\W%J`VIEJ`VLFJ,~> -!1\W%J`VIEJ`VLFJ,~> -!T[+/6@hIS6@hIU6@]~> -!T[+/6@hIS6@hIU6@]~> -!T[+/6@hIS6@hIU6@]~> -!ouWfJQ.2"JQ.2"KN*I~> -!ouWfJQ.2"JQ.2"KN*I~> -!ouWfJQ.2"JQ.2"KN*I~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLQ2^m!`0L?'S`PG&JcC<$i;\<~> -!ouXLQ2^m!`0L?'S`PG&JcC<$i;\<~> -!ouXLQ2^m!`0L?'S`PG&JcC<$i;\<~> -"QVjNs.9-i!1*E[!L)+*rrR=EF8Z%>Dc_2VrrI?7rr3)%^&N-N<rg/5rr?^0<rgP6rrU,eg\:^K -o6/O]!ioDNpAY05U[\9aJa!(4!2BHo!,VW6!lAR@JcC<$JcF^/J,~> -"QVjNs.9-i!1*E[!L)+*rrR=EF8Z%>Dc_2VrrI?7rr3)%^&N-N<rg/5rr?^0<rgP6rrU,eg\:^K -o6/O]!ioDNpAY05U[\9aJa!(4!2BHo!,VW6!lAR@JcC<$JcF^/J,~> -"QVjNs.9-i!1*E[!L)+*rrR=EF8Z%>Dc_2VrrI?7rr3)%^&N-N<rg/5rr?^0<rgP6rrU,eg\:^K -o6/O]!ioDNpAY05U[\9aJa!(4!2BHo!,VW6!lAR@JcC<$JcF^/J,~> -"lqsOs)!Pi_uSNdrrHB@o)Ad;\gmXX!mS).p&>%Ili-neJXl`h]D]YJlM1AZb5K6Z:po`k!N()7 -rrML@l2LdgT^2UZil(<`rrJFsrVlntF7K88K;)-<s8T'RrkniDCAn/50C=>jJcC<$iW"E~> -"lqsOs)!Pi_uSNdrrHB@o)Ad;\gmXX!mS).p&>%Ili-neJXl`h]D]YJlM1AZb5K6Z:po`k!N()7 -rrML@l2LdgT^2UZil(<`rrJFsrVlntF7K88K;)-<s8T'RrkniDCAn/50C=>jJcC<$iW"E~> -"lqsOs)!Pi_uSNdrrHB@o)Ad;\gmXX!mS).p&>%Ili-neJXl`h]D]YJlM1AZb5K6Z:po`k!N()7 -rrML@l2LdgT^2UZil(<`rrJFsrVlntF7K88K;)-<s8T'RrkniDCAn/50C=>jJcC<$iW"E~> -"lqsOs)#"3rrHB@nc&X\.f95Hkqi#4!AWp>rrdnCs!dR.rrSCIp@&"_b$si5rrML@l2LdPK]E(5 -GGY9<!NC/2rs4ONpZ4C7s,`6>rrN#\rVlo\2M(mZs+14/s*t~> -"lqsOs)#"3rrHB@nc&X\.f95Hkqi#4!AWp>rrdnCs!dR.rrSCIp@&"_b$si5rrML@l2LdPK]E(5 -GGY9<!NC/2rs4ONpZ4C7s,`6>rrN#\rVlo\2M(mZs+14/s*t~> -"lqsOs)#"3rrHB@nc&X\.f95Hkqi#4!AWp>rrdnCs!dR.rrSCIp@&"_b$si5rrML@l2LdPK]E(5 -GGY9<!NC/2rs4ONpZ4C7s,`6>rrN#\rVlo\2M(mZs+14/s*t~> -#in9Rs)"@hjludE!Us(f*"5s=s'2Za*#r;Ts6`DV*!'XArr3#i.f95Hkqi#4$2ktGs.=c>s!c4l -*!(ffp&>*eKVIo7!Q/(<rrCjQ*!EJBm4518*!<VHr42bG&A7u":Z[6L*5hd.*"`Z#*8gPk!Q/1@ -rrsVGs/-hF]Dhg?\f;.l*$"qWWG$>m*$OSArs>H^rr<#^9E1*5p\t46JcC<$JcF^/J,~> -#in9Rs)"@hjludE!Us(f*"5s=s'2Za*#r;Ts6`DV*!'XArr3#i.f95Hkqi#4$2ktGs.=c>s!c4l -*!(ffp&>*eKVIo7!Q/(<rrCjQ*!EJBm4518*!<VHr42bG&A7u":Z[6L*5hd.*"`Z#*8gPk!Q/1@ -rrsVGs/-hF]Dhg?\f;.l*$"qWWG$>m*$OSArs>H^rr<#^9E1*5p\t46JcC<$JcF^/J,~> -#in9Rs)"@hjludE!Us(f*"5s=s'2Za*#r;Ts6`DV*!'XArr3#i.f95Hkqi#4$2ktGs.=c>s!c4l -*!(ffp&>*eKVIo7!Q/(<rrCjQ*!EJBm4518*!<VHr42bG&A7u":Z[6L*5hd.*"`Z#*8gPk!Q/1@ -rrsVGs/-hF]Dhg?\f;.l*$"qWWG$>m*$OSArs>H^rr<#^9E1*5p\t46JcC<$JcF^/J,~> -#in9Rs(s&?2H0VT!G&_>rsZf$s'-u6s8T->s&7&=rrJm@rr3#i.f95Hkqhu3#T`sFSpp_><^Zld -!I1F5rrJj?mJd4)=nhq!7G$o6ErQ(@4l><[rVm<akl8@2QiI(:nGiNVK_>?L_HQutn,FF,rrHT? -r;QeAV>^DuW>MT6s7dl/rs"REs8UEef)5OJ*J+6As+14/s*t~> -#in9Rs(s&?2H0VT!G&_>rsZf$s'-u6s8T->s&7&=rrJm@rr3#i.f95Hkqhu3#T`sFSpp_><^Zld -!I1F5rrJj?mJd4)=nhq!7G$o6ErQ(@4l><[rVm<akl8@2QiI(:nGiNVK_>?L_HQutn,FF,rrHT? -r;QeAV>^DuW>MT6s7dl/rs"REs8UEef)5OJ*J+6As+14/s*t~> -#in9Rs(s&?2H0VT!G&_>rsZf$s'-u6s8T->s&7&=rrJm@rr3#i.f95Hkqhu3#T`sFSpp_><^Zld -!I1F5rrJj?mJd4)=nhq!7G$o6ErQ(@4l><[rVm<akl8@2QiI(:nGiNVK_>?L_HQutn,FF,rrHT? -r;QeAV>^DuW>MT6s7dl/rs"REs8UEef)5OJ*J+6As+14/s*t~> -"lqsOs)#";rrJFMriH=Cs8Q??rr3,%EW8soriH3>HN*pFngaP:!U2E4rrciCl&)D8rrIA?pAY3[ -N2>qA!Q/(<rrDWgXTL6.m4eM="$PQ&3;rj[2<b(S?N0s.E:s82R=t85#/XRDCU3s\rVln-]);R/ -GGY9<!NC/>rrMm?nG`]SNW9#h7m6eM!$-XjJcC<$iW"E~> -"lqsOs)#";rrJFMriH=Cs8Q??rr3,%EW8soriH3>HN*pFngaP:!U2E4rrciCl&)D8rrIA?pAY3[ -N2>qA!Q/(<rrDWgXTL6.m4eM="$PQ&3;rj[2<b(S?N0s.E:s82R=t85#/XRDCU3s\rVln-]);R/ -GGY9<!NC/>rrMm?nG`]SNW9#h7m6eM!$-XjJcC<$iW"E~> -"lqsOs)#";rrJFMriH=Cs8Q??rr3,%EW8soriH3>HN*pFngaP:!U2E4rrciCl&)D8rrIA?pAY3[ -N2>qA!Q/(<rrDWgXTL6.m4eM="$PQ&3;rj[2<b(S?N0s.E:s82R=t85#/XRDCU3s\rVln-]);R/ -GGY9<!NC/>rrMm?nG`]SNW9#h7m6eM!$-XjJcC<$iW"E~> -"lqsOs)#":rrAAaD?P3us'3D>rrfBBs&2tsD?.$BrrM[?qu6]]1\C\Lp*RC[q>UJ?V"Xfh^Kp4+ -!Q/(=rrN"UrGD]YfBk9jrrYFAj>d,<"?#EC^0^[9!L\W6rs$>Ds(eq?*W?!=@_2L;!I(C=rrK*? -rr3#o,k1g7OH'8>!T-'<rr='js+13$s5F!.~> -"lqsOs)#":rrAAaD?P3us'3D>rrfBBs&2tsD?.$BrrM[?qu6]]1\C\Lp*RC[q>UJ?V"Xfh^Kp4+ -!Q/(=rrN"UrGD]YfBk9jrrYFAj>d,<"?#EC^0^[9!L\W6rs$>Ds(eq?*W?!=@_2L;!I(C=rrK*? -rr3#o,k1g7OH'8>!T-'<rr='js+13$s5F!.~> -"lqsOs)#":rrAAaD?P3us'3D>rrfBBs&2tsD?.$BrrM[?qu6]]1\C\Lp*RC[q>UJ?V"Xfh^Kp4+ -!Q/(=rrN"UrGD]YfBk9jrrYFAj>d,<"?#EC^0^[9!L\W6rs$>Ds(eq?*W?!=@_2L;!I(C=rrK*? -rr3#o,k1g7OH'8>!T-'<rr='js+13$s5F!.~> -"lqsOs)#";rrK1Rrr3,.C&_GSrr3,%EW8tZq>UKd.f95Hkqhu3"84(R@K-9-Mu!AP!I1F>rrV/% -Zi0n*m!?)+rrV55[Jp1,odBb="fictm1u>nrrYFAj>d,<"?#EC^0^[9"dt&Ds,$[Lrs$>D^O^an -*W?!=@_2L;#C!$Es+UKPF8l1?pa#A/!K`<?rrM"?rVlnZNIh+\s+14/s*t~> -"lqsOs)#";rrK1Rrr3,.C&_GSrr3,%EW8tZq>UKd.f95Hkqhu3"84(R@K-9-Mu!AP!I1F>rrV/% -Zi0n*m!?)+rrV55[Jp1,odBb="fictm1u>nrrYFAj>d,<"?#EC^0^[9"dt&Ds,$[Lrs$>D^O^an -*W?!=@_2L;#C!$Es+UKPF8l1?pa#A/!K`<?rrM"?rVlnZNIh+\s+14/s*t~> -"lqsOs)#";rrK1Rrr3,.C&_GSrr3,%EW8tZq>UKd.f95Hkqhu3"84(R@K-9-Mu!AP!I1F>rrV/% -Zi0n*m!?)+rrV55[Jp1,odBb="fictm1u>nrrYFAj>d,<"?#EC^0^[9"dt&Ds,$[Lrs$>D^O^an -*W?!=@_2L;#C!$Es+UKPF8l1?pa#A/!K`<?rrM"?rVlnZNIh+\s+14/s*t~> -"lqsOs(spt=Tb&ka`%/]"E;N`>f$F>"KQPB_eK*Q!1!Q`"F!iV=e#Ej"E@<P=ePKg"8nU*aSu2? -ZsEZ6!J95.rrU7AErH"=gd(0)!N()?rrN%dr`KD\/_BA3O8`8aPP"R6rE08hp]%s6qYp`RIT]gC -rV?I'lAL)E_.]YEs1_\\6!=!^rs-kl=]qs.WH8(=!Vdr0rrLc"r`K83]D_a10C=>jJcC<$iW"E~> -"lqsOs(spt=Tb&ka`%/]"E;N`>f$F>"KQPB_eK*Q!1!Q`"F!iV=e#Ej"E@<P=ePKg"8nU*aSu2? -ZsEZ6!J95.rrU7AErH"=gd(0)!N()?rrN%dr`KD\/_BA3O8`8aPP"R6rE08hp]%s6qYp`RIT]gC -rV?I'lAL)E_.]YEs1_\\6!=!^rs-kl=]qs.WH8(=!Vdr0rrLc"r`K83]D_a10C=>jJcC<$iW"E~> -"lqsOs(spt=Tb&ka`%/]"E;N`>f$F>"KQPB_eK*Q!1!Q`"F!iV=e#Ej"E@<P=ePKg"8nU*aSu2? -ZsEZ6!J95.rrU7AErH"=gd(0)!N()?rrN%dr`KD\/_BA3O8`8aPP"R6rE08hp]%s6qYp`RIT]gC -rV?I'lAL)E_.]YEs1_\\6!=!^rs-kl=]qs.WH8(=!Vdr0rrLc"r`K83]D_a10C=>jJcC<$iW"E~> -"QVjNs4mOh"53_Se,I2eeGoR$nG`FjleVU@ci1c]f`(mNc2PQ[gA_*PbPo?Yh"C[Jp<rm=!6+rS -!93tW!qO4arVlomdH^`5l@c>>rrDcl_?K,Np&!#$rk\d,s8VZg_?BH0s7"\:rr_/q_Y3a(#jL4G -s3:H@s6'?t!<)lr#1p`/s8VB?rr3#tb4#?1h>Y7kb5M>AGH(Ijs+13$s5F!.~> -"QVjNs4mOh"53_Se,I2eeGoR$nG`FjleVU@ci1c]f`(mNc2PQ[gA_*PbPo?Yh"C[Jp<rm=!6+rS -!93tW!qO4arVlomdH^`5l@c>>rrDcl_?K,Np&!#$rk\d,s8VZg_?BH0s7"\:rr_/q_Y3a(#jL4G -s3:H@s6'?t!<)lr#1p`/s8VB?rr3#tb4#?1h>Y7kb5M>AGH(Ijs+13$s5F!.~> -"QVjNs4mOh"53_Se,I2eeGoR$nG`FjleVU@ci1c]f`(mNc2PQ[gA_*PbPo?Yh"C[Jp<rm=!6+rS -!93tW!qO4arVlomdH^`5l@c>>rrDcl_?K,Np&!#$rk\d,s8VZg_?BH0s7"\:rr_/q_Y3a(#jL4G -s3:H@s6'?t!<)lr#1p`/s8VB?rr3#tb4#?1h>Y7kb5M>AGH(Ijs+13$s5F!.~> -!ouXLQ2^mSnWj+TkkTf0JcC<$i;\<~> -!ouXLQ2^mSnWj+TkkTf0JcC<$i;\<~> -!ouXLQ2^mSnWj+TkkTf0JcC<$i;\<~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcG]K!TNR]rr_0&bgEm!"4YQ=h#.0PdXhFLs/5mI~> -!ouXLJcG]K!TNR]rr_0&bgEm!"4YQ=h#.0PdXhFLs/5mI~> -!ouXLJcG]K!TNR]rr_0&bgEm!"4YQ=h#.0PdXhFLs/5mI~> -!ouXLrVll.r;Qf;o()e]\@V&,!kGPPr;QirYf6S@!PSC#rr_SkYi""2!o&"@rVm>df)Ne\s8V;e -g&M)arUBgji3;2?s1.k'"4H?3\b5t)>rthhrVluBmf'fsrr^ZQYd<0c!6"l@!6Y!7"1eHrci3qH -Bhpuir;Qe$_L_`<s/>sJ~> -!ouXLrVll.r;Qf;o()e]\@V&,!kGPPr;QirYf6S@!PSC#rr_SkYi""2!o&"@rVm>df)Ne\s8V;e -g&M)arUBgji3;2?s1.k'"4H?3\b5t)>rthhrVluBmf'fsrr^ZQYd<0c!6"l@!6Y!7"1eHrci3qH -Bhpuir;Qe$_L_`<s/>sJ~> -!ouXLrVll.r;Qf;o()e]\@V&,!kGPPr;QirYf6S@!PSC#rr_SkYi""2!o&"@rVm>df)Ne\s8V;e -g&M)arUBgji3;2?s1.k'"4H?3\b5t)>rthhrVluBmf'fsrr^ZQYd<0c!6"l@!6Y!7"1eHrci3qH -Bhpuir;Qe$_L_`<s/>sJ~> -!ouXLrr3"u(&\(5P`>P2rrICpm/I-7?T\2c!r?\qrVlmIoCDnbn;;!sKAbYe!T1]hrrJ(?r;RA& -HiH[ds6YVXJCjfHq>^KAch7;Bie2*#ir:%mrr[/AruLe4!F<J;rsMiIr#l%>c$X;BD5H.i!P<LR -CB8[tpAY48s0uV;rrLA?r;QfW3e@<^s/>sJ~> -!ouXLrr3"u(&\(5P`>P2rrICpm/I-7?T\2c!r?\qrVlmIoCDnbn;;!sKAbYe!T1]hrrJ(?r;RA& -HiH[ds6YVXJCjfHq>^KAch7;Bie2*#ir:%mrr[/AruLe4!F<J;rsMiIr#l%>c$X;BD5H.i!P<LR -CB8[tpAY48s0uV;rrLA?r;QfW3e@<^s/>sJ~> -!ouXLrr3"u(&\(5P`>P2rrICpm/I-7?T\2c!r?\qrVlmIoCDnbn;;!sKAbYe!T1]hrrJ(?r;RA& -HiH[ds6YVXJCjfHq>^KAch7;Bie2*#ir:%mrr[/AruLe4!F<J;rsMiIr#l%>c$X;BD5H.i!P<LR -CB8[tpAY48s0uV;rrLA?r;QfW3e@<^s/>sJ~> -#NS0Qs8SgH'Dqe1RtBDp!T?-5rrFS?o)AmK5l^js[GUubZ>0::!n)SAr;RA&HiH[ds3jR>_1$W_ -r;ZeYN:m2T\mk]II!C_Grr[/AruLe4!F<J;rsMiIr#l%>LR%o>oI8\t#.&^Es8U`apAY48s0uV; -rrLA?r;QigKVj>#JcD_LJ,~> -#NS0Qs8SgH'Dqe1RtBDp!T?-5rrFS?o)AmK5l^js[GUubZ>0::!n)SAr;RA&HiH[ds3jR>_1$W_ -r;ZeYN:m2T\mk]II!C_Grr[/AruLe4!F<J;rsMiIr#l%>LR%o>oI8\t#.&^Es8U`apAY48s0uV; -rrLA?r;QigKVj>#JcD_LJ,~> -#NS0Qs8SgH'Dqe1RtBDp!T?-5rrFS?o)AmK5l^js[GUubZ>0::!n)SAr;RA&HiH[ds3jR>_1$W_ -r;ZeYN:m2T\mk]II!C_Grr[/AruLe4!F<J;rsMiIr#l%>LR%o>oI8\t#.&^Es8U`apAY48s0uV; -rrLA?r;QigKVj>#JcD_LJ,~> -#NS0Qs.PG>*W#d:UNuP4!e+Bor;QbBr`fGnp&>'O48f*[Bj?GlrrFS4r`fH/rVlrS>c%E!#M_TE -s2a:$pAJ50_Z0XSs3"YPaT)6E>a;X#c2[h+rEKWWs79J\-<sg.rr3#!F8PtRh9c29n,Mjis8U'5 -o)IQO1br<@mf3=+rEKd&s5qB%s1G-(s3748r`fI&rr3)Dir?1SrrHE?qu72Dli+*fs+cm>s7@c? -s/j-:rrM&<rr3"Nm/?qjU<NXUs4*P;s,-e\!/pjV"@#[e>`o$c!.XuQ!1*T`"0V[da8Gr<btn6: -!QA,ks+13Ls*t~> -#NS0Qs.PG>*W#d:UNuP4!e+Bor;QbBr`fGnp&>'O48f*[Bj?GlrrFS4r`fH/rVlrS>c%E!#M_TE -s2a:$pAJ50_Z0XSs3"YPaT)6E>a;X#c2[h+rEKWWs79J\-<sg.rr3#!F8PtRh9c29n,Mjis8U'5 -o)IQO1br<@mf3=+rEKd&s5qB%s1G-(s3748r`fI&rr3)Dir?1SrrHE?qu72Dli+*fs+cm>s7@c? -s/j-:rrM&<rr3"Nm/?qjU<NXUs4*P;s,-e\!/pjV"@#[e>`o$c!.XuQ!1*T`"0V[da8Gr<btn6: -!QA,ks+13Ls*t~> -#NS0Qs.PG>*W#d:UNuP4!e+Bor;QbBr`fGnp&>'O48f*[Bj?GlrrFS4r`fH/rVlrS>c%E!#M_TE -s2a:$pAJ50_Z0XSs3"YPaT)6E>a;X#c2[h+rEKWWs79J\-<sg.rr3#!F8PtRh9c29n,Mjis8U'5 -o)IQO1br<@mf3=+rEKd&s5qB%s1G-(s3748r`fI&rr3)Dir?1SrrHE?qu72Dli+*fs+cm>s7@c? -s/j-:rrM&<rr3"Nm/?qjU<NXUs4*P;s,-e\!/pjV"@#[e>`o$c!.XuQ!1*T`"0V[da8Gr<btn6: -!QA,ks+13Ls*t~> -#NS0Qs4Zf=*W#d;ql"c5rrUHX,5qNBGcC\W!KEfHrrM(?r;Qi:U."t[!@^M;^B&_orr3&@!-8&< -!Sfs<rr>sq^CtP2s0b1+^V=R6rYN>5HbX4Is7Q?*#\)ch^P5S"^[V7&!NL5.rsA82Ch^Z!q#AcZ -rP&>0q#:E#)he4*!*/Ie!F<J5rs=H,5X7I]s8RS?rr3#E:B(7o4Q68=$#ZsH*WNf[s,<HH^BC!c -s+R-F^BBjes*pjD^B'Ldp&>';:](.m`E.WjJcD_LJ,~> -#NS0Qs4Zf=*W#d;ql"c5rrUHX,5qNBGcC\W!KEfHrrM(?r;Qi:U."t[!@^M;^B&_orr3&@!-8&< -!Sfs<rr>sq^CtP2s0b1+^V=R6rYN>5HbX4Is7Q?*#\)ch^P5S"^[V7&!NL5.rsA82Ch^Z!q#AcZ -rP&>0q#:E#)he4*!*/Ie!F<J5rs=H,5X7I]s8RS?rr3#E:B(7o4Q68=$#ZsH*WNf[s,<HH^BC!c -s+R-F^BBjes*pjD^B'Ldp&>';:](.m`E.WjJcD_LJ,~> -#NS0Qs4Zf=*W#d;ql"c5rrUHX,5qNBGcC\W!KEfHrrM(?r;Qi:U."t[!@^M;^B&_orr3&@!-8&< -!Sfs<rr>sq^CtP2s0b1+^V=R6rYN>5HbX4Is7Q?*#\)ch^P5S"^[V7&!NL5.rsA82Ch^Z!q#AcZ -rP&>0q#:E#)he4*!*/Ie!F<J5rs=H,5X7I]s8RS?rr3#E:B(7o4Q68=$#ZsH*WNf[s,<HH^BC!c -s+R-F^BBjes*pjD^B'Ldp&>';:](.m`E.WjJcD_LJ,~> -!ouXLrVlj<q>UKC9D/;cqBGn<!DCl?rrJR?pAY0P48]$YfgPf=!@cOtrrIA?rr3&og["k="?7J0 -,`Vg'!$2%<&RW6Okq)#ts&R/=+9/3^s%^l:rrkjCs8TB>qu6\sF6ii,OGs/<!Q&%=rrCsOrrTH1 -mf*4d*U`q.?,-(4%YoShgX7PNs6XR>s6`D>rr3!]iVic_DQj'\s1Me>A[h[="LVqC?,6I>"KZSB -<65(=!V5UMrrLA?qu6]9=+UC&s/H$K~> -!ouXLrVlj<q>UKC9D/;cqBGn<!DCl?rrJR?pAY0P48]$YfgPf=!@cOtrrIA?rr3&og["k="?7J0 -,`Vg'!$2%<&RW6Okq)#ts&R/=+9/3^s%^l:rrkjCs8TB>qu6\sF6ii,OGs/<!Q&%=rrCsOrrTH1 -mf*4d*U`q.?,-(4%YoShgX7PNs6XR>s6`D>rr3!]iVic_DQj'\s1Me>A[h[="LVqC?,6I>"KZSB -<65(=!V5UMrrLA?qu6]9=+UC&s/H$K~> -!ouXLrVlj<q>UKC9D/;cqBGn<!DCl?rrJR?pAY0P48]$YfgPf=!@cOtrrIA?rr3&og["k="?7J0 -,`Vg'!$2%<&RW6Okq)#ts&R/=+9/3^s%^l:rrkjCs8TB>qu6\sF6ii,OGs/<!Q&%=rrCsOrrTH1 -mf*4d*U`q.?,-(4%YoShgX7PNs6XR>s6`D>rr3!]iVic_DQj'\s1Me>A[h[="LVqC?,6I>"KZSB -<65(=!V5UMrrLA?qu6]9=+UC&s/H$K~> -!ouXLrVlj<qYpWR7/HTV!W"#=rrGd@rr3"fK(f3FiB-r:!SKm>rrFS?rr3"DV"jrmpsqY'qu6Tq -*W?!@?bQL(1]IC^qYgC8s/(#?:<rj^r>YtHfDklVCA\#3WcRM+!K`9=rrN(ur>Ygmq#:B"C]485 -*U`q.?,-(4"c&BCs7@c>rrd5Er7aR:rrG7@rVm1AYQ#XC]jLeN\,QC1[:oSG_#F?=XDn4+7iWLI -oD\j9:](.m`E.WjJcD_LJ,~> -!ouXLrVlj<qYpWR7/HTV!W"#=rrGd@rr3"fK(f3FiB-r:!SKm>rrFS?rr3"DV"jrmpsqY'qu6Tq -*W?!@?bQL(1]IC^qYgC8s/(#?:<rj^r>YtHfDklVCA\#3WcRM+!K`9=rrN(ur>Ygmq#:B"C]485 -*U`q.?,-(4"c&BCs7@c>rrd5Er7aR:rrG7@rVm1AYQ#XC]jLeN\,QC1[:oSG_#F?=XDn4+7iWLI -oD\j9:](.m`E.WjJcD_LJ,~> -!ouXLrVlj<qYpWR7/HTV!W"#=rrGd@rr3"fK(f3FiB-r:!SKm>rrFS?rr3"DV"jrmpsqY'qu6Tq -*W?!@?bQL(1]IC^qYgC8s/(#?:<rj^r>YtHfDklVCA\#3WcRM+!K`9=rrN(ur>Ygmq#:B"C]485 -*U`q.?,-(4"c&BCs7@c>rrd5Er7aR:rrG7@rVm1AYQ#XC]jLeN\,QC1[:oSG_#F?=XDn4+7iWLI -oD\j9:](.m`E.WjJcD_LJ,~> -!ouXLrVlj<qu6]J7e?W\qBGn<!DCl?rrJR?pAY0P48]$YfgPf=!@c+hrrIA?rr3&lcfG')!Sfs< -rr=)<rrc]Bs62?;rsAZHs/(#?:<rM[rr3Mf37n31Z>0F>gA1dK\p3N,rs+XEs8UUKoAKTI!$1k7 -!O6G=rr=)4rrV!%r;HWr?,-(4"c&BCs7@c=rrPU@*W5pJ4Q6.is8Qu?ruM-Q?iO]Hrr3,/B`DAR -rr3,&E;rnYrr3#ejn8WSbtn9;!rAp@r;Qincf'HTJcE"TJ,~> -!ouXLrVlj<qu6]J7e?W\qBGn<!DCl?rrJR?pAY0P48]$YfgPf=!@c+hrrIA?rr3&lcfG')!Sfs< -rr=)<rrc]Bs62?;rsAZHs/(#?:<rM[rr3Mf37n31Z>0F>gA1dK\p3N,rs+XEs8UUKoAKTI!$1k7 -!O6G=rr=)4rrV!%r;HWr?,-(4"c&BCs7@c=rrPU@*W5pJ4Q6.is8Qu?ruM-Q?iO]Hrr3,/B`DAR -rr3,&E;rnYrr3#ejn8WSbtn9;!rAp@r;Qincf'HTJcE"TJ,~> -!ouXLrVlj<qu6]J7e?W\qBGn<!DCl?rrJR?pAY0P48]$YfgPf=!@c+hrrIA?rr3&lcfG')!Sfs< -rr=)<rrc]Bs62?;rsAZHs/(#?:<rM[rr3Mf37n31Z>0F>gA1dK\p3N,rs+XEs8UUKoAKTI!$1k7 -!O6G=rr=)4rrV!%r;HWr?,-(4"c&BCs7@c=rrPU@*W5pJ4Q6.is8Qu?ruM-Q?iO]Hrr3,/B`DAR -rr3,&E;rnYrr3#ejn8WSbtn9;!rAp@r;Qincf'HTJcE"TJ,~> -&*-#Ys3n9Z'XG$js8U/Gp@S@j_ljo_cN!oqT`24tMQ$:L"M:6SZI]$T#e?<UZIo3W.8^#L!I_`^ -rrU7AErH"=gd(f;!+#Q/"EMoikqi8;$2u%H_4Ua&cM1ZDZ3k[gfDklmGI"Mcl2L\`N0*E+#I/ug -Z<@4XE;d'B>PS4!Z"s=<!$1b4!_EC^rVln(^\.U1X,+'eY%dk7!dpbLr;R:NVPeS:s-]%U'XF*e -s-&cJZN$0ks,EHGZ36;Zs+m3EZ2ouZp&>';:]14ni]?u:!nmW^JcC<$Z2]=~> -&*-#Ys3n9Z'XG$js8U/Gp@S@j_ljo_cN!oqT`24tMQ$:L"M:6SZI]$T#e?<UZIo3W.8^#L!I_`^ -rrU7AErH"=gd(f;!+#Q/"EMoikqi8;$2u%H_4Ua&cM1ZDZ3k[gfDklmGI"Mcl2L\`N0*E+#I/ug -Z<@4XE;d'B>PS4!Z"s=<!$1b4!_EC^rVln(^\.U1X,+'eY%dk7!dpbLr;R:NVPeS:s-]%U'XF*e -s-&cJZN$0ks,EHGZ36;Zs+m3EZ2ouZp&>';:]14ni]?u:!nmW^JcC<$Z2]=~> -&*-#Ys3n9Z'XG$js8U/Gp@S@j_ljo_cN!oqT`24tMQ$:L"M:6SZI]$T#e?<UZIo3W.8^#L!I_`^ -rrU7AErH"=gd(f;!+#Q/"EMoikqi8;$2u%H_4Ua&cM1ZDZ3k[gfDklmGI"Mcl2L\`N0*E+#I/ug -Z<@4XE;d'B>PS4!Z"s=<!$1b4!_EC^rVln(^\.U1X,+'eY%dk7!dpbLr;R:NVPeS:s-]%U'XF*e -s-&cJZN$0ks,EHGZ36;Zs+m3EZ2ouZp&>';:]14ni]?u:!nmW^JcC<$Z2]=~> -"QVjNs/Gp1"JPkqP32B9!/UVg!2'8j!/(8b!i5k1qj%?1s8RBDB`P=8rr@0?B`tdBs+0V;B`P[A -rrV%kXSr/"l]1oC!;HG+"NUQBnq[/C!WIHErr\VIs60Gr!l^>crr3)9Bkc?#rrTfah<b.GXD)D; -s8U7?B`Rf#rrLNGrVlkDp&>)W'(Pr#"'oo4T_ABfVeKj`qu6\Hq>:0mH?oJh"INm3Boi8n!0dCr -!0mK_!07%m!1Eid!/^\h!1roa"/_B0:]14nOc0,:!pOEmJcC<$Z2]=~> -"QVjNs/Gp1"JPkqP32B9!/UVg!2'8j!/(8b!i5k1qj%?1s8RBDB`P=8rr@0?B`tdBs+0V;B`P[A -rrV%kXSr/"l]1oC!;HG+"NUQBnq[/C!WIHErr\VIs60Gr!l^>crr3)9Bkc?#rrTfah<b.GXD)D; -s8U7?B`Rf#rrLNGrVlkDp&>)W'(Pr#"'oo4T_ABfVeKj`qu6\Hq>:0mH?oJh"INm3Boi8n!0dCr -!0mK_!07%m!1Eid!/^\h!1roa"/_B0:]14nOc0,:!pOEmJcC<$Z2]=~> -"QVjNs/Gp1"JPkqP32B9!/UVg!2'8j!/(8b!i5k1qj%?1s8RBDB`P=8rr@0?B`tdBs+0V;B`P[A -rrV%kXSr/"l]1oC!;HG+"NUQBnq[/C!WIHErr\VIs60Gr!l^>crr3)9Bkc?#rrTfah<b.GXD)D; -s8U7?B`Rf#rrLNGrVlkDp&>)W'(Pr#"'oo4T_ABfVeKj`qu6\Hq>:0mH?oJh"INm3Boi8n!0dCr -!0mK_!07%m!1Eid!/^\h!1roa"/_B0:]14nOc0,:!pOEmJcC<$Z2]=~> -!ouXLg&D&Xqh5$jXoAF5fYd^i/+NT<"0mQ6OPKj9*SgYsQ\C-or;Qb\JcC<$VuM8~> -!ouXLg&D&Xqh5$jXoAF5fYd^i/+NT<"0mQ6OPKj9*SgYsQ\C-or;Qb\JcC<$VuM8~> -!ouXLg&D&Xqh5$jXoAF5fYd^i/+NT<"0mQ6OPKj9*SgYsQ\C-or;Qb\JcC<$VuM8~> -!ouXLJcEIa!fWE@eGfLhJcC<$JcGNFJ,~> -!ouXLJcEIa!fWE@eGfLhJcC<$JcGNFJ,~> -!ouXLJcEIa!fWE@eGfLhJcC<$JcGNFJ,~> -!ouXLJcEIa!RUJfrrBugs+13$s7lVE~> -!ouXLJcEIa!RUJfrrBugs+13$s7lVE~> -!ouXLJcEIa!RUJfrrBugs+13$s7lVE~> -!ouXLrr3't-73*urrYk?->%i/VuHj>-71q,rrYb<->A&2JcDGDJ,~> -!ouXLrr3't-73*urrYk?->%i/VuHj>-71q,rrYb<->A&2JcDGDJ,~> -!ouXLrr3't-73*urrYk?->%i/VuHj>-71q,rrYb<->A&2JcDGDJ,~> -!ouXLrr3'UiUusDrs(%<p%\ReoM>H+"C_!'=r@2X",R!J62hi)Dt`u+!V%uF*!C]as#M+t*!3#; -5lDZ''<(^+!:'M&".8rb)Z1QV`W%.\*!$Vlq>UKpc2AUb[/Bt%Y5TCHaoDD<V]6\VqtU0lr3?2? -"47(m&H*RN*rl,4r>Ygpq#:BkQMhd'mem(cnKn27"SQdS*96en!V^p>*!%tfr;Qr]1&q:ID#PCZ -7.^HYq"=;#o`#1Qo$gS;s)5IHo)Ae=s1<%Frr_uf`D;'bJcDGDJ,~> -!ouXLrr3'UiUusDrs(%<p%\ReoM>H+"C_!'=r@2X",R!J62hi)Dt`u+!V%uF*!C]as#M+t*!3#; -5lDZ''<(^+!:'M&".8rb)Z1QV`W%.\*!$Vlq>UKpc2AUb[/Bt%Y5TCHaoDD<V]6\VqtU0lr3?2? -"47(m&H*RN*rl,4r>Ygpq#:BkQMhd'mem(cnKn27"SQdS*96en!V^p>*!%tfr;Qr]1&q:ID#PCZ -7.^HYq"=;#o`#1Qo$gS;s)5IHo)Ae=s1<%Frr_uf`D;'bJcDGDJ,~> -!ouXLrr3'UiUusDrs(%<p%\ReoM>H+"C_!'=r@2X",R!J62hi)Dt`u+!V%uF*!C]as#M+t*!3#; -5lDZ''<(^+!:'M&".8rb)Z1QV`W%.\*!$Vlq>UKpc2AUb[/Bt%Y5TCHaoDD<V]6\VqtU0lr3?2? -"47(m&H*RN*rl,4r>Ygpq#:BkQMhd'mem(cnKn27"SQdS*96en!V^p>*!%tfr;Qr]1&q:ID#PCZ -7.^HYq"=;#o`#1Qo$gS;s)5IHo)Ae=s1<%Frr_uf`D;'bJcDGDJ,~> -!ouXLrr3!SlMLS^.eEW=!F3J?rrfBBs&7&:rrGd@rr3"fK)#?H3o^/="Gr?B1$eT6!pk9@q#:=7 -rVlt4[Jq9@rrV=od/!\BodB_<"@^r?ZYfX?#PtQEs8R)Bqt^6mdn0N<"!m]c;>^@o_HQp<!$1k7 -!O6G=rr=)<rsRa\$ig7pJueqO6eV87!K`<?rrM"?rVm)U2_"e,J"HZ>!R=I<rr=)3rrXeBdRsN= -!C,E2rrX;A\7GO;!R4Dks+13Ds*t~> -!ouXLrr3!SlMLS^.eEW=!F3J?rrfBBs&7&:rrGd@rr3"fK)#?H3o^/="Gr?B1$eT6!pk9@q#:=7 -rVlt4[Jq9@rrV=od/!\BodB_<"@^r?ZYfX?#PtQEs8R)Bqt^6mdn0N<"!m]c;>^@o_HQp<!$1k7 -!O6G=rr=)<rsRa\$ig7pJueqO6eV87!K`<?rrM"?rVm)U2_"e,J"HZ>!R=I<rr=)3rrXeBdRsN= -!C,E2rrX;A\7GO;!R4Dks+13Ds*t~> -!ouXLrr3!SlMLS^.eEW=!F3J?rrfBBs&7&:rrGd@rr3"fK)#?H3o^/="Gr?B1$eT6!pk9@q#:=7 -rVlt4[Jq9@rrV=od/!\BodB_<"@^r?ZYfX?#PtQEs8R)Bqt^6mdn0N<"!m]c;>^@o_HQp<!$1k7 -!O6G=rr=)<rsRa\$ig7pJueqO6eV87!K`<?rrM"?rVm)U2_"e,J"HZ>!R=I<rr=)3rrXeBdRsN= -!C,E2rrX;A\7GO;!R4Dks+13Ds*t~> -!ouXLrr3!SlMLS^.eEW=!F3J?rt2;Os&7%P[C+B]s*rr+s6>N>q#:@Uir8r\M3Irokl.sigACmN -QA>57!$2%<"D>.B*V99<!9="W!oJ@Aq#:Bf-iO&I7G$o\qu6of@a>#Rc!]u8rrLS?rVm!Gq9)Xm -rj;k&s2%t<rr=)7rrKB?rVlj<rr3DWCt]p0s1Eg>s8TE?q#:AVNW/qYh`^u=#KpH:.KBEtT)S`j -c;+<;!$1_3").AbJ,]HLGGkH=rrp[9]sY8prVlt,s36](rrLA?JcC<$U&TW~> -!ouXLrr3!SlMLS^.eEW=!F3J?rt2;Os&7%P[C+B]s*rr+s6>N>q#:@Uir8r\M3Irokl.sigACmN -QA>57!$2%<"D>.B*V99<!9="W!oJ@Aq#:Bf-iO&I7G$o\qu6of@a>#Rc!]u8rrLS?rVm!Gq9)Xm -rj;k&s2%t<rr=)7rrKB?rVlj<rr3DWCt]p0s1Eg>s8TE?q#:AVNW/qYh`^u=#KpH:.KBEtT)S`j -c;+<;!$1_3").AbJ,]HLGGkH=rrp[9]sY8prVlt,s36](rrLA?JcC<$U&TW~> -!ouXLrr3!SlMLS^.eEW=!F3J?rt2;Os&7%P[C+B]s*rr+s6>N>q#:@Uir8r\M3Irokl.sigACmN -QA>57!$2%<"D>.B*V99<!9="W!oJ@Aq#:Bf-iO&I7G$o\qu6of@a>#Rc!]u8rrLS?rVm!Gq9)Xm -rj;k&s2%t<rr=)7rrKB?rVlj<rr3DWCt]p0s1Eg>s8TE?q#:AVNW/qYh`^u=#KpH:.KBEtT)S`j -c;+<;!$1_3").AbJ,]HLGGkH=rrp[9]sY8prVlt,s36](rrLA?JcC<$U&TW~> -!ouXLrr3!SlMLS^.eEW=%U?jMs6409s&42YAnH;1rVlreMkg%H#s.)Gs4gM9s"TH2Ac[D5rVlrX -KX^^U!$2(="jT<>rtpjsAc[YJrr3)X=&duMrrMd?rr3/<.bF&Ai;T,MkPtS<GF=kBht[3Pdn0Q= -"g\s>b;"YKAcn:t_HQs=!N[(3rrKB?rr38#*WQ/eI*Va4rr3,/Kpe?Lp\u"jNW9%XL->S:_fb#3 -.KBEtT)\ibHqsV>!$1G+!ILR>rruGICM%1'an>Z7btiojJcDGDJ,~> -!ouXLrr3!SlMLS^.eEW=%U?jMs6409s&42YAnH;1rVlreMkg%H#s.)Gs4gM9s"TH2Ac[D5rVlrX -KX^^U!$2(="jT<>rtpjsAc[YJrr3)X=&duMrrMd?rr3/<.bF&Ai;T,MkPtS<GF=kBht[3Pdn0Q= -"g\s>b;"YKAcn:t_HQs=!N[(3rrKB?rr38#*WQ/eI*Va4rr3,/Kpe?Lp\u"jNW9%XL->S:_fb#3 -.KBEtT)\ibHqsV>!$1G+!ILR>rruGICM%1'an>Z7btiojJcDGDJ,~> -!ouXLrr3!SlMLS^.eEW=%U?jMs6409s&42YAnH;1rVlreMkg%H#s.)Gs4gM9s"TH2Ac[D5rVlrX -KX^^U!$2(="jT<>rtpjsAc[YJrr3)X=&duMrrMd?rr3/<.bF&Ai;T,MkPtS<GF=kBht[3Pdn0Q= -"g\s>b;"YKAcn:t_HQs=!N[(3rrKB?rr38#*WQ/eI*Va4rr3,/Kpe?Lp\u"jNW9%XL->S:_fb#3 -.KBEtT)\ibHqsV>!$1G+!ILR>rruGICM%1'an>Z7btiojJcDGDJ,~> -!ouXLrr3!SlMLS^.eEW=%^1>0I=>7;s/UbCs8Sj?rr3&pI\lc<$(cToI=F_Ms-e`BrrI\@rVlo) -C%hQ,NrFG1Il4Y6MO4>B!FNP>rrgr*Jq)eUrrMtIrd=s#,M2<!If=p)Idd<rItE9%jS8`Ul@Jq_ -"b@<^jat#ArrX;AiILoU!J(s[rrLf'rd>''*<4K;aoDA]rr3,:J:`B,p\t98J,Xj)E]sH>JD'tp -.KBF`J,XisBhnU+!$1D*!$2%<##o4*s8Sm?p&>';:P&Oss.TIC~> -!ouXLrr3!SlMLS^.eEW=%^1>0I=>7;s/UbCs8Sj?rr3&pI\lc<$(cToI=F_Ms-e`BrrI\@rVlo) -C%hQ,NrFG1Il4Y6MO4>B!FNP>rrgr*Jq)eUrrMtIrd=s#,M2<!If=p)Idd<rItE9%jS8`Ul@Jq_ -"b@<^jat#ArrX;AiILoU!J(s[rrLf'rd>''*<4K;aoDA]rr3,:J:`B,p\t98J,Xj)E]sH>JD'tp -.KBF`J,XisBhnU+!$1D*!$2%<##o4*s8Sm?p&>';:P&Oss.TIC~> -!ouXLrr3!SlMLS^.eEW=%^1>0I=>7;s/UbCs8Sj?rr3&pI\lc<$(cToI=F_Ms-e`BrrI\@rVlo) -C%hQ,NrFG1Il4Y6MO4>B!FNP>rrgr*Jq)eUrrMtIrd=s#,M2<!If=p)Idd<rItE9%jS8`Ul@Jq_ -"b@<^jat#ArrX;AiILoU!J(s[rrLf'rd>''*<4K;aoDA]rr3,:J:`B,p\t98J,Xj)E]sH>JD'tp -.KBF`J,XisBhnU+!$1D*!$2%<##o4*s8Sm?p&>';:P&Oss.TIC~> -!ouXLrr3!SlMLS^.eET<"h("oZ`A*CrrJm@rr3":Y4V_tWLf]sM3Ii:!J-d?rrV2$`qKE4rViAi -c"FH]rrHK?qu6[t`q]Q6nG]!_fgXN[*kVFO#sI26DSQ5O]l*B8rrD*YSc\%"q>:0o*WQ/qrgj/X -*V]R6f)D6Do,[k1/H0&a$[;WhJ(Xf$TR?M6(!<,>TAMg3LH/dO>n;nos21G"VTqs7rr=)*rrJR? -rr3!uaSu2?Uj;Y5!R4Dks+13Ds*t~> -!ouXLrr3!SlMLS^.eET<"h("oZ`A*CrrJm@rr3":Y4V_tWLf]sM3Ii:!J-d?rrV2$`qKE4rViAi -c"FH]rrHK?qu6[t`q]Q6nG]!_fgXN[*kVFO#sI26DSQ5O]l*B8rrD*YSc\%"q>:0o*WQ/qrgj/X -*V]R6f)D6Do,[k1/H0&a$[;WhJ(Xf$TR?M6(!<,>TAMg3LH/dO>n;nos21G"VTqs7rr=)*rrJR? -rr3!uaSu2?Uj;Y5!R4Dks+13Ds*t~> -!ouXLrr3!SlMLS^.eET<"h("oZ`A*CrrJm@rr3":Y4V_tWLf]sM3Ii:!J-d?rrV2$`qKE4rViAi -c"FH]rrHK?qu6[t`q]Q6nG]!_fgXN[*kVFO#sI26DSQ5O]l*B8rrD*YSc\%"q>:0o*WQ/qrgj/X -*V]R6f)D6Do,[k1/H0&a$[;WhJ(Xf$TR?M6(!<,>TAMg3LH/dO>n;nos21G"VTqs7rr=)*rrJR? -rr3!uaSu2?Uj;Y5!R4Dks+13Ds*t~> -!ouXLrr3!SlMLS^.eEH8!NU5;rro0Ds8Q]>n,EEFPPb@\JXl`>!ROO0rrHc?qu6\(^&.g1<lXb2 -"%Ci/0`D"R4l><[rVlmUkk"fT,l.?;!$1q9!$1Y1!Zh=)rON+H`;cKXrr3#g/G&lDh`_"srji0: -*mOT^!R=I<rr=)*rs&7lJcGaLaSu2?Uj;Y5!R4Dks+13Ds*t~> -!ouXLrr3!SlMLS^.eEH8!NU5;rro0Ds8Q]>n,EEFPPb@\JXl`>!ROO0rrHc?qu6\(^&.g1<lXb2 -"%Ci/0`D"R4l><[rVlmUkk"fT,l.?;!$1q9!$1Y1!Zh=)rON+H`;cKXrr3#g/G&lDh`_"srji0: -*mOT^!R=I<rr=)*rs&7lJcGaLaSu2?Uj;Y5!R4Dks+13Ds*t~> -!ouXLrr3!SlMLS^.eEH8!NU5;rro0Ds8Q]>n,EEFPPb@\JXl`>!ROO0rrHc?qu6\(^&.g1<lXb2 -"%Ci/0`D"R4l><[rVlmUkk"fT,l.?;!$1q9!$1Y1!Zh=)rON+H`;cKXrr3#g/G&lDh`_"srji0: -*mOT^!R=I<rr=)*rs&7lJcGaLaSu2?Uj;Y5!R4Dks+13Ds*t~> -!ouXLrr3!SlMLS^.eEK9"jpfCs)6?brro0Ds(Jn>qYpWa.;\k\"grXDs&/:ars"%Es8VR[iqr`W -cmaeIrre^NoD_,TrrZWAs$?V`!ER5>rrTPVV>C2pI&Hf-0`D"X4l?.@E<#rUZMXY$!gkFQqYp\* -^AcSurVlj<qu6[obPhGBHR[hJrrGL?qu6sCs8VS?WW2u_h>R?T?RbjKrrW-`i;ETUoI9\;!q&\@ -r;Qa;qu6[Y8Flcaa]&6><65(=!Mk#6rrLA?JcC<$U&TW~> -!ouXLrr3!SlMLS^.eEK9"jpfCs)6?brro0Ds(Jn>qYpWa.;\k\"grXDs&/:ars"%Es8VR[iqr`W -cmaeIrre^NoD_,TrrZWAs$?V`!ER5>rrTPVV>C2pI&Hf-0`D"X4l?.@E<#rUZMXY$!gkFQqYp\* -^AcSurVlj<qu6[obPhGBHR[hJrrGL?qu6sCs8VS?WW2u_h>R?T?RbjKrrW-`i;ETUoI9\;!q&\@ -r;Qa;qu6[Y8Flcaa]&6><65(=!Mk#6rrLA?JcC<$U&TW~> -!ouXLrr3!SlMLS^.eEK9"jpfCs)6?brro0Ds(Jn>qYpWa.;\k\"grXDs&/:ars"%Es8VR[iqr`W -cmaeIrre^NoD_,TrrZWAs$?V`!ER5>rrTPVV>C2pI&Hf-0`D"X4l?.@E<#rUZMXY$!gkFQqYp\* -^AcSurVlj<qu6[obPhGBHR[hJrrGL?qu6sCs8VS?WW2u_h>R?T?RbjKrrW-`i;ETUoI9\;!q&\@ -r;Qa;qu6[Y8Flcaa]&6><65(=!Mk#6rrLA?JcC<$U&TW~> -!ouXLrr3'Uh!jt7rrXb3nFZ_[#ZMc`9(r;bp.>6'"D[`3<Z:oV!0I3[!p^7krVm-\*#rScs8VaD -rYu)rqZ$T`48SsYb6i:hrrDop*!Cojs8V9\*!;u6s5<hq!NQ(srrT5,PlC[_h#88rTD\`gb5E:c -^]"31WuN+^r;HWsM[$WhrrBe4*!EqQs89%u*!>!rs0)DA!QtE?rrQs=fDbdMT`,o2f_YUJ/,oPO -q/RGpkPY>]9EP%hrrdon*$4bLrrMaLrr3+B*#pR'rr3)nnF.IqrrF>jo)AmkXapFYbPqMBWIagD -"7krt:P&Oss.TIC~> -!ouXLrr3'Uh!jt7rrXb3nFZ_[#ZMc`9(r;bp.>6'"D[`3<Z:oV!0I3[!p^7krVm-\*#rScs8VaD -rYu)rqZ$T`48SsYb6i:hrrDop*!Cojs8V9\*!;u6s5<hq!NQ(srrT5,PlC[_h#88rTD\`gb5E:c -^]"31WuN+^r;HWsM[$WhrrBe4*!EqQs89%u*!>!rs0)DA!QtE?rrQs=fDbdMT`,o2f_YUJ/,oPO -q/RGpkPY>]9EP%hrrdon*$4bLrrMaLrr3+B*#pR'rr3)nnF.IqrrF>jo)AmkXapFYbPqMBWIagD -"7krt:P&Oss.TIC~> -!ouXLrr3'Uh!jt7rrXb3nFZ_[#ZMc`9(r;bp.>6'"D[`3<Z:oV!0I3[!p^7krVm-\*#rScs8VaD -rYu)rqZ$T`48SsYb6i:hrrDop*!Cojs8V9\*!;u6s5<hq!NQ(srrT5,PlC[_h#88rTD\`gb5E:c -^]"31WuN+^r;HWsM[$WhrrBe4*!EqQs89%u*!>!rs0)DA!QtE?rrQs=fDbdMT`,o2f_YUJ/,oPO -q/RGpkPY>]9EP%hrrdon*$4bLrrMaLrr3+B*#pR'rr3)nnF.IqrrF>jo)AmkXapFYbPqMBWIagD -"7krt:P&Oss.TIC~> -!ouXLrr3(#.k>-.rrZ"H.r+/F!R+C#rrK-?j8T.9PiMcEB=?k#!CbW#rrFA?k5PO+.k=!arrMm@ -h>[RM.k>Ifs+13Ds*t~> -!ouXLrr3(#.k>-.rrZ"H.r+/F!R+C#rrK-?j8T.9PiMcEB=?k#!CbW#rrFA?k5PO+.k=!arrMm@ -h>[RM.k>Ifs+13Ds*t~> -!ouXLrr3(#.k>-.rrZ"H.r+/F!R+C#rrK-?j8T.9PiMcEB=?k#!CbW#rrFA?k5PO+.k=!arrMm@ -h>[RM.k>Ifs+13Ds*t~> -!ouXLf)GgITn2;)!q2;?jSo;DK<jS<!o8"AjSo;1B&htP!m4UAh#@Dd@Y+Q1s+14Gs*t~> -!ouXLf)GgITn2;)!q2;?jSo;DK<jS<!o8"AjSo;1B&htP!m4UAh#@Dd@Y+Q1s+14Gs*t~> -!ouXLf)GgITn2;)!q2;?jSo;DK<jS<!o8"AjSo;1B&htP!m4UAh#@Dd@Y+Q1s+14Gs*t~> -!ouXLf)GdAK&ck3h3[1%!QhG'rrKLBj8T.Pe`6Z1MsB's!-NkmJcC<$q#>j~> -!ouXLf)GdAK&ck3h3[1%!QhG'rrKLBj8T.Pe`6Z1MsB's!-NkmJcC<$q#>j~> -!ouXLf)GdAK&ck3h3[1%!QhG'rrKLBj8T.Pe`6Z1MsB's!-NkmJcC<$q#>j~> -!ouXLL&V1cdZa\2NkPGmp\oXB_RKOFg\u[&hYmHTaMn&V!Q<*2s-Nb9~> -!ouXLL&V1cdZa\2NkPGmp\oXB_RKOFg\u[&hYmHTaMn&V!Q<*2s-Nb9~> -!ouXLL&V1cdZa\2NkPGmp\oXB_RKOFg\u[&hYmHTaMn&V!Q<*2s-Nb9~> -"lqsOs8S>_@fVJerrJ2Co)A`3GfB[_Fl<9$^4G)<rrUAR]C#V#c!t8,r;Qi,A'k5T!S*h3rrSHq -B[m%_G,G3;",$1/N;ih\O(7qad\H:2"b:Cgs2))8rr[EDb,b79"R[8"SC%98#OmHI]"7qAr;L1+ -Xks'Xj8EHfg%PFR`if?(j8]/>S=DXRrVlrKIEMKf!muA@JcD,;J,~> -"lqsOs8S>_@fVJerrJ2Co)A`3GfB[_Fl<9$^4G)<rrUAR]C#V#c!t8,r;Qi,A'k5T!S*h3rrSHq -B[m%_G,G3;",$1/N;ih\O(7qad\H:2"b:Cgs2))8rr[EDb,b79"R[8"SC%98#OmHI]"7qAr;L1+ -Xks'Xj8EHfg%PFR`if?(j8]/>S=DXRrVlrKIEMKf!muA@JcD,;J,~> -"lqsOs8S>_@fVJerrJ2Co)A`3GfB[_Fl<9$^4G)<rrUAR]C#V#c!t8,r;Qi,A'k5T!S*h3rrSHq -B[m%_G,G3;",$1/N;ih\O(7qad\H:2"b:Cgs2))8rr[EDb,b79"R[8"SC%98#OmHI]"7qAr;L1+ -Xks'Xj8EHfg%PFR`if?(j8]/>S=DXRrVlrKIEMKf!muA@JcD,;J,~> -"lqsOs-ArL\-AC]s8U8Gp@J:b^VS_*!V0skrr=(trrJC?r;Qi]\DZcS"6d6nWVlbthRMhLrrK]? -nc&`YPdn,0hZ!V$j8/cV*rc*;$o@/%6N@(IR(-<![:oR>!FYftrs!qIZ=X'*JbK*G*WN'\pAY0] -0)PYRju37"NrT,`rjVu\[,Crbo3D7(!Ft<errf'Bs%:`;rrHK?r;Qe>W;HSqCpAQkR/_[~> -"lqsOs-ArL\-AC]s8U8Gp@J:b^VS_*!V0skrr=(trrJC?r;Qi]\DZcS"6d6nWVlbthRMhLrrK]? -nc&`YPdn,0hZ!V$j8/cV*rc*;$o@/%6N@(IR(-<![:oR>!FYftrs!qIZ=X'*JbK*G*WN'\pAY0] -0)PYRju37"NrT,`rjVu\[,Crbo3D7(!Ft<errf'Bs%:`;rrHK?r;Qe>W;HSqCpAQkR/_[~> -"lqsOs-ArL\-AC]s8U8Gp@J:b^VS_*!V0skrr=(trrJC?r;Qi]\DZcS"6d6nWVlbthRMhLrrK]? -nc&`YPdn,0hZ!V$j8/cV*rc*;$o@/%6N@(IR(-<![:oR>!FYftrs!qIZ=X'*JbK*G*WN'\pAY0] -0)PYRju37"NrT,`rjVu\[,Crbo3D7(!Ft<errf'Bs%:`;rrHK?r;Qe>W;HSqCpAQkR/_[~> -"lqsOs)#">rrKc?rr3#R6HoH1m4[i+!$1%u!l&a@j8T.$WV6>m\mk40"E(CBpa"_r!CYT;rrHE@ -qu7'\l.SK(s(/\>b:?iZrr3!CqXsjm9[NaJ.rFSFrrX;AW-.h6!U_T;rs.[Es,N->ruM+=!JZs! -rrW,+CB"56hYHpG"JU5B9%*Y;!FNP<rrV@pci!eEk$Q\js-`n;~> -"lqsOs)#">rrKc?rr3#R6HoH1m4[i+!$1%u!l&a@j8T.$WV6>m\mk40"E(CBpa"_r!CYT;rrHE@ -qu7'\l.SK(s(/\>b:?iZrr3!CqXsjm9[NaJ.rFSFrrX;AW-.h6!U_T;rs.[Es,N->ruM+=!JZs! -rrW,+CB"56hYHpG"JU5B9%*Y;!FNP<rrV@pci!eEk$Q\js-`n;~> -"lqsOs)#">rrKc?rr3#R6HoH1m4[i+!$1%u!l&a@j8T.$WV6>m\mk40"E(CBpa"_r!CYT;rrHE@ -qu7'\l.SK(s(/\>b:?iZrr3!CqXsjm9[NaJ.rFSFrrX;AW-.h6!U_T;rs.[Es,N->ruM+=!JZs! -rrW,+CB"56hYHpG"JU5B9%*Y;!FNP<rrV@pci!eEk$Q\js-`n;~> -$KOKTs7Z<hs3js?rVlrY6h^6R!_aRerVlol6N.r*EV]V6!p^A$rr3!gf_uj%J,91/m/R*]LB%9= -)?h*#PkY1Xn,44/S,<4+cMedcU\t/Xr>Z3Fr;JVFV]6\]rVt:D*!NkNs8TB>r;QlD*#=n?rrN)2 -r>Yj_rq??mF/f-<"0W[Z[f6:.\m:*j*!#='rrQ^Air/l^DQa$>o)JQDrYuV$o`(\EnkpG]p&C<n -*5aNjp&G&<rYu2-pA^*l#8eFOrVlm\iVWWkoD\^\s8Vfis8MN[s8R!W"<8Cns8VdbrYuMaq#C!a -s8DH\s8PmA,9.\Iq>UBrnc/I[pAY0]0)PYRrU^'aq#C@7rpg2AQiI(9rVm%8_#OG]>5\C+/,u]" -s'!eLdet-g\,H<I&cNaP^A\&Lr>Z*^rr<#op]'m`r;Qe)^&.g1=2t.;!D^pks-`n;~> -$KOKTs7Z<hs3js?rVlrY6h^6R!_aRerVlol6N.r*EV]V6!p^A$rr3!gf_uj%J,91/m/R*]LB%9= -)?h*#PkY1Xn,44/S,<4+cMedcU\t/Xr>Z3Fr;JVFV]6\]rVt:D*!NkNs8TB>r;QlD*#=n?rrN)2 -r>Yj_rq??mF/f-<"0W[Z[f6:.\m:*j*!#='rrQ^Air/l^DQa$>o)JQDrYuV$o`(\EnkpG]p&C<n -*5aNjp&G&<rYu2-pA^*l#8eFOrVlm\iVWWkoD\^\s8Vfis8MN[s8R!W"<8Cns8VdbrYuMaq#C!a -s8DH\s8PmA,9.\Iq>UBrnc/I[pAY0]0)PYRrU^'aq#C@7rpg2AQiI(9rVm%8_#OG]>5\C+/,u]" -s'!eLdet-g\,H<I&cNaP^A\&Lr>Z*^rr<#op]'m`r;Qe)^&.g1=2t.;!D^pks-`n;~> -$KOKTs7Z<hs3js?rVlrY6h^6R!_aRerVlol6N.r*EV]V6!p^A$rr3!gf_uj%J,91/m/R*]LB%9= -)?h*#PkY1Xn,44/S,<4+cMedcU\t/Xr>Z3Fr;JVFV]6\]rVt:D*!NkNs8TB>r;QlD*#=n?rrN)2 -r>Yj_rq??mF/f-<"0W[Z[f6:.\m:*j*!#='rrQ^Air/l^DQa$>o)JQDrYuV$o`(\EnkpG]p&C<n -*5aNjp&G&<rYu2-pA^*l#8eFOrVlm\iVWWkoD\^\s8Vfis8MN[s8R!W"<8Cns8VdbrYuMaq#C!a -s8DH\s8PmA,9.\Iq>UBrnc/I[pAY0]0)PYRrU^'aq#C@7rpg2AQiI(9rVm%8_#OG]>5\C+/,u]" -s'!eLdet-g\,H<I&cNaP^A\&Lr>Z*^rr<#op]'m`r;Qe)^&.g1=2t.;!D^pks-`n;~> -!ouXLrVloJ8c&Gfd7a04!W"#=rrGd@rr3"fK)YcOm3ulNrrG/,rr37\PQ*B's8S[>rr3#d0D,8E -*W?!@JAM6u:&b.n?bQ@:$Wb:Ii!OT+s%^l4-iO&KA)71bZ>079!K<->rrLn@rVlmLnFlk_F/f': -!Gf"?rrTbCPlC[_*W?!JF=H>Os7+ZGP1KO1s.Fc=rt4`Os8REaaoCN]s,`6?39B$\qu6]J7fNDg -7+hD:!Bf?,rrF>?rVlmtaSu2?ZB"_[#"'X1s8S:?n,EFV0(f/D)ZD/q'pnt#5McA>l>"B>s34C< -rs0\GVfi#8c1WL_rrYdBmP"P="$YT'2uWaW<pTGY!FNP;rrH3@qu6[lc@Q"`s*t~> -!ouXLrVloJ8c&Gfd7a04!W"#=rrGd@rr3"fK)YcOm3ulNrrG/,rr37\PQ*B's8S[>rr3#d0D,8E -*W?!@JAM6u:&b.n?bQ@:$Wb:Ii!OT+s%^l4-iO&KA)71bZ>079!K<->rrLn@rVlmLnFlk_F/f': -!Gf"?rrTbCPlC[_*W?!JF=H>Os7+ZGP1KO1s.Fc=rt4`Os8REaaoCN]s,`6?39B$\qu6]J7fNDg -7+hD:!Bf?,rrF>?rVlmtaSu2?ZB"_[#"'X1s8S:?n,EFV0(f/D)ZD/q'pnt#5McA>l>"B>s34C< -rs0\GVfi#8c1WL_rrYdBmP"P="$YT'2uWaW<pTGY!FNP;rrH3@qu6[lc@Q"`s*t~> -!ouXLrVloJ8c&Gfd7a04!W"#=rrGd@rr3"fK)YcOm3ulNrrG/,rr37\PQ*B's8S[>rr3#d0D,8E -*W?!@JAM6u:&b.n?bQ@:$Wb:Ii!OT+s%^l4-iO&KA)71bZ>079!K<->rrLn@rVlmLnFlk_F/f': -!Gf"?rrTbCPlC[_*W?!JF=H>Os7+ZGP1KO1s.Fc=rt4`Os8REaaoCN]s,`6?39B$\qu6]J7fNDg -7+hD:!Bf?,rrF>?rVlmtaSu2?ZB"_[#"'X1s8S:?n,EFV0(f/D)ZD/q'pnt#5McA>l>"B>s34C< -rs0\GVfi#8c1WL_rrYdBmP"P="$YT'2uWaW<pTGY!FNP;rrH3@qu6[lc@Q"`s*t~> -!ouXLrr3#?<Vl^sqPAT4rrMs?rVlmkdf07IRY(>7!BT6>rs4IFs"Wj>s.4]=rrML?o`"n3qYpO9 -rVlt,^&Rp,\cb7;s56$=rr[`)pfIF*!:9^b!O?J:rrJ(?rr3#S62gfa/F`B5!HY7;rrHo@rr3#1 -@f?<,*VfX@^dT:t7IU9VTR?b='_![Rs*LL?s6a\&OH'9"jki6$s4@7]!M)^ZrrGO?qu6[ZiTpLE -,5V9<!J7$E\cC4RrrGL?rr3"_MXUQGmOn/3!$2(=$&4fHs7.Z>s*^O=rrLA@r;R$Ds/1#>:X/S[ -rVlsif'Y3irrYIAlsB\&!9s+T!FNP;rrH3@qu6[lc@Q"`s*t~> -!ouXLrr3#?<Vl^sqPAT4rrMs?rVlmkdf07IRY(>7!BT6>rs4IFs"Wj>s.4]=rrML?o`"n3qYpO9 -rVlt,^&Rp,\cb7;s56$=rr[`)pfIF*!:9^b!O?J:rrJ(?rr3#S62gfa/F`B5!HY7;rrHo@rr3#1 -@f?<,*VfX@^dT:t7IU9VTR?b='_![Rs*LL?s6a\&OH'9"jki6$s4@7]!M)^ZrrGO?qu6[ZiTpLE -,5V9<!J7$E\cC4RrrGL?rr3"_MXUQGmOn/3!$2(=$&4fHs7.Z>s*^O=rrLA@r;R$Ds/1#>:X/S[ -rVlsif'Y3irrYIAlsB\&!9s+T!FNP;rrH3@qu6[lc@Q"`s*t~> -!ouXLrr3#?<Vl^sqPAT4rrMs?rVlmkdf07IRY(>7!BT6>rs4IFs"Wj>s.4]=rrML?o`"n3qYpO9 -rVlt,^&Rp,\cb7;s56$=rr[`)pfIF*!:9^b!O?J:rrJ(?rr3#S62gfa/F`B5!HY7;rrHo@rr3#1 -@f?<,*VfX@^dT:t7IU9VTR?b='_![Rs*LL?s6a\&OH'9"jki6$s4@7]!M)^ZrrGO?qu6[ZiTpLE -,5V9<!J7$E\cC4RrrGL?rr3"_MXUQGmOn/3!$2(=$&4fHs7.Z>s*^O=rrLA@r;R$Ds/1#>:X/S[ -rVlsif'Y3irrYIAlsB\&!9s+T!FNP;rrH3@qu6[lc@Q"`s*t~> -#NS0Qs8T`Ko(r@eT76G4!W"#=rrGd@rr3"fK)#?H3o^/=#`4cF1$el>Spp\=!UVQ4rr=)9rr=)< -rrZWAs-rsq"<kebi&po:!9a;h"c`$Os0?D9rrJ(?rr3#S62gfa/F`B5!HY7;rrHo@rr3#1@f?<, -*VTL6DQ`s<!MFi>rrqmCs8RG?r;R(bNW2!"h`_"eHN%=R;+CQb!CYT;rrG7@li-u0qY^?nKDo9[ -GKfj^!CPQ>rrJ=@n,EFV0(f/D*WH'FL6qr?pM7=mJ&M?d!R4I=rs0\GVfi#8c1WL_rrYdBmP"P= -"$YT7OoAbhbk(i8?bQ@:!E[;<rrGm?JcD/<J,~> -#NS0Qs8T`Ko(r@eT76G4!W"#=rrGd@rr3"fK)#?H3o^/=#`4cF1$el>Spp\=!UVQ4rr=)9rr=)< -rrZWAs-rsq"<kebi&po:!9a;h"c`$Os0?D9rrJ(?rr3#S62gfa/F`B5!HY7;rrHo@rr3#1@f?<, -*VTL6DQ`s<!MFi>rrqmCs8RG?r;R(bNW2!"h`_"eHN%=R;+CQb!CYT;rrG7@li-u0qY^?nKDo9[ -GKfj^!CPQ>rrJ=@n,EFV0(f/D*WH'FL6qr?pM7=mJ&M?d!R4I=rs0\GVfi#8c1WL_rrYdBmP"P= -"$YT7OoAbhbk(i8?bQ@:!E[;<rrGm?JcD/<J,~> -#NS0Qs8T`Ko(r@eT76G4!W"#=rrGd@rr3"fK)#?H3o^/=#`4cF1$el>Spp\=!UVQ4rr=)9rr=)< -rrZWAs-rsq"<kebi&po:!9a;h"c`$Os0?D9rrJ(?rr3#S62gfa/F`B5!HY7;rrHo@rr3#1@f?<, -*VTL6DQ`s<!MFi>rrqmCs8RG?r;R(bNW2!"h`_"eHN%=R;+CQb!CYT;rrG7@li-u0qY^?nKDo9[ -GKfj^!CPQ>rrJ=@n,EFV0(f/D*WH'FL6qr?pM7=mJ&M?d!R4I=rs0\GVfi#8c1WL_rrYdBmP"P= -"$YT7OoAbhbk(i8?bQ@:!E[;<rrGm?JcD/<J,~> -#38'Ps0mL>qYpS^L@bEGqBGn<!DCl?rrJR?rr3&lJuSbL!BP?%rs4IFs"Wj>s.4]=rrqdCs8Td\ -q#:=7rVlu-g]&;mrrZWAruM+="hQ>*s56$;rrMt]rVm'jfDkm'J&M6a!K<->rrLn@rVlmLnFlk_ -F/f':!Gf"?rrTbe_>aH7*W?!>Y(H0ArrI#?rVlnkI/a-Ln1=V>H_UH<%Zl\M39B$\s+cm>s7pM$ -rr3*hf`1-5rr3%hJc>$9#9s$Ef"(g]jSo/[Uj;b8!CPQ>rrJ=@pAY3]K!G:S!U_T4rr=)=rrIk@ -rr3)N8",&.rt!@Ns1?e\ruV3<FoP7^p*Tb<"%Ur10E(nQ52PB[rVlngoC`+a?bQC;!kWsAr;Qi- -J*-\/!jdLEJcDGDJ,~> -#38'Ps0mL>qYpS^L@bEGqBGn<!DCl?rrJR?rr3&lJuSbL!BP?%rs4IFs"Wj>s.4]=rrqdCs8Td\ -q#:=7rVlu-g]&;mrrZWAruM+="hQ>*s56$;rrMt]rVm'jfDkm'J&M6a!K<->rrLn@rVlmLnFlk_ -F/f':!Gf"?rrTbe_>aH7*W?!>Y(H0ArrI#?rVlnkI/a-Ln1=V>H_UH<%Zl\M39B$\s+cm>s7pM$ -rr3*hf`1-5rr3%hJc>$9#9s$Ef"(g]jSo/[Uj;b8!CPQ>rrJ=@pAY3]K!G:S!U_T4rr=)=rrIk@ -rr3)N8",&.rt!@Ns1?e\ruV3<FoP7^p*Tb<"%Ur10E(nQ52PB[rVlngoC`+a?bQC;!kWsAr;Qi- -J*-\/!jdLEJcDGDJ,~> -#38'Ps0mL>qYpS^L@bEGqBGn<!DCl?rrJR?rr3&lJuSbL!BP?%rs4IFs"Wj>s.4]=rrqdCs8Td\ -q#:=7rVlu-g]&;mrrZWAruM+="hQ>*s56$;rrMt]rVm'jfDkm'J&M6a!K<->rrLn@rVlmLnFlk_ -F/f':!Gf"?rrTbe_>aH7*W?!>Y(H0ArrI#?rVlnkI/a-Ln1=V>H_UH<%Zl\M39B$\s+cm>s7pM$ -rr3*hf`1-5rr3%hJc>$9#9s$Ef"(g]jSo/[Uj;b8!CPQ>rrJ=@pAY3]K!G:S!U_T4rr=)=rrIk@ -rr3)N8",&.rt!@Ns1?e\ruV3<FoP7^p*Tb<"%Ur10E(nQ52PB[rVlngoC`+a?bQC;!kWsAr;Qi- -J*-\/!jdLEJcDGDJ,~> -"lqsOs(t7(Ad+k-s,iH?o`#2OA.E4Bs8TQHral1Wc2R_Ekl=QZrrG0:ralakeGlXcAnH==_uKc3 -OCi*Ug\CdKUA\[+K]2qOrVlt,^&OGuAd*cC`rFsZr;QfpOo8kmMspZF!L8H=rs7Fm3'([/s7)'H -Ac\"hq#:rOAhHJ`n,NF0Ah-A`o`)KaJ,X$[TDeck=odLZrrI#?rVloOJGs-aBrh:6H_UH<%Zl\M -YOp^8s3H%(AnZ`brr3,.DJ!jtrVlm>rp9XiVe9Uc`rEYjral1UanYl:6eVJ=!L&E7rrUmS@/^*+ -mOn/3!2BI)!IiSurr_\IHHlEg&*o'aK&$D+P@d08Ar5jNOo8koMsgA%rFQ.ko(A%AAc[qbp&>&" -^&7m2FK#*:!Go%<rrQ[1eq*jps*t~> -"lqsOs(t7(Ad+k-s,iH?o`#2OA.E4Bs8TQHral1Wc2R_Ekl=QZrrG0:ralakeGlXcAnH==_uKc3 -OCi*Ug\CdKUA\[+K]2qOrVlt,^&OGuAd*cC`rFsZr;QfpOo8kmMspZF!L8H=rs7Fm3'([/s7)'H -Ac\"hq#:rOAhHJ`n,NF0Ah-A`o`)KaJ,X$[TDeck=odLZrrI#?rVloOJGs-aBrh:6H_UH<%Zl\M -YOp^8s3H%(AnZ`brr3,.DJ!jtrVlm>rp9XiVe9Uc`rEYjral1UanYl:6eVJ=!L&E7rrUmS@/^*+ -mOn/3!2BI)!IiSurr_\IHHlEg&*o'aK&$D+P@d08Ar5jNOo8koMsgA%rFQ.ko(A%AAc[qbp&>&" -^&7m2FK#*:!Go%<rrQ[1eq*jps*t~> -"lqsOs(t7(Ad+k-s,iH?o`#2OA.E4Bs8TQHral1Wc2R_Ekl=QZrrG0:ralakeGlXcAnH==_uKc3 -OCi*Ug\CdKUA\[+K]2qOrVlt,^&OGuAd*cC`rFsZr;QfpOo8kmMspZF!L8H=rs7Fm3'([/s7)'H -Ac\"hq#:rOAhHJ`n,NF0Ah-A`o`)KaJ,X$[TDeck=odLZrrI#?rVloOJGs-aBrh:6H_UH<%Zl\M -YOp^8s3H%(AnZ`brr3,.DJ!jtrVlm>rp9XiVe9Uc`rEYjral1UanYl:6eVJ=!L&E7rrUmS@/^*+ -mOn/3!2BI)!IiSurr_\IHHlEg&*o'aK&$D+P@d08Ar5jNOo8koMsgA%rFQ.ko(A%AAc[qbp&>&" -^&7m2FK#*:!Go%<rrQ[1eq*jps*t~> -"QVjNs4.%T"O[8Lb4G6)!6+rF!7:`F!5e`C!7LiG!r97Jrr3![ir6=cfDbdR]=#&og>`,3"nB". -h#DQp8cls2rVa,+iW&qlrVluIm/Qn\[0>C3mf3"#qu6ZgrNuXkrVlrWI)#[\!:Tlo"7Z?jm/=<m -o(DiO!rDr[rNub%s8V3Z[06@+ldFMd[/g.'rrUNSpAP!le`Zl1!8IL\!4i+/!SQQ3rrM$6rr3;u -a8c1h[C*O9ao25@^pV)XrrKi?li.$p[E\^N!6+rF!7:K?!Qk!5rrM'6pAY3dL1'u["RZ^k8u_Rb -!<2u*!8.5L!UA,1rrVDlh>[E[p9f'B[HRYjo_l0"li7"TrNuaps8VQd[/f[irrgP<8fYPCrrTHY -k5>5\X,-!:rrUWVo7?q8s*t~> -"QVjNs4.%T"O[8Lb4G6)!6+rF!7:`F!5e`C!7LiG!r97Jrr3![ir6=cfDbdR]=#&og>`,3"nB". -h#DQp8cls2rVa,+iW&qlrVluIm/Qn\[0>C3mf3"#qu6ZgrNuXkrVlrWI)#[\!:Tlo"7Z?jm/=<m -o(DiO!rDr[rNub%s8V3Z[06@+ldFMd[/g.'rrUNSpAP!le`Zl1!8IL\!4i+/!SQQ3rrM$6rr3;u -a8c1h[C*O9ao25@^pV)XrrKi?li.$p[E\^N!6+rF!7:K?!Qk!5rrM'6pAY3dL1'u["RZ^k8u_Rb -!<2u*!8.5L!UA,1rrVDlh>[E[p9f'B[HRYjo_l0"li7"TrNuaps8VQd[/f[irrgP<8fYPCrrTHY -k5>5\X,-!:rrUWVo7?q8s*t~> -"QVjNs4.%T"O[8Lb4G6)!6+rF!7:`F!5e`C!7LiG!r97Jrr3![ir6=cfDbdR]=#&og>`,3"nB". -h#DQp8cls2rVa,+iW&qlrVluIm/Qn\[0>C3mf3"#qu6ZgrNuXkrVlrWI)#[\!:Tlo"7Z?jm/=<m -o(DiO!rDr[rNub%s8V3Z[06@+ldFMd[/g.'rrUNSpAP!le`Zl1!8IL\!4i+/!SQQ3rrM$6rr3;u -a8c1h[C*O9ao25@^pV)XrrKi?li.$p[E\^N!6+rF!7:K?!Qk!5rrM'6pAY3dL1'u["RZ^k8u_Rb -!<2u*!8.5L!UA,1rrVDlh>[E[p9f'B[HRYjo_l0"li7"TrNuaps8VQd[/f[irrgP<8fYPCrrTHY -k5>5\X,-!:rrUWVo7?q8s*t~> -!ouXLd/O,-ip?[Fh##J!nC@O>kO7p?!;u]@!<0,#!7o'f!PDh=rrDurd/`FerrK$?h>[KGrm:`; -rVloalMLS^lKj*%QiDR~> -!ouXLd/O,-ip?[Fh##J!nC@O>kO7p?!;u]@!<0,#!7o'f!PDh=rrDurd/`FerrK$?h>[KGrm:`; -rVloalMLS^lKj*%QiDR~> -!ouXLd/O,-ip?[Fh##J!nC@O>kO7p?!;u]@!<0,#!7o'f!PDh=rrDurd/`FerrK$?h>[KGrm:`; -rVloalMLS^lKj*%QiDR~> -!ouXLd/O,5jFR>grrV%Uo[NmAWdB<sJcF[.J,~> -!ouXLd/O,5jFR>grrV%Uo[NmAWdB<sJcF[.J,~> -!ouXLd/O,5jFR>grrV%Uo[NmAWdB<sJcF[.J,~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -#in9Rs8UK[]uSt/!65#O!82r'JcC<$JcE(VJ,~> -#in9Rs8UK[]uSt/!65#O!82r'JcC<$JcE(VJ,~> -#in9Rs8UK[]uSt/!65#O!82r'JcC<$JcE(VJ,~> -$04BSs2f=g?>-n,rrKZDra#VPe:IXNs+13$s0VfV~> -$04BSs2f=g?>-n,rrKZDra#VPe:IXNs+13$s0VfV~> -$04BSs2f=g?>-n,rrKZDra#VPe:IXNs+13$s0VfV~> -$04BSs)#"?s4Kcsrs#$Hqu?]9_L_`<s+13$s0VfV~> -$04BSs)#"?s4Kcsrs#$Hqu?]9_L_`<s+13$s0VfV~> -$04BSs)#"?s4Kcsrs#$Hqu?]9_L_`<s+13$s0VfV~> -%HKfWs)#"?s4Kd>s.n3ErrLQFrr3"HrVca&Rc"$ks2_GEs+C;b!2TVo"=7VnBrV+3!."QX!3UnQ -JcC<$JcE@^J,~> -%HKfWs)#"?s4Kd>s.n3ErrLQFrr3"HrVca&Rc"$ks2_GEs+C;b!2TVo"=7VnBrV+3!."QX!3UnQ -JcC<$JcE@^J,~> -%HKfWs)#"?s4Kd>s.n3ErrLQFrr3"HrVca&Rc"$ks2_GEs+C;b!2TVo"=7VnBrV+3!."QX!3UnQ -JcC<$JcE@^J,~> -%HKfWs(sVe9L2&Gs(&Y=rrKK@rr3!Bqu-O$;p"k[s.ao?JY<"K"H'/XH_gYI"Ga/[Ff55F!J@_0 -s+13$s+13_s*t~> -%HKfWs(sVe9L2&Gs(&Y=rrKK@rr3!Bqu-O$;p"k[s.ao?JY<"K"H'/XH_gYI"Ga/[Ff55F!J@_0 -s+13$s+13_s*t~> -%HKfWs(sVe9L2&Gs(&Y=rrKK@rr3!Bqu-O$;p"k[s.ao?JY<"K"H'/XH_gYI"Ga/[Ff55F!J@_0 -s+13$s+13_s*t~> -'')>\s)!eBc`fe:s5I;>s4Ui>rr3!Bqu-O$;p"k[s.ao?9@Eh>"IarB6JDG="Hn]C3o^/=!U8m# -s+13$s+13_s*t~> -'')>\s)!eBc`fe:s5I;>s4Ui>rr3!Bqu-O$;p"k[s.ao?9@Eh>"IarB6JDG="Hn]C3o^/=!U8m# -s+13$s+13_s*t~> -'')>\s)!eBc`fe:s5I;>s4Ui>rr3!Bqu-O$;p"k[s.ao?9@Eh>"IarB6JDG="Hn]C3o^/=!U8m# -s+13$s+13_s*t~> -$04BSs)#"?s4Kd=rrc$Brle7<rrF;?rVm1&and4]UO)r5df07LRY(Q+gA_*WP)KA)1)q9LJcC<$ -JcC<$])R9~> -$04BSs)#"?s4Kd=rrc$Brle7<rrF;?rVm1&and4]UO)r5df07LRY(Q+gA_*WP)KA)1)q9LJcC<$ -JcC<$])R9~> -$04BSs)#"?s4Kd=rrc$Brle7<rrF;?rVm1&and4]UO)r5df07LRY(Q+gA_*WP)KA)1)q9LJcC<$ -JcC<$])R9~> -$04BSs)#"?s4Kd<rrO\00)Y_[+oD#ss8Q$>qBGs7HN-Xdrr3+iK)\0krr3+aMuPitrr3#fn:CUj -s+13$s1JA^~> -$04BSs)#"?s4Kd<rrO\00)Y_[+oD#ss8Q$>qBGs7HN-Xdrr3+iK)\0krr3+aMuPitrr3#fn:CUj -s+13$s1JA^~> -$04BSs)#"?s4Kd<rrO\00)Y_[+oD#ss8Q$>qBGs7HN-Xdrr3+iK)\0krr3+aMuPitrr3#fn:CUj -s+13$s1JA^~> -$04BSs,i\`^T;JSrrQQ4@f66:=hUV\s8RPD]G\JHS,[`4rkASqU&T,7rkASmW;gY<rkAJeY(?V( -s+13$s1JA^~> -$04BSs,i\`^T;JSrrQQ4@f66:=hUV\s8RPD]G\JHS,[`4rkASqU&T,7rkASmW;gY<rkAJeY(?V( -s+13$s1JA^~> -$04BSs,i\`^T;JSrrQQ4@f66:=hUV\s8RPD]G\JHS,[`4rkASqU&T,7rkASmW;gY<rkAJeY(?V( -s+13$s1JA^~> -#in9Rs8S-b>]flC!,q`6!FC9SrrddS$s].urr@?D>QC;nrr@0?>QCMtrr?s9>QC[Qs+13$s+13^ -s*t~> -#in9Rs8S-b>]flC!,q`6!FC9SrrddS$s].urr@?D>QC;nrr@0?>QCMtrr?s9>QC[Qs+13$s+13^ -s*t~> -#in9Rs8S-b>]flC!,q`6!FC9SrrddS$s].urr@?D>QC;nrr@0?>QCMtrr?s9>QC[Qs+13$s+13^ -s*t~> -!ouXLk5PJY,(]cFs+13$s.TIC~> -!ouXLk5PJY,(]cFs+13$s.TIC~> -!ouXLk5PJY,(]cFs+13$s.TIC~> -!ouXLk5PJY,(]cFs+13$s.TIC~> -!ouXLk5PJY,(]cFs+13$s.TIC~> -!ouXLk5PJY,(]cFs+13$s.TIC~> -!ouXLk5PJ]\q0m4s+13$s.TIC~> -!ouXLk5PJ]\q0m4s+13$s.TIC~> -!ouXLk5PJ]\q0m4s+13$s.TIC~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLq#:A8^4H<8s+13$s,[21~> -!ouXLq#:A8^4H<8s+13$s,[21~> -!ouXLq#:A8^4H<8s+13$s,[21~> -!ouXLq#:A*\:O[2s+13$s,[21~> -!ouXLq#:A*\:O[2s+13$s,[21~> -!ouXLq#:A*\:O[2s+13$s,[21~> -"lqsOs8UXK_?A<es(&Y=rrMNAJcC<$JcC<$PlH7~> -"lqsOs8UXK_?A<es(&Y=rrMNAJcC<$JcC<$PlH7~> -"lqsOs8UXK_?A<es(&Y=rrMNAJcC<$JcC<$PlH7~> -"lqsOs3,K^=UArcs(&Y>q504DJcC<$JcC<$PlH7~> -"lqsOs3,K^=UArcs(&Y>q504DJcC<$JcC<$PlH7~> -"lqsOs3,K^=UArcs(&Y>q504DJcC<$JcC<$PlH7~> -"lqsOs)#">rs68Fs(&X1Lio;?s+13$s+136s*t~> -"lqsOs)#">rs68Fs(&X1Lio;?s+13$s+136s*t~> -"lqsOs)#">rs68Fs(&X1Lio;?s+13$s+136s*t~> -"lqsOs)#">rs$,Ds("oaR=YBhs+13$s,m>3~> -"lqsOs)#">rs$,Ds("oaR=YBhs+13$s,m>3~> -"lqsOs)#">rs$,Ds("oaR=YBhs+13$s,m>3~> -"lqsOs)#">rs$,Ds($Od?%N$,s+13$s,m>3~> -"lqsOs)#">rs$,Ds($Od?%N$,s+13$s,m>3~> -"lqsOs)#">rs$,Ds($Od?%N$,s+13$s,m>3~> -"lqsOs)#">rs68Fs(&Xf^c$1`s+13$s+136s*t~> -"lqsOs)#">rs68Fs(&Xf^c$1`s+13$s+136s*t~> -"lqsOs)#">rs68Fs(&Xf^c$1`s+13$s+136s*t~> -"lqsOs6s7l*!oL2s(8hArT1&)JcC<$JcC<$PlH7~> -"lqsOs6s7l*!oL2s(8hArT1&)JcC<$JcC<$PlH7~> -"lqsOs6s7l*!oL2s(8hArT1&)JcC<$JcC<$PlH7~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -!ouXLJcC<$JcC<$K`?Q~> -"QVjNs/l3<"K)5!R-9,$JcC<$JcCi3J,~> -"QVjNs/l3<"K)5!R-9,$JcC<$JcCi3J,~> -"QVjNs/l3<"K)5!R-9,$JcC<$JcCi3J,~> -"QVjNs3LYE#(Bt[s2&7>JcC<$JcC<$OoKq~> -"QVjNs3LYE#(Bt[s2&7>JcC<$JcC<$OoKq~> -"QVjNs3LYE#(Bt[s2&7>JcC<$JcC<$OoKq~> -!ouXLr;QiX?JPP[!ROMks+13$s+134s*t~> -!ouXLr;QiX?JPP[!ROMks+13$s+134s*t~> -!ouXLr;QiX?JPP[!ROMks+13$s+134s*t~> -!ouXLrVlrn3U6PB!S9bks+13$s+135s*t~> -!ouXLrVlrn3U6PB!S9bks+13$s+135s*t~> -!ouXLrVlrn3U6PB!S9bks+13$s+135s*t~> -%%EndData -showpage -%%Trailer -end -%%EOF diff --git a/lib/stdlib/doc/src/win32reg.xml b/lib/stdlib/doc/src/win32reg.xml index 99fd7fdeb6..8835f931b2 100644 --- a/lib/stdlib/doc/src/win32reg.xml +++ b/lib/stdlib/doc/src/win32reg.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2000</year><year>2011</year> + <year>2000</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/zip.xml b/lib/stdlib/doc/src/zip.xml index cf0d581352..48b376743d 100644 --- a/lib/stdlib/doc/src/zip.xml +++ b/lib/stdlib/doc/src/zip.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2006</year><year>2011</year> + <year>2006</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -123,6 +123,18 @@ </taglist> </desc> </datatype> + <datatype> + <name name="filename"/> + <p>The name of a zip file.</p> + </datatype> + <datatype><name name="extension"/></datatype> + <datatype><name name="extension_spec"/></datatype> + <datatype> + <name name="create_option"/> + <desc> + <p>These options are described in <seealso marker="#zip_options">create/3</seealso>.</p> + </desc> + </datatype> </datatypes> <funcs> <func> @@ -160,6 +172,7 @@ set to <c>["gif", "jpg"]</c> and <c>uncompress</c> is set to <c>["jpg"]</c>, only files with <c>"gif"</c> as extension will be compressed. No other files will be compressed.</p> + <marker id="zip_options"></marker> <p>The following options are available:</p> <taglist> <tag><c>cooked</c></tag> @@ -217,7 +230,7 @@ <tag><c>{uncompress, <anno>What</anno>}</c></tag> <item> <p>Controls what types of files will be uncompressed. It is by - default set to <c>[".Z",".zip",".zoo",".arc",".lzh",".arj"]</c>. + default set to <c>[".Z", ".zip", ".zoo", ".arc", ".lzh", ".arj"]</c>. The following values of <c>What</c> are allowed:</p> <taglist> <tag><c>all</c></tag> @@ -355,7 +368,7 @@ {ok,{"dummy.zip", <<80,75,3,4,20,0,0,0,0,0,74,152,97,60,171,39,212,26,3,0, 0,0,3,0,0,...>>}} -> <input>catch zip:foldl(fun("foo", _, B, _) -> throw(B()); (_, _, _, Acc) -> Acc end, [], {Name, Bin}). </input> +> <input>catch zip:foldl(fun("foo", _, B, _) -> throw(B()); (_,_,_,Acc) -> Acc end, [], {Name, Bin}). </input> <<"FOO">> </pre> </desc> |
