diff options
Diffstat (limited to 'lib/stdlib/doc')
71 files changed, 4249 insertions, 2523 deletions
diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile index 4541b4a463..4b22e35e3b 100644 --- a/lib/stdlib/doc/src/Makefile +++ b/lib/stdlib/doc/src/Makefile @@ -28,11 +28,6 @@ VSN=$(STDLIB_VSN) APPLICATION=stdlib # ---------------------------------------------------- -# Release directory specification -# ---------------------------------------------------- -RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) - -# ---------------------------------------------------- # Target Specs # ---------------------------------------------------- XML_APPLICATION_FILES = ref_man.xml @@ -89,6 +84,7 @@ XML_REF3_FILES = \ sets.xml \ shell.xml \ shell_default.xml \ + shell_docs.xml \ slave.xml \ sofs.xml \ string.xml \ @@ -105,7 +101,7 @@ XML_REF6_FILES = stdlib_app.xml XML_PART_FILES = part.xml XML_CHAPTER_FILES = introduction.xml io_protocol.xml unicode_usage.xml \ - notes.xml assert_hrl.xml + uri_string_usage.xml notes.xml assert_hrl.xml BOOK_FILES = book.xml @@ -113,74 +109,12 @@ XML_FILES = \ $(BOOK_FILES) $(XML_CHAPTER_FILES) \ $(XML_PART_FILES) $(XML_REF3_FILES) $(XML_REF6_FILES) $(XML_APPLICATION_FILES) -# ---------------------------------------------------- - -HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ - $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) - -INFO_FILE = ../../info - -MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) -MAN6_FILES = $(XML_REF6_FILES:%_app.xml=$(MAN6DIR)/%.6) - -HTML_REF_MAN_FILE = $(HTMLDIR)/index.html - -TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf - -SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml) - TOP_SPECS_FILE = specs.xml -# ---------------------------------------------------- -# FLAGS -# ---------------------------------------------------- -XML_FLAGS += - -SPECS_FLAGS = -I../../include -I../../../kernel/include - -# ---------------------------------------------------- -# Targets -# ---------------------------------------------------- -docs: man pdf html - -$(TOP_PDF_FILE): $(XML_FILES) - -pdf: $(TOP_PDF_FILE) - -html: $(HTML_REF_MAN_FILE) - -man: $(MAN3_FILES) $(MAN6_FILES) - -debug opt: - -clean clean_docs: - rm -rf $(HTMLDIR)/* - rm -rf $(XMLDIR) - rm -f $(MAN3DIR)/* - rm -f $(MAN6DIR)/* - rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) - rm -f $(SPECDIR)/* - rm -f errs core *~ - $(SPECDIR)/specs_erl_id_trans.xml: $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ -o$(dir $@) -module erl_id_trans -# ---------------------------------------------------- -# Release Target -# ---------------------------------------------------- -include $(ERL_TOP)/make/otp_release_targets.mk - -release_docs_spec: docs - $(INSTALL_DIR) "$(RELSYSDIR)/doc/pdf" - $(INSTALL_DATA) $(TOP_PDF_FILE) "$(RELSYSDIR)/doc/pdf" - $(INSTALL_DIR) "$(RELSYSDIR)/doc/html" - $(INSTALL_DATA) $(HTMLDIR)/* \ - "$(RELSYSDIR)/doc/html" - $(INSTALL_DATA) $(INFO_FILE) "$(RELSYSDIR)" - $(INSTALL_DIR) "$(RELEASE_PATH)/man/man3" - $(INSTALL_DATA) $(MAN3DIR)/* "$(RELEASE_PATH)/man/man3" - $(INSTALL_DIR) "$(RELEASE_PATH)/man/man6" - $(INSTALL_DATA) $(MAN6_FILES) "$(RELEASE_PATH)/man/man6" +NO_CHUNKS = erl_id_trans.xml -release_spec: +include $(ERL_TOP)/make/doc.mk diff --git a/lib/stdlib/doc/src/array.xml b/lib/stdlib/doc/src/array.xml index 3607c4f162..bb18489994 100644 --- a/lib/stdlib/doc/src/array.xml +++ b/lib/stdlib/doc/src/array.xml @@ -47,14 +47,14 @@ value is the atom <c>undefined</c>. There is no difference between an unset entry and an entry that has been explicitly set to the same value as the default one (compare - <seealso marker="#reset-2"><c>reset/2</c></seealso>). If you need to + <seemfa marker="#reset/2"><c>reset/2</c></seemfa>). If you need to differentiate between unset and set entries, ensure that the default value cannot be confused with the values of set entries.</p> <p>The array never shrinks automatically. If an index <c>I</c> has been used to set an entry successfully, all indices in the range [0,<c>I</c>] stay accessible unless the array size is explicitly changed by calling - <seealso marker="#resize-2"><c>resize/2</c></seealso>.</p> + <seemfa marker="#resize/2"><c>resize/2</c></seemfa>.</p> <p><em>Examples:</em></p> @@ -139,20 +139,20 @@ A3 = array:fix(A2).</pre> <func> <name name="default" arity="1" since=""/> <fsummary>Get the value used for uninitialized entries.</fsummary> - <desc><marker id="default-1"/> + <desc> <p>Gets the value used for uninitialized entries.</p> - <p>See also <seealso marker="#new-2"><c>new/2</c></seealso>.</p> + <p>See also <seemfa marker="#new/2"><c>new/2</c></seemfa>.</p> </desc> </func> <func> <name name="fix" arity="1" since=""/> <fsummary>Fix the array size.</fsummary> - <desc><marker id="fix-1"/> + <desc> <p>Fixes the array size. This prevents it from growing automatically upon insertion.</p> - <p>See also <seealso marker="#set-3"><c>set/3</c></seealso> and - <seealso marker="#relax-1"><c>relax/1</c></seealso>.</p> + <p>See also <seemfa marker="#set/3"><c>set/3</c></seemfa> and + <seemfa marker="#relax/1"><c>relax/1</c></seemfa>.</p> </desc> </func> @@ -160,14 +160,14 @@ A3 = array:fix(A2).</pre> <name name="foldl" arity="3" since=""/> <fsummary>Fold the array elements using the specified function and initial accumulator value.</fsummary> - <desc><marker id="foldl-3"/> + <desc> <p>Folds the array elements using the specified function and initial accumulator value. The elements are visited in order from the lowest index to the highest. If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>.</p> - <p>See also <seealso marker="#foldr-3"><c>foldr/3</c></seealso>, - <seealso marker="#map-2"><c>map/2</c></seealso>, - <seealso marker="#sparse_foldl-3"><c>sparse_foldl/3</c></seealso>.</p> + <p>See also <seemfa marker="#foldr/3"><c>foldr/3</c></seemfa>, + <seemfa marker="#map/2"><c>map/2</c></seemfa>, + <seemfa marker="#sparse_foldl/3"><c>sparse_foldl/3</c></seemfa>.</p> </desc> </func> @@ -175,35 +175,35 @@ A3 = array:fix(A2).</pre> <name name="foldr" arity="3" since=""/> <fsummary>Fold the array elements right-to-left using the specified function and initial accumulator value.</fsummary> - <desc><marker id="foldr-3"/> + <desc> <p>Folds the array elements right-to-left using the specified function and initial accumulator value. The elements are visited in order from the highest index to the lowest. If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>.</p> - <p>See also <seealso marker="#foldl-3"><c>foldl/3</c></seealso>, - <seealso marker="#map-2"><c>map/2</c></seealso>.</p> + <p>See also <seemfa marker="#foldl/3"><c>foldl/3</c></seemfa>, + <seemfa marker="#map/2"><c>map/2</c></seemfa>.</p> </desc> </func> <func> <name name="from_list" arity="1" since=""/> <fsummary>Equivalent to <c>from_list(List, undefined)</c>.</fsummary> - <desc><marker id="from_list-1"/> + <desc> <p>Equivalent to - <seealso marker="#from_list-2"><c>from_list(<anno>List</anno>, undefined)</c></seealso>.</p> + <seemfa marker="#from_list/2"><c>from_list(<anno>List</anno>, undefined)</c></seemfa>.</p> </desc> </func> <func> <name name="from_list" arity="2" since=""/> <fsummary>Convert a list to an extendible array.</fsummary> - <desc><marker id="from_list-2"/> + <desc> <p>Converts a list to an extendible array. <c><anno>Default</anno></c> is used as the value for uninitialized entries of the array. If <c><anno>List</anno></c> is not a proper list, the call fails with reason <c>badarg</c>.</p> - <p>See also <seealso marker="#new-2"><c>new/2</c></seealso>, - <seealso marker="#to_list-1"><c>to_list/1</c></seealso>.</p> + <p>See also <seemfa marker="#new/2"><c>new/2</c></seemfa>, + <seemfa marker="#to_list/1"><c>to_list/1</c></seemfa>.</p> </desc> </func> @@ -211,9 +211,9 @@ A3 = array:fix(A2).</pre> <name name="from_orddict" arity="1" since=""/> <fsummary>Equivalent to <c>from_orddict(Orddict, undefined)</c>. </fsummary> - <desc><marker id="from_orddict-1"/> + <desc> <p>Equivalent to - <seealso marker="#from_orddict-2"><c>from_orddict(<anno>Orddict</anno>, undefined)</c></seealso>.</p> + <seemfa marker="#from_orddict/2"><c>from_orddict(<anno>Orddict</anno>, undefined)</c></seemfa>.</p> </desc> </func> @@ -221,22 +221,22 @@ A3 = array:fix(A2).</pre> <name name="from_orddict" arity="2" since=""/> <fsummary>Convert an ordered list of pairs <c>{Index, Value}</c> to a corresponding extendible array.</fsummary> - <desc><marker id="from_orddict-2"/> + <desc> <p>Converts 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 non-negative integers, the call fails with reason <c>badarg</c>.</p> - <p>See also <seealso marker="#new-2"><c>new/2</c></seealso>, - <seealso marker="#to_orddict-1"><c>to_orddict/1</c></seealso>.</p> + <p>See also <seemfa marker="#new/2"><c>new/2</c></seemfa>, + <seemfa marker="#to_orddict/1"><c>to_orddict/1</c></seemfa>.</p> </desc> </func> <func> <name name="get" arity="2" since=""/> <fsummary>Get the value of entry <c>I</c>.</fsummary> - <desc><marker id="get-2"/> + <desc> <p>Gets the value of entry <c><anno>I</anno></c>. If <c><anno>I</anno></c> is not a non-negative integer, or if the array has fixed size and <c><anno>I</anno></c> is larger than the maximum @@ -244,7 +244,7 @@ A3 = array:fix(A2).</pre> <p>If the array does not have fixed size, the default value for any index <c><anno>I</anno></c> greater than <c>size(<anno>Array</anno>)-1</c> is returned.</p> - <p>See also <seealso marker="#set-3"><c>set/3</c></seealso>.</p> + <p>See also <seemfa marker="#set/3"><c>set/3</c></seemfa>.</p> </desc> </func> @@ -252,7 +252,7 @@ A3 = array:fix(A2).</pre> <name name="is_array" arity="1" since=""/> <fsummary>Returns <c>true</c> if <c>X</c> is an array, otherwise <c>false</c>.</fsummary> - <desc><marker id="is_array-1"/> + <desc> <p>Returns <c>true</c> if <c><anno>X</anno></c> is an array, otherwise <c>false</c>. Notice that the check is only shallow, as there is no guarantee that <c><anno>X</anno></c> is a well-formed array @@ -263,24 +263,24 @@ A3 = array:fix(A2).</pre> <func> <name name="is_fix" arity="1" since=""/> <fsummary>Check if the array has fixed size.</fsummary> - <desc><marker id="is_fix-1"/> + <desc> <p>Checks if the array has fixed size. Returns <c>true</c> if the array is fixed, otherwise <c>false</c>.</p> - <p>See also <seealso marker="#fix-1"><c>fix/1</c></seealso>.</p> + <p>See also <seemfa marker="#fix/1"><c>fix/1</c></seemfa>.</p> </desc> </func> <func> <name name="map" arity="2" since=""/> <fsummary>Map the specified function onto each array element.</fsummary> - <desc><marker id="map-2"/> + <desc> <p>Maps the specified function onto each array element. The elements are visited in order from the lowest index to the highest. If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>.</p> - <p>See also <seealso marker="#foldl-3"><c>foldl/3</c></seealso>, - <seealso marker="#foldr-3"><c>foldr/3</c></seealso>, - <seealso marker="#sparse_map-2"><c>sparse_map/2</c></seealso>.</p> + <p>See also <seemfa marker="#foldl/3"><c>foldl/3</c></seemfa>, + <seemfa marker="#foldr/3"><c>foldr/3</c></seemfa>, + <seemfa marker="#sparse_map/2"><c>sparse_map/2</c></seemfa>.</p> </desc> </func> @@ -288,10 +288,10 @@ A3 = array:fix(A2).</pre> <name name="new" arity="0" since=""/> <fsummary>Create a new, extendible array with initial size zero. </fsummary> - <desc><marker id="new-0"/> + <desc> <p>Creates a new, extendible array with initial size zero.</p> - <p>See also <seealso marker="#new-1"><c>new/1</c></seealso>, - <seealso marker="#new-2"><c>new/2</c></seealso>.</p> + <p>See also <seemfa marker="#new/1"><c>new/1</c></seemfa>, + <seemfa marker="#new/2"><c>new/2</c></seemfa>.</p> </desc> </func> @@ -299,7 +299,7 @@ A3 = array:fix(A2).</pre> <name name="new" arity="1" since=""/> <fsummary>Create a new array according to the specified options. </fsummary> - <desc><marker id="new-1"/> + <desc> <p>Creates a new array according to the specified otions. By default, the array is extendible and has initial size zero. Array indices start at <c>0</c>.</p> @@ -313,7 +313,7 @@ A3 = array:fix(A2).</pre> call fails with reason <c>badarg</c>.</p></item> <tag><c>fixed</c> or <c>{fixed, true}</c></tag> <item><p>Creates a fixed-size array. See also - <seealso marker="#fix-1"><c>fix/1</c></seealso>.</p></item> + <seemfa marker="#fix/1"><c>fix/1</c></seemfa>.</p></item> <tag><c>{fixed, false}</c></tag> <item><p>Creates an extendible (non-fixed-size) array.</p></item> <tag><c>{default, Value}</c></tag> @@ -336,12 +336,12 @@ array:new({default,0})</pre> array:new([{size,10},{fixed,false},{default,-1}])</pre> <p>creates an extendible array with initial size 10 whose default value is <c>-1</c>.</p> - <p>See also <seealso marker="#fix-1"><c>fix/1</c></seealso>, - <seealso marker="#from_list-2"><c>from_list/2</c></seealso>, - <seealso marker="#get-2"><c>get/2</c></seealso>, - <seealso marker="#new-0"><c>new/0</c></seealso>, - <seealso marker="#new-2"><c>new/2</c></seealso>, - <seealso marker="#set-3"><c>set/3</c></seealso>.</p> + <p>See also <seemfa marker="#fix/1"><c>fix/1</c></seemfa>, + <seemfa marker="#from_list/2"><c>from_list/2</c></seemfa>, + <seemfa marker="#get/2"><c>get/2</c></seemfa>, + <seemfa marker="#new/0"><c>new/0</c></seemfa>, + <seemfa marker="#new/2"><c>new/2</c></seemfa>, + <seemfa marker="#set/3"><c>set/3</c></seemfa>.</p> </desc> </func> @@ -349,7 +349,7 @@ array:new([{size,10},{fixed,false},{default,-1}])</pre> <name name="new" arity="2" since=""/> <fsummary>Create a new array according to the specified size and options. </fsummary> - <desc><marker id="new-2"/> + <desc> <p>Creates a new array according to the specified size and options. If <c><anno>Size</anno></c> is not a non-negative integer, the call fails with reason <c>badarg</c>. By default, the array has fixed size. @@ -365,17 +365,17 @@ array:new([{size,10},{fixed,false},{default,-1}])</pre> array:new(100, {default,0})</pre> <p>creates a fixed-size array of size 100, whose default value is <c>0</c>.</p> - <p>See also <seealso marker="#new-1"><c>new/1</c></seealso>.</p> + <p>See also <seemfa marker="#new/1"><c>new/1</c></seemfa>.</p> </desc> </func> <func> <name name="relax" arity="1" since=""/> <fsummary>Make the array resizable.</fsummary> - <desc><marker id="relax-1"/> + <desc> <p>Makes the array resizable. (Reverses the effects of - <seealso marker="#fix-1"><c>fix/1</c></seealso>.)</p> - <p>See also <seealso marker="#fix-1"><c>fix/1</c></seealso>.</p> + <seemfa marker="#fix/1"><c>fix/1</c></seemfa>.)</p> + <p>See also <seemfa marker="#fix/1"><c>fix/1</c></seemfa>.</p> </desc> </func> @@ -383,18 +383,18 @@ array:new(100, {default,0})</pre> <name name="reset" arity="2" since=""/> <fsummary>Reset entry <c>I</c> to the default value for the array. </fsummary> - <desc><marker id="reset-2"/> + <desc> <p>Resets entry <c><anno>I</anno></c> to the default value for the array. If the value of entry <c><anno>I</anno></c> is the default value, the array is returned unchanged. Reset never changes the array size. Shrinking can be done explicitly by calling - <seealso marker="#resize-2"><c>resize/2</c></seealso>.</p> + <seemfa marker="#resize/2"><c>resize/2</c></seemfa>.</p> <p>If <c><anno>I</anno></c> is not a non-negative integer, or if the array has fixed size and <c><anno>I</anno></c> is larger than the maximum index, the call fails with reason <c>badarg</c>; compare - <seealso marker="#set-3"><c>set/3</c></seealso></p> - <p>See also <seealso marker="#new-2"><c>new/2</c></seealso>, - <seealso marker="#set-3"><c>set/3</c></seealso>.</p> + <seemfa marker="#set/3"><c>set/3</c></seemfa></p> + <p>See also <seemfa marker="#new/2"><c>new/2</c></seemfa>, + <seemfa marker="#set/3"><c>set/3</c></seemfa>.</p> </desc> </func> @@ -402,20 +402,20 @@ array:new(100, {default,0})</pre> <name name="resize" arity="1" since=""/> <fsummary>Change the array size to that reported by <c>sparse_size/1</c>. </fsummary> - <desc><marker id="resize-1"/> + <desc> <p>Changes the array size to that reported by - <seealso marker="#sparse_size-1"><c>sparse_size/1</c></seealso>. If + <seemfa marker="#sparse_size/1"><c>sparse_size/1</c></seemfa>. If the specified array has fixed size, also the resulting array has fixed size.</p> - <p>See also <seealso marker="#resize-2"><c>resize/2</c></seealso>, - <seealso marker="#sparse_size-1"><c>sparse_size/1</c></seealso>.</p> + <p>See also <seemfa marker="#resize/2"><c>resize/2</c></seemfa>, + <seemfa marker="#sparse_size/1"><c>sparse_size/1</c></seemfa>.</p> </desc> </func> <func> <name name="resize" arity="2" since=""/> <fsummary>Change the array size.</fsummary> - <desc><marker id="resize-2"/> + <desc> <p>Change the array size. If <c><anno>Size</anno></c> is not a non-negative integer, the call fails with reason <c>badarg</c>. If the specified array has fixed size, also the resulting array has fixed @@ -426,7 +426,7 @@ array:new(100, {default,0})</pre> <func> <name name="set" arity="3" since=""/> <fsummary>Set entry <c>I</c> of the array to <c>Value</c>.</fsummary> - <desc><marker id="set-3"/> + <desc> <p>Sets entry <c><anno>I</anno></c> of the array to <c><anno>Value</anno></c>. If <c><anno>I</anno></c> is not a non-negative integer, or if the array has fixed size and @@ -435,21 +435,21 @@ array:new(100, {default,0})</pre> <p>If the array does not have fixed size, and <c><anno>I</anno></c> is greater than <c>size(<anno>Array</anno>)-1</c>, the array grows to size <c><anno>I</anno>+1</c>.</p> - <p>See also <seealso marker="#get-2"><c>get/2</c></seealso>, - <seealso marker="#reset-2"><c>reset/2</c></seealso>.</p> + <p>See also <seemfa marker="#get/2"><c>get/2</c></seemfa>, + <seemfa marker="#reset/2"><c>reset/2</c></seemfa>.</p> </desc> </func> <func> <name name="size" arity="1" since=""/> <fsummary>Get the number of entries in the array.</fsummary> - <desc><marker id="size-1"/> + <desc> <p>Gets the number of entries in the array. Entries are numbered from <c>0</c> to <c>size(<anno>Array</anno>)-1</c>. Hence, this is also the index of the first entry that is guaranteed to not have been previously set.</p> - <p>See also <seealso marker="#set-3"><c>set/3</c></seealso>, - <seealso marker="#sparse_size-1"><c>sparse_size/1</c></seealso>.</p> + <p>See also <seemfa marker="#set/3"><c>set/3</c></seemfa>, + <seemfa marker="#sparse_size/1"><c>sparse_size/1</c></seemfa>.</p> </desc> </func> @@ -457,14 +457,14 @@ array:new(100, {default,0})</pre> <name name="sparse_foldl" arity="3" since=""/> <fsummary>Fold the array elements using the specified function and initial accumulator value, skipping default-valued entries.</fsummary> - <desc><marker id="sparse_foldl-3"/> + <desc> <p>Folds the array elements using the specified function and initial accumulator value, skipping default-valued entries. The elements are visited in order from the lowest index to the highest. If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>.</p> - <p>See also <seealso marker="#foldl-3"><c>foldl/3</c></seealso>, - <seealso marker="#sparse_foldr-3"><c>sparse_foldr/3</c></seealso>.</p> + <p>See also <seemfa marker="#foldl/3"><c>foldl/3</c></seemfa>, + <seemfa marker="#sparse_foldr/3"><c>sparse_foldr/3</c></seemfa>.</p> </desc> </func> @@ -473,14 +473,14 @@ array:new(100, {default,0})</pre> <fsummary>Fold the array elements right-to-left using the specified function and initial accumulator value, skipping default-valued entries.</fsummary> - <desc><marker id="sparse_foldr-3"/> + <desc> <p>Folds the array elements right-to-left using the specified function and initial accumulator value, skipping default-valued entries. The elements are visited in order from the highest index to the lowest. If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>.</p> - <p>See also <seealso marker="#foldr-3"><c>foldr/3</c></seealso>, - <seealso marker="#sparse_foldl-3"><c>sparse_foldl/3</c></seealso>.</p> + <p>See also <seemfa marker="#foldr/3"><c>foldr/3</c></seemfa>, + <seemfa marker="#sparse_foldl/3"><c>sparse_foldl/3</c></seemfa>.</p> </desc> </func> @@ -488,12 +488,12 @@ array:new(100, {default,0})</pre> <name name="sparse_map" arity="2" since=""/> <fsummary>Map the specified function onto each array element, skipping default-valued entries.</fsummary> - <desc><marker id="sparse_map-2"/> + <desc> <p>Maps the specified function onto each array element, skipping default-valued entries. The elements are visited in order from the lowest index to the highest. If <c><anno>Function</anno></c> is not a function, the call fails with reason <c>badarg</c>.</p> - <p>See also <seealso marker="#map-2"><c>map/2</c></seealso>.</p> + <p>See also <seemfa marker="#map/2"><c>map/2</c></seemfa>.</p> </desc> </func> @@ -501,13 +501,13 @@ array:new(100, {default,0})</pre> <name name="sparse_size" arity="1" since=""/> <fsummary>Get the number of entries in the array up until the last non-default-valued entry.</fsummary> - <desc><marker id="sparse_size-1"/> + <desc> <p>Gets the number of entries in the array up until the last non-default-valued entry. That is, returns <c>I+1</c> if <c>I</c> is the last non-default-valued entry in the array, or zero if no such entry exists.</p> - <p>See also <seealso marker="#resize-1"><c>resize/1</c></seealso>, - <seealso marker="#size-1"><c>size/1</c></seealso>.</p> + <p>See also <seemfa marker="#resize/1"><c>resize/1</c></seemfa>, + <seemfa marker="#size/1"><c>size/1</c></seemfa>.</p> </desc> </func> @@ -515,9 +515,9 @@ array:new(100, {default,0})</pre> <name name="sparse_to_list" arity="1" since=""/> <fsummary>Convert the array to a list, skipping default-valued entries. </fsummary> - <desc><marker id="sparse_to_list-1"/> + <desc> <p>Converts the array to a list, skipping default-valued entries.</p> - <p>See also <seealso marker="#to_list-1"><c>to_list/1</c></seealso>.</p> + <p>See also <seemfa marker="#to_list/1"><c>to_list/1</c></seemfa>.</p> </desc> </func> @@ -525,21 +525,21 @@ array:new(100, {default,0})</pre> <name name="sparse_to_orddict" arity="1" since=""/> <fsummary>Convert the array to an ordered list of pairs <c>{Index, Value}</c>, skipping default-valued entries.</fsummary> - <desc><marker id="sparse_to_orddict-1"/> + <desc> <p>Converts the array to an ordered list of pairs <c>{Index, <anno>Value</anno>}</c>, skipping default-valued entries.</p> <p>See also - <seealso marker="#to_orddict-1"><c>to_orddict/1</c></seealso>.</p> + <seemfa marker="#to_orddict/1"><c>to_orddict/1</c></seemfa>.</p> </desc> </func> <func> <name name="to_list" arity="1" since=""/> <fsummary>Convert the array to a list.</fsummary> - <desc><marker id="to_list-1"/> + <desc> <p>Converts the array to a list.</p> - <p>See also <seealso marker="#from_list-2"><c>from_list/2</c></seealso>, - <seealso marker="#sparse_to_list-1"><c>sparse_to_list/1</c></seealso>. + <p>See also <seemfa marker="#from_list/2"><c>from_list/2</c></seemfa>, + <seemfa marker="#sparse_to_list/1"><c>sparse_to_list/1</c></seemfa>. </p> </desc> </func> @@ -548,12 +548,12 @@ array:new(100, {default,0})</pre> <name name="to_orddict" arity="1" since=""/> <fsummary>Convert the array to an ordered list of pairs <c>{Index, Value}</c>.</fsummary> - <desc><marker id="to_orddict-1"/> + <desc> <p>Converts the array to an ordered list of pairs <c>{Index, <anno>Value</anno>}</c>.</p> <p>See also - <seealso marker="#from_orddict-2"><c>from_orddict/2</c></seealso>, - <seealso marker="#sparse_to_orddict-1"><c>sparse_to_orddict/1</c></seealso>. + <seemfa marker="#from_orddict/2"><c>from_orddict/2</c></seemfa>, + <seemfa marker="#sparse_to_orddict/1"><c>sparse_to_orddict/1</c></seemfa>. </p> </desc> </func> diff --git a/lib/stdlib/doc/src/assert_hrl.xml b/lib/stdlib/doc/src/assert_hrl.xml index fb27954235..c08066d7fb 100644 --- a/lib/stdlib/doc/src/assert_hrl.xml +++ b/lib/stdlib/doc/src/assert_hrl.xml @@ -185,7 +185,7 @@ erlc -DNOASSERT=true *.erl</code> <section> <title>See Also</title> - <p><seealso marker="compiler:compile"><c>compile(3)</c></seealso>, - <seealso marker="erts:erlc"><c>erlc(3)</c></seealso></p> + <p><seeerl marker="compiler:compile"><c>compile(3)</c></seeerl>, + <seecom marker="erts:erlc"><c>erlc(3)</c></seecom></p> </section> </fileref> diff --git a/lib/stdlib/doc/src/beam_lib.xml b/lib/stdlib/doc/src/beam_lib.xml index 91e5a6d14a..a33c5b076c 100644 --- a/lib/stdlib/doc/src/beam_lib.xml +++ b/lib/stdlib/doc/src/beam_lib.xml @@ -59,9 +59,9 @@ <marker id="debug_info"></marker> <title>Debug Information/Abstract Code</title> <p>Option <c>debug_info</c> can be specified to the Compiler (see - <seealso marker="compiler:compile#debug_info"><c>compile(3)</c></seealso>) - to have debug information, such as <seealso marker="erts:absform">Erlang - Abstract Format</seealso>, stored in the <c>debug_info</c> chunk. + <seeerl marker="compiler:compile#debug_info"><c>compile(3)</c></seeerl>) + to have debug information, such as <seeguide marker="erts:absform">Erlang + Abstract Format</seeguide>, stored in the <c>debug_info</c> chunk. Tools such as Debugger and Xref require the debug information to be included.</p> @@ -71,9 +71,9 @@ </warning> <p>The debug information can also be removed from BEAM files - using <seealso marker="#strip/1"><c>strip/1</c></seealso>, - <seealso marker="#strip_files/1"><c>strip_files/1</c></seealso>, and/or - <seealso marker="#strip_release/1"><c>strip_release/1</c></seealso>.</p> + using <seemfa marker="#strip/1"><c>strip/1</c></seemfa>, + <seemfa marker="#strip_files/1"><c>strip_files/1</c></seemfa>, and/or + <seemfa marker="#strip_release/1"><c>strip_release/1</c></seemfa>.</p> </section> <section> @@ -101,7 +101,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> <p>The default type (and currently the only type) of crypto algorithm is <c>des3_cbc</c>, three rounds of DES. The key string is scrambled using - <seealso marker="erts:erlang#md5/1"><c>erlang:md5/1</c></seealso> + <seemfa marker="erts:erlang#md5/1"><c>erlang:md5/1</c></seemfa> to generate the keys used for <c>des3_cbc</c>.</p> <note> @@ -117,9 +117,9 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> <list type="ordered"> <item> <p>Use Compiler option <c>{debug_info_key,Key}</c>, see - <seealso marker="compiler:compile#debug_info_key"><c>compile(3)</c></seealso> + <seeerl marker="compiler:compile#debug_info_key"><c>compile(3)</c></seeerl> and function - <seealso marker="#crypto_key_fun/1"><c>crypto_key_fun/1</c></seealso> + <seemfa marker="#crypto_key_fun/1"><c>crypto_key_fun/1</c></seemfa> to register a fun that returns the key whenever <c>beam_lib</c> must decrypt the debug information.</p> <p>If no such fun is registered, <c>beam_lib</c> instead @@ -129,7 +129,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> <p>Store the key in a text file named <c>.erlang.crypt</c>.</p> <p>In this case, Compiler option <c>encrypt_debug_info</c> can be used, see - <seealso marker="compiler:compile#encrypt_debug_info"><c>compile(3)</c></seealso>. + <seeerl marker="compiler:compile#encrypt_debug_info"><c>compile(3)</c></seeerl>. </p> </item> </list> @@ -317,7 +317,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> <desc> <p>Unregisters the crypto key fun and terminates the process holding it, started by - <seealso marker="#crypto_key_fun/1"><c>crypto_key_fun/1</c></seealso>. + <seemfa marker="#crypto_key_fun/1"><c>crypto_key_fun/1</c></seemfa>. </p> <p>Returns either <c>{ok, undefined}</c> if no crypto key fun is registered, or <c>{ok, Term}</c>, where <c>Term</c> is @@ -402,7 +402,7 @@ CryptoKeyFun(clear) -> term()</code> <fsummary>Compare the BEAM files in two directories.</fsummary> <desc> <p>Compares the BEAM files in two directories as - <seealso marker="#cmp_dirs/2"><c>cmp_dirs/2</c></seealso>, but the + <seemfa marker="#cmp_dirs/2"><c>cmp_dirs/2</c></seemfa>, but the names of files that exist in only one directory or are different are presented on standard output.</p> </desc> @@ -416,7 +416,7 @@ CryptoKeyFun(clear) -> term()</code> <p>For a specified error returned by any function in this module, this function returns a descriptive string of the error in English. For file errors, function - <seealso marker="kernel:file#format_error/1"><c>file:format_error(Posix)</c></seealso> + <seemfa marker="kernel:file#format_error/1"><c>file:format_error(Posix)</c></seemfa> is to be called.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/binary.xml b/lib/stdlib/doc/src/binary.xml index 2dd6c6a436..412a0f5def 100644 --- a/lib/stdlib/doc/src/binary.xml +++ b/lib/stdlib/doc/src/binary.xml @@ -64,7 +64,7 @@ </datatype> <datatype> <name name="part"/> - <desc><p>A representaion of a part (or range) in a binary. <c>Start</c> is + <desc><p>A representation of a part (or range) in a binary. <c>Start</c> is a zero-based offset into a <c>binary()</c> and <c>Length</c> is the length of that part. As input to functions in this module, a reverse part specification is allowed, constructed with a negative @@ -131,10 +131,10 @@ <desc> <p>Builds an internal structure representing a compilation of a search pattern, later to be used in functions - <seealso marker="#match-3"><c>match/3</c></seealso>, - <seealso marker="#matches-3"><c>matches/3</c></seealso>, - <seealso marker="#split-3"><c>split/3</c></seealso>, or - <seealso marker="#replace-4"><c>replace/4</c></seealso>. + <seemfa marker="#match/3"><c>match/3</c></seemfa>, + <seemfa marker="#matches/3"><c>matches/3</c></seemfa>, + <seemfa marker="#split/3"><c>split/3</c></seemfa>, or + <seemfa marker="#replace/4"><c>replace/4</c></seemfa>. The <c>cp()</c> returned is guaranteed to be a <c>tuple()</c> to allow programs to distinguish it from non-precompiled search patterns.</p> @@ -173,7 +173,7 @@ duplicated <c><anno>N</anno></c> times.</p> <p>This function always creates a new binary, even if <c><anno>N</anno> = - 1</c>. By using <seealso marker="#copy/1"><c>copy/1</c></seealso> + 1</c>. By using <seemfa marker="#copy/1"><c>copy/1</c></seemfa> on a binary referencing a larger binary, one can free up the larger binary for garbage collection.</p> @@ -267,7 +267,7 @@ <fsummary>Convert a list of integers and binaries to a binary.</fsummary> <desc> <p>Works exactly as - <seealso marker="erts:erlang#list_to_binary/1"><c>erlang:list_to_binary/1</c></seealso>, + <seemfa marker="erts:erlang#list_to_binary/1"><c>erlang:list_to_binary/1</c></seemfa>, added for completeness.</p> </desc> </func> @@ -361,7 +361,7 @@ atom <c>nomatch</c> is returned.</p> <p>For a description of <c><anno>Pattern</anno></c>, see function - <seealso marker="#compile_pattern-1"><c>compile_pattern/1</c></seealso>. + <seemfa marker="#compile_pattern/1"><c>compile_pattern/1</c></seemfa>. </p> <p>If <c>{scope, {Start,Length}}</c> is specified in the options such @@ -385,7 +385,7 @@ <fsummary>Search for all matches of a pattern in a binary.</fsummary> <type name="part"/> <desc> - <p>As <seealso marker="#match-2"><c>match/2</c></seealso>, + <p>As <seemfa marker="#match/2"><c>match/2</c></seemfa>, but <c><anno>Subject</anno></c> is searched until exhausted and a list of all non-overlapping parts matching <c><anno>Pattern</anno></c> is returned (in order).</p> @@ -411,9 +411,9 @@ returned.</p> <p>For a description of <c><anno>Pattern</anno></c>, see - <seealso marker="#compile_pattern-1"><c>compile_pattern/1</c></seealso>. + <seemfa marker="#compile_pattern/1"><c>compile_pattern/1</c></seemfa>. For a description of available options, see - <seealso marker="#match-3"><c>match/3</c></seealso>.</p> + <seemfa marker="#match/3"><c>match/3</c></seemfa>.</p> <p>If <c>{scope, {<anno>Start</anno>,<anno>Length</anno>}}</c> is specified in the options such that <c><anno>Start</anno></c> > size @@ -440,9 +440,9 @@ <<6,7,8,9,10>></code> <note> - <p><seealso marker="#part-2">part/2</seealso> and - <seealso marker="#part-3">part/3</seealso> are also available in the - <seealso marker="erts:erlang"><c>erlang</c></seealso> + <p><seemfa marker="#part/2">part/2</seemfa> and + <seemfa marker="#part/3">part/3</seemfa> are also available in the + <seeerl marker="erts:erlang"><c>erlang</c></seeerl> module under the names <c>binary_part/2</c> and <c>binary_part/3</c>. Those BIFs are allowed in guard tests.</p> </note> @@ -469,7 +469,7 @@ <p>If a binary references a larger binary (often described as being a subbinary), it can be useful to get the size of the referenced binary. This function can be used in a program to trigger the - use of <seealso marker="#copy/1"><c>copy/1</c></seealso>. By copying a + use of <seemfa marker="#copy/1"><c>copy/1</c></seemfa>. By copying a binary, one can dereference the original, possibly large, binary that a smaller binary is a reference to.</p> @@ -566,11 +566,11 @@ store(Binary, GBSet) -> of the replacement binary, a <c>badarg</c> exception is raised.</p> <p>Options <c>global</c> and <c>{scope, part()}</c> work as for - <seealso marker="#split-3"><c>split/3</c></seealso>. + <seemfa marker="#split/3"><c>split/3</c></seemfa>. The return type is always a <c>binary()</c>.</p> <p>For a description of <c><anno>Pattern</anno></c>, see - <seealso marker="#compile_pattern-1"><c>compile_pattern/1</c></seealso>. + <seemfa marker="#compile_pattern/1"><c>compile_pattern/1</c></seemfa>. </p> </desc> </func> @@ -608,23 +608,23 @@ store(Binary, GBSet) -> <taglist> <tag>{scope, part()}</tag> - <item><p>Works as in <seealso marker="#match-3"><c>match/3</c></seealso> - and <seealso marker="#matches-3"><c>matches/3</c></seealso>. Notice that + <item><p>Works as in <seemfa marker="#match/3"><c>match/3</c></seemfa> + and <seemfa marker="#matches/3"><c>matches/3</c></seemfa>. Notice that this only defines the scope of the search for matching strings, it does not cut the binary before splitting. The bytes before and after the scope are kept in the result. See the example below.</p></item> <tag>trim</tag> <item><p>Removes trailing empty parts of the result (as does <c>trim</c> - in <seealso marker="re#split/3"><c>re:split/3</c></seealso>.</p></item> + in <seemfa marker="re#split/3"><c>re:split/3</c></seemfa>.</p></item> <tag>trim_all</tag> <item><p>Removes all empty parts of the result.</p></item> <tag>global</tag> <item><p>Repeats the split until <c><anno>Subject</anno></c> is exhausted. Conceptually option <c>global</c> makes split work on the positions returned by - <seealso marker="#matches-3"><c>matches/3</c></seealso>, while it + <seemfa marker="#matches/3"><c>matches/3</c></seemfa>, while it normally works on the position returned by - <seealso marker="#match-3"><c>match/3</c></seealso>.</p></item> + <seemfa marker="#match/3"><c>match/3</c></seemfa>.</p></item> </taglist> <p>Example of the difference between a scope and taking the @@ -643,7 +643,7 @@ store(Binary, GBSet) -> of the split are no longer referenced.</p> <p>For a description of <c><anno>Pattern</anno></c>, see - <seealso marker="#compile_pattern-1"><c>compile_pattern/1</c></seealso>. + <seemfa marker="#compile_pattern/1"><c>compile_pattern/1</c></seemfa>. </p> </desc> </func> diff --git a/lib/stdlib/doc/src/c.xml b/lib/stdlib/doc/src/c.xml index 29edc373c7..b481596379 100644 --- a/lib/stdlib/doc/src/c.xml +++ b/lib/stdlib/doc/src/c.xml @@ -63,8 +63,8 @@ source file, then the code path is searched to locate the object file for the module and extract its original compiler options and source path. If the source file is not found in the original - location, <seealso - marker="filelib#find_source/1"><c>filelib:find_source/1</c></seealso> + location, <seemfa + marker="filelib#find_source/1"><c>filelib:find_source/1</c></seemfa> is used to search for it relative to the directory of the object file.</p> <p>The source file is compiled with the the original @@ -120,6 +120,64 @@ </func> <func> + <name name="h" arity="1" since="OTP 23.0"/> + <fsummary>Module help information</fsummary> + <type name="h_return"/> + <desc> + <p>Print the documentation for <c>Module</c></p> + </desc> + </func> + + <func> + <name name="h" arity="2" since="OTP 23.0"/> + <fsummary>Function help information</fsummary> + <type name="h_return"/> + <type name="hf_return"/> + <desc> + <p>Print the documentation for all <c>Module:Function</c>s (regardless of arity).</p> + </desc> + </func> + + <func> + <name name="h" arity="3" since="OTP 23.0"/> + <fsummary>Function help information</fsummary> + <type name="h_return"/> + <type name="hf_return"/> + <desc> + <p>Print the documentation for <c>Module:Function/Arity</c>.</p> + </desc> + </func> + + <func> + <name name="ht" arity="1" since="OTP 23.0"/> + <fsummary>Type help information</fsummary> + <type name="h_return"/> + <desc> + <p>Print the type documentation for <c>Module</c></p> + </desc> + </func> + + <func> + <name name="ht" arity="2" since="OTP 23.0"/> + <fsummary>Type help information</fsummary> + <type name="h_return"/> + <type name="ht_return"/> + <desc> + <p>Print the type documentation for <c>Type</c> in <c>Module</c> regardless of arity.</p> + </desc> + </func> + + <func> + <name name="ht" arity="3" since="OTP 23.0"/> + <fsummary>Type help information</fsummary> + <type name="h_return"/> + <type name="ht_return"/> + <desc> + <p>Print the type documentation for <c>Type/Arity</c> in <c>Module</c>.</p> + </desc> + </func> + + <func> <name name="i" arity="0" since=""/> <name name="ni" arity="0" since=""/> <fsummary>System information.</fsummary> @@ -165,7 +223,7 @@ <c>compile:file(File, [report_errors, report_warnings])</c> for each <c>File</c> in <c>Files</c>.</p> <p>For information about <c>File</c>, see - <seealso marker="file#type-filename"><c>file:filename()</c></seealso>. + <seetype marker="file#filename"><c>file:filename()</c></seetype>. </p> </desc> </func> @@ -218,7 +276,7 @@ <fsummary>Lists all modified modules.</fsummary> <desc> <p>Lists all modified modules. Shorthand for - <seealso marker="kernel:code#modified_modules/0"><c>code:modified_modules/0</c></seealso>.</p> + <seemfa marker="kernel:code#modified_modules/0"><c>code:modified_modules/0</c></seemfa>.</p> </desc> </func> @@ -227,7 +285,7 @@ <fsummary>Memory allocation information.</fsummary> <desc> <p>Memory allocation information. Equivalent to - <seealso marker="erts:erlang#memory/0"><c>erlang:memory/0</c></seealso>.</p> + <seemfa marker="erts:erlang#memory/0"><c>erlang:memory/0</c></seemfa>.</p> </desc> </func> @@ -237,7 +295,7 @@ <fsummary>Memory allocation information.</fsummary> <desc> <p>Memory allocation information. Equivalent to - <seealso marker="erts:erlang#memory/1"><c>erlang:memory/1</c></seealso>.</p> + <seemfa marker="erts:erlang#memory/1"><c>erlang:memory/1</c></seemfa>.</p> </desc> </func> @@ -336,9 +394,9 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w <code type="none"> yecc:file(File)</code> <p>For information about <c>File = name()</c>, see - <seealso marker="filename"><c>filename(3)</c></seealso>. + <seeerl marker="filename"><c>filename(3)</c></seeerl>. For information about <c>YeccRet</c>, see - <seealso marker="parsetools:yecc#file/1"><c>yecc:file/2</c></seealso>. + <seemfa marker="parsetools:yecc#file/1"><c>yecc:file/2</c></seemfa>. </p> </desc> </func> @@ -355,9 +413,9 @@ yecc:file(File)</code> <code type="none"> yecc:file(File, Options)</code> <p>For information about <c>File = name()</c>, see - <seealso marker="filename"><c>filename(3)</c></seealso>. + <seeerl marker="filename"><c>filename(3)</c></seeerl>. For information about <c>Options</c> and <c>YeccRet</c>, see - <seealso marker="parsetools:yecc#file/1"><c>yecc:file/2</c></seealso>. + <seemfa marker="parsetools:yecc#file/1"><c>yecc:file/2</c></seemfa>. </p> </desc> </func> @@ -365,11 +423,11 @@ yecc:file(File, Options)</code> <section> <title>See Also</title> - <p><seealso marker="filename"><c>filename(3)</c></seealso>, - <seealso marker="compiler:compile"><c>compile(3)</c></seealso>, - <seealso marker="erts:erlang"><c>erlang(3)</c></seealso>, - <seealso marker="parsetools:yecc"><c>yecc(3)</c></seealso>, - <seealso marker="tools:xref"><c>xref(3)</c></seealso></p> + <p><seeerl marker="filename"><c>filename(3)</c></seeerl>, + <seeerl marker="compiler:compile"><c>compile(3)</c></seeerl>, + <seeerl marker="erts:erlang"><c>erlang(3)</c></seeerl>, + <seeerl marker="parsetools:yecc"><c>yecc(3)</c></seeerl>, + <seeerl marker="tools:xref"><c>xref(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/calendar.xml b/lib/stdlib/doc/src/calendar.xml index 6cc0befd45..213bca365d 100644 --- a/lib/stdlib/doc/src/calendar.xml +++ b/lib/stdlib/doc/src/calendar.xml @@ -41,7 +41,7 @@ Greenwich Mean Time (GMT).</p> <p>The time functions <c>local_time/0</c> and <c>universal_time/0</c> in this module both return date - and time. The is because separate functions for date + and time. This is because separate functions for date and time can result in a date/time combination that is displaced by 24 hours. This occurs if one of the functions is called before midnight, and the other after midnight. This problem also @@ -201,7 +201,7 @@ <p>Returns tuple <c>{Year, WeekNum}</c> representing the ISO week number for the actual date. To determine the actual date, use function - <seealso marker="#local_time/0"><c>local_time/0</c></seealso>.</p> + <seemfa marker="#local_time/0"><c>local_time/0</c></seemfa>.</p> </desc> </func> @@ -241,8 +241,8 @@ date after Jan 1, 1970.</p> <warning> <p>This function is deprecated. Use - <seealso marker="#local_time_to_universal_time_dst/1"> - <c>local_time_to_universal_time_dst/1</c></seealso> + <seemfa marker="#local_time_to_universal_time_dst/1"> + <c>local_time_to_universal_time_dst/1</c></seemfa> instead, as it gives a more correct and complete result. Especially for the period that does not exist, as it is skipped during @@ -290,7 +290,7 @@ <desc> <p>Returns Universal Coordinated Time (UTC) converted from the return value from - <seealso marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso>. + <seemfa marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seemfa>. </p> </desc> </func> @@ -300,7 +300,7 @@ <fsummary>Convert now to local date and time.</fsummary> <desc> <p>Returns local date and time converted from the return value from - <seealso marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso>. + <seemfa marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seemfa>. </p> </desc> </func> @@ -311,7 +311,7 @@ <desc> <p>Returns Universal Coordinated Time (UTC) converted from the return value from - <seealso marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso>. + <seemfa marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seemfa>. </p> </desc> </func> diff --git a/lib/stdlib/doc/src/dets.xml b/lib/stdlib/doc/src/dets.xml index ba319cf8ff..873167714c 100644 --- a/lib/stdlib/doc/src/dets.xml +++ b/lib/stdlib/doc/src/dets.xml @@ -84,7 +84,7 @@ is important to realize that a single look-up operation involves a series of disk seek and read operations. The Dets functions are therefore much slower than the corresponding - <seealso marker="ets"><c>ets(3)</c></seealso> functions, + <seeerl marker="ets"><c>ets(3)</c></seeerl> functions, although Dets exports a similar interface.</p> <p>Dets organizes data as a linear hash list and the hash list @@ -107,8 +107,8 @@ ordered disk-based term storage.</p> <p>All Dets functions return <c>{error, Reason}</c> if an error - occurs (<seealso marker="#first/1"><c>first/1</c></seealso> and - <seealso marker="#next/2"><c>next/2</c></seealso> are exceptions, they + occurs (<seemfa marker="#first/1"><c>first/1</c></seemfa> and + <seemfa marker="#next/2"><c>next/2</c></seemfa> are exceptions, they exit the process with the error tuple). If badly formed arguments are specified, all functions exit the process with a <c>badarg</c> message.</p> @@ -124,16 +124,16 @@ <datatype> <name name="bindings_cont"/> <desc> - <p>Opaque continuation used by <seealso marker="#match/1"> - <c>match/1</c></seealso> and <seealso marker="#match/3"> - <c>match/3</c></seealso>.</p> + <p>Opaque continuation used by <seemfa marker="#match/1"> + <c>match/1</c></seemfa> and <seemfa marker="#match/3"> + <c>match/3</c></seemfa>.</p> </desc> </datatype> <datatype> <name name="cont"/> <desc> - <p>Opaque continuation used by <seealso marker="#bchunk/2"> - <c>bchunk/2</c></seealso>.</p> + <p>Opaque continuation used by <seemfa marker="#bchunk/2"> + <c>bchunk/2</c></seemfa>.</p> </desc> </datatype> <datatype> @@ -143,9 +143,9 @@ <name name="match_spec"/> <desc> <p>Match specifications, see section - <seealso marker="erts:match_spec"> - Match Specification in Erlang</seealso> in ERTS User's Guide and the - <seealso marker="ms_transform"><c>ms_transform(3)</c></seealso> + <seeguide marker="erts:match_spec"> + Match Specification in Erlang</seeguide> in ERTS User's Guide and the + <seeerl marker="ms_transform"><c>ms_transform(3)</c></seeerl> module.</p> </desc> </datatype> @@ -158,24 +158,24 @@ <datatype> <name name="object_cont"/> <desc> - <p>Opaque continuation used by <seealso marker="#match_object/1"> - <c>match_object/1</c></seealso> and - <seealso marker="#match_object/3"><c>match_object/3</c></seealso>.</p> + <p>Opaque continuation used by <seemfa marker="#match_object/1"> + <c>match_object/1</c></seemfa> and + <seemfa marker="#match_object/3"><c>match_object/3</c></seemfa>.</p> </desc> </datatype> <datatype> <name name="pattern"/> <desc> <p>For a description of patterns, see - <seealso marker="ets#match/2"><c>ets:match/2</c></seealso>.</p> + <seemfa marker="ets#match/2"><c>ets:match/2</c></seemfa>.</p> </desc> </datatype> <datatype> <name name="select_cont"/> <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> + <p>Opaque continuation used by <seemfa marker="#select/1"> + <c>select/1</c></seemfa> and <seemfa marker="#select/3"> + <c>select/3</c></seemfa>.</p> </desc> </datatype> <datatype> @@ -205,7 +205,7 @@ representation of the returned objects is not public. The lists of data can be used for initializing a table by specifying value <c>bchunk</c> to option <c>format</c> of function - <seealso marker="#init_table/3"><c>init_table/3</c></seealso> + <seemfa marker="#init_table/3"><c>init_table/3</c></seemfa> The Mnesia application uses this function for copying open tables.</p> <p>Unless the table is protected using <c>safe_fixtable/2</c>, @@ -277,7 +277,7 @@ according to the internal order of the table, or <c>'$end_of_table'</c> if the table is empty.</p> <p>Unless the table is protected using <c>safe_fixtable/2</c>, - subsequent calls to <seealso marker="#next/2"><c>next/2</c></seealso> + subsequent calls to <seemfa marker="#next/2"><c>next/2</c></seemfa> do possibly not work as expected if concurrent updates are made to the table.</p> <p>If an error occurs, the process is exited with an error @@ -287,9 +287,9 @@ are not to be used: they are not efficient, and they prevent the use of key <c>'$end_of_table'</c>, as this atom is used to indicate the end of the table. If possible, use functions - <seealso marker="#match/1"><c>match</c></seealso>, - <seealso marker="#match_object/1"><c>match_object</c></seealso>, and - <seealso marker="#select/1"><c>select</c></seealso> + <seemfa marker="#match/1"><c>match</c></seemfa>, + <seemfa marker="#match_object/1"><c>match_object</c></seemfa>, and + <seemfa marker="#select/1"><c>select</c></seemfa> for traversing tables.</p> </desc> </func> @@ -333,21 +333,21 @@ bytes.</p> </item> <item> - <p><c>{filename, </c><seealso marker="file#type-name"> - <c>file:name()</c></seealso><c>}</c> - The name of the file + <p><c>{filename, </c><seetype marker="file#name"> + <c>file:name()</c></seetype><c>}</c> - The name of the file where objects are stored.</p> </item> <item> - <p><c>{keypos, </c><seealso marker="#type-keypos"> - <c>keypos()</c></seealso><c>}</c> - The key position.</p> + <p><c>{keypos, </c><seetype marker="#keypos"> + <c>keypos()</c></seetype><c>}</c> - The key position.</p> </item> <item> <p><c>{size, integer() >= 0}</c> - The number of objects stored in the table.</p> </item> <item> - <p><c>{type, </c><seealso marker="#type-type"> - <c>type()</c></seealso><c>}</c> - The table type.</p> + <p><c>{type, </c><seetype marker="#type"> + <c>type()</c></seetype><c>}</c> - The table type.</p> </item> </list> </desc> @@ -361,16 +361,16 @@ <p>Returns the information associated with <c><anno>Item</anno></c> for table <c><anno>Name</anno></c>. In addition to the <c>{<anno>Item</anno>, <anno>Value</anno>}</c> - pairs defined for <seealso marker="#info/1"><c>info/1</c></seealso>, + pairs defined for <seemfa marker="#info/1"><c>info/1</c></seemfa>, the following items are allowed:</p> <list type="bulleted"> <item> - <p><c>{access, </c><seealso marker="#type-access"> - <c>access()</c></seealso><c>}</c> - The access mode.</p> + <p><c>{access, </c><seetype marker="#access"> + <c>access()</c></seetype><c>}</c> - The access mode.</p> </item> <item> - <p><c>{auto_save, </c><seealso marker="#type-auto_save"> - <c>auto_save()</c></seealso><c>}</c> - The autosave interval.</p> + <p><c>{auto_save, </c><seetype marker="#auto_save"> + <c>auto_save()</c></seetype><c>}</c> - The autosave interval.</p> </item> <item> <p><c>{bchunk_format, binary()}</c> - An opaque binary @@ -429,25 +429,25 @@ There can be any number of processes in the list. If the table is not fixed, <c>SafeFixed</c> is the atom <c>false</c>.</p> <p><c>FixedAtTime</c> corresponds to the result returned by - <seealso marker="erts:erlang#monotonic_time/0"> - <c>erlang:monotonic_time/0</c></seealso> at the time of fixation. + <seemfa marker="erts:erlang#monotonic_time/0"> + <c>erlang:monotonic_time/0</c></seemfa> at the time of fixation. The use of <c>safe_fixed_monotonic_time</c> is - <seealso marker="erts:time_correction#Time_Warp_Safe_Code"> - time warp safe</seealso>.</p> + <seeguide marker="erts:time_correction#Time_Warp_Safe_Code"> + time warp safe</seeguide>.</p> </item> <item> <p><c>{safe_fixed, SafeFixed}</c> - The same as <c>{safe_fixed_monotonic_time, SafeFixed}</c> except the format and value of <c>FixedAtTime</c>.</p> <p><c>FixedAtTime</c> corresponds to the result returned by - <seealso marker="erts:erlang#timestamp/0"> - <c>erlang:timestamp/0</c></seealso> at the time of fixation. + <seemfa marker="erts:erlang#timestamp/0"> + <c>erlang:timestamp/0</c></seemfa> at the time of fixation. Notice that when the system uses single or multi - <seealso marker="erts:time_correction#Time_Warp_Modes">time warp - modes</seealso>, this can produce strange results. This is + <seeguide marker="erts:time_correction#Time_Warp_Modes">time warp + modes</seeguide>, this can produce strange results. This is because the use of <c>safe_fixed</c> is not - <seealso marker="erts:time_correction#Time_Warp_Safe_Code"> - time warp safe</seealso>. Time warp safe code must use + <seeguide marker="erts:time_correction#Time_Warp_Safe_Code"> + time warp safe</seeguide>. Time warp safe code must use <c>safe_fixed_monotonic_time</c> instead.</p> </item> </list> @@ -508,7 +508,7 @@ <c><anno>InitFun</anno></c> is assumed to return a list of tuples. If <c>Format</c> is <c>bchunk</c>, <c><anno>InitFun</anno></c> is assumed to return <c><anno>Data</anno></c> as returned by - <seealso marker="#bchunk/2"><c>bchunk/2</c></seealso>. + <seemfa marker="#bchunk/2"><c>bchunk/2</c></seemfa>. This option overrides option <c>min_no_slots</c>.</p> </item> </list> @@ -544,9 +544,9 @@ <desc> <p>Returns <c>true</c> if it would be possible to initialize table <c><anno>Name</anno></c>, using - <seealso marker="#init_table/3"><c>init_table/3</c></seealso> with + <seemfa marker="#init_table/3"><c>init_table/3</c></seemfa> with option <c>{format, bchunk}</c>, with objects read with - <seealso marker="#bchunk/2"><c>bchunk/2</c></seealso> from some + <seemfa marker="#bchunk/2"><c>bchunk/2</c></seemfa> from some table <c>T</c>, such that calling <c>info(T, bchunk_format)</c> returns <c>BchunkFormat</c>.</p> @@ -613,7 +613,7 @@ ok <p>Returns for each object of table <c><anno>Name</anno></c> that matches <c><anno>Pattern</anno></c> a list of bindings in some unspecified order. For a description of patterns, see - <seealso marker="ets#match/2"><c>ets:match/2</c></seealso>. + <seemfa marker="ets#match/2"><c>ets:match/2</c></seemfa>. If the keypos'th element of <c><anno>Pattern</anno></c> is unbound, all table objects are matched. If the keypos'th element is bound, only the @@ -630,12 +630,12 @@ ok returns a non-empty list of the bindings that match <c><anno>Pattern</anno></c> in some unspecified order. For a description of patterns, see - <seealso marker="ets#match/2"><c>ets:match/2</c></seealso>.</p> + <seemfa marker="ets#match/2"><c>ets:match/2</c></seemfa>.</p> <p>A tuple of the bindings and a continuation is returned, unless the table is empty, in which case <c>'$end_of_table'</c> is returned. The continuation is to be used when matching further objects by calling - <seealso marker="#match/1"><c>match/1</c></seealso>.</p> + <seemfa marker="#match/1"><c>match/1</c></seemfa>.</p> <p>If the keypos'th element of <c><anno>Pattern</anno></c> is bound, all table objects are matched. If the keypos'th element is unbound, all table objects are matched, <c><anno>N</anno></c> @@ -647,7 +647,7 @@ ok same key are always matched at the same time, which implies that more than <anno>N</anno> objects can sometimes be matched.</p> <p>The table is always to be protected using - <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> + <seemfa marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seemfa> before calling <c>match/3</c>, otherwise errors can occur when calling <c>match/1</c>.</p> </desc> @@ -660,7 +660,7 @@ ok <desc> <p>Deletes all objects that match <c><anno>Pattern</anno></c> from table <c><anno>Name</anno></c>. For a description of patterns, - see <seealso marker="ets#match/2"><c>ets:match/2</c></seealso>.</p> + see <seemfa marker="ets#match/2"><c>ets:match/2</c></seemfa>.</p> <p>If the keypos'th element of <c>Pattern</c> is bound, only the objects with the correct key are matched.</p> </desc> @@ -690,7 +690,7 @@ ok <p>Returns a list of all objects of table <c><anno>Name</anno></c> that match <c><anno>Pattern</anno></c> in some unspecified order. For a description of patterns, see - <seealso marker="ets#match/2"><c>ets:match/2</c></seealso>.</p> + <seemfa marker="ets#match/2"><c>ets:match/2</c></seemfa>.</p> <p>If the keypos'th element of <c><anno>Pattern</anno></c> is unbound, all table objects are matched. If the keypos'th element of <c><anno>Pattern</anno></c> is bound, only the @@ -710,12 +710,12 @@ ok and returns a non-empty list of the objects that match <c><anno>Pattern</anno></c> in some unspecified order. For a description of patterns, see - <seealso marker="ets#match/2"><c>ets:match/2</c></seealso>.</p> + <seemfa marker="ets#match/2"><c>ets:match/2</c></seemfa>.</p> <p>A list of objects and a continuation is returned, unless the table is empty, in which case <c>'$end_of_table'</c> is returned. The continuation is to be used when matching further objects by calling - <seealso marker="#match_object/1"><c>match_object/1</c></seealso>.</p> + <seemfa marker="#match_object/1"><c>match_object/1</c></seemfa>.</p> <p>If the keypos'th element of <c><anno>Pattern</anno></c> is bound, all table objects are matched. If the keypos'th element is unbound, all table objects are matched, <c><anno>N</anno></c> @@ -728,7 +728,7 @@ ok in the same reply, which implies that more than <anno>N</anno> objects can sometimes be returned.</p> <p>The table is always to be protected using - <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> + <seemfa marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seemfa> before calling <c>match_object/3</c>, otherwise errors can occur when calling <c>match_object/1</c>.</p> </desc> @@ -738,7 +738,7 @@ ok <name name="member" arity="2" since=""/> <fsummary>Test for occurrence of a key in a Dets table.</fsummary> <desc> - <p>Works like <seealso marker="#lookup/2"><c>lookup/2</c></seealso>, + <p>Works like <seemfa marker="#lookup/2"><c>lookup/2</c></seemfa>, but does not return the objects. Returns <c>true</c> if one or more table elements has key <c><anno>Key</anno></c>, otherwise <c>false</c>.</p> @@ -755,7 +755,7 @@ ok <p>If an error occurs, the process is exited with an error tuple <c>{error, Reason}</c>.</p> <p>To find the first key in the table, use - <seealso marker="#first/1"><c>first/1</c></seealso>.</p> + <seemfa marker="#first/1"><c>first/1</c></seemfa>.</p> </desc> </func> @@ -787,16 +787,16 @@ ok tuples, where the following values are allowed:</p> <list type="bulleted"> <item> - <p><c>{access, </c><seealso marker="#type-access"> - <c>access()</c></seealso><c>}</c> - Existing tables can be + <p><c>{access, </c><seetype marker="#access"> + <c>access()</c></seetype><c>}</c> - Existing tables can be opened in read-only mode. A table that is opened in read-only mode is not subjected to the automatic file reparation algorithm if it is later opened after a crash. Defaults to <c>read_write</c>.</p> </item> <item> - <p><c>{auto_save, </c><seealso marker="#type-auto_save"> - <c>auto_save()</c></seealso><c>}</c> - The autosave + <p><c>{auto_save, </c><seetype marker="#auto_save"> + <c>auto_save()</c></seetype><c>}</c> - The autosave interval. If the interval is an integer <c>Time</c>, the table is flushed to disk whenever it is not accessed for <c>Time</c> milliseconds. A table that has been flushed @@ -806,18 +806,18 @@ ok 180000 (3 minutes).</p> </item> <item> - <p><c>{estimated_no_objects, </c><seealso marker="#type-no_slots"> - <c>no_slots()</c></seealso><c>}</c> - Equivalent to option + <p><c>{estimated_no_objects, </c><seetype marker="#no_slots"> + <c>no_slots()</c></seetype><c>}</c> - Equivalent to option <c>min_no_slots</c>.</p> </item> <item> - <p><c>{file, </c><seealso marker="file#type-name"> - <c>file:name()</c></seealso><c>}</c> - The name of the file to be + <p><c>{file, </c><seetype marker="file#name"> + <c>file:name()</c></seetype><c>}</c> - The name of the file to be opened. Defaults to the table name.</p> </item> <item> - <p><c>{max_no_slots, </c><seealso marker="#type-no_slots"> - <c>no_slots()</c></seealso><c>}</c> - The maximum number + <p><c>{max_no_slots, </c><seetype marker="#no_slots"> + <c>no_slots()</c></seetype><c>}</c> - The maximum number of slots to be used. Defaults to 32 M, which is the maximal value. Notice that a higher value can increase the table fragmentation, and @@ -825,16 +825,16 @@ ok the expense of execution time.</p> </item> <item> - <p><c>{min_no_slots, </c><seealso marker="#type-no_slots"> - <c>no_slots()</c></seealso><c>}</c> - Application + <p><c>{min_no_slots, </c><seetype marker="#no_slots"> + <c>no_slots()</c></seetype><c>}</c> - Application performance can be enhanced with this flag by specifying, when the table is created, the estimated number of different keys to be stored in the table. Defaults to 256, which is the minimum value.</p> </item> <item> - <p><c>{keypos, </c><seealso marker="#type-keypos"> - <c>keypos()</c></seealso><c>}</c> - The position of the + <p><c>{keypos, </c><seetype marker="#keypos"> + <c>keypos()</c></seetype><c>}</c> - The position of the element of each object to be used as key. Defaults to 1. The ability to explicitly state the key position is most convenient when we want to store Erlang @@ -863,8 +863,8 @@ ok <p>Option <c>repair</c> is ignored if the table is already open.</p> </item> <item> - <p><c>{type, </c><seealso marker="#type-type"> - <c>type()</c></seealso><c>}</c> - The table type. Defaults to + <p><c>{type, </c><seetype marker="#type"> + <c>type()</c></seetype><c>}</c> - The table type. Defaults to <c>set</c>.</p> </item> </list> @@ -889,8 +889,8 @@ ok <desc> <p>This function can be used to restore an opaque continuation returned by - <seealso marker="#select/3"><c>select/3</c></seealso> or - <seealso marker="#select/1"><c>select/1</c></seealso> if the + <seemfa marker="#select/3"><c>select/3</c></seemfa> or + <seemfa marker="#select/1"><c>select/1</c></seemfa> if the continuation has passed through external term format (been sent between nodes or stored on disk).</p> <p>The reason for this function is that continuation terms @@ -901,7 +901,7 @@ ok used in subsequent <c>select/1</c> calls even though it has been stored on disk or on another node.</p> <p>For more information and examples, see the - <seealso marker="ets"><c>ets(3)</c></seealso> module.</p> + <seeerl marker="ets"><c>ets(3)</c></seeerl> module.</p> <note> <p>This function is rarely needed in application code. It is used by application Mnesia to provide distributed <c>select/3</c> @@ -933,7 +933,7 @@ ok <c>next/2</c>, or select and match functions work as expected even if the table is fixed; the limited support for concurrency provided by the - <seealso marker="ets"><c>ets(3)</c></seealso> module is not yet + <seeerl marker="ets"><c>ets(3)</c></seeerl> module is not yet provided by Dets. Fixing a table currently only disables resizing of the hash list of the table.</p> @@ -954,8 +954,8 @@ ok table, the match specification, and the number of objects that are matched are all defined by <c><anno>Continuation</anno></c>, which is returned by a previous call to - <seealso marker="#select/1"><c>select/1</c></seealso> or - <seealso marker="#select/3"><c>select/3</c></seealso>.</p> + <seemfa marker="#select/1"><c>select/1</c></seemfa> or + <seemfa marker="#select/3"><c>select/3</c></seemfa>.</p> <p>When all objects of the table have been matched, <c>'$end_of_table'</c> is returned.</p> </desc> @@ -970,7 +970,7 @@ ok <c><anno>MatchSpec</anno></c> to all or some objects stored in table <c><anno>Name</anno></c>. The order of the objects is not specified. For a description of match specifications, see the - <seealso marker="erts:match_spec">ERTS User's Guide</seealso>.</p> + <seeguide marker="erts:match_spec">ERTS User's Guide</seeguide>.</p> <p>If the keypos'th element of <c><anno>MatchSpec</anno></c> is unbound, the match specification is applied to all objects of the table. If the keypos'th element is bound, the match @@ -992,12 +992,12 @@ ok <c><anno>MatchSpec</anno></c> to some or all objects stored in table <c><anno>Name</anno></c>. The order of the objects is not specified. For a description of match specifications, see the - <seealso marker="erts:match_spec">ERTS User's Guide</seealso>.</p> + <seeguide marker="erts:match_spec">ERTS User's Guide</seeguide>.</p> <p>A tuple of the results of applying the match specification and a continuation is returned, unless the table is empty, in which case <c>'$end_of_table'</c> is returned. The continuation is to be used when matching more objects by calling - <seealso marker="#select/1"><c>select/1</c></seealso>.</p> + <seemfa marker="#select/1"><c>select/1</c></seemfa>.</p> <p>If the keypos'th element of <c><anno>MatchSpec</anno></c> is bound, the match specification is applied to all objects of the table with the correct key(s). If the keypos'th element of @@ -1012,7 +1012,7 @@ ok match specification can be applied to more than <anno>N</anno> objects.</p> <p>The table is always to be protected using - <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> + <seemfa marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seemfa> before calling <c>select/3</c>, otherwise errors can occur when calling <c>select/1</c>.</p> </desc> @@ -1027,7 +1027,7 @@ ok applying match specification <c><anno>MatchSpec</anno></c> to the object returns value <c>true</c>. For a description of match specifications, see the - <seealso marker="erts:match_spec">ERTS User's Guide</seealso>. + <seeguide marker="erts:match_spec">ERTS User's Guide</seeguide>. Returns the number of deleted objects.</p> <p>If the keypos'th element of <c><anno>MatchSpec</anno></c> is bound, the match specification is applied to the objects @@ -1070,16 +1070,16 @@ ok <desc> <p>Returns a Query List Comprehension (QLC) query handle. The - <seealso marker="qlc"><c>qlc(3)</c></seealso> module + <seeerl marker="qlc"><c>qlc(3)</c></seeerl> module provides a query language aimed mainly for Mnesia, but ETS tables, Dets tables, and lists are also recognized by <c>qlc</c> as sources of data. Calling - <seealso marker="dets#table/1"><c>dets:table/1,2</c></seealso> is the + <seemfa marker="dets#table/1"><c>dets:table/1,2</c></seemfa> is the means to make Dets table <c><anno>Name</anno></c> usable to <c>qlc</c>.</p> <p>When there are only simple restrictions on the key position, <c>qlc</c> uses - <seealso marker="dets#lookup/2"><c>dets:lookup/2</c></seealso> + <seemfa marker="dets#lookup/2"><c>dets:lookup/2</c></seemfa> to look up the keys. When that is not possible, the whole table is traversed. Option <c>traverse</c> determines how this is done:</p> @@ -1090,8 +1090,8 @@ ok </item> <item> <p><c>select</c> - The table is traversed by calling - <seealso marker="dets#select/3"><c>dets:select/3</c></seealso> and - <seealso marker="dets#select/1"><c>dets:select/1</c></seealso>. + <seemfa marker="dets#select/3"><c>dets:select/3</c></seemfa> and + <seemfa marker="dets#select/1"><c>dets:select/1</c></seemfa>. Option <c>n_objects</c> determines the number of objects returned (the third argument of <c>select/3</c>). The match specification (the second argument of @@ -1109,8 +1109,8 @@ ok </list> </item> <item> - <p><c>{select, </c><seealso marker="#type-match_spec"> - match_spec()</seealso><c>}</c> - As for <c>select</c>, + <p><c>{select, </c><seetype marker="#match_spec"> + match_spec()</seetype><c>}</c> - As for <c>select</c>, the table is traversed by calling <c>dets:select/3</c> and <c>dets:select/1</c>. The difference is that the match specification is specified explicitly. This is how to @@ -1213,9 +1213,9 @@ fun(X) -> {continue, X} end.</pre> <section> <title>See Also</title> - <p><seealso marker="ets"><c>ets(3)</c></seealso>, - <seealso marker="mnesia:mnesia"><c>mnesia(3)</c></seealso>, - <seealso marker="qlc"><c>qlc(3)</c></seealso></p> + <p><seeerl marker="ets"><c>ets(3)</c></seeerl>, + <seeerl marker="mnesia:mnesia"><c>mnesia(3)</c></seeerl>, + <seeerl marker="qlc"><c>qlc(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml index 197269190e..aeb2584509 100644 --- a/lib/stdlib/doc/src/dict.xml +++ b/lib/stdlib/doc/src/dict.xml @@ -34,7 +34,7 @@ <p>This module provides a <c>Key</c>-<c>Value</c> dictionary. The representation of a dictionary is not defined.</p> <p>This module provides the same interface as the - <seealso marker="orddict"><c>orddict(3)</c></seealso> module. + <seeerl marker="orddict"><c>orddict(3)</c></seeerl> module. One difference is that while this module considers two keys as different if they do not match (<c>=:=</c>), <c>orddict</c> considers two keys as different if and only if @@ -45,7 +45,7 @@ <datatype> <name name="dict" n_vars="2"/> <desc><p>Dictionary as returned by - <seealso marker="#new/0"><c>new/0</c></seealso>.</p> + <seemfa marker="#new/0"><c>new/0</c></seemfa>.</p> </desc> </datatype> <datatype> @@ -60,7 +60,7 @@ <desc> <p>Appends a new <c><anno>Value</anno></c> to the current list of values associated with <c><anno>Key</anno></c>.</p> - <p>See also section <seealso marker="#notes">Notes</seealso>.</p> + <p>See also section <seeerl marker="#notes">Notes</seeerl>.</p> </desc> </func> @@ -72,7 +72,7 @@ the current list of values associated with <c><anno>Key</anno></c>. An exception is generated if the initial value associated with <c><anno>Key</anno></c> is not a list of values.</p> - <p>See also section <seealso marker="#notes">Notes</seealso>.</p> + <p>See also section <seeerl marker="#notes">Notes</seeerl>.</p> </desc> </func> @@ -93,7 +93,7 @@ <c><anno>Key</anno></c> is present in dictionary <c>Dict</c>, and an exception is generated if <c><anno>Key</anno></c> is not in the dictionary.</p> - <p>See also section <seealso marker="#notes">Notes</seealso>.</p> + <p>See also section <seeerl marker="#notes">Notes</seeerl>.</p> </desc> </func> @@ -134,7 +134,7 @@ <c>{ok, <anno>Value</anno>}</c>, where <c><anno>Value</anno></c> is the value associated with <c><anno>Key</anno></c>, or <c>error</c> if the key is not present in the dictionary.</p> - <p>See also section <seealso marker="#notes">Notes</seealso>.</p> + <p>See also section <seeerl marker="#notes">Notes</seeerl>.</p> </desc> </func> @@ -307,8 +307,8 @@ update_counter(Key, Incr, D) -> <section> <title>See Also</title> - <p><seealso marker="gb_trees"><c>gb_trees(3)</c></seealso>, - <seealso marker="orddict"><c>orddict(3)</c></seealso></p> + <p><seeerl marker="gb_trees"><c>gb_trees(3)</c></seeerl>, + <seeerl marker="orddict"><c>orddict(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/digraph.xml b/lib/stdlib/doc/src/digraph.xml index 51aabe4ef6..721429d819 100644 --- a/lib/stdlib/doc/src/digraph.xml +++ b/lib/stdlib/doc/src/digraph.xml @@ -39,13 +39,13 @@ directed graphs ("digraphs").</p> <p>The digraphs managed by this module are stored in - <seealso marker="ets">ETS tables</seealso>. + <seeerl marker="ets">ETS tables</seeerl>. That implies the following:</p> <list type="bulleted"> <item><p>Only the process that created the digraph is allowed to update it.</p></item> <item><p>Digraphs will not be garbage collected. The ETS tables used for a - digraph will only be deleted when <seealso marker="#delete/1"><c>delete/1</c></seealso> + digraph will only be deleted when <seemfa marker="#delete/1"><c>delete/1</c></seemfa> is called or the process that created the digraph terminates.</p></item> <item><p>A digraph is a mutable data structure.</p></item> </list> @@ -142,7 +142,7 @@ <datatype> <name name="graph"/> <desc><p>A digraph as returned by - <seealso marker="#new/0"><c>new/0,1</c></seealso>.</p></desc> + <seemfa marker="#new/0"><c>new/0,1</c></seemfa>.</p></desc> </datatype> <datatype> <name>edge()</name> @@ -165,10 +165,10 @@ <desc> <p><c>add_edge/5</c> creates (or modifies) edge <c><anno>E</anno></c> of digraph <c><anno>G</anno></c>, using <c><anno>Label</anno></c> as - the (new) <seealso marker="#label">label</seealso> of the edge. The - edge is <seealso marker="#emanate">emanating</seealso> from + the (new) <seeerl marker="#label">label</seeerl> of the edge. The + edge is <seeerl marker="#emanate">emanating</seeerl> from <c><anno>V1</anno></c> and - <seealso marker="#incident">incident</seealso> + <seeerl marker="#incident">incident</seeerl> on <c><anno>V2</anno></c>. Returns <c><anno>E</anno></c>.</p> <p><c>add_edge(<anno>G</anno>, <anno>V1</anno>, <anno>V2</anno>, <anno>Label</anno>)</c> is equivalent to @@ -181,7 +181,7 @@ <c>add_edge(<anno>G</anno>, <anno>V1</anno>, <anno>V2</anno>, [])</c>. </p> <p>If the edge would create a cycle in - an <seealso marker="#acyclic_digraph">acyclic digraph</seealso>, + an <seeerl marker="#acyclic_digraph">acyclic digraph</seeerl>, <c>{error, {bad_edge, <anno>Path</anno>}}</c> is returned. If <c><anno>G</anno></c> already has an edge with value <c><anno>E</anno></c> connecting a different pair of vertices, @@ -204,7 +204,7 @@ <p><c>add_vertex/3</c> creates (or modifies) vertex <c><anno>V</anno></c> of digraph <c><anno>G</anno></c>, using <c><anno>Label</anno></c> as the (new) - <seealso marker="#label">label</seealso> of the + <seeerl marker="#label">label</seeerl> of the vertex. Returns <c><anno>V</anno></c>.</p> <p><c>add_vertex(<anno>G</anno>, <anno>V</anno>)</c> is equivalent to <c>add_vertex(<anno>G</anno>, <anno>V</anno>, [])</c>. @@ -239,20 +239,20 @@ <fsummary>Delete paths from a digraph.</fsummary> <desc> <p>Deletes edges from digraph <c><anno>G</anno></c> until there are no - <seealso marker="#path">paths</seealso> from vertex + <seeerl marker="#path">paths</seeerl> from vertex <c><anno>V1</anno></c> to vertex <c><anno>V2</anno></c>.</p> <p>A sketch of the procedure employed:</p> <list type="bulleted"> <item> <p>Find an arbitrary - <seealso marker="#simple_path">simple path</seealso> + <seeerl marker="#simple_path">simple path</seeerl> v[1], v[2], ..., v[k] from <c><anno>V1</anno></c> to <c><anno>V2</anno></c> in <c><anno>G</anno></c>.</p> </item> <item> <p>Remove all edges of <c><anno>G</anno></c> - <seealso marker="#emanate">emanating</seealso> from v[i] and - <seealso marker="#incident">incident</seealso> to v[i+1] for + <seeerl marker="#emanate">emanating</seeerl> from v[i] and + <seeerl marker="#incident">incident</seeerl> to v[i+1] for 1 <= i < k (including multiple edges).</p> </item> @@ -270,9 +270,9 @@ <desc> <p>Deletes vertex <c><anno>V</anno></c> from digraph <c><anno>G</anno></c>. Any edges - <seealso marker="#emanate">emanating</seealso> from + <seeerl marker="#emanate">emanating</seeerl> from <c><anno>V</anno></c> or - <seealso marker="#incident">incident</seealso> + <seeerl marker="#incident">incident</seeerl> on <c><anno>V</anno></c> are also deleted.</p> </desc> </func> @@ -305,10 +305,10 @@ <p>Returns <c>{<anno>E</anno>, <anno>V1</anno>, <anno>V2</anno>, <anno>Label</anno>}</c>, where <c><anno>Label</anno></c> is the - <seealso marker="#label">label</seealso> of edge - <c><anno>E</anno></c> <seealso marker="#emanate">emanating</seealso> + <seeerl marker="#label">label</seeerl> of edge + <c><anno>E</anno></c> <seeerl marker="#emanate">emanating</seeerl> from <c><anno>V1</anno></c> and - <seealso marker="#incident">incident</seealso> on + <seeerl marker="#incident">incident</seeerl> on <c><anno>V2</anno></c> of digraph <c><anno>G</anno></c>. If no edge <c><anno>E</anno></c> of digraph <c><anno>G</anno></c> exists, <c>false</c> is returned.</p> @@ -330,8 +330,8 @@ a digraph.</fsummary> <desc> <p>Returns a list of all - edges <seealso marker="#emanate">emanating</seealso> from or - <seealso marker="#incident">incident</seealso> on<c><anno>V</anno></c> + edges <seeerl marker="#emanate">emanating</seeerl> from or + <seeerl marker="#incident">incident</seeerl> on<c><anno>V</anno></c> of digraph <c><anno>G</anno></c>, in some unspecified order.</p> </desc> </func> @@ -340,15 +340,15 @@ <name name="get_cycle" arity="2" since=""/> <fsummary>Find one cycle in a digraph.</fsummary> <desc> - <p>If a <seealso marker="#simple_cycle">simple cycle</seealso> of + <p>If a <seeerl marker="#simple_cycle">simple cycle</seeerl> of length two or more exists through vertex <c><anno>V</anno></c>, the cycle is returned as a list <c>[<anno>V</anno>, ..., <anno>V</anno>]</c> of vertices. - If a <seealso marker="#loop">loop</seealso> through + If a <seeerl marker="#loop">loop</seeerl> through <c><anno>V</anno></c> exists, the loop is returned as a list <c>[<anno>V</anno>]</c>. If no cycles through <c><anno>V</anno></c> exist, <c>false</c> is returned.</p> - <p><seealso marker="#get_path/3"><c>get_path/3</c></seealso> is used + <p><seemfa marker="#get_path/3"><c>get_path/3</c></seemfa> is used for finding a simple cycle through <c><anno>V</anno></c>.</p> </desc> </func> @@ -358,7 +358,7 @@ <fsummary>Find one path in a digraph.</fsummary> <desc> <p>Tries to find - a <seealso marker="#simple_path">simple path</seealso> from vertex + a <seeerl marker="#simple_path">simple path</seeerl> from vertex <c><anno>V1</anno></c> to vertex <c><anno>V2</anno></c> of digraph <c><anno>G</anno></c>. Returns the path as a list <c>[<anno>V1</anno>, ..., <anno>V2</anno>]</c> of vertices, @@ -374,15 +374,15 @@ <fsummary>Find one short cycle in a digraph.</fsummary> <desc> <p>Tries to find an as short as possible - <seealso marker="#simple_cycle">simple cycle</seealso> through + <seeerl marker="#simple_cycle">simple cycle</seeerl> through vertex <c><anno>V</anno></c> of digraph <c>G</c>. Returns the cycle as a list <c>[<anno>V</anno>, ..., <anno>V</anno>]</c> of vertices, or <c>false</c> if no simple cycle through <c><anno>V</anno></c> exists. - Notice that a <seealso marker="#loop">loop</seealso> through + Notice that a <seeerl marker="#loop">loop</seeerl> through <c><anno>V</anno></c> is returned as list <c>[<anno>V</anno>, <anno>V</anno>]</c>.</p> - <p><seealso marker="#get_short_path/3"><c>get_short_path/3</c></seealso> + <p><seemfa marker="#get_short_path/3"><c>get_short_path/3</c></seemfa> is used for finding a simple cycle through <c><anno>V</anno></c>.</p> </desc> </func> @@ -392,7 +392,7 @@ <fsummary>Find one short path in a digraph.</fsummary> <desc> <p>Tries to find an as short as possible - <seealso marker="#simple_path">simple path</seealso> from vertex + <seeerl marker="#simple_path">simple path</seeerl> from vertex <c><anno>V1</anno></c> to vertex <c><anno>V2</anno></c> of digraph <c><anno>G</anno></c>. Returns the path as a list <c>[<anno>V1</anno>, ..., <anno>V2</anno>]</c> of @@ -408,7 +408,7 @@ <name name="in_degree" arity="2" since=""/> <fsummary>Return the in-degree of a vertex of a digraph.</fsummary> <desc> - <p>Returns the <seealso marker="#in_degree">in-degree</seealso> of + <p>Returns the <seeerl marker="#in_degree">in-degree</seeerl> of vertex <c><anno>V</anno></c> of digraph <c><anno>G</anno></c>.</p> </desc> </func> @@ -418,7 +418,7 @@ <fsummary>Return all edges incident on a vertex of a digraph.</fsummary> <desc> <p>Returns a list of all - edges <seealso marker="#incident">incident</seealso> on + edges <seeerl marker="#incident">incident</seeerl> on <c><anno>V</anno></c> of digraph <c><anno>G</anno></c>, in some unspecified order.</p> </desc> @@ -429,7 +429,7 @@ <fsummary>Return all in-neighbors of a vertex of a digraph.</fsummary> <desc> <p>Returns a list of - all <seealso marker="#in_neighbour">in-neighbors</seealso> of + all <seeerl marker="#in_neighbour">in-neighbors</seeerl> of <c><anno>V</anno></c> of digraph <c><anno>G</anno></c>, in some unspecified order.</p> </desc> @@ -483,15 +483,15 @@ <type name="d_protection"/> <desc> <p>Returns - an <seealso marker="#empty_digraph">empty digraph</seealso> with + an <seeerl marker="#empty_digraph">empty digraph</seeerl> with properties according to the options in <c><anno>Type</anno></c>:</p> <taglist> <tag><c>cyclic</c></tag> - <item><p>Allows <seealso marker="#cycle">cycles</seealso> in the + <item><p>Allows <seeerl marker="#cycle">cycles</seeerl> in the digraph (default).</p></item> <tag><c>acyclic</c></tag> <item><p>The digraph is to be kept - <seealso marker="#acyclic_digraph">acyclic</seealso>.</p></item> + <seeerl marker="#acyclic_digraph">acyclic</seeerl>.</p></item> <tag><c>protected</c></tag> <item><p>Other processes can read the digraph (default).</p></item> <tag><c>private</c></tag> @@ -524,7 +524,7 @@ <name name="out_degree" arity="2" since=""/> <fsummary>Return the out-degree of a vertex of a digraph.</fsummary> <desc> - <p>Returns the <seealso marker="#out_degree">out-degree</seealso> of + <p>Returns the <seeerl marker="#out_degree">out-degree</seeerl> of vertex <c><anno>V</anno></c> of digraph <c><anno>G</anno></c>.</p> </desc> </func> @@ -535,7 +535,7 @@ </fsummary> <desc> <p>Returns a list of all - edges <seealso marker="#emanate">emanating</seealso> from + edges <seeerl marker="#emanate">emanating</seeerl> from <c><anno>V</anno></c> of digraph <c><anno>G</anno></c>, in some unspecified order.</p> </desc> @@ -546,7 +546,7 @@ <fsummary>Return all out-neighbors of a vertex of a digraph.</fsummary> <desc> <p>Returns a list of - all <seealso marker="#out_neighbour">out-neighbors</seealso> of + all <seeerl marker="#out_neighbour">out-neighbors</seeerl> of <c><anno>V</anno></c> of digraph <c><anno>G</anno></c>, in some unspecified order.</p> </desc> @@ -558,7 +558,7 @@ <desc> <p>Returns <c>{<anno>V</anno>, <anno>Label</anno>}</c>, where <c><anno>Label</anno></c> is the - <seealso marker="#label">label</seealso> of the vertex + <seeerl marker="#label">label</seeerl> of the vertex <c><anno>V</anno></c> of digraph <c><anno>G</anno></c>, or <c>false</c> if no vertex <c><anno>V</anno></c> of digraph <c><anno>G</anno></c> exists.</p> @@ -577,8 +577,8 @@ <section> <title>See Also</title> - <p><seealso marker="digraph_utils"><c>digraph_utils(3)</c></seealso>, - <seealso marker="ets"><c>ets(3)</c></seealso></p> + <p><seeerl marker="digraph_utils"><c>digraph_utils(3)</c></seeerl>, + <seeerl marker="ets"><c>ets(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/digraph_utils.xml b/lib/stdlib/doc/src/digraph_utils.xml index 8739445852..94fcc26ee5 100644 --- a/lib/stdlib/doc/src/digraph_utils.xml +++ b/lib/stdlib/doc/src/digraph_utils.xml @@ -37,7 +37,7 @@ <description> <p>This module provides algorithms based on depth-first traversal of directed graphs. For basic functions on directed graphs, see the - <seealso marker="digraph"><c>digraph(3)</c></seealso> module.</p> + <seeerl marker="digraph"><c>digraph(3)</c></seeerl> module.</p> <list type="bulleted"> <item> @@ -158,7 +158,7 @@ <fsummary>Check if a digraph is an arborescence.</fsummary> <desc> <p>Returns <c>{yes, <anno>Root</anno>}</c> if <c><anno>Root</anno></c> - is the <seealso marker="#root">root</seealso> of the arborescence + is the <seeerl marker="#root">root</seeerl> of the arborescence <c><anno>Digraph</anno></c>, otherwise <c>no</c>.</p> </desc> </func> @@ -168,7 +168,7 @@ <fsummary>Return the components of a digraph.</fsummary> <desc> <p>Returns a list - of <seealso marker="#components">connected components.</seealso>. + of <seeerl marker="#components">connected components.</seeerl>. Each component is represented by its vertices. The order of the vertices and the order of the components are arbitrary. Each vertex of digraph @@ -181,22 +181,22 @@ <fsummary>Return a condensed graph of a digraph.</fsummary> <desc> <p>Creates a digraph where the vertices are - the <seealso marker="#strong_components">strongly connected - components</seealso> of <c><anno>Digraph</anno></c> as returned by - <seealso marker="#strong_components/1"> - <c>strong_components/1</c></seealso>. + the <seeerl marker="#strong_components">strongly connected + components</seeerl> of <c><anno>Digraph</anno></c> as returned by + <seemfa marker="#strong_components/1"> + <c>strong_components/1</c></seemfa>. If X and Y are two different strongly connected components, and vertices x and y exist in X and Y, respectively, such that there is an - edge <seealso marker="#emanate">emanating</seealso> from x - and <seealso marker="#incident">incident</seealso> on y, then + edge <seeerl marker="#emanate">emanating</seeerl> from x + and <seeerl marker="#incident">incident</seeerl> on y, then an edge emanating from X and incident on Y is created.</p> <p>The created digraph has the same type as <c><anno>Digraph</anno></c>. All vertices and edges have the - default <seealso marker="#label">label</seealso> <c>[]</c>.</p> - <p>Each <seealso marker="#cycle">cycle</seealso> is + default <seeerl marker="#label">label</seeerl> <c>[]</c>.</p> + <p>Each <seeerl marker="#cycle">cycle</seeerl> is included in some strongly connected component, which implies that - a <seealso marker="#topsort">topological ordering</seealso> of the + a <seeerl marker="#topsort">topological ordering</seeerl> of the created digraph always exists.</p> </desc> </func> @@ -205,15 +205,15 @@ <name name="cyclic_strong_components" arity="1" since=""/> <fsummary>Return the cyclic strong components of a digraph.</fsummary> <desc> - <p>Returns a list of <seealso marker="#strong_components">strongly - connected components</seealso>. Each strongly component is represented + <p>Returns a list of <seeerl marker="#strong_components">strongly + connected components</seeerl>. Each strongly component is represented by its vertices. The order of the vertices and the order of the components are arbitrary. Only vertices that are - included in some <seealso marker="#cycle">cycle</seealso> in + included in some <seeerl marker="#cycle">cycle</seeerl> in <c><anno>Digraph</anno></c> are returned, otherwise the returned list is equal to that returned by - <seealso marker="#strong_components/1"> - <c>strong_components/1</c></seealso>.</p> + <seemfa marker="#strong_components/1"> + <c>strong_components/1</c></seemfa>.</p> </desc> </func> @@ -223,7 +223,7 @@ <desc> <p>Returns <c>true</c> if and only if digraph <c><anno>Digraph</anno></c> is - <seealso marker="#acyclic_digraph">acyclic</seealso>.</p> + <seeerl marker="#acyclic_digraph">acyclic</seeerl>.</p> </desc> </func> @@ -233,7 +233,7 @@ <desc> <p>Returns <c>true</c> if and only if digraph <c><anno>Digraph</anno></c> is - an <seealso marker="#arborescence">arborescence</seealso>.</p> + an <seeerl marker="#arborescence">arborescence</seeerl>.</p> </desc> </func> @@ -243,7 +243,7 @@ <desc> <p>Returns <c>true</c> if and only if digraph <c><anno>Digraph</anno></c> is - a <seealso marker="#tree">tree</seealso>.</p> + a <seeerl marker="#tree">tree</seeerl>.</p> </desc> </func> @@ -253,7 +253,7 @@ </fsummary> <desc> <p>Returns a list of all vertices of <c><anno>Digraph</anno></c> that - are included in some <seealso marker="#loop">loop</seealso>.</p> + are included in some <seeerl marker="#loop">loop</seeerl>.</p> </desc> </func> @@ -263,8 +263,8 @@ <desc> <p>Returns all vertices of digraph <c><anno>Digraph</anno></c>. The order is given by - a <seealso marker="#depth_first_traversal">depth-first - traversal</seealso> of the digraph, collecting visited + a <seeerl marker="#depth_first_traversal">depth-first + traversal</seeerl> of the digraph, collecting visited vertices in postorder. More precisely, the vertices visited while searching from an arbitrarily chosen vertex are collected in postorder, and all those collected vertices are @@ -278,8 +278,8 @@ <desc> <p>Returns all vertices of digraph <c><anno>Digraph</anno></c>. The order is given by - a <seealso marker="#depth_first_traversal">depth-first - traversal</seealso> of the digraph, collecting visited + a <seeerl marker="#depth_first_traversal">depth-first + traversal</seeerl> of the digraph, collecting visited vertices in preorder.</p> </desc> </func> @@ -291,7 +291,7 @@ <desc> <p>Returns an unsorted list of digraph vertices such that for each vertex in the list, there is a - <seealso marker="#path">path</seealso> in <c><anno>Digraph</anno></c> + <seeerl marker="#path">path</seeerl> in <c><anno>Digraph</anno></c> from some vertex of <c><anno>Vertices</anno></c> to the vertex. In particular, as paths can have length zero, the vertices of @@ -306,12 +306,12 @@ <desc> <p>Returns an unsorted list of digraph vertices such that for each vertex in the list, there is a - <seealso marker="#path">path</seealso> in <c><anno>Digraph</anno></c> + <seeerl marker="#path">path</seeerl> in <c><anno>Digraph</anno></c> of length one or more from some vertex of <c><anno>Vertices</anno></c> to the vertex. As a consequence, only those vertices of <c><anno>Vertices</anno></c> that are included in - some <seealso marker="#cycle">cycle</seealso> are returned.</p> + some <seeerl marker="#cycle">cycle</seeerl> are returned.</p> </desc> </func> @@ -322,7 +322,7 @@ <desc> <p>Returns an unsorted list of digraph vertices such that for each vertex in the list, there is - a <seealso marker="#path">path</seealso> from the vertex to some + a <seeerl marker="#path">path</seeerl> from the vertex to some vertex of <c><anno>Vertices</anno></c>. In particular, as paths can have length zero, the vertices of <c><anno>Vertices</anno></c> are included in the returned list.</p> @@ -336,11 +336,11 @@ <desc> <p>Returns an unsorted list of digraph vertices such that for each vertex in the list, there is - a <seealso marker="#path">path</seealso> of length one or more + a <seeerl marker="#path">path</seeerl> of length one or more from the vertex to some vertex of <c><anno>Vertices</anno></c>. Therefore only those vertices of <c><anno>Vertices</anno></c> that are included - in some <seealso marker="#cycle">cycle</seealso> are returned.</p> + in some <seeerl marker="#cycle">cycle</seeerl> are returned.</p> </desc> </func> @@ -348,8 +348,8 @@ <name name="strong_components" arity="1" since=""/> <fsummary>Return the strong components of a digraph.</fsummary> <desc> - <p>Returns a list of <seealso marker="#strong_components">strongly - connected components</seealso>. + <p>Returns a list of <seeerl marker="#strong_components">strongly + connected components</seeerl>. Each strongly component is represented by its vertices. The order of the vertices and the order of the components are arbitrary. Each vertex of digraph @@ -363,7 +363,7 @@ <name name="subgraph" arity="3" since=""/> <fsummary>Return a subgraph of a digraph.</fsummary> <desc> - <p>Creates a maximal <seealso marker="#subgraph">subgraph</seealso> + <p>Creates a maximal <seeerl marker="#subgraph">subgraph</seeerl> of <c>Digraph</c> having as vertices those vertices of <c><anno>Digraph</anno></c> that are mentioned in <c><anno>Vertices</anno></c>.</p> @@ -371,10 +371,10 @@ the default, the type of <c><anno>Digraph</anno></c> is used for the subgraph as well. Otherwise the option value of <c>type</c> is used as argument to - <seealso marker="digraph#new/1"><c>digraph:new/1</c></seealso>.</p> + <seemfa marker="digraph#new/1"><c>digraph:new/1</c></seemfa>.</p> <p>If the value of option <c>keep_labels</c> is <c>true</c>, which is the default, - the <seealso marker="#label">labels</seealso> of vertices and edges + the <seeerl marker="#label">labels</seeerl> of vertices and edges of <c><anno>Digraph</anno></c> are used for the subgraph as well. If the value is <c>false</c>, default label <c>[]</c> is used for the vertices and edges of the subgroup.</p> @@ -391,11 +391,11 @@ <fsummary>Return a topological sorting of the vertices of a digraph. </fsummary> <desc> - <p>Returns a <seealso marker="#topsort">topological - ordering</seealso> of the vertices of digraph + <p>Returns a <seeerl marker="#topsort">topological + ordering</seeerl> of the vertices of digraph <c><anno>Digraph</anno></c> if such an ordering exists, otherwise <c>false</c>. For each vertex in the returned list, - no <seealso marker="#out_neighbour">out-neighbors</seealso> + no <seeerl marker="#out_neighbour">out-neighbors</seeerl> occur earlier in the list.</p> </desc> </func> @@ -403,7 +403,7 @@ <section> <title>See Also</title> - <p><seealso marker="digraph"><c>digraph(3)</c></seealso></p> + <p><seeerl marker="digraph"><c>digraph(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/epp.xml b/lib/stdlib/doc/src/epp.xml index 2244b02908..29d3a488c8 100644 --- a/lib/stdlib/doc/src/epp.xml +++ b/lib/stdlib/doc/src/epp.xml @@ -36,7 +36,7 @@ <modulesummary>An Erlang code preprocessor.</modulesummary> <description> <p>The Erlang code preprocessor includes functions that are used by the - <seealso marker="compiler:compile"><c>compile</c></seealso> + <seeerl marker="compiler:compile"><c>compile</c></seeerl> module to preprocess macros and include files before the parsing takes place.</p> @@ -98,10 +98,10 @@ <desc> <p>Returns a string representation of an encoding. The string is recognized by - <seealso marker="#read_encoding/1"><c>read_encoding/1,2</c></seealso>, - <seealso marker="#read_encoding_from_binary/1"> - <c>read_encoding_from_binary/1,2</c></seealso>, and - <seealso marker="#set_encoding/1"><c>set_encoding/1,2</c></seealso> + <seemfa marker="#read_encoding/1"><c>read_encoding/1,2</c></seemfa>, + <seemfa marker="#read_encoding_from_binary/1"> + <c>read_encoding_from_binary/1,2</c></seemfa>, and + <seemfa marker="#set_encoding/1"><c>set_encoding/1,2</c></seemfa> as a valid encoding.</p> </desc> </func> @@ -115,7 +115,7 @@ describes the error or warning. This function is usually called implicitly when processing an <c>ErrorInfo</c> structure (see section - <seealso marker="#errorinfo">Error Information</seealso>).</p> + <seeerl marker="#errorinfo">Error Information</seeerl>).</p> </desc> </func> @@ -198,7 +198,7 @@ <name name="read_encoding" arity="2" since="OTP R16B"/> <fsummary>Read the encoding from a file.</fsummary> <desc> - <p>Read the <seealso marker="#encoding">encoding</seealso> from + <p>Read the <seeerl marker="#encoding">encoding</seeerl> from a file. Returns the read encoding, or <c>none</c> if no valid encoding is found.</p> <p>Option <c>in_comment_only</c> is <c>true</c> by @@ -213,7 +213,7 @@ <name name="read_encoding_from_binary" arity="2" since="OTP R16B"/> <fsummary>Read the encoding from a binary.</fsummary> <desc> - <p>Read the <seealso marker="#encoding">encoding</seealso> from + <p>Read the <seeerl marker="#encoding">encoding</seeerl> from a binary. Returns the read encoding, or <c>none</c> if no valid encoding is found.</p> <p>Option <c>in_comment_only</c> is <c>true</c> by @@ -227,7 +227,7 @@ <name name="set_encoding" arity="1" since="OTP R16B"/> <fsummary>Read and set the encoding of an I/O device.</fsummary> <desc> - <p>Reads the <seealso marker="#encoding">encoding</seealso> from + <p>Reads the <seeerl marker="#encoding">encoding</seeerl> from an I/O device and sets the encoding of the device accordingly. The position of the I/O device referenced by <c><anno>File</anno></c> is not affected. If no valid @@ -242,13 +242,13 @@ <name name="set_encoding" arity="2" since="OTP 17.0"/> <fsummary>Read and set the encoding of an I/O device.</fsummary> <desc> - <p>Reads the <seealso marker="#encoding">encoding</seealso> from + <p>Reads the <seeerl marker="#encoding">encoding</seeerl> from an I/O device and sets the encoding of the device accordingly. The position of the I/O device referenced by <c><anno>File</anno></c> is not affected. If no valid encoding can be read from the I/O device, the encoding of the I/O device is set to the - <seealso marker="#encoding">encoding</seealso> specified by + <seeerl marker="#encoding">encoding</seeerl> specified by <c><anno>Default</anno></c>.</p> <p>Returns the read encoding, or <c>none</c> if no valid encoding is found.</p> @@ -270,7 +270,7 @@ Module:format_error(ErrorDescriptor)</code> <section> <title>See Also</title> - <p><seealso marker="erl_parse"><c>erl_parse(3)</c></seealso></p> + <p><seeerl marker="erl_parse"><c>erl_parse(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/erl_anno.xml b/lib/stdlib/doc/src/erl_anno.xml index 8026aa827b..6c3f0eef4b 100644 --- a/lib/stdlib/doc/src/erl_anno.xml +++ b/lib/stdlib/doc/src/erl_anno.xml @@ -78,30 +78,30 @@ <tag><c>record</c></tag> <item><p>A Boolean indicating if the origin of the abstract code is a record. Used by - <seealso marker="dialyzer:dialyzer">Dialyzer</seealso> + <seeerl marker="dialyzer:dialyzer">Dialyzer</seeerl> to assign types to tuple elements.</p> </item> </taglist> <p>The functions - <seealso marker="erl_scan#column/1"><c>column()</c></seealso>, - <seealso marker="erl_scan#end_location/1"><c>end_location()</c></seealso>, - <seealso marker="erl_scan#line/1"><c>line()</c></seealso>, - <seealso marker="erl_scan#location/1"><c>location()</c></seealso>, and - <seealso marker="erl_scan#text/1"><c>text()</c></seealso> + <seemfa marker="erl_scan#column/1"><c>column()</c></seemfa>, + <seemfa marker="erl_scan#end_location/1"><c>end_location()</c></seemfa>, + <seemfa marker="erl_scan#line/1"><c>line()</c></seemfa>, + <seemfa marker="erl_scan#location/1"><c>location()</c></seemfa>, and + <seemfa marker="erl_scan#text/1"><c>text()</c></seemfa> in the <c>erl_scan</c> module can be used for inspecting annotations in tokens.</p> <p>The functions - <seealso marker="erl_parse#anno_from_term/1"> - <c>anno_from_term()</c></seealso>, - <seealso marker="erl_parse#anno_to_term/1"> - <c>anno_to_term()</c></seealso>, - <seealso marker="erl_parse#fold_anno/3"><c>fold_anno()</c></seealso>, - <seealso marker="erl_parse#map_anno/2"><c>map_anno()</c></seealso>, - <seealso marker="erl_parse#mapfold_anno/3"> - <c>mapfold_anno()</c></seealso>, - and <seealso marker="erl_parse#new_anno/1"><c>new_anno()</c></seealso>, + <seemfa marker="erl_parse#anno_from_term/1"> + <c>anno_from_term()</c></seemfa>, + <seemfa marker="erl_parse#anno_to_term/1"> + <c>anno_to_term()</c></seemfa>, + <seemfa marker="erl_parse#fold_anno/3"><c>fold_anno()</c></seemfa>, + <seemfa marker="erl_parse#map_anno/2"><c>map_anno()</c></seemfa>, + <seemfa marker="erl_parse#mapfold_anno/3"> + <c>mapfold_anno()</c></seemfa>, + and <seemfa marker="erl_parse#new_anno/1"><c>new_anno()</c></seemfa>, in the <c>erl_parse</c> module can be used for manipulating annotations in abstract code.</p> </description> @@ -169,7 +169,7 @@ <fsummary>Return annotations given a term.</fsummary> <desc> <p>Returns annotations with representation <anno>Term</anno>.</p> - <p>See also <seealso marker="#to_term/1">to_term()</seealso>.</p> + <p>See also <seemfa marker="#to_term/1">to_term()</seemfa>.</p> </desc> </func> @@ -291,14 +291,14 @@ </fsummary> <desc> <p>Returns the term representing the annotations <anno>Anno</anno>.</p> - <p>See also <seealso marker="#from_term/1">from_term()</seealso>.</p> + <p>See also <seemfa marker="#from_term/1">from_term()</seemfa>.</p> </desc> </func> </funcs> <section> <title>See Also</title> - <p><seealso marker="erl_parse"><c>erl_parse(3)</c></seealso>, - <seealso marker="erl_scan"><c>erl_scan(3)</c></seealso></p> + <p><seeerl marker="erl_parse"><c>erl_parse(3)</c></seeerl>, + <seeerl marker="erl_scan"><c>erl_scan(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/erl_eval.xml b/lib/stdlib/doc/src/erl_eval.xml index a35b1b34dd..e54dcdbdc9 100644 --- a/lib/stdlib/doc/src/erl_eval.xml +++ b/lib/stdlib/doc/src/erl_eval.xml @@ -37,8 +37,8 @@ <description> <p>This module provides an interpreter for Erlang expressions. The expressions are in the abstract syntax as returned by - <seealso marker="erl_parse"><c>erl_parse</c></seealso>, - the Erlang parser, or <seealso marker="io"><c>io</c></seealso>.</p> + <seeerl marker="erl_parse"><c>erl_parse</c></seeerl>, + the Erlang parser, or <seeerl marker="io"><c>io</c></seeerl>.</p> </description> <datatypes> @@ -54,10 +54,10 @@ </datatype> <datatype> <name name="expressions"/> - <desc><p>As returned by <seealso marker="erl_parse#parse_exprs/1"> - <c>erl_parse:parse_exprs/1</c></seealso> or - <seealso marker="io#parse_erl_exprs/2"> - <c>io:parse_erl_exprs/2</c></seealso>.</p></desc> + <desc><p>As returned by <seemfa marker="erl_parse#parse_exprs/1"> + <c>erl_parse:parse_exprs/1</c></seemfa> or + <seemfa marker="io#parse_erl_exprs/2"> + <c>io:parse_erl_exprs/2</c></seemfa>.</p></desc> </datatype> <datatype> <name name="expression_list"/> @@ -74,8 +74,8 @@ <datatype> <name name="local_function_handler"/> <desc><p>Further described in section - <seealso marker="#local_function_handler"> - Local Function Handler</seealso> in this module</p></desc> + <seeerl marker="#local_function_handler"> + Local Function Handler</seeerl> in this module</p></desc> </datatype> <datatype> <name name="name"/> @@ -86,8 +86,8 @@ <datatype> <name name="non_local_function_handler"/> <desc><p>Further described in section - <seealso marker="#non_local_function_handler"> - Non-Local Function Handler</seealso> in this module.</p></desc> + <seeerl marker="#non_local_function_handler"> + Non-Local Function Handler</seeerl> in this module.</p></desc> </datatype> <datatype> <name name="value"/> @@ -146,10 +146,10 @@ For an explanation of when and how to use arguments <c><anno>LocalFunctionHandler</anno></c> and <c><anno>NonLocalFunctionHandler</anno></c>, see sections - <seealso marker="#local_function_handler"> - Local Function Handler</seealso> and - <seealso marker="#non_local_function_handler"> - Non-Local Function Handler</seealso> in this module.</p> + <seeerl marker="#local_function_handler"> + Local Function Handler</seeerl> and + <seeerl marker="#non_local_function_handler"> + Non-Local Function Handler</seeerl> in this module.</p> <p>Returns <c>{value, <anno>Value</anno>, <anno>NewBindings</anno>}</c> by default. If <c><anno>ReturnFormat</anno></c> is <c>value</c>, only <c><anno>Value</anno></c> is returned.</p> @@ -166,8 +166,8 @@ initial bindings for each expression. Attempts are made to merge the bindings returned from each evaluation. This function is useful in <c>LocalFunctionHandler</c>, see section - <seealso marker="#local_function_handler"> - Local Function Handler</seealso> in this module.</p> + <seeerl marker="#local_function_handler"> + Local Function Handler</seeerl> in this module.</p> <p>Returns <c>{<anno>ValueList</anno>, <anno>NewBindings</anno>}</c>. </p> </desc> @@ -182,15 +182,15 @@ <p>Evaluates <c><anno>Expressions</anno></c> with the set of bindings <c><anno>Bindings</anno></c>, where <c><anno>Expressions</anno></c> is a sequence of expressions (in abstract syntax) of a type that can - be returned by <seealso marker="io#parse_erl_exprs/2"> - <c>io:parse_erl_exprs/2</c></seealso>. + be returned by <seemfa marker="io#parse_erl_exprs/2"> + <c>io:parse_erl_exprs/2</c></seemfa>. For an explanation of when and how to use arguments <c><anno>LocalFunctionHandler</anno></c> and <c><anno>NonLocalFunctionHandler</anno></c>, see sections - <seealso marker="#local_function_handler"> - Local Function Handler</seealso> and - <seealso marker="#non_local_function_handler"> - Non-Local Function Handler</seealso> in this module.</p> + <seeerl marker="#local_function_handler"> + Local Function Handler</seeerl> and + <seeerl marker="#non_local_function_handler"> + Non-Local Function Handler</seeerl> in this module.</p> <p>Returns <c>{value, <anno>Value</anno>, <anno>NewBindings</anno>}</c> </p> </desc> diff --git a/lib/stdlib/doc/src/erl_expand_records.xml b/lib/stdlib/doc/src/erl_expand_records.xml index 0980af94b1..a7f273158c 100644 --- a/lib/stdlib/doc/src/erl_expand_records.xml +++ b/lib/stdlib/doc/src/erl_expand_records.xml @@ -55,7 +55,7 @@ <section> <title>See Also</title> - <p>Section <seealso marker="erts:absform">The Abstract Format</seealso> + <p>Section <seeguide marker="erts:absform">The Abstract Format</seeguide> in ERTS User's Guide.</p> </section> </erlref> diff --git a/lib/stdlib/doc/src/erl_id_trans.xml b/lib/stdlib/doc/src/erl_id_trans.xml index 686f3148a4..337cb6215f 100644 --- a/lib/stdlib/doc/src/erl_id_trans.xml +++ b/lib/stdlib/doc/src/erl_id_trans.xml @@ -49,9 +49,9 @@ <name since="">parse_transform(Forms, Options) -> Forms</name> <fsummary>Transform Erlang forms.</fsummary> <type> - <v>Forms = [<seealso marker="erl_parse#type-abstract_form">erl_parse:abstract_form()</seealso> - | <seealso marker="erl_parse#type-form_info">erl_parse:form_info()</seealso>]</v> - <v>Options = [<seealso marker="compile#type-option">compile:option()</seealso>]</v> + <v>Forms = [<seetype marker="erl_parse#abstract_form">erl_parse:abstract_form()</seetype> + | <seetype marker="erl_parse#form_info">erl_parse:form_info()</seetype>]</v> + <v>Options = [<seetype marker="compile#option">compile:option()</seetype>]</v> </type> <desc> <p>Performs an identity transformation on Erlang forms, as an example. @@ -73,8 +73,8 @@ <section> <title>See Also</title> - <p><seealso marker="erl_parse"><c>erl_parse(3)</c></seealso>, - <seealso marker="compiler:compile"><c>compile(3)</c></seealso></p> + <p><seeerl marker="erl_parse"><c>erl_parse(3)</c></seeerl>, + <seeerl marker="compiler:compile"><c>compile(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/erl_lint.xml b/lib/stdlib/doc/src/erl_lint.xml index 6c8102c37a..bd33a00a48 100644 --- a/lib/stdlib/doc/src/erl_lint.xml +++ b/lib/stdlib/doc/src/erl_lint.xml @@ -85,7 +85,7 @@ that describes the error or warning. This function is usually called implicitly when processing an <c>ErrorInfo</c> structure (see section - <seealso marker="#errorinfo">Error Information</seealso>).</p> + <seeerl marker="#errorinfo">Error Information</seeerl>).</p> </desc> </func> @@ -95,8 +95,8 @@ <desc> <p>Tests if <c><anno>Expr</anno></c> is a legal guard test. <c><anno>Expr</anno></c> is an Erlang term representing the abstract - form for the expression. <seealso marker="erl_parse#parse_exprs/1"> - <c>erl_parse:parse_exprs(Tokens)</c></seealso> + form for the expression. <seemfa marker="erl_parse#parse_exprs/1"> + <c>erl_parse:parse_exprs(Tokens)</c></seemfa> can be used to generate a list of <c><anno>Expr</anno></c>.</p> </desc> </func> @@ -122,14 +122,14 @@ compiler, and to avoid the same description in two places, the elements of <c>Options</c> that control the warnings are only described in the - <seealso marker="compiler:compile#erl_lint_options"> - <c>compile(3)</c></seealso> module.</p> + <seeerl marker="compiler:compile#erl_lint_options"> + <c>compile(3)</c></seeerl> module.</p> <p><c><anno>AbsForms</anno></c> of a module, which comes from a file that is read through <c>epp</c>, the Erlang preprocessor, can come from many files. This means that any references to errors must - include the filename, see the <seealso marker="epp"> - <c>epp(3)</c></seealso> module or parser (see the - <seealso marker="erl_parse"><c>erl_parse(3)</c></seealso> module). + include the filename, see the <seeerl marker="epp"> + <c>epp(3)</c></seeerl> module or parser (see the + <seeerl marker="erl_parse"><c>erl_parse(3)</c></seeerl> module). The returned errors and warnings have the following format:</p> <code type="none"> [{<anno>FileName2</anno>,[<anno>ErrorInfo</anno>]}]</code> @@ -154,8 +154,8 @@ Module:format_error(ErrorDescriptor)</code> <section> <title>See Also</title> - <p><seealso marker="epp"><c>epp(3)</c></seealso>, - <seealso marker="erl_parse"><c>erl_parse(3)</c></seealso></p> + <p><seeerl marker="epp"><c>epp(3)</c></seeerl>, + <seeerl marker="erl_parse"><c>erl_parse(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/erl_parse.xml b/lib/stdlib/doc/src/erl_parse.xml index 9bbf3adb49..25f5d4d905 100644 --- a/lib/stdlib/doc/src/erl_parse.xml +++ b/lib/stdlib/doc/src/erl_parse.xml @@ -38,10 +38,10 @@ <p>This module is the basic Erlang parser that converts tokens into the abstract form of either forms (that is, top-level constructs), expressions, or terms. The Abstract Format is described in the - <seealso marker="erts:absform">ERTS User's Guide</seealso>. + <seeguide marker="erts:absform">ERTS User's Guide</seeguide>. Notice that a token list must end with the <em>dot</em> token to be - acceptable to the parse functions (see the <seealso marker="erl_scan"> - <c>erl_scan(3)</c></seealso>) module.</p> + acceptable to the parse functions (see the <seeerl marker="erl_scan"> + <c>erl_scan(3)</c></seeerl>) module.</p> </description> <datatypes> @@ -69,6 +69,31 @@ <name name="erl_parse_tree"></name> </datatype> <datatype> + <name>af_binelement(_)</name> + <desc> + <p>Abstract representation of an element of a bitstring.</p> + </desc> + </datatype> + <datatype> + <name>af_field_decl()</name> + <desc> + <p>Abstract representation of a record field.</p> + </desc> + </datatype> + <datatype> + <name>af_generator()</name> + <desc> + <p>Abstract representation of a generator + or a bitstring generator.</p> + </desc> + </datatype> + <datatype> + <name>af_remote_function()></name> + <desc> + <p>Abstract representation of a remote function call.</p> + </desc> + </datatype> + <datatype> <name name="error_description"></name> </datatype> <datatype> @@ -95,7 +120,7 @@ <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an abstract form of type <c><anno>AbsTerm</anno></c>. This function is the inverse of - <seealso marker="#normalise/1"><c>normalise/1</c></seealso>.</p> + <seemfa marker="#normalise/1"><c>normalise/1</c></seemfa>.</p> <p><c>erl_parse:abstract(T)</c> is equivalent to <c>erl_parse:abstract(T, 0)</c>.</p> </desc> @@ -113,8 +138,8 @@ <p>Option <c><anno>Encoding</anno></c> is used for selecting which integer lists to be considered as strings. The default is to use the encoding returned by - function <seealso marker="epp#default_encoding/0"> - <c>epp:default_encoding/0</c></seealso>. + function <seemfa marker="epp#default_encoding/0"> + <c>epp:default_encoding/0</c></seemfa>. Value <c>none</c> means that no integer lists are considered as strings. <c>encoding_func()</c> is called with one integer of a list at a time; if it @@ -132,8 +157,8 @@ say <c>T</c>, where a <c>erl_parse</c> tree has collections of annotations. Returns a <c>erl_parse</c> tree where each term <c>T</c> is replaced by the value returned by - <seealso marker="erl_anno#from_term/1"> - <c>erl_anno:from_term(T)</c></seealso>. The term + <seemfa marker="erl_anno#from_term/1"> + <c>erl_anno:from_term(T)</c></seemfa>. The term <c><anno>Term</anno></c> is traversed in a depth-first, left-to-right fashion.</p> </desc> @@ -146,8 +171,8 @@ <p>Returns a term where each collection of annotations <c>Anno</c> of the nodes of the <c>erl_parse</c> tree <c><anno>Abstr</anno></c> is replaced by the term - returned by <seealso marker="erl_anno#to_term/1"> - <c>erl_anno:to_term(Anno)</c></seealso>. The + returned by <seemfa marker="erl_anno#to_term/1"> + <c>erl_anno:to_term(Anno)</c></seemfa>. The <c>erl_parse</c> tree is traversed in a depth-first, left-to-right fashion.</p> </desc> @@ -174,16 +199,16 @@ <name since="">format_error(ErrorDescriptor) -> Chars</name> <fsummary>Format an error descriptor.</fsummary> <type> - <v>ErrorDescriptor = <seealso - marker="#type-error_info">error_description()</seealso></v> + <v>ErrorDescriptor = <seetype + marker="#error_info">error_description()</seetype></v> <v>Chars = [char() | Chars]</v> </type> <desc> <p>Uses an <c>ErrorDescriptor</c> and returns a string that describes the error. This function is usually called implicitly when an <c>ErrorInfo</c> structure is processed - (see section <seealso marker="#errorinfo"> - Error Information</seealso>).</p> + (see section <seeerl marker="#errorinfo"> + Error Information</seeerl>).</p> </desc> </func> @@ -224,12 +249,12 @@ <fsummary>Create new annotations.</fsummary> <desc> <p>Assumes that <c><anno>Term</anno></c> is a term with the same - structure as a <c>erl_parse</c> tree, but with <seealso - marker="erl_anno#type-location">locations</seealso> where a + structure as a <c>erl_parse</c> tree, but with <seetype + marker="erl_anno#location">locations</seetype> where a <c>erl_parse</c> tree has collections of annotations. Returns a <c>erl_parse</c> tree where each location <c>L</c> - is replaced by the value returned by <seealso - marker="erl_anno#new/1"><c>erl_anno:new(L)</c></seealso>. + is replaced by the value returned by <seemfa + marker="erl_anno#new/1"><c>erl_anno:new(L)</c></seemfa>. The term <c><anno>Term</anno></c> is traversed in a depth-first, left-to-right fashion.</p> </desc> @@ -242,7 +267,7 @@ <p>Converts the abstract form <c><anno>AbsTerm</anno></c> of a term into a conventional Erlang data structure (that is, the term itself). This function is the inverse of - <seealso marker="#abstract/1"><c>abstract/1</c></seealso>.</p> + <seemfa marker="#abstract/1"><c>abstract/1</c></seemfa>.</p> </desc> </func> @@ -332,10 +357,10 @@ Module:format_error(ErrorDescriptor)</code> <section> <title>See Also</title> - <p><seealso marker="erl_anno"><c>erl_anno(3)</c></seealso>, - <seealso marker="erl_scan"><c>erl_scan(3)</c></seealso>, - <seealso marker="io"><c>io(3)</c></seealso>, - section <seealso marker="erts:absform">The Abstract Format</seealso> + <p><seeerl marker="erl_anno"><c>erl_anno(3)</c></seeerl>, + <seeerl marker="erl_scan"><c>erl_scan(3)</c></seeerl>, + <seeerl marker="io"><c>io(3)</c></seeerl>, + section <seeguide marker="erts:absform">The Abstract Format</seeguide> in the ERTS User's Guide</p> </section> </erlref> diff --git a/lib/stdlib/doc/src/erl_pp.xml b/lib/stdlib/doc/src/erl_pp.xml index 0a46139db6..0600881fbe 100644 --- a/lib/stdlib/doc/src/erl_pp.xml +++ b/lib/stdlib/doc/src/erl_pp.xml @@ -57,7 +57,7 @@ is to be a valid expression. If <c>HookFunction</c> is equal to <c>none</c>, there is no hook function.</p> <p>The called hook function is to return a (possibly deep) list of - characters. Function <seealso marker="#expr/4"><c>expr/4</c></seealso> + characters. Function <seemfa marker="#expr/4"><c>expr/4</c></seemfa> is useful in a hook.</p> <p>If <c><anno>CurrentIndentation</anno></c> is negative, there are no line breaks and only a space is used as a separator.</p> @@ -68,6 +68,10 @@ <desc> <p>The option <c>quote_singleton_atom_types</c> is used to add quotes to all singleton atom types.</p> + <p>The option <c>linewidth</c> controls the maximum line + width for formatted lines (defaults to 72 characters).</p> + <p>The option <c>indent</c> controls the + indention for formatted lines (defaults to 4 spaces).</p> </desc> </datatype> <datatype> @@ -81,7 +85,7 @@ <name name="attribute" arity="2" since=""/> <fsummary>Pretty print an attribute.</fsummary> <desc> - <p>Same as <seealso marker="#form/1"><c>form/1,2</c></seealso>, + <p>Same as <seemfa marker="#form/1"><c>form/1,2</c></seemfa>, but only for attribute <c><anno>Attribute</anno></c>.</p> </desc> </func> @@ -95,7 +99,7 @@ <desc> <p>Prints one expression. It is useful for implementing hooks (see section - <seealso marker="#knownlimitations">Known Limitations</seealso>).</p> + <seeerl marker="#knownlimitations">Known Limitations</seeerl>).</p> </desc> </func> @@ -105,7 +109,7 @@ <name name="exprs" arity="3" since=""/> <fsummary>Pretty print <c>Expressions</c>.</fsummary> <desc> - <p>Same as <seealso marker="#form/1"><c>form/1,2</c></seealso>, + <p>Same as <seemfa marker="#form/1"><c>form/1,2</c></seemfa>, but only for the sequence of expressions in <c><anno>Expressions</anno></c>.</p> </desc> @@ -118,8 +122,8 @@ <desc> <p>Pretty prints a <c><anno>Form</anno></c>, which is an abstract form of a type that is - returned by <seealso marker="erl_parse#parse_form/1"> - <c>erl_parse:parse_form/1</c></seealso>.</p> + returned by <seemfa marker="erl_parse#parse_form/1"> + <c>erl_parse:parse_form/1</c></seemfa>.</p> </desc> </func> @@ -128,7 +132,7 @@ <name name="function" arity="2" since=""/> <fsummary>Pretty print a function.</fsummary> <desc> - <p>Same as <seealso marker="#form/1"><c>form/1,2</c></seealso>, + <p>Same as <seemfa marker="#form/1"><c>form/1,2</c></seemfa>, but only for function <c><anno>Function</anno></c>.</p> </desc> </func> @@ -138,7 +142,7 @@ <name name="guard" arity="2" since=""/> <fsummary>Pretty print a guard.</fsummary> <desc> - <p>Same as <seealso marker="#form/1"><c>form/1,2</c></seealso>, + <p>Same as <seemfa marker="#form/1"><c>form/1,2</c></seemfa>, but only for the guard test <c><anno>Guard</anno></c>.</p> </desc> </func> @@ -153,9 +157,9 @@ <section> <title>See Also</title> - <p><seealso marker="erl_eval"><c>erl_eval(3)</c></seealso>, - <seealso marker="erl_parse"><c>erl_parse(3)</c></seealso>, - <seealso marker="io"><c>io(3)</c></seealso></p> + <p><seeerl marker="erl_eval"><c>erl_eval(3)</c></seeerl>, + <seeerl marker="erl_parse"><c>erl_parse(3)</c></seeerl>, + <seeerl marker="io"><c>io(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/erl_scan.xml b/lib/stdlib/doc/src/erl_scan.xml index 92c4d5627c..4cfad284e7 100644 --- a/lib/stdlib/doc/src/erl_scan.xml +++ b/lib/stdlib/doc/src/erl_scan.xml @@ -108,7 +108,7 @@ that describes the error or warning. This function is usually called implicitly when an <c>ErrorInfo</c> structure is processed (see section - <seealso marker="#errorinfo">Error Information</seealso>).</p> + <seeerl marker="#errorinfo">Error Information</seeerl>).</p> </desc> </func> @@ -180,10 +180,10 @@ line where the token begins, as well as the text of the token (if option <c>text</c> is specified), all of which can be accessed by calling - <seealso marker="#column/1"><c>column/1</c></seealso>, - <seealso marker="#line/1"><c>line/1</c></seealso>, - <seealso marker="#location/1"><c>location/1</c></seealso>, and - <seealso marker="#text/1"><c>text/1</c></seealso>.</p> + <seemfa marker="#column/1"><c>column/1</c></seemfa>, + <seemfa marker="#line/1"><c>line/1</c></seemfa>, + <seemfa marker="#location/1"><c>location/1</c></seemfa>, and + <seemfa marker="#text/1"><c>text/1</c></seemfa>.</p> <p>A <em>token</em> is a tuple containing information about syntactic category, the token annotations, and the terminal symbol. For punctuation characters (such as <c>;</c> and @@ -296,7 +296,7 @@ <c>tokens(<anno>Continuation</anno>, <anno>CharSpec</anno>, <anno>StartLocation</anno>, [])</c>.</p> <p>For a description of the options, see - <seealso marker="#string/3"><c>string/3</c></seealso>.</p> + <seemfa marker="#string/3"><c>string/3</c></seemfa>.</p> </desc> </func> </funcs> @@ -323,8 +323,8 @@ Module:format_error(ErrorDescriptor)</code> <section> <title>See Also</title> - <p><seealso marker="erl_anno"><c>erl_anno(3)</c></seealso>, - <seealso marker="erl_parse"><c>erl_parse(3)</c></seealso>, - <seealso marker="io"><c>io(3)</c></seealso></p> + <p><seeerl marker="erl_anno"><c>erl_anno(3)</c></seeerl>, + <seeerl marker="erl_parse"><c>erl_parse(3)</c></seeerl>, + <seeerl marker="io"><c>io(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/erl_tar.xml b/lib/stdlib/doc/src/erl_tar.xml index be55dc0777..ace73372c2 100644 --- a/lib/stdlib/doc/src/erl_tar.xml +++ b/lib/stdlib/doc/src/erl_tar.xml @@ -48,41 +48,41 @@ To abide to the convention, add "<c>.tar</c>" to the name.</p> <p>Tar files can be created in one operation using function - <seealso marker="#create/2"><c>create/2</c></seealso> or - <seealso marker="#create/3"><c>create/3</c></seealso>.</p> + <seemfa marker="#create/2"><c>create/2</c></seemfa> or + <seemfa marker="#create/3"><c>create/3</c></seemfa>.</p> <p>Alternatively, for more control, use functions - <seealso marker="#open/2"><c>open/2</c></seealso>, - <seealso marker="#add/3"><c>add/3,4</c></seealso>, and - <seealso marker="#close/1"><c>close/1</c></seealso>.</p> + <seemfa marker="#open/2"><c>open/2</c></seemfa>, + <seemfa marker="#add/3"><c>add/3,4</c></seemfa>, and + <seemfa marker="#close/1"><c>close/1</c></seemfa>.</p> <p>To extract all files from a tar file, use function - <seealso marker="#extract/1"><c>extract/1</c></seealso>. + <seemfa marker="#extract/1"><c>extract/1</c></seemfa>. To extract only some files or to be able to specify some more options, - use function <seealso marker="#extract/2"><c>extract/2</c></seealso>.</p> + use function <seemfa marker="#extract/2"><c>extract/2</c></seemfa>.</p> <p>To return a list of the files in a tar file, - use function <seealso marker="#table/1"><c>table/1</c></seealso> or - <seealso marker="#table/2"><c>table/2</c></seealso>. + use function <seemfa marker="#table/1"><c>table/1</c></seemfa> or + <seemfa marker="#table/2"><c>table/2</c></seemfa>. To print a list of files to the Erlang shell, - use function <seealso marker="#t/1"><c>t/1</c></seealso> or - <seealso marker="#tt/1"><c>tt/1</c></seealso>.</p> + use function <seemfa marker="#t/1"><c>t/1</c></seemfa> or + <seemfa marker="#tt/1"><c>tt/1</c></seemfa>.</p> <p>To convert an error term returned from one of the functions above to a readable message, use function - <seealso marker="#format_error/1"><c>format_error/1</c></seealso>.</p> + <seemfa marker="#format_error/1"><c>format_error/1</c></seemfa>.</p> </description> <section> <title>Unicode Support</title> - <p>If <seealso marker="kernel:file#native_name_encoding/0"> - <c>file:native_name_encoding/0</c></seealso> + <p>If <seemfa marker="kernel:file#native_name_encoding/0"> + <c>file:native_name_encoding/0</c></seemfa> returns <c>utf8</c>, path names are encoded in UTF-8 when creating tar files, and path names are assumed to be encoded in UTF-8 when extracting tar files.</p> - <p>If <seealso marker="kernel:file#native_name_encoding/0"> - <c>file:native_name_encoding/0</c></seealso> + <p>If <seemfa marker="kernel:file#native_name_encoding/0"> + <c>file:native_name_encoding/0</c></seemfa> returns <c>latin1</c>, no translation of path names is done.</p> <p>Unicode metadata stored in PAX headers is preserved</p> @@ -90,16 +90,16 @@ <section> <title>Other Storage Media</title> - <p>The <seealso marker="ftp:ftp"><c>ftp</c></seealso> + <p>The <seeerl marker="ftp:ftp"><c>ftp</c></seeerl> module normally accesses the tar file on disk using - the <seealso marker="kernel:file"><c>file</c></seealso> module. + the <seeerl marker="kernel:file"><c>file</c></seeerl> module. When other needs arise, you can define your own low-level Erlang functions to perform the writing and reading on the storage media; - use function <seealso marker="#init/3"><c>init/3</c></seealso>.</p> + use function <seemfa marker="#init/3"><c>init/3</c></seemfa>.</p> <p>An example of this is the SFTP support in - <seealso marker="ssh:ssh_sftp#open_tar/3"> - <c>ssh_sftp:open_tar/3</c></seealso>. This function opens a tar file + <seemfa marker="ssh:ssh_sftp#open_tar/3"> + <c>ssh_sftp:open_tar/3</c></seemfa>. This function opens a tar file on a remote machine using an SFTP channel.</p> </section> @@ -146,7 +146,7 @@ <type name="add_opt"/> <desc> <p>Adds a file to a tar file that has been opened for writing by - <seealso marker="#open/2"><c>open/1</c></seealso>.</p> + <seemfa marker="#open/2"><c>open/1</c></seemfa>.</p> <p><c>NameInArchive</c> is the name under which the file becomes stored in the tar file. The file gets this name when it is extracted from the tar file.</p> @@ -168,44 +168,44 @@ <p>Reads data in parts from the file. This is intended for memory-limited machines that, for example, builds a tar file on a remote machine over SFTP, see - <seealso marker="ssh:ssh_sftp#open_tar/3"> - <c>ssh_sftp:open_tar/3</c></seealso>.</p> + <seemfa marker="ssh:ssh_sftp#open_tar/3"> + <c>ssh_sftp:open_tar/3</c></seemfa>.</p> </item> <tag><c>{atime,non_neg_integer()}</c></tag> <item> <p>Sets the last time, as - <seealso marker="erts:time_correction#POSIX_Time"> - POSIX time</seealso>, when the file was read. See also - <seealso marker="kernel:file#read_file_info/1"> - <c>file:read_file_info/1</c></seealso>.</p> + <seeguide marker="erts:time_correction#POSIX_Time"> + POSIX time</seeguide>, when the file was read. See also + <seemfa marker="kernel:file#read_file_info/1"> + <c>file:read_file_info/1</c></seemfa>.</p> </item> <tag><c>{mtime,non_neg_integer()}</c></tag> <item> <p>Sets the last time, as - <seealso marker="erts:time_correction#POSIX_Time"> - POSIX time</seealso>, when the file was written. See also - <seealso marker="kernel:file#read_file_info/1"> - <c>file:read_file_info/1</c></seealso>.</p> + <seeguide marker="erts:time_correction#POSIX_Time"> + POSIX time</seeguide>, when the file was written. See also + <seemfa marker="kernel:file#read_file_info/1"> + <c>file:read_file_info/1</c></seemfa>.</p> </item> <tag><c>{ctime,non_neg_integer()}</c></tag> <item> <p>Sets the time, as - <seealso marker="erts:time_correction#POSIX_Time"> - POSIX time</seealso>, when the file was created. See also - <seealso marker="kernel:file#read_file_info/1"> - <c>file:read_file_info/1</c></seealso>.</p> + <seeguide marker="erts:time_correction#POSIX_Time"> + POSIX time</seeguide>, when the file was created. See also + <seemfa marker="kernel:file#read_file_info/1"> + <c>file:read_file_info/1</c></seemfa>.</p> </item> <tag><c>{uid,non_neg_integer()}</c></tag> <item> <p>Sets the file owner. - <seealso marker="kernel:file#read_file_info/1"> - <c>file:read_file_info/1</c></seealso>.</p> + <seemfa marker="kernel:file#read_file_info/1"> + <c>file:read_file_info/1</c></seemfa>.</p> </item> <tag><c>{gid,non_neg_integer()}</c></tag> <item> <p>Sets the group that the file owner belongs to. - <seealso marker="kernel:file#read_file_info/1"> - <c>file:read_file_info/1</c></seealso>.</p> + <seemfa marker="kernel:file#read_file_info/1"> + <c>file:read_file_info/1</c></seemfa>.</p> </item> </taglist> </desc> @@ -216,7 +216,7 @@ <fsummary>Close an open tar file.</fsummary> <desc> <p>Closes a tar file - opened by <seealso marker="#open/2"><c>open/2</c></seealso>.</p> + opened by <seemfa marker="#open/2"><c>open/2</c></seemfa>.</p> </desc> </func> @@ -288,6 +288,11 @@ writing the file. That is, absolute paths will be turned into relative paths. There will be an info message written to the error logger when paths are changed in this way.</p></note> + <warning> + <p>The <c>compressed</c> and <c>cooked</c> flags are invalid when + passing a file descriptor with <c>{file,Fd}</c>. The file is + assumed to have been opened with the appropriate flags.</p> + </warning> </desc> </func> @@ -349,6 +354,11 @@ <p>Prints an informational message for each extracted file.</p> </item> </taglist> + <warning> + <p>The <c>compressed</c> and <c>cooked</c> flags are invalid when + passing a file descriptor with <c>{file,Fd}</c>. The file is + assumed to have been opened with the appropriate flags.</p> + </warning> </desc> </func> @@ -401,14 +411,14 @@ <tag><c>(position,{UserData,Position})</c></tag> <item> <p>Sets the position of <c>UserData</c> as defined for files in - <seealso marker="kernel:file#position-2"> - <c>file:position/2</c></seealso></p> + <seemfa marker="kernel:file#position/2"> + <c>file:position/2</c></seemfa></p> </item> </taglist> <p><em>Example:</em></p> <p>The following is a complete <c>Fun</c> parameter for reading and writing on files using the - <seealso marker="kernel:file"><c>file</c></seealso> module:</p> + <seeerl marker="kernel:file"><c>file</c></seeerl> module:</p> <code type="none"> ExampleFun = fun(write, {Fd,Data}) -> file:write(Fd, Data); @@ -431,7 +441,7 @@ erl_tar:close(TarDesc)</code> <note> <p>This example with the <c>file</c> module operations is not necessary to use directly, as that is what function - <seealso marker="#open/2"><c>open/2</c></seealso> in principle + <seemfa marker="#open/2"><c>open/2</c></seemfa> in principle does.</p> </note> <warning> @@ -470,14 +480,19 @@ erl_tar:close(TarDesc)</code> </item> </taglist> <p>To add one file at the time into an opened tar file, use function - <seealso marker="#add/3"><c>add/3,4</c></seealso>. When you are - finished adding files, use function <seealso marker="#close/1"> - <c>close/1</c></seealso> to close the tar file.</p> + <seemfa marker="#add/3"><c>add/3,4</c></seemfa>. When you are + finished adding files, use function <seemfa marker="#close/1"> + <c>close/1</c></seemfa> to close the tar file.</p> + <warning> + <p>The <c>compressed</c> and <c>cooked</c> flags are invalid when + passing a file descriptor with <c>{file,Fd}</c>. The file must + already be opened with the appropriate flags.</p> + </warning> <warning> <p>The <c>TarDescriptor</c> term is not a file descriptor. You are advised not to rely on the specific contents of this term, as it can change in future Erlang/OTP releases when more features are - added to this module..</p> + added to this module.</p> </warning> </desc> </func> diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index f7e18fbbf8..4f43ae28d0 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -57,10 +57,10 @@ The previous default limit was about 1400 tables and could be increased by setting the environment variable <c>ERL_MAX_ETS_TABLES</c> or the command line option - <seealso marker="erts:erl#+e"><c>+e</c></seealso> before starting the + <seecom marker="erts:erl#+e"><c>+e</c></seecom> before starting the Erlang runtime system. This hard limit has been removed, but it is currently useful to set the <c>ERL_MAX_ETS_TABLES</c> anyway. It should be - set to an approximate of the maximum amount of tables used. This since + set to an approximate of the maximum amount of tables used since an internal table for named tables is sized using this value. If large amounts of named tables are used and <c>ERL_MAX_ETS_TABLES</c> hasn't been increased, the performance of named table lookup will @@ -72,11 +72,11 @@ Even if there are no references to a table from any process, it is not automatically destroyed unless the owner process terminates. To destroy a table explicitly, use function - <seealso marker="#delete/1"><c>delete/1</c></seealso>. + <seemfa marker="#delete/1"><c>delete/1</c></seemfa>. The default owner is the process that created the table. To transfer table ownership at process termination, use - option <seealso marker="#heir"><c>heir</c></seealso> or call - <seealso marker="#give_away/3"><c>give_away/3</c></seealso>.</p> + option <seeerl marker="#heir"><c>heir</c></seeerl> or call + <seemfa marker="#give_away/3"><c>give_away/3</c></seemfa>.</p> <p>Some implementation details:</p> @@ -85,8 +85,8 @@ look-up operation results in a copy of the object.</p></item> <item><p><c>'$end_of_table'</c> is not to be used as a key, as this atom is used to mark the end of the table when using functions - <seealso marker="#first/1"><c>first/1</c></seealso> and - <seealso marker="#next/2"><c>next/2</c></seealso>.</p></item> + <seemfa marker="#first/1"><c>first/1</c></seemfa> and + <seemfa marker="#next/2"><c>next/2</c></seemfa>.</p></item> </list> <p>Notice the subtle difference between @@ -116,13 +116,41 @@ </list> </description> - <section> - <title>Failure</title> - <p>The functions in this module exits with reason - <c>badarg</c> if any argument has the wrong format, if the - table identifier is invalid, or if the operation is denied because of - table access rights (<seealso marker="#protected">protected</seealso> - or <seealso marker="#private">private</seealso>).</p> + <section><marker id="ets_failures"></marker> + <title>Failures</title> + <p>Functions in this module fail by raising an error exception + with error reason:</p> + <taglist> + <tag><c>badarg</c></tag> + <item><p> + If any argument has the wrong format. + </p></item> + <tag><c>badarg</c></tag> + <item><p> + If the table identifier is invalid. + </p></item> + <tag><c>badarg</c></tag> + <item><p> + If the operation is denied because of + table access rights (<seeerl marker="#protected">protected</seeerl> + or <seeerl marker="#private">private</seeerl>). + </p></item> + <tag><c>system_limit</c></tag> + <item><p> + Modification of a value causes it to not be representable + internally in the VM. For example, incrementation of a + counter past the largest integer representable. + </p></item> + <tag><c>system_limit</c></tag> + <item><p> + If a match specification passed as argument has excessive + nesting which causes scheduler stack exhaustion for the + scheduler that the calling process is executing on. + <seecom marker="erts:erl#sched_thread_stack_size">Scheduler + stack size</seecom> can be configured when starting the + runtime system. + </p></item> + </taglist> </section> <section><marker id="concurrency"></marker> @@ -145,32 +173,42 @@ <p>There are different ways to traverse through the objects of a table.</p> <list type="bulleted"> <item><p><em>Single-step</em> traversal one key at at time, using - <seealso marker="#first/1"><c>first/1</c></seealso>, - <seealso marker="#next/2"><c>next/2</c></seealso>, - <seealso marker="#last/1"><c>last/1</c></seealso> and - <seealso marker="#prev/2"><c>prev/2</c></seealso>.</p> + <seemfa marker="#first/1"><c>first/1</c></seemfa>, + <seemfa marker="#next/2"><c>next/2</c></seemfa>, + <seemfa marker="#last/1"><c>last/1</c></seemfa> and + <seemfa marker="#prev/2"><c>prev/2</c></seemfa>.</p> </item> <item><p>Search with simple <em>match patterns</em>, using - <seealso marker="#match/1"><c>match/1/2/3</c></seealso>, - <seealso marker="#match_delete/2"><c>match_delete/2</c></seealso> and - <seealso marker="#match_object/1"><c>match_object/1/2/3</c></seealso>.</p> + <seemfa marker="#match/1"><c>match/1/2/3</c></seemfa>, + <seemfa marker="#match_delete/2"><c>match_delete/2</c></seemfa> and + <seemfa marker="#match_object/1"><c>match_object/1/2/3</c></seemfa>.</p> </item> <item><p>Search with more powerful <em>match specifications</em>, using - <seealso marker="#select/1"><c>select/1/2/3</c></seealso>, - <seealso marker="#select_count/2"><c>select_count/2</c></seealso>, - <seealso marker="#select_delete/2"><c>select_delete/2</c></seealso>, - <seealso marker="#select_replace/2"><c>select_replace/2</c></seealso> and - <seealso marker="#select_reverse/1"><c>select_reverse/1/2/3</c></seealso>.</p> + <seemfa marker="#select/1"><c>select/1/2/3</c></seemfa>, + <seemfa marker="#select_count/2"><c>select_count/2</c></seemfa>, + <seemfa marker="#select_delete/2"><c>select_delete/2</c></seemfa>, + <seemfa marker="#select_replace/2"><c>select_replace/2</c></seemfa> and + <seemfa marker="#select_reverse/1"><c>select_reverse/1/2/3</c></seemfa>.</p> </item> <item><p><em>Table conversions</em>, using - <seealso marker="#tab2file/2"><c>tab2file/2/3</c></seealso> and - <seealso marker="#tab2list/1"><c>tab2list/1</c></seealso>.</p> + <seemfa marker="#tab2file/2"><c>tab2file/2/3</c></seemfa> and + <seemfa marker="#tab2list/1"><c>tab2list/1</c></seemfa>.</p> </item> </list> - <p>None of these ways of table traversal will guarantee a consistent table snapshot - if the table is also updated during the traversal. Moreover, traversals not - done in a <em>safe</em> way, on tables where keys are inserted or deleted - during the traversal, may yield the following undesired effects:</p> + <p> + No table traversal will guarantee a consistent snapshot of the entire + table if the table is also updated by concurrent processes during the + traversal. The result of each concurrently updated object may be seen (or + not) depending on if it has happened when the traversal visits that part + of the table. The only way to guarantee a full consistent table snapshot + (if you really need that) is to disallow concurrent updates during the + entire traversal. + </p> + <p> + Moreover, traversals not done in a <em>safe</em> way, on tables where + keys are inserted or deleted during the traversal, may yield the + following undesired effects: + </p> <list type="bulleted"> <item><p>Any key may be missed.</p></item> <item><p>Any key may be found more than once.</p></item> @@ -184,13 +222,13 @@ <item><p>the entire table traversal is done within one ETS function call.</p> </item> - <item><p>function <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> + <item><p>function <seemfa marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seemfa> is used to keep the table fixated during the entire traversal.</p> </item> </list> <note> <p>Even though the access of a single object is always guaranteed to be - <seealso marker="#concurrency">atomic and isolated</seealso>, each traversal + <seeerl marker="#concurrency">atomic and isolated</seeerl>, each traversal through a table to find the next key is not done with such guarantees. This is often not a problem, but may cause rare subtle "unexpected" effects if a concurrent process inserts objects during a traversal. For example, consider one @@ -209,7 +247,7 @@ ets:insert(t, {3}), ordered directly after <c>1</c>.</p> <p>Effects like this are improbable but possible. The probability will further be reduced (if not vanish) if table option - <seealso marker="#new_2_write_concurrency"><c>write_concurrency</c></seealso> + <seeerl marker="#new_2_write_concurrency"><c>write_concurrency</c></seeerl> is not enabled. This can also only be a potential concern for <c>ordered_set</c> where the traversal order is defined.</p> </note> @@ -235,9 +273,12 @@ true <title>Match Specifications</title> <p>Some of the functions use a <em>match specification</em>, <c>match_spec</c>. For a brief explanation, see - <seealso marker="#select/2"><c>select/2</c></seealso>. For a detailed - description, see section <seealso marker="erts:match_spec"> - Match Specifications in Erlang</seealso> in ERTS User's Guide.</p> + <seemfa marker="#select/2"><c>select/2</c></seemfa>. For a detailed + description, see section <seeguide marker="erts:match_spec"> + Match Specifications in Erlang</seeguide> in ERTS User's Guide.</p> + <p>A match specifications with excessive nesting will cause a + <seeerl marker="#ets_failures"><c>system_limit</c></seeerl> error + exception to be raised.</p> </section> <datatypes> @@ -247,11 +288,11 @@ true <datatype> <name>continuation()</name> <desc> - <p>Opaque continuation used by <seealso marker="#select/1"> - <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> + <p>Opaque continuation used by <seemfa marker="#select/1"> + <c>select/1,3</c></seemfa>, <seemfa marker="#select_reverse/1"> + <c>select_reverse/1,3</c></seemfa>, <seemfa marker="#match/1"> + <c>match/1,3</c></seemfa>, and <seemfa marker="#match_object/1"> + <c>match_object/1,3</c></seemfa>.</p> </desc> </datatype> <datatype> @@ -271,7 +312,7 @@ true <datatype> <name name="tid"/> <desc><p>A table identifier, as returned by - <seealso marker="#new/2"><c>new/2</c></seealso>.</p></desc> + <seemfa marker="#new/2"><c>new/2</c></seemfa>.</p></desc> </datatype> <datatype> <name name="type"/> @@ -318,7 +359,7 @@ true <desc> <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> + <seeerl marker="#concurrency">atomic and isolated</seeerl>.</p> </desc> </func> @@ -338,9 +379,9 @@ true <name name="file2tab" arity="1" since=""/> <fsummary>Read an ETS table from a file.</fsummary> <desc> - <p>Reads a file produced by <seealso marker="#tab2file/2"> - <c>tab2file/2</c></seealso> or - <seealso marker="#tab2file/3"><c>tab2file/3</c></seealso> and + <p>Reads a file produced by <seemfa marker="#tab2file/2"> + <c>tab2file/2</c></seemfa> or + <seemfa marker="#tab2file/3"><c>tab2file/3</c></seemfa> and creates the corresponding table <c><anno>Tab</anno></c>.</p> <p>Equivalent to <c>file2tab(<anno>Filename</anno>, [])</c>.</p> </desc> @@ -350,16 +391,16 @@ true <name name="file2tab" arity="2" since=""/> <fsummary>Read an ETS table from a file.</fsummary> <desc> - <p>Reads a file produced by <seealso marker="#tab2file/2"> - <c>tab2file/2</c></seealso> or <seealso marker="#tab2file/3"> - <c>tab2file/3</c></seealso> and creates the + <p>Reads a file produced by <seemfa marker="#tab2file/2"> + <c>tab2file/2</c></seemfa> or <seemfa marker="#tab2file/3"> + <c>tab2file/3</c></seemfa> and creates the corresponding table <c><anno>Tab</anno></c>.</p> <p>The only supported option is <c>{verify,boolean()}</c>. If verification is turned on (by specifying <c>{verify,true}</c>), the function uses whatever information is present in the file to assert that the information is not damaged. How this is done depends on which <c>extended_info</c> was written using - <seealso marker="#tab2file/3"><c>tab2file/3</c></seealso>.</p> + <seemfa marker="#tab2file/3"><c>tab2file/3</c></seemfa>.</p> <p>If no <c>extended_info</c> is present in the file and <c>{verify,true}</c> is specified, the number of objects written is compared to the size of the original table when the @@ -368,7 +409,7 @@ true table was dumped to file. To avoid this problem, either do not verify files dumped while updated simultaneously or use option <c>{extended_info, [object_count]}</c> to - <seealso marker="#tab2file/3"><c>tab2file/3</c></seealso>, which + <seemfa marker="#tab2file/3"><c>tab2file/3</c></seemfa>, which extends the information in the file with the number of objects written.</p> <p>If verification is turned on and the file was written with @@ -389,7 +430,7 @@ true order of the table is returned. If the table is empty, <c>'$end_of_table'</c> is returned.</p> <p>To find subsequent keys in the table, use - <seealso marker="#next/2"><c>next/2</c></seealso>.</p> + <seemfa marker="#next/2"><c>next/2</c></seemfa>.</p> </desc> </func> @@ -399,7 +440,7 @@ true <desc> <p><c><anno>Acc0</anno></c> is returned if the table is empty. This function is similar to - <seealso marker="lists#foldl/3"><c>lists:foldl/3</c></seealso>. + <seemfa marker="lists#foldl/3"><c>lists:foldl/3</c></seemfa>. The table elements are traversed in an unspecified order, except for <c>ordered_set</c> tables, where they are traversed first to last.</p> <p>If <c><anno>Function</anno></c> inserts objects into the table, @@ -415,7 +456,7 @@ true <desc> <p><c><anno>Acc0</anno></c> is returned if the table is empty. This function is similar to - <seealso marker="lists#foldr/3"><c>lists:foldr/3</c></seealso>. + <seemfa marker="lists#foldr/3"><c>lists:foldr/3</c></seemfa>. The table elements are traversed in an unspecified order, except for <c>ordered_set</c> tables, where they are traversed last to first.</p> <p>If <c><anno>Function</anno></c> inserts objects into the table, @@ -447,7 +488,7 @@ true <p>Pseudo function that by a <c>parse_transform</c> translates <c><anno>LiteralFun</anno></c> typed as parameter in the function call to a - <seealso marker="#match_spec">match specification</seealso>. + <seeerl marker="#match_spec">match specification</seeerl>. With "literal" is meant that the fun must textually be written as the parameter of the function, it cannot be held in a variable that in turn is passed to the function.</p> @@ -503,8 +544,8 @@ Error: fun containing local Erlang function calls code never calls the function, but the function call is replaced by a literal match specification.</p> </warning> - <p>For more information, see <seealso marker="ms_transform#top"> - <c>ms_transform(3)</c></seealso>.</p> + <p>For more information, see <seeerl marker="ms_transform#top"> + <c>ms_transform(3)</c></seeerl>.</p> </desc> </func> @@ -520,7 +561,7 @@ Error: fun containing local Erlang function calls already the owner of the table. The calling process must be the table owner.</p> <p>Notice that this function does not affect option - <seealso marker="#heir"><c>heir</c></seealso> of the table. A table + <seeerl marker="#heir"><c>heir</c></seeerl> of the table. A table owner can, for example, set <c>heir</c> to itself, give the table away, and then get it back if the receiver terminates.</p> </desc> @@ -557,13 +598,17 @@ Error: fun containing local Erlang function calls <item> <p>Indicates if the table is compressed.</p> </item> + <tag><c>{decentralized_counters, boolean()}</c></tag> + <item> + <p>Indicates whether the table uses <c>decentralized_counters</c>.</p> + </item> <tag><c>{heir, pid() | none}</c></tag> <item> <p>The pid of the heir of the table, or <c>none</c> if no heir is set.</p> </item> - <tag><c>{id,</c><seealso marker="#type-tid"> - <c>tid()</c></seealso><c>}</c></tag> + <tag><c>{id,</c><seetype marker="#tid"> + <c>tid()</c></seetype><c>}</c></tag> <item> <p>The table identifier.</p> </item> @@ -592,8 +637,8 @@ Error: fun containing local Erlang function calls <item> <p>The pid of the owner of the table.</p> </item> - <tag><c>{protection,</c> <seealso marker="#type-access"> - <c>access()</c></seealso><c>}</c></tag> + <tag><c>{protection,</c> <seetype marker="#access"> + <c>access()</c></seetype><c>}</c></tag> <item> <p>The table access rights.</p> </item> @@ -601,8 +646,8 @@ Error: fun containing local Erlang function calls <item> <p>The number of objects inserted in the table.</p> </item> - <tag><c>{type,</c> <seealso marker="#type-type"> - <c>type()</c></seealso><c>}</c></tag> + <tag><c>{type,</c> <seetype marker="#type"> + <c>type()</c></seetype><c>}</c></tag> <item> <p>The table type.</p> </item> @@ -616,6 +661,13 @@ Error: fun containing local Erlang function calls <p>Indicates whether the table uses <c>write_concurrency</c>.</p> </item> </taglist> + <note><p>The execution time of this function is affected by + the <seeerl marker="#new_2_decentralized_counters"> + <c>decentralized_counters</c></seeerl> table option. + The execution time is much longer when the <c>decentralized_counters</c> + option is set to <c>true</c> than when the <c>decentralized_counters</c> + option is set to <c>false</c>.</p> + </note> </desc> </func> @@ -631,7 +683,7 @@ Error: fun containing local Erlang function calls not of the correct type, or if <c><anno>Item</anno></c> is not one of the allowed values, a <c>badarg</c> exception is raised.</p> <p>In addition to the <c>{<anno>Item</anno>,<anno>Value</anno>}</c> - pairs defined for <seealso marker="#info/1"><c>info/1</c></seealso>, + pairs defined for <seemfa marker="#info/1"><c>info/1</c></seemfa>, the following items are allowed:</p> <list type="bulleted"> <item> @@ -651,8 +703,8 @@ Error: fun containing local Erlang function calls <p><c>Item=safe_fixed|safe_fixed_monotonic_time, Value={FixationTime,Info}|false</c></p> <p>If the table is fixed using - <seealso marker="#safe_fixtable/2"> - <c>safe_fixtable/2</c></seealso>, + <seemfa marker="#safe_fixtable/2"> + <c>safe_fixtable/2</c></seemfa>, the call returns a tuple where <c>FixationTime</c> is the last time when the table changed from unfixed to fixed.</p> <p>The format and value of <c>FixationTime</c> depends on @@ -661,24 +713,24 @@ Error: fun containing local Erlang function calls <tag><c>safe_fixed</c></tag> <item> <p><c>FixationTime</c> corresponds to the result returned by - <seealso marker="erts:erlang#timestamp/0"> - <c>erlang:timestamp/0</c></seealso> at the time of fixation. + <seemfa marker="erts:erlang#timestamp/0"> + <c>erlang:timestamp/0</c></seemfa> at the time of fixation. Notice that when the system uses single or multi - <seealso marker="erts:time_correction#Time_Warp_Modes">time - warp modes</seealso> this can produce strange results, as + <seeguide marker="erts:time_correction#Time_Warp_Modes">time + warp modes</seeguide> this can produce strange results, as the use of <c>safe_fixed</c> is not - <seealso marker="erts:time_correction#Time_Warp_Safe_Code"> - time warp safe</seealso>. Time warp safe code must use + <seeguide marker="erts:time_correction#Time_Warp_Safe_Code"> + time warp safe</seeguide>. Time warp safe code must use <c>safe_fixed_monotonic_time</c> instead.</p> </item> <tag><c>safe_fixed_monotonic_time</c></tag> <item> <p><c>FixationTime</c> corresponds to the result returned by - <seealso marker="erts:erlang#monotonic_time/0"> - <c>erlang:monotonic_time/0</c></seealso> at the time of + <seemfa marker="erts:erlang#monotonic_time/0"> + <c>erlang:monotonic_time/0</c></seemfa> at the time of fixation. The use of <c>safe_fixed_monotonic_time</c> is - <seealso marker="erts:time_correction#Time_Warp_Safe_Code"> - time warp safe</seealso>.</p> + <seeguide marker="erts:time_correction#Time_Warp_Safe_Code"> + time warp safe</seeguide>.</p> </item> </taglist> <p><c>Info</c> is a possibly empty lists of tuples @@ -686,10 +738,10 @@ Error: fun containing local Erlang function calls table is fixed by now. <c>RefCount</c> is the value of the reference counter and it keeps track of how many times the table has been fixed by the process.</p> - <p>Table fixations are not limited to <seealso marker="#safe_fixtable/2"> - <c>safe_fixtable/2</c></seealso>. Temporary fixations may also - be done by for example <seealso marker="#traversal">traversing - functions</seealso> like <c>select</c> and <c>match</c>. Such + <p>Table fixations are not limited to <seemfa marker="#safe_fixtable/2"> + <c>safe_fixtable/2</c></seemfa>. Temporary fixations may also + be done by for example <seeerl marker="#traversal">traversing + functions</seeerl> like <c>select</c> and <c>match</c>. Such table fixations are automatically released before the corresponding functions returns, but they may be seen by a concurrent call to @@ -701,6 +753,15 @@ Error: fun containing local Erlang function calls <p>Returns internal statistics about tables on an internal format used by OTP test suites. Not for production use.</p></item> </list> + <note> + <p>The execution time of this function is affected by + the <seeerl marker="#new_2_decentralized_counters"> + <c>decentralized_counters</c></seeerl> table option when the second + argument of the function is <c>size</c> or <c>memory</c>. + The execution time is much longer when the <c>decentralized_counters</c> + option is set to <c>true</c> than when the <c>decentralized_counters</c> + option is set to <c>false</c>.</p> + </note> </desc> </func> @@ -714,7 +775,7 @@ Error: fun containing local Erlang function calls see below. This function is provided for compatibility with the <c>dets</c> module, it is not more efficient than filling a table by using - <seealso marker="#insert/2"><c>insert/2</c></seealso>.</p> + <seemfa marker="#insert/2"><c>insert/2</c></seemfa>.</p> <p>When called with argument <c>read</c>, the function <c><anno>InitFun</anno></c> is assumed to return <c>end_of_input</c> when @@ -761,7 +822,7 @@ Error: fun containing local Erlang function calls </item> </list> <p>The entire operation is guaranteed to be - <seealso marker="#concurrency">atomic and isolated</seealso>, + <seeerl marker="#concurrency">atomic and isolated</seeerl>, even when a list of objects is inserted.</p> </desc> </func> @@ -771,7 +832,7 @@ Error: fun containing local Erlang function calls <fsummary>Insert an object into an ETS table if the key is not already present.</fsummary> <desc> - <p>Same as <seealso marker="#insert/2"><c>insert/2</c></seealso> + <p>Same as <seemfa marker="#insert/2"><c>insert/2</c></seemfa> except that instead of overwriting objects with the same key (for <c>set</c> or <c>ordered_set</c>) or adding more objects with keys already existing in the table (for <c>bag</c> and @@ -781,7 +842,7 @@ Error: fun containing local Erlang function calls inserting anything. Nothing is inserted unless <em>all</em> keys present in the list are absent from the table. Like <c>insert/2</c>, the entire operation is guaranteed to be - <seealso marker="#concurrency">atomic and isolated</seealso>.</p> + <seeerl marker="#concurrency">atomic and isolated</seeerl>.</p> </desc> </func> @@ -791,10 +852,10 @@ Error: fun containing local Erlang function calls <c>match_spec_compile</c>.</fsummary> <desc> <p>Checks if a term represent a valid compiled - <seealso marker="#match_spec">match specification</seealso>. + <seeerl marker="#match_spec">match specification</seeerl>. A compiled match specifications is only valid on the Erlang node where - it was compiled by calling <seealso marker="#match_spec_compile/1"> - <c>match_spec_compile/1</c></seealso>.</p> + it was compiled by calling <seemfa marker="#match_spec_compile/1"> + <c>match_spec_compile/1</c></seemfa>.</p> <note> <p> Before STDLIB 3.4 (OTP 20.0) compiled match specifications did @@ -821,10 +882,10 @@ Error: fun containing local Erlang function calls <p>Returns the last key <c><anno>Key</anno></c> according to Erlang term order in table <c>Tab</c> of type <c>ordered_set</c>. For other table types, the function is synonymous to - <seealso marker="#first/1"><c>first/1</c></seealso>. + <seemfa marker="#first/1"><c>first/1</c></seemfa>. If the table is empty, <c>'$end_of_table'</c> is returned.</p> <p>To find preceding keys in the table, use - <seealso marker="#prev/2"><c>prev/2</c></seealso>.</p> + <seemfa marker="#prev/2"><c>prev/2</c></seemfa>.</p> </desc> </func> @@ -896,7 +957,7 @@ Error: fun containing local Erlang function calls <fsummary>Continues matching objects in an ETS table.</fsummary> <desc> <p>Continues a match started with - <seealso marker="#match/3"><c>match/3</c></seealso>. The next + <seemfa marker="#match/3"><c>match/3</c></seemfa>. The next chunk of the size specified in the initial <c>match/3</c> call is returned together with a new <c><anno>Continuation</anno></c>, which can be used in subsequent calls to this function.</p> @@ -942,20 +1003,20 @@ Error: fun containing local Erlang function calls <fsummary>Match the objects in an ETS table against a pattern and return part of the answers.</fsummary> <desc> - <p>Works like <seealso marker="#match/2"><c>match/2</c></seealso>, + <p>Works like <seemfa marker="#match/2"><c>match/2</c></seemfa>, but returns only a limited (<c><anno>Limit</anno></c>) number of matching objects. Term <c><anno>Continuation</anno></c> can then - be used in subsequent calls to <seealso marker="#match/1"> - <c>match/1</c></seealso> to get the next chunk of matching + be used in subsequent calls to <seemfa marker="#match/1"> + <c>match/1</c></seemfa> to get the next chunk of matching objects. This is a space-efficient way to work on objects in a table, which is faster than traversing the table object by object using - <seealso marker="#first/1"><c>first/1</c></seealso> and - <seealso marker="#next/2"><c>next/2</c></seealso>.</p> + <seemfa marker="#first/1"><c>first/1</c></seemfa> and + <seemfa marker="#next/2"><c>next/2</c></seemfa>.</p> <p>If the table is empty, <c>'$end_of_table'</c> is returned.</p> - <p>Use <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> - to guarantee <seealso marker="#traversal">safe traversal</seealso> - for subsequent calls to <seealso marker="#match/1"><c>match/1</c></seealso>.</p> + <p>Use <seemfa marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seemfa> + to guarantee <seeerl marker="#traversal">safe traversal</seeerl> + for subsequent calls to <seemfa marker="#match/1"><c>match/1</c></seemfa>.</p> </desc> </func> @@ -966,7 +1027,7 @@ Error: fun containing local Erlang function calls <desc> <p>Deletes all objects that match pattern <c><anno>Pattern</anno></c> from table <c><anno>Tab</anno></c>. For a description of patterns, - see <seealso marker="#match/2"><c>match/2</c></seealso>.</p> + see <seemfa marker="#match/2"><c>match/2</c></seemfa>.</p> </desc> </func> @@ -975,7 +1036,7 @@ Error: fun containing local Erlang function calls <fsummary>Continues matching objects in an ETS table.</fsummary> <desc> <p>Continues a match started with - <seealso marker="#match_object/3"><c>match_object/3</c></seealso>. + <seemfa marker="#match_object/3"><c>match_object/3</c></seemfa>. The next chunk of the size specified in the initial <c>match_object/3</c> call is returned together with a new <c><anno>Continuation</anno></c>, which can be used in subsequent @@ -992,7 +1053,7 @@ Error: fun containing local Erlang function calls <desc> <p>Matches the objects in table <c><anno>Tab</anno></c> against pattern <c><anno>Pattern</anno></c>. For a description of patterns, - see <seealso marker="#match/2"><c>match/2</c></seealso>. + see <seemfa marker="#match/2"><c>match/2</c></seemfa>. The function returns a list of all objects that match the pattern.</p> <p>If the key is specified in the pattern, the match is very @@ -1009,22 +1070,22 @@ Error: fun containing local Erlang function calls <fsummary>Match the objects in an ETS table against a pattern and return part of the answers.</fsummary> <desc> - <p>Works like <seealso marker="#match_object/2"> - <c>match_object/2</c></seealso>, but only returns a + <p>Works like <seemfa marker="#match_object/2"> + <c>match_object/2</c></seemfa>, but only returns a limited (<c><anno>Limit</anno></c>) number of matching objects. Term <c><anno>Continuation</anno></c> can then be used in subsequent - calls to <seealso marker="#match_object/1"> - <c>match_object/1</c></seealso> to get the next chunk of matching + calls to <seemfa marker="#match_object/1"> + <c>match_object/1</c></seemfa> to get the next chunk of matching objects. This is a space-efficient way to work on objects in a table, which is faster than traversing the table object by object using - <seealso marker="#first/1"><c>first/1</c></seealso> and - <seealso marker="#next/2"><c>next/2</c></seealso>.</p> + <seemfa marker="#first/1"><c>first/1</c></seemfa> and + <seemfa marker="#next/2"><c>next/2</c></seemfa>.</p> <p>If the table is empty, <c>'$end_of_table'</c> is returned.</p> - <p>Use <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> - to guarantee <seealso marker="#traversal">safe traversal</seealso> - for subsequent calls to <seealso marker="#match_object/1"> - <c>match_object/1</c></seealso>.</p> + <p>Use <seemfa marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seemfa> + to guarantee <seeerl marker="#traversal">safe traversal</seeerl> + for subsequent calls to <seemfa marker="#match_object/1"> + <c>match_object/1</c></seemfa>.</p> </desc> </func> @@ -1034,19 +1095,18 @@ Error: fun containing local Erlang function calls </fsummary> <desc> <p>Transforms a - <seealso marker="#match_spec">match specification</seealso> into an + <seeerl marker="#match_spec">match specification</seeerl> into an internal representation that can be used in subsequent calls to - <seealso marker="#match_spec_run/2"><c>match_spec_run/2</c></seealso>. + <seemfa marker="#match_spec_run/2"><c>match_spec_run/2</c></seemfa>. The internal representation is opaque. To check the validity of a compiled match specification, use - <seealso marker="#is_compiled_ms/1"><c>is_compiled_ms/1</c></seealso>. + <seemfa marker="#is_compiled_ms/1"><c>is_compiled_ms/1</c></seemfa>. </p> - <p>If term <c><anno>MatchSpec</anno></c> cannot be compiled (does not - represent a valid match specification), a <c>badarg</c> exception is - raised.</p> + <p>If term <c><anno>MatchSpec</anno></c> does not represent a valid + match specification, a <c>badarg</c> exception is raised.</p> <note> <p>This function has limited use in normal code. It is used by the - <seealso marker="dets"><c>dets</c></seealso> module + <seeerl marker="dets"><c>dets</c></seeerl> module to perform the <c>dets:select()</c> operations.</p> </note> </desc> @@ -1058,10 +1118,10 @@ Error: fun containing local Erlang function calls list of terms.</fsummary> <desc> <p>Executes the matching specified in a compiled - <seealso marker="#match_spec">match specification</seealso> on a list + <seeerl marker="#match_spec">match specification</seeerl> on a list of terms. Term <c><anno>CompiledMatchSpec</anno></c> is to be - the result of a call to <seealso marker="#match_spec_compile/1"> - <c>match_spec_compile/1</c></seealso> and is hence the internal + the result of a call to <seemfa marker="#match_spec_compile/1"> + <c>match_spec_compile/1</c></seemfa> and is hence the internal representation of the match specification one wants to use.</p> <p>The matching is executed on each element in <c><anno>List</anno></c> and the function returns a list containing all results. If an element @@ -1082,7 +1142,7 @@ ets:match_spec_run(ets:tab2list(Table), ets:select(Table, MatchSpec),</code> <note> <p>This function has limited use in normal code. It is used by the - <seealso marker="dets"><c>dets</c></seealso> module + <seeerl marker="dets"><c>dets</c></seeerl> module to perform the <c>dets:select()</c> operations and by Mnesia during transactions.</p> </note> @@ -1093,7 +1153,7 @@ ets:select(Table, MatchSpec),</code> <name name="member" arity="2" since=""/> <fsummary>Tests for occurrence of a key in an ETS table.</fsummary> <desc> - <p>Works like <seealso marker="#lookup/2"><c>lookup/2</c></seealso>, + <p>Works like <seemfa marker="#lookup/2"><c>lookup/2</c></seemfa>, but does not return the objects. Returns <c>true</c> if one or more elements in the table has key <c><anno>Key</anno></c>, otherwise <c>false</c>.</p> @@ -1113,7 +1173,8 @@ ets:select(Table, MatchSpec),</code> table is named. Default values are used for omitted options. This means that not specifying any options (<c>[]</c>) is the same as specifying <c>[set, protected, {keypos,1}, {heir,none}, - {write_concurrency,false}, {read_concurrency,false}]</c>.</p> + {write_concurrency,false}, {read_concurrency,false}, + {decentralized_counters,false}]</c>.</p> <taglist> <tag><c>set</c></tag> <item> @@ -1172,7 +1233,7 @@ ets:select(Table, MatchSpec),</code> <p>The function will also return the <c><anno>Name</anno></c> instead of the table identifier. To get the table identifier of a named table, use - <seealso marker="#whereis/1"><c>whereis/1</c></seealso>.</p> + <seemfa marker="#whereis/1"><c>whereis/1</c></seemfa>.</p> </item> <tag><c>{keypos,<anno>Pos</anno>}</c></tag> <item> @@ -1208,17 +1269,27 @@ ets:select(Table, MatchSpec),</code> (and read) by concurrent processes. This is achieved to some degree at the expense of memory consumption and the performance of sequential access and concurrent reading.</p> - <p>Option <c>write_concurrency</c> can be combined with option - <seealso marker="#new_2_read_concurrency"> - <c>read_concurrency</c></seealso>. You typically want to combine - these when large concurrent read bursts and large concurrent + <p>The <c>write_concurrency</c> option can be combined with the options + <seeerl marker="#new_2_read_concurrency"> + <c>read_concurrency</c></seeerl> and + <seeerl marker="#new_2_decentralized_counters"> + <c>decentralized_counters</c></seeerl>. You typically want to combine + <c>write_concurrency</c> with <c>read_concurrency</c> when large + concurrent read bursts and large concurrent write bursts are common; for more information, see option - <seealso marker="#new_2_read_concurrency"> - <c>read_concurrency</c></seealso>.</p> + <seeerl marker="#new_2_read_concurrency"> + <c>read_concurrency</c></seeerl>. The <c>decentralized_counters</c> + option is turned on by default for tables of type <c>ordered_set</c> + with the <c>write_concurrency</c> option enabled, and the + <c>decentralized_counters</c> option is turned off by default for + all other table types. + For more information, see the documentation for the + <seeerl marker="#new_2_decentralized_counters"> + <c>decentralized_counters</c></seeerl> option.</p> <p>Notice that this option does not change any guarantees about - <seealso marker="#concurrency">atomicity and isolation</seealso>. + <seeerl marker="#concurrency">atomicity and isolation</seeerl>. Functions that makes such promises over many objects (like - <seealso marker="#insert/2"><c>insert/2</c></seealso>) + <seemfa marker="#insert/2"><c>insert/2</c></seemfa>) gain less (or nothing) from this option.</p> <p>The memory consumption inflicted by both <c>write_concurrency</c> and <c>read_concurrency</c> is a constant overhead per table for @@ -1252,11 +1323,43 @@ ets:select(Table, MatchSpec),</code> operations repeatedly. In this case, you would get a performance degradation by enabling this option.</p> <p>Option <c>read_concurrency</c> can be combined with option - <seealso marker="#new_2_write_concurrency"> - <c>write_concurrency</c></seealso>. + <seeerl marker="#new_2_write_concurrency"> + <c>write_concurrency</c></seeerl>. You typically want to combine these when large concurrent read bursts and large concurrent write bursts are common.</p> - <marker id="new_2_compressed"></marker> + <marker id="new_2_decentralized_counters"></marker> + </item> + <tag><c>{decentralized_counters,boolean()}</c></tag> + <item> + <p> + Performance tuning. Defaults to <c>true</c> for tables + of type <c>ordered_set</c> with the + <seeerl marker="#new_2_write_concurrency"> + <c>write_concurrency</c></seeerl> option enabled, and defaults to + false for all other table types. This option has no effect if + the <c>write_concurrency</c> option is set to <c>false</c>.</p> + <p> + When this option is set to <c>true</c>, the table is optimized for + frequent concurrent calls to operations that modify the tables + size and/or its memory consumption (e.g., <seemfa + marker="#insert/2"><c>insert/2</c></seemfa> and <seemfa + marker="#delete/2"><c>delete/2</c></seemfa>). + The drawback is that calls to + <seemfa marker="#info/1"><c>info/1</c></seemfa> and + <seemfa marker="#info/2"><c>info/2</c></seemfa> with <c>size</c> or + <c>memory</c> as the second argument can get much slower when the + <c>decentralized_counters</c> option is turned on.</p> + <p> + When this option is enabled the counters for the + table size and memory consumption are distributed over + several cache lines and the scheduling threads are + mapped to one of those cache lines. The <c>erl</c> + option <seecom + marker="erts:erl#+dcg"><c>+dcg</c></seecom> can be used + to control the number of cache lines that the counters + are distributed over. + </p> + <marker id="new_2_compressed"></marker> </item> <tag><c>compressed</c></tag> <item> @@ -1281,10 +1384,10 @@ ets:select(Table, MatchSpec),</code> according to the internal order of the table is returned. If no next key exists, <c>'$end_of_table'</c> is returned.</p> <p>To find the first key in the table, use - <seealso marker="#first/1"><c>first/1</c></seealso>.</p> + <seemfa marker="#first/1"><c>first/1</c></seemfa>.</p> <p>Unless a table of type <c>set</c>, <c>bag</c>, or <c>duplicate_bag</c> is fixated using - <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso>, + <seemfa marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seemfa>, a call to <c>next/2</c> will fail if <c><anno>Key1</anno></c> no longer exists in the table. For table type <c>ordered_set</c>, the function always returns the next key after <c><anno>Key1</anno></c> in term @@ -1302,10 +1405,10 @@ ets:select(Table, MatchSpec),</code> <c><anno>Key1</anno></c> according to Erlang term order in table <c><anno>Tab</anno></c> of type <c>ordered_set</c>. For other table types, the function is synonymous to - <seealso marker="#next/2"><c>next/2</c></seealso>. + <seemfa marker="#next/2"><c>next/2</c></seemfa>. If no previous key exists, <c>'$end_of_table'</c> is returned.</p> <p>To find the last key in an <c>ordered_set</c> table, use - <seealso marker="#last/1"><c>last/1</c></seealso>.</p> + <seemfa marker="#last/1"><c>last/1</c></seemfa>.</p> </desc> </func> @@ -1325,8 +1428,8 @@ ets:select(Table, MatchSpec),</code> that has passed through external representation.</fsummary> <desc> <p>Restores an opaque continuation returned by - <seealso marker="#select/3"><c>select/3</c></seealso> or - <seealso marker="#select/1"><c>select/1</c></seealso> if the + <seemfa marker="#select/3"><c>select/3</c></seemfa> or + <seemfa marker="#select/1"><c>select/1</c></seemfa> if the continuation has passed through external term format (been sent between nodes or stored on disk).</p> <p>The reason for this function is that continuation terms @@ -1364,7 +1467,7 @@ ets:select(ets:repair_continuation(MaybeBroken,MS)).</code> <p>The actual behavior of compiled match specifications when recreated from external format has changed and may change in future releases, but this interface remains for backward compatibility. - See <seealso marker="#is_compiled_ms/1"><c>is_compiled_ms/1</c></seealso>.</p> + See <seemfa marker="#is_compiled_ms/1"><c>is_compiled_ms/1</c></seemfa>.</p> </note> </desc> </func> @@ -1374,16 +1477,16 @@ ets:select(ets:repair_continuation(MaybeBroken,MS)).</code> <fsummary>Fix an ETS table for safe traversal.</fsummary> <desc> <p>Fixes a table of type <c>set</c>, <c>bag</c>, or - <c>duplicate_bag</c> for <seealso marker="#traversal"> - safe traversal</seealso> using - <seealso marker="#first/1"><c>first/1</c></seealso> & - <seealso marker="#next/2"><c>next/2</c></seealso>, - <seealso marker="#match/3"><c>match/3</c></seealso> & - <seealso marker="#match/1"><c>match/1</c></seealso>, - <seealso marker="#match_object/3"><c>match_object/3</c></seealso> & - <seealso marker="#match_object/1"><c>match_object/1</c></seealso>, or - <seealso marker="#select/3"><c>select/3</c></seealso> & - <seealso marker="#select/1"><c>select/1</c></seealso>.</p> + <c>duplicate_bag</c> for <seeerl marker="#traversal"> + safe traversal</seeerl> using + <seemfa marker="#first/1"><c>first/1</c></seemfa> & + <seemfa marker="#next/2"><c>next/2</c></seemfa>, + <seemfa marker="#match/3"><c>match/3</c></seemfa> & + <seemfa marker="#match/1"><c>match/1</c></seemfa>, + <seemfa marker="#match_object/3"><c>match_object/3</c></seemfa> & + <seemfa marker="#match_object/1"><c>match_object/1</c></seemfa>, or + <seemfa marker="#select/3"><c>select/3</c></seemfa> & + <seemfa marker="#select/1"><c>select/1</c></seemfa>.</p> <p>A process fixes a table by calling <c>safe_fixtable(<anno>Tab</anno>, true)</c>. The table remains fixed until the process releases it by calling @@ -1394,8 +1497,8 @@ ets:select(ets:repair_continuation(MaybeBroken,MS)).</code> A reference counter is kept on a per process basis, and N consecutive fixes requires N releases to release the table.</p> <p>When a table is fixed, a sequence of - <seealso marker="#first/1"><c>first/1</c></seealso> and - <seealso marker="#next/2"><c>next/2</c></seealso> calls are + <seemfa marker="#first/1"><c>first/1</c></seemfa> and + <seemfa marker="#next/2"><c>next/2</c></seemfa> calls are guaranteed to succeed even if keys are removed during the traversal. The keys for objects inserted or deleted during a traversal may or may not be returned by <c>next/2</c> depending on @@ -1424,13 +1527,13 @@ clean_all_with_value(Tab,X,Key) -> objects is never freed. The performance of operations on the table also degrades significantly.</p> <p>To retrieve information about which processes have fixed which - tables, use <seealso marker="#info_2_safe_fixed_monotonic_time"> - <c>info(Tab, safe_fixed_monotonic_time)</c></seealso>. A system with + tables, use <seeerl marker="#info_2_safe_fixed_monotonic_time"> + <c>info(Tab, safe_fixed_monotonic_time)</c></seeerl>. A system with many processes fixing tables can need a monitor that sends alarms when tables have been fixed for too long.</p> <p>Notice that <c>safe_fixtable/2</c> is not necessary for table type <c>ordered_set</c> and for traversals done by a single ETS function call, - like <seealso marker="#select/2"><c>select/2</c></seealso>.</p> + like <seemfa marker="#select/2"><c>select/2</c></seemfa>.</p> </desc> </func> @@ -1439,7 +1542,7 @@ clean_all_with_value(Tab,X,Key) -> <fsummary>Continue matching objects in an ETS table.</fsummary> <desc> <p>Continues a match started with - <seealso marker="#select/3"><c>select/3</c></seealso>. The next + <seemfa marker="#select/3"><c>select/3</c></seemfa>. The next chunk of the size specified in the initial <c>select/3</c> call is returned together with a new <c><anno>Continuation</anno></c>, which can be used in subsequent calls to this function.</p> @@ -1454,10 +1557,10 @@ clean_all_with_value(Tab,X,Key) -> match specification.</fsummary> <desc> <p>Matches the objects in table <c><anno>Tab</anno></c> using a - <seealso marker="#match_spec">match specification</seealso>. + <seeerl marker="#match_spec">match specification</seeerl>. This is a more general call than - <seealso marker="#match/2"><c>match/2</c></seealso> and - <seealso marker="#match_object/2"><c>match_object/2</c></seealso> + <seemfa marker="#match/2"><c>match/2</c></seemfa> and + <seemfa marker="#match_object/2"><c>match_object/2</c></seemfa> calls. In its simplest form, the match specification is as follows:</p> <code type="none"> @@ -1469,7 +1572,7 @@ Result = "Term construct"</code> <p>This means that the match specification is always a list of one or more tuples (of arity 3). The first element of the tuple is to be a pattern as described in - <seealso marker="#match/2"><c>match/2</c></seealso>. + <seemfa marker="#match/2"><c>match/2</c></seemfa>. The second element of the tuple is to be a list of 0 or more guard tests (described below). The third element of the tuple is to be a list containing a @@ -1512,8 +1615,8 @@ ets:select(Tab,[{{'$1','$2','$1'},[],['$_']}])</code> ets:select(Tab,[{{'$1','$2','$1'},[],[{{'$1','$2','$3'}}]}])</code> <p>This syntax is equivalent to the syntax used in the trace patterns (see the - <seealso marker="runtime_tools:dbg"> - <c>dbg(3)</c></seealso>) module in Runtime_Tools.</p> + <seeerl marker="runtime_tools:dbg"> + <c>dbg(3)</c></seeerl>) module in Runtime_Tools.</p> <p>The <c>Guard</c>s are constructed as tuples, where the first element is the test name and the remaining elements are the test parameters. To check for a specific type @@ -1548,20 +1651,20 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> <fsummary>Match the objects in an ETS table against a match specification and return part of the answers.</fsummary> <desc> - <p>Works like <seealso marker="#select/2"><c>select/2</c></seealso>, + <p>Works like <seemfa marker="#select/2"><c>select/2</c></seemfa>, but only returns a limited (<c><anno>Limit</anno></c>) number of matching objects. Term <c><anno>Continuation</anno></c> can then be used in subsequent - calls to <seealso marker="#select/1"><c>select/1</c></seealso> + calls to <seemfa marker="#select/1"><c>select/1</c></seemfa> 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 by - object using <seealso marker="#first/1"><c>first/1</c></seealso> - and <seealso marker="#next/2"><c>next/2</c></seealso>.</p> + object using <seemfa marker="#first/1"><c>first/1</c></seemfa> + and <seemfa marker="#next/2"><c>next/2</c></seemfa>.</p> <p>If the table is empty, <c>'$end_of_table'</c> is returned.</p> - <p>Use <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> - to guarantee <seealso marker="#traversal">safe traversal</seealso> - for subsequent calls to <seealso marker="#select/1"><c>select/1</c></seealso>.</p> + <p>Use <seemfa marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seemfa> + to guarantee <seeerl marker="#traversal">safe traversal</seeerl> + for subsequent calls to <seemfa marker="#select/1"><c>select/1</c></seemfa>.</p> </desc> </func> @@ -1572,13 +1675,13 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> specification returned <c>true</c>.</fsummary> <desc> <p>Matches the objects in table <c><anno>Tab</anno></c> using a - <seealso marker="#match_spec">match specification</seealso>. If the + <seeerl marker="#match_spec">match specification</seeerl>. If the match specification returns <c>true</c> for an object, that object considered a match and is counted. For any other result from the match specification the object is not considered a match and is therefore not counted.</p> <p>This function can be described as a - <seealso marker="#match_delete/2"><c>match_delete/2</c></seealso> + <seemfa marker="#match_delete/2"><c>match_delete/2</c></seemfa> function that does not delete any elements, but only counts them.</p> <p>The function returns the number of objects matched.</p> </desc> @@ -1591,12 +1694,12 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> returns <c>true</c>.</fsummary> <desc> <p>Matches the objects in table <c><anno>Tab</anno></c> using a - <seealso marker="#match_spec">match specification</seealso>. If the + <seeerl marker="#match_spec">match specification</seeerl>. If the match specification returns <c>true</c> for an object, that object is removed from the table. For any other result from the match specification the object is retained. This is a more general - call than the <seealso marker="#match_delete/2"> - <c>match_delete/2</c></seealso> call.</p> + call than the <seemfa marker="#match_delete/2"> + <c>match_delete/2</c></seemfa> call.</p> <p>The function returns the number of objects deleted from the table.</p> <note> @@ -1613,11 +1716,11 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> <fsummary>Match and replace objects atomically in an ETS table</fsummary> <desc> <p>Matches the objects in the table <c><anno>Tab</anno></c> using a - <seealso marker="#match_spec">match specification</seealso>. For each + <seeerl marker="#match_spec">match specification</seeerl>. For each matched object, the existing object is replaced with the match specification result.</p> <p>The match-and-replace operation for each individual object is guaranteed to be - <seealso marker="#concurrency">atomic and isolated</seealso>. The + <seeerl marker="#concurrency">atomic and isolated</seeerl>. The <c>select_replace</c> table traversal as a whole, like all other select functions, does not give such guarantees.</p> <p>The match specifiction must be guaranteed to <em>retain the key</em> @@ -1651,13 +1754,13 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), <name name="select_reverse" arity="1" since="OTP R14B"/> <fsummary>Continue matching objects in an ETS table.</fsummary> <desc> - <p>Continues a match started with <seealso marker="#select_reverse/3"> - <c>select_reverse/3</c></seealso>. For tables of type + <p>Continues a match started with <seemfa marker="#select_reverse/3"> + <c>select_reverse/3</c></seemfa>. For tables of type <c>ordered_set</c>, the traversal of the table continues to objects with keys earlier in the Erlang term order. The returned list also contains objects with keys in reverse order. For all other table types, the behavior is exactly that of - <seealso marker="#select/1"><c>select/1</c></seealso>.</p> + <seemfa marker="#select/1"><c>select/1</c></seemfa>.</p> <p><em>Example:</em></p> <code> 1> T = ets:new(x,[ordered_set]). @@ -1685,7 +1788,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), <fsummary>Match the objects in an ETS table against a match specification.</fsummary> <desc> - <p>Works like <seealso marker="#select/2"><c>select/2</c></seealso>, + <p>Works like <seemfa marker="#select/2"><c>select/2</c></seemfa>, but returns the list in reverse order for table type <c>ordered_set</c>. For all other table types, the return value is identical to that of <c>select/2</c>.</p> @@ -1697,7 +1800,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), <fsummary>Match the objects in an ETS table against a match specification and return part of the answers.</fsummary> <desc> - <p>Works like <seealso marker="#select/3"><c>select/3</c></seealso>, + <p>Works like <seemfa marker="#select/3"><c>select/3</c></seemfa>, but for table type <c>ordered_set</c> traversing is done starting at the last object in Erlang term order and moves to the first. For all other table @@ -1716,7 +1819,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), <desc> <p>Sets table options. The only allowed option to be set after the table has been created is - <seealso marker="#heir"><c>heir</c></seealso>. + <seeerl marker="#heir"><c>heir</c></seeerl>. The calling process must be the table owner.</p> </desc> </func> @@ -1738,7 +1841,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), the function fails with reason <c>badarg</c>.</p> <p>Unless a table of type <c>set</c>, <c>bag</c>, or <c>duplicate_bag</c> is protected using - <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso>, + <seemfa marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seemfa>, a traversal can fail if concurrent updates are made to the table. For table type <c>ordered_set</c>, the function returns a list containing @@ -1817,8 +1920,8 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), <fsummary>Return a list of all objects in an ETS table.</fsummary> <desc> <p>Returns information about the table dumped to file by - <seealso marker="#tab2file/2"><c>tab2file/2</c></seealso> or - <seealso marker="#tab2file/3"><c>tab2file/3</c></seealso>.</p> + <seemfa marker="#tab2file/2"><c>tab2file/2</c></seemfa> or + <seemfa marker="#tab2file/3"><c>tab2file/3</c></seemfa>.</p> <p>The following items are returned:</p> <taglist> <tag><c>name</c></tag> @@ -1826,7 +1929,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), <p>The name of the dumped table. If the table was a named table, a table with the same name cannot exist when the table is loaded from file with - <seealso marker="#file2tab/2"><c>file2tab/2</c></seealso>. + <seemfa marker="#file2tab/2"><c>file2tab/2</c></seemfa>. If the table is not saved as a named table, this field has no significance when loading the table from file.</p> @@ -1867,8 +1970,8 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), <item> <p>The extended information written in the file footer to allow stronger verification during table loading from file, as - specified to <seealso marker="#tab2file/3"> - <c>tab2file/3</c></seealso>. Notice that this + specified to <seemfa marker="#tab2file/3"> + <c>tab2file/3</c></seemfa>. Notice that this function only tells <em>which</em> information is present, not the values in the file footer. The value is a list containing one or more of the atoms <c>object_count</c> and <c>md5sum</c>.</p> @@ -1885,8 +1988,8 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), </taglist> <p>An error is returned if the file is inaccessible, badly damaged, or not produced with - <seealso marker="#tab2file/2"><c>tab2file/2</c></seealso> or - <seealso marker="#tab2file/3"><c>tab2file/3</c></seealso>.</p> + <seemfa marker="#tab2file/2"><c>tab2file/2</c></seemfa> or + <seemfa marker="#tab2file/3"><c>tab2file/3</c></seemfa>.</p> </desc> </func> @@ -1897,14 +2000,14 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), <desc> <p>Returns a Query List Comprehension (QLC) query handle. The - <seealso marker="qlc"><c>qlc</c></seealso> module provides + <seeerl marker="qlc"><c>qlc</c></seeerl> module provides a query language aimed mainly at Mnesia, but ETS tables, Dets tables, and lists are also recognized by QLC as sources of data. Calling <c>table/1,2</c> is the means to make the ETS table <c>Tab</c> usable to QLC.</p> <p>When there are only simple restrictions on the key position, - QLC uses <seealso marker="#lookup/2"><c>lookup/2</c></seealso> + QLC uses <seemfa marker="#lookup/2"><c>lookup/2</c></seemfa> to look up the keys. When that is not possible, the whole table is traversed. Option <c>traverse</c> determines how this is done:</p> @@ -1912,24 +2015,24 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), <tag><c>first_next</c></tag> <item> <p>The table is traversed one key at a time by calling - <seealso marker="#first/1"><c>first/1</c></seealso> and - <seealso marker="#next/2"><c>next/2</c></seealso>.</p> + <seemfa marker="#first/1"><c>first/1</c></seemfa> and + <seemfa marker="#next/2"><c>next/2</c></seemfa>.</p> </item> <tag><c>last_prev</c></tag> <item> <p>The table is traversed one key at a time by calling - <seealso marker="#last/1"><c>last/1</c></seealso> and - <seealso marker="#prev/2"><c>prev/2</c></seealso>.</p> + <seemfa marker="#last/1"><c>last/1</c></seemfa> and + <seemfa marker="#prev/2"><c>prev/2</c></seemfa>.</p> </item> <tag><c>select</c></tag> <item> <p>The table is traversed by calling - <seealso marker="#select/3"><c>select/3</c></seealso> and - <seealso marker="#select/1"><c>select/1</c></seealso>. + <seemfa marker="#select/3"><c>select/3</c></seemfa> and + <seemfa marker="#select/1"><c>select/1</c></seemfa>. Option <c>n_objects</c> determines the number of objects returned (the third argument of <c>select/3</c>); the default is to return <c>100</c> objects at a time. The - <seealso marker="#match_spec">match specification</seealso> (the + <seeerl marker="#match_spec">match specification</seeerl> (the second argument of <c>select/3</c>) is assembled by QLC: simple filters are translated into equivalent match specifications while more complicated filters must be applied to all @@ -1939,8 +2042,8 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), <tag><c>{select, <anno>MatchSpec</anno>}</c></tag> <item> <p>As for <c>select</c>, the table is traversed by calling - <seealso marker="#select/3"><c>select/3</c></seealso> and - <seealso marker="#select/1"><c>select/1</c></seealso>. + <seemfa marker="#select/3"><c>select/3</c></seemfa> and + <seemfa marker="#select/1"><c>select/1</c></seemfa>. The difference is that the match specification is explicitly specified. This is how to state match specifications that cannot easily be expressed within the syntax provided by QLC.</p> @@ -1978,8 +2081,8 @@ true</pre> by either <em>comparing equal</em> the key of an object in an <c>ordered_set</c> table, or <em>matching</em> in other types of tables (for details on the difference, see - <seealso marker="#lookup/2"><c>lookup/2</c></seealso> and - <seealso marker="#new/2"><c>new/2</c></seealso>).</p> + <seemfa marker="#lookup/2"><c>lookup/2</c></seemfa> and + <seemfa marker="#new/2"><c>new/2</c></seemfa>).</p> </desc> </func> <func> @@ -1988,8 +2091,8 @@ true</pre> </fsummary> <desc> <p>This function is a utility to test a - <seealso marker="#match_spec">match specification</seealso> used in - calls to <seealso marker="#select/2"><c>select/2</c></seealso>. + <seeerl marker="#match_spec">match specification</seeerl> used in + calls to <seemfa marker="#select/2"><c>select/2</c></seemfa>. The function both tests <c><anno>MatchSpec</anno></c> for "syntactic" correctness and runs the match specification against object <c><anno>Tuple</anno></c>.</p> @@ -2004,8 +2107,8 @@ true</pre> descriptions of what was wrong with the match specification.</p> <p>This is a useful debugging and test tool, especially when writing complicated <c>select/2</c> calls.</p> - <p>See also: <seealso marker="erts:erlang#match_spec_test/3"> - erlang:match_spec_test/3</seealso>.</p> + <p>See also: <seemfa marker="erts:erlang#match_spec_test/3"> + erlang:match_spec_test/3</seemfa>.</p> </desc> </func> @@ -2040,7 +2143,7 @@ true</pre> counters, without the trouble of having to look up an object, update the object by incrementing an element, and insert the resulting object into the table again. The operation is guaranteed to be - <seealso marker="#concurrency">atomic and isolated</seealso>.</p> + <seeerl marker="#concurrency">atomic and isolated</seeerl>.</p> <p>This function destructively update the object with key <c><anno>Key</anno></c> in table <c><anno>Tab</anno></c> by adding <c><anno>Incr</anno></c> to the element at position @@ -2074,8 +2177,8 @@ true</pre> 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 (for details on the difference, see - <seealso marker="#lookup/2"><c>lookup/2</c></seealso> and - <seealso marker="#new/2"><c>new/2</c></seealso>).</p> + <seemfa marker="#lookup/2"><c>lookup/2</c></seemfa> and + <seemfa marker="#new/2"><c>new/2</c></seemfa>).</p> <p>If a default object <c><anno>Default</anno></c> is specified, it is used as the object to be updated if the key is missing from the table. The @@ -2133,8 +2236,8 @@ true</pre> 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 (for details on the difference, see - <seealso marker="#lookup/2"><c>lookup/2</c></seealso> and - <seealso marker="#new/2"><c>new/2</c></seealso>).</p> + <seemfa marker="#lookup/2"><c>lookup/2</c></seemfa> and + <seemfa marker="#new/2"><c>new/2</c></seemfa>).</p> <p>The function fails with reason <c>badarg</c> in the following situations:</p> <list type="bulleted"> @@ -2151,7 +2254,7 @@ true</pre> <fsummary>Retrieves the tid() of a named table.</fsummary> <desc> <p>This function returns the - <seealso marker="#type-tid"><c>tid()</c></seealso> of the named table + <seetype marker="#tid"><c>tid()</c></seetype> of the named table identified by <c><anno>TableName</anno></c>, or <c>undefined</c> if no such table exists. The <c>tid()</c> can be used in place of the table name in all operations, which is slightly faster since the name diff --git a/lib/stdlib/doc/src/file_sorter.xml b/lib/stdlib/doc/src/file_sorter.xml index 0bd2399bff..3a90ade7dd 100644 --- a/lib/stdlib/doc/src/file_sorter.xml +++ b/lib/stdlib/doc/src/file_sorter.xml @@ -242,7 +242,7 @@ output(L) -> <item> <p><c>{file_error, FileName, file:posix()}</c> - For an explanation of <c>file:posix()</c>, see - <seealso marker="kernel:file"><c>file(3)</c></seealso>.</p> + <seeerl marker="kernel:file"><c>file(3)</c></seeerl>.</p> </item> <item> <p><c>{premature_eof, FileName}</c> - End-of-file was diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml index 5df415834f..75040e03de 100644 --- a/lib/stdlib/doc/src/filelib.xml +++ b/lib/stdlib/doc/src/filelib.xml @@ -37,14 +37,14 @@ </modulesummary> <description> <p>This module contains utilities on a higher level than the - <seealso marker="kernel:file"><c>file</c></seealso> module.</p> + <seeerl marker="kernel:file"><c>file</c></seeerl> module.</p> <p>This module does not support "raw" filenames (that is, files whose names do not comply with the expected encoding). Such files are ignored by the functions in this module.</p> <p>For more information about raw filenames, see the - <seealso marker="kernel:file"><c>file</c></seealso> module.</p> + <seeerl marker="kernel:file"><c>file</c></seeerl> module.</p> <note> <p> @@ -123,7 +123,7 @@ <c><anno>F</anno></c> in directory <c><anno>Dir</anno></c> that match the regular expression <c><anno>RegExp</anno></c> (for a description of the allowed regular expressions, - see the <seealso marker="re"><c>re</c></seealso> module). + see the <seeerl marker="re"><c>re</c></seeerl> module). If <c><anno>Recursive</anno></c> is <c>true</c>, all subdirectories to <c>Dir</c> are processed. The regular expression matching is only done on @@ -137,7 +137,7 @@ not conform to the expected character encoding (that is, are not encoded in valid UTF-8).</p> <p>For more information about raw filenames, see the - <seealso marker="kernel:file"><c>file</c></seealso> module.</p> + <seeerl marker="kernel:file"><c>file</c></seeerl> module.</p> </desc> </func> @@ -256,7 +256,7 @@ filelib:wildcard("lib/**/*.{erl,hrl}")</code> <fsummary>Match filenames using Unix-style wildcards starting at a specified directory.</fsummary> <desc> - <p>Same as <seealso marker="#wildcard/1"><c>wildcard/1</c></seealso>, + <p>Same as <seemfa marker="#wildcard/1"><c>wildcard/1</c></seemfa>, except that <c><anno>Cwd</anno></c> is used instead of the working directory.</p> </desc> @@ -273,8 +273,8 @@ filelib:wildcard("lib/**/*.{erl,hrl}")</code> corresponding path ending in <c>"src"</c> should be searched.</p> <p>If <c><anno>Rules</anno></c> is left out or is an empty list, the default system rules are used. See also the Kernel application - parameter <seealso - marker="kernel:kernel_app#source_search_rules"><c>source_search_rules</c></seealso>.</p> + parameter <seeapp + marker="kernel:kernel_app#source_search_rules"><c>source_search_rules</c></seeapp>.</p> </desc> </func> <func> @@ -297,14 +297,44 @@ filelib:wildcard("lib/**/*.{erl,hrl}")</code> look for a file with a corresponding extension <c>.erl</c> by replacing the suffix <c>"ebin"</c> of the object directory path with <c>"src"</c> or <c>"src/*"</c>. - The file search is done through <seealso - marker="#find_file/3"><c>find_file/3</c></seealso>. The directory of + The file search is done through <seemfa + marker="#find_file/3"><c>find_file/3</c></seemfa>. The directory of the object file is always tried before any other directory specified by the rules.</p> <p>If <c><anno>Rules</anno></c> is left out or is an empty list, the default system rules are used. See also the Kernel application - parameter <seealso - marker="kernel:kernel_app#source_search_rules"><c>source_search_rules</c></seealso>.</p> + parameter <seeapp + marker="kernel:kernel_app#source_search_rules"><c>source_search_rules</c></seeapp>.</p> + </desc> + </func> + <func> + <name name="safe_relative_path" arity="2" since="OTP 23.0"/> + <fsummary>Sanitize a relative path to avoid directory traversal attacks.</fsummary> + <desc> + <p>Sanitizes the relative path by eliminating ".." and "." + components to protect against directory traversal attacks. + Either returns the sanitized path name, or the atom + <c>unsafe</c> if the path is unsafe. + The path is considered unsafe in the following circumstances:</p> + <list type="bulleted"> + <item><p>The path is not relative.</p></item> + <item><p>A ".." component would climb up above the root of + the relative path.</p></item> + <item><p>A symbolic link in the path points above the root + of the relative path.</p></item> + </list> + <p><em>Examples:</em></p> + <pre> +1> <input>{ok, Cwd} = file:get_cwd().</input> +... +2> <input>filelib:safe_relative_path("dir/sub_dir/..", Cwd).</input> +"dir" +3> <input>filelib:safe_relative_path("dir/..", Cwd).</input> +[] +4> <input>filelib:safe_relative_path("dir/../..", Cwd).</input> +unsafe +5> <input>filelib:safe_relative_path("/abs/path", Cwd).</input> +unsafe</pre> </desc> </func> </funcs> diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index 70a1e60499..ec2ff0f40c 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -44,21 +44,21 @@ <p>In Windows, all functions return filenames with forward slashes only, even if the arguments contain backslashes. To normalize a filename by removing redundant directory separators, use - <seealso marker="#join/1"><c>join/1</c></seealso>.</p> + <seemfa marker="#join/1"><c>join/1</c></seemfa>.</p> <p> The module supports - <seealso marker="unicode_usage#notes-about-raw-filenames">raw - filenames</seealso> in the way that if a binary is + <seeguide marker="unicode_usage#notes-about-raw-filenames">raw + filenames</seeguide> in the way that if a binary is present, or the filename cannot be interpreted according to the return - value of <seealso marker="kernel:file#native_name_encoding/0"> - <c>file:native_name_encoding/0</c></seealso>, a raw filename is also + value of <seemfa marker="kernel:file#native_name_encoding/0"> + <c>file:native_name_encoding/0</c></seemfa>, a raw filename is also returned. For example, <c>join/1</c> provided with a path component that is a binary (and cannot be interpreted under the current native filename encoding) results in a raw filename that is returned (the join operation is performed of course). For more information about raw filenames, see the - <seealso marker="kernel:file"><c>file</c></seealso> module.</p> + <seeerl marker="kernel:file"><c>file</c></seeerl> module.</p> <note> <p> @@ -123,7 +123,7 @@ <fsummary>Convert a filename to an absolute name, relative a specified directory.</fsummary> <desc> - <p>Same as <seealso marker="#absname/1"><c>absname/1</c></seealso>, + <p>Same as <seemfa marker="#absname/1"><c>absname/1</c></seemfa>, except that the directory to which the filename is to be made relative is specified in argument <c><anno>Dir</anno></c>.</p> </desc> @@ -134,7 +134,7 @@ <fsummary>Join an absolute directory with a relative filename.</fsummary> <desc> <p>Joins an absolute directory with a relative filename. Similar to - <seealso marker="#join/2"><c>join/2</c></seealso>, but on platforms + <seemfa marker="#join/2"><c>join/2</c></seemfa>, but on platforms with tight restrictions on raw filename length and no support for symbolic links (read: VxWorks), leading parent directory components in <c><anno>Filename</anno></c> are matched against trailing @@ -157,10 +157,10 @@ <type variable="Application"/> <desc> <p> - Equivalent to <seealso marker="#basedir_3_1"> - basedir(<anno>PathType</anno>, <anno>Application</anno>, #{})</seealso> - or <seealso marker="#basedir_3_2"> -basedir(<anno>PathsType</anno>, <anno>Application</anno>, #{})</seealso>. + Equivalent to <seeerl marker="#basedir_3_1"> + basedir(<anno>PathType</anno>, <anno>Application</anno>, #{})</seeerl> + or <seeerl marker="#basedir_3_2"> +basedir(<anno>PathsType</anno>, <anno>Application</anno>, #{})</seeerl>. </p> </desc> </func> @@ -395,12 +395,12 @@ true <fsummary>Find the filename and compiler options for a module.</fsummary> <desc> <p>Finds the source filename and compiler options for a module. - The result can be fed to <seealso marker="compiler:compile#file/2"> - <c>compile:file/2</c></seealso> to compile the file again.</p> + The result can be fed to <seemfa marker="compiler:compile#file/2"> + <c>compile:file/2</c></seemfa> to compile the file again.</p> <warning> - <p>This function is deprecated. Use <seealso marker="filelib#find_source/1"> - <c>filelib:find_source/1</c></seealso> instead for finding source files.</p> - <p>If possible, use the <seealso marker="beam_lib"><c>beam_lib(3)</c></seealso> + <p>This function is deprecated. Use <seemfa marker="filelib#find_source/1"> + <c>filelib:find_source/1</c></seemfa> instead for finding source files.</p> + <p>If possible, use the <seeerl marker="beam_lib"><c>beam_lib(3)</c></seeerl> module to extract the compiler options and the abstract code format from the Beam file and compile that instead.</p></warning> <p>Argument <c><anno>Beam</anno></c>, which can be a string or an atom, @@ -415,8 +415,8 @@ true object is located matches <c><anno>BinSuffix</anno></c>, then the name created by replacing <c><anno>BinSuffix</anno></c> with <c><anno>SourceSuffix</anno></c> is expanded by calling - <seealso marker="filelib#wildcard/1"> - <c>filelib:wildcard/1</c></seealso>. + <seemfa marker="filelib#wildcard/1"> + <c>filelib:wildcard/1</c></seemfa>. If a regular file is found among the matches, the function returns that location together with <c><anno>Options</anno></c>. Otherwise the next rule is tried, and so on.</p> @@ -494,7 +494,7 @@ true shell and native applications on the current platform. On Windows, forward slashes are converted to backward slashes. On all platforms, the name is normalized as done by - <seealso marker="#join/1"><c>join/1</c></seealso>.</p> + <seemfa marker="#join/1"><c>join/1</c></seemfa>.</p> <p><em>Examples:</em></p> <pre> 19> <input>filename:nativename("/usr/local/bin/").</input> % Unix @@ -570,6 +570,10 @@ true <item><p>A ".." component would climb up above the root of the relative path.</p></item> </list> + <warning> + <p>This function is deprecated. Use <seemfa marker="filelib#safe_relative_path/2"> + <c>filelib:safe_relative_path/2</c></seemfa> instead for sanitizing paths.</p> + </warning> <p><em>Examples:</em></p> <pre> 1> <input>filename:safe_relative_path("dir/sub_dir/..").</input> diff --git a/lib/stdlib/doc/src/gb_sets.xml b/lib/stdlib/doc/src/gb_sets.xml index a9596c6e4d..ffdcf54c5a 100644 --- a/lib/stdlib/doc/src/gb_sets.xml +++ b/lib/stdlib/doc/src/gb_sets.xml @@ -62,44 +62,44 @@ <title>Compatibility</title> <p>The following functions in this module also exist and provides the same functionality in the - <seealso marker="sets"><c>sets(3)</c></seealso> and - <seealso marker="ordsets"><c>ordsets(3)</c></seealso> + <seeerl marker="sets"><c>sets(3)</c></seeerl> and + <seeerl marker="ordsets"><c>ordsets(3)</c></seeerl> modules. That is, by only changing the module name for each call, you can try out different set representations.</p> <list type="bulleted"> - <item><seealso marker="#add_element/2"><c>add_element/2</c></seealso> + <item><seemfa marker="#add_element/2"><c>add_element/2</c></seemfa> </item> - <item><seealso marker="#del_element/2"><c>del_element/2</c></seealso> + <item><seemfa marker="#del_element/2"><c>del_element/2</c></seemfa> </item> - <item><seealso marker="#filter/2"><c>filter/2</c></seealso> + <item><seemfa marker="#filter/2"><c>filter/2</c></seemfa> </item> - <item><seealso marker="#fold/3"><c>fold/3</c></seealso> + <item><seemfa marker="#fold/3"><c>fold/3</c></seemfa> </item> - <item><seealso marker="#from_list/1"><c>from_list/1</c></seealso> + <item><seemfa marker="#from_list/1"><c>from_list/1</c></seemfa> </item> - <item><seealso marker="#intersection/1"><c>intersection/1</c></seealso> + <item><seemfa marker="#intersection/1"><c>intersection/1</c></seemfa> </item> - <item><seealso marker="#intersection/2"><c>intersection/2</c></seealso> + <item><seemfa marker="#intersection/2"><c>intersection/2</c></seemfa> </item> - <item><seealso marker="#is_element/2"><c>is_element/2</c></seealso> + <item><seemfa marker="#is_element/2"><c>is_element/2</c></seemfa> </item> - <item><seealso marker="#is_empty/1"><c>is_empty/1</c></seealso> + <item><seemfa marker="#is_empty/1"><c>is_empty/1</c></seemfa> </item> - <item><seealso marker="#is_set/1"><c>is_set/1</c></seealso> + <item><seemfa marker="#is_set/1"><c>is_set/1</c></seemfa> </item> - <item><seealso marker="#is_subset/2"><c>is_subset/2</c></seealso> + <item><seemfa marker="#is_subset/2"><c>is_subset/2</c></seemfa> </item> - <item><seealso marker="#new/0"><c>new/0</c></seealso> + <item><seemfa marker="#new/0"><c>new/0</c></seemfa> </item> - <item><seealso marker="#size/1"><c>size/1</c></seealso> + <item><seemfa marker="#size/1"><c>size/1</c></seemfa> </item> - <item><seealso marker="#subtract/2"><c>subtract/2</c></seealso> + <item><seemfa marker="#subtract/2"><c>subtract/2</c></seemfa> </item> - <item><seealso marker="#to_list/1"><c>to_list/1</c></seealso> + <item><seemfa marker="#to_list/1"><c>to_list/1</c></seemfa> </item> - <item><seealso marker="#union/1"><c>union/1</c></seealso> + <item><seemfa marker="#union/1"><c>union/1</c></seemfa> </item> - <item><seealso marker="#union/2"><c>union/2</c></seealso> + <item><seemfa marker="#union/2"><c>union/2</c></seemfa> </item> </list> </section> @@ -324,10 +324,10 @@ <desc> <p>Returns an iterator that can be used for traversing the entries of <c><anno>Set</anno></c>; see - <seealso marker="#next/1"><c>next/1</c></seealso>. The implementation + <seemfa marker="#next/1"><c>next/1</c></seemfa>. The implementation of this is very efficient; traversing the whole set using <c>next/1</c> is only slightly slower than getting the list of all - elements using <seealso marker="#to_list/1"><c>to_list/1</c></seealso> + elements using <seemfa marker="#to_list/1"><c>to_list/1</c></seemfa> and traversing that. The main advantage of the iterator approach is that it does not require the complete list of all elements to be built in @@ -342,9 +342,9 @@ <desc> <p>Returns an iterator that can be used for traversing the entries of <c><anno>Set</anno></c>; see - <seealso marker="#next/1"><c>next/1</c></seealso>. + <seemfa marker="#next/1"><c>next/1</c></seemfa>. The difference as compared to the iterator returned by - <seealso marker="#iterator/1"><c>iterator/1</c></seealso> + <seemfa marker="#iterator/1"><c>iterator/1</c></seemfa> is that the first element greater than or equal to <c><anno>Element</anno></c> is returned.</p> </desc> @@ -467,9 +467,9 @@ <section> <title>See Also</title> - <p><seealso marker="gb_trees"><c>gb_trees(3)</c></seealso>, - <seealso marker="ordsets"><c>ordsets(3)</c></seealso>, - <seealso marker="sets"><c>sets(3)</c></seealso></p> + <p><seeerl marker="gb_trees"><c>gb_trees(3)</c></seeerl>, + <seeerl marker="ordsets"><c>ordsets(3)</c></seeerl>, + <seeerl marker="sets"><c>sets(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml index 9a9f61ae52..c8944347a5 100644 --- a/lib/stdlib/doc/src/gb_trees.xml +++ b/lib/stdlib/doc/src/gb_trees.xml @@ -202,11 +202,11 @@ <desc> <p>Returns an iterator that can be used for traversing the entries of <c><anno>Tree</anno></c>; see - <seealso marker="#next/1"><c>next/1</c></seealso>. The implementation + <seemfa marker="#next/1"><c>next/1</c></seemfa>. The implementation of this is very efficient; traversing the whole tree using <c>next/1</c> is only slightly slower than getting the list of all elements using - <seealso marker="#to_list/1"><c>to_list/1</c></seealso> + <seemfa marker="#to_list/1"><c>to_list/1</c></seemfa> and traversing that. The main advantage of the iterator approach is that it does not require the complete list of all elements to be built in @@ -221,9 +221,9 @@ <desc> <p>Returns an iterator that can be used for traversing the entries of <c><anno>Tree</anno></c>; see - <seealso marker="#next/1"><c>next/1</c></seealso>. + <seemfa marker="#next/1"><c>next/1</c></seemfa>. The difference as compared to the iterator returned by - <seealso marker="#iterator/1"><c>iterator/1</c></seealso> + <seemfa marker="#iterator/1"><c>iterator/1</c></seemfa> is that the first key greater than or equal to <c><anno>Key</anno></c> is returned.</p> </desc> @@ -360,8 +360,8 @@ <section> <title>See Also</title> - <p><seealso marker="dict"><c>dict(3)</c></seealso>, - <seealso marker="gb_sets"><c>gb_sets(3)</c></seealso></p> + <p><seeerl marker="dict"><c>dict(3)</c></seeerl>, + <seeerl marker="gb_sets"><c>gb_sets(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index 2915c4f507..2ddff240d2 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -39,7 +39,7 @@ set of interface functions and includes functionality for tracing and error reporting. It also fits into an OTP supervision tree. For more information, see - <seealso marker="doc/design_principles:events">OTP Design Principles</seealso>. + <seeguide marker="system/design_principles:events">OTP Design Principles</seeguide>. </p> <p>Each event handler is implemented as a callback module exporting @@ -50,6 +50,7 @@ gen_event module Callback module ---------------- --------------- gen_event:start +gen_event:start_monitor gen_event:start_link -----> - gen_event:add_handler @@ -58,6 +59,7 @@ gen_event:add_sup_handler -----> Module:init/1 gen_event:notify gen_event:sync_notify -----> Module:handle_event/2 +gen_event:send_request gen_event:call -----> Module:handle_call/2 - -----> Module:handle_info/2 @@ -81,21 +83,21 @@ gen_event:stop -----> Module:terminate/2 an installed event handler fails with <c>Reason</c>, or returns a bad value <c>Term</c>, the event manager does not fail. It deletes the event handler by calling callback function - <seealso marker="#Module:terminate/2"><c>Module:terminate/2</c></seealso>, + <seemfa marker="#Module:terminate/2"><c>Module:terminate/2</c></seemfa>, giving as argument <c>{error,{'EXIT',Reason}}</c> or <c>{error,Term}</c>, respectively. No other event handler is affected.</p> <p>A <c>gen_event</c> process handles system messages as described in - <seealso marker="sys"><c>sys(3)</c></seealso>. The <c>sys</c> module + <seeerl marker="sys"><c>sys(3)</c></seeerl>. The <c>sys</c> module can be used for debugging an event manager.</p> <p>Notice that an event manager <em>does</em> trap exit signals automatically.</p> <p>The <c>gen_event</c> process can go into hibernation - (see <seealso marker="erts:erlang#hibernate/3"> - <c>erlang:hibernate/3</c></seealso>) if a callback function in + (see <seemfa marker="erts:erlang#hibernate/3"> + <c>erlang:hibernate/3</c></seemfa>) if a callback function in a handler module specifies <c>hibernate</c> in its return value. This can be useful if the server is expected to be idle for a long time. However, use this feature with care, as hibernation @@ -126,6 +128,15 @@ gen_event:stop -----> Module:terminate/2 <datatype> <name name="del_handler_ret"/> </datatype> + <datatype> + <name name="request_id"/> + <desc> + <p> + A request handle, see <seemfa marker="#send_request/3"> <c>send_request/3</c> </seemfa> + for details. + </p> + </desc> + </datatype> </datatypes> <funcs> @@ -147,7 +158,7 @@ gen_event:stop -----> Module:terminate/2 <desc> <p>Adds a new event handler to event manager <c>EventMgrRef</c>. The event manager calls - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> to initiate the event handler and its internal state.</p> <p><c>EventMgrRef</c> can be any of the following:</p> <list type="bulleted"> @@ -195,14 +206,14 @@ gen_event:stop -----> Module:terminate/2 </type> <desc> <p>Adds a new event handler in the same way as - <seealso marker="#add_handler/3"><c>add_handler/3</c></seealso>, + <seemfa marker="#add_handler/3"><c>add_handler/3</c></seemfa>, but also supervises the connection between the event handler and the calling process.</p> <list type="bulleted"> <item>If the calling process later terminates with <c>Reason</c>, the event manager deletes the event handler by calling - <seealso marker="#Module:terminate/2"> - <c>Module:terminate/2</c></seealso> + <seemfa marker="#Module:terminate/2"> + <c>Module:terminate/2</c></seemfa> with <c>{stop,Reason}</c> as argument. </item> <item> @@ -224,10 +235,10 @@ gen_event:stop -----> Module:terminate/2 <p><c>{swapped,NewHandler,Pid}</c>, if the process <c>Pid</c> has replaced the event handler with another event handler <c>NewHandler</c> using a call to - <seealso marker="#swap_handler/3"> - <c>swap_handler/3</c></seealso> or - <seealso marker="#swap_sup_handler/3"> - <c>swap_sup_handler/3</c></seealso>.</p> + <seemfa marker="#swap_handler/3"> + <c>swap_handler/3</c></seemfa> or + <seemfa marker="#swap_sup_handler/3"> + <c>swap_sup_handler/3</c></seemfa>.</p> </item> <item> <p>A term, if the event handler is removed because of an error. @@ -236,7 +247,7 @@ gen_event:stop -----> Module:terminate/2 </item> </list> <p>For a description of the arguments and return values, see - <seealso marker="#add_handler/3"><c>add_handler/3</c></seealso>.</p> + <seemfa marker="#add_handler/3"><c>add_handler/3</c></seemfa>.</p> </desc> </func> @@ -263,10 +274,10 @@ gen_event:stop -----> Module:terminate/2 <p>Makes a synchronous call to event handler <c>Handler</c> installed in event manager <c>EventMgrRef</c> by sending a request and waiting until a reply arrives or a time-out occurs. - The event manager calls <seealso marker="#Module:handle_call/2"> - <c>Module:handle_call/2</c></seealso> to handle the request.</p> + The event manager calls <seemfa marker="#Module:handle_call/2"> + <c>Module:handle_call/2</c></seemfa> to handle the request.</p> <p>For a description of <c>EventMgrRef</c> and <c>Handler</c>, see - <seealso marker="#add_handler/3"><c>add_handler/3</c></seealso>.</p> + <seemfa marker="#add_handler/3"><c>add_handler/3</c></seemfa>.</p> <p><c>Request</c> is any term that is passed as one of the arguments to <c>Module:handle_call/2</c>.</p> <p><c>Timeout</c> is an integer greater than zero that specifies @@ -284,6 +295,40 @@ gen_event:stop -----> Module:terminate/2 </desc> </func> + + <func> + <name since="OTP-23">check_response(Msg, RequestId) -> Result</name> + <fsummary>Check if a message is a reply from a server.</fsummary> + <type> + <v>Msg = term()</v> + <v>RequestId = request_id()</v> + <v>Result = {reply, Reply} | no_reply | {error, Error}</v> + <v>Reply = Error = term()</v> + </type> + <desc> + <p> + This function is used to check if a previously received + message, for example by <c>receive</c> or + <c>handle_info/2</c>, is a result of a request made with + <seemfa marker="#send_request/3"><c>send_request/3</c></seemfa>. + If <c>Msg</c> is a reply to the handle <c>RequestId</c> + the result of the request is returned in <c>Reply</c>. + Otherwise returns <c>no_reply</c> and no cleanup is done, and + thus the function shall be invoked repeatedly until a reply + is returned. + </p> + <p> + If the specified event handler is not + installed, the function returns <c>{error,bad_module}</c>. If + the callback function fails with <c>Reason</c> or returns an + unexpected value <c>Term</c>, this function returns + <c>{error,{'EXIT',Reason}}</c> or <c>{error,Term}</c>, + respectively. If the event manager dies before or during the + request this function returns <c>{error,{Reason, EventMgrRef}}</c>. + </p> + </desc> + </func> + <func> <name since="">delete_handler(EventMgrRef, Handler, Args) -> Result</name> <fsummary>Delete an event handler from a generic event manager.</fsummary> @@ -302,11 +347,11 @@ gen_event:stop -----> Module:terminate/2 <desc> <p>Deletes an event handler from event manager <c>EventMgrRef</c>. The event manager calls - <seealso marker="#Module:terminate/2"> - <c>Module:terminate/2</c></seealso> to terminate the event + <seemfa marker="#Module:terminate/2"> + <c>Module:terminate/2</c></seemfa> to terminate the event handler.</p> <p>For a description of <c>EventMgrRef</c> and <c>Handler</c>, see - <seealso marker="#add_handler/3"><c>add_handler/3</c></seealso>.</p> + <seemfa marker="#add_handler/3"><c>add_handler/3</c></seemfa>.</p> <p><c>Args</c> is any term that is passed as one of the arguments to <c>Module:terminate/2</c>.</p> <p>The return value is the return value of <c>Module:terminate/2</c>. @@ -331,23 +376,66 @@ gen_event:stop -----> Module:terminate/2 <desc> <p>Sends an event notification to event manager <c>EventMgrRef</c>. The event manager calls - <seealso marker="#Module:handle_event/2"> - <c>Module:handle_event/2</c></seealso> + <seemfa marker="#Module:handle_event/2"> + <c>Module:handle_event/2</c></seemfa> for each installed event handler to handle the event.</p> <p><c>notify/2</c> is asynchronous and returns immediately after the event notification has been sent. <c>sync_notify/2</c> is synchronous in the sense that it returns <c>ok</c> after the event has been handled by all event handlers.</p> <p>For a description of <c>EventMgrRef</c>, see - <seealso marker="#add_handler/3"><c>add_handler/3</c></seealso>.</p> + <seemfa marker="#add_handler/3"><c>add_handler/3</c></seemfa>.</p> <p><c>Event</c> is any term that is passed as one of - the arguments to <seealso marker="#Module:handle_event/2"> - <c>Module:handle_event/2</c></seealso>.</p> + the arguments to <seemfa marker="#Module:handle_event/2"> + <c>Module:handle_event/2</c></seemfa>.</p> <p><c>notify/1</c> does not fail even if the specified event manager does not exist, unless it is specified as <c>Name</c>.</p> </desc> </func> + + <func> + <name since="OTP-23">send_request(EventMgrRef, Handler, Request) -> RequestId</name> + <fsummary>Send a request to a generic event manager.</fsummary> + <type> + <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName}</v> + <v> | {via,Module,ViaName} | pid()</v> + <v> Node = atom()</v> + <v> GlobalName = ViaName = term()</v> + <v>Handler = Module | {Module,Id}</v> + <v> Module = atom()</v> + <v> Id = term()</v> + <v>Request = term()</v> + <v>RequestId = request_id()</v> + </type> + <desc> + <p> + Sends a request to event handler <c>Handler</c> installed in + event manager <c>EventMgrRef</c> and returns a handle + <c>RequestId</c>. The return value <c>RequestId</c> shall + later be used with <seemfa marker="#wait_response/2"> + <c>wait_response/2</c></seemfa> or <seemfa + marker="#check_response/2"> + <c>check_response/2</c></seemfa> in the same process to + fetch the actual result of the request. + </p> + <p> + The call <c>gen_event:wait_response(gen_event:send_request(EventMgrRef,Handler,Request), Timeout)</c> + can be seen as equivalent to + <seemfa marker="#call/3"><c>gen_event:call(EventMgrRef,Handler,Request,Timeout)</c></seemfa>, + ignoring the error handling. + </p> + <p> + The event manager calls <seemfa marker="#Module:handle_call/2"> + <c>Module:handle_call/2</c></seemfa> to handle the request. + </p> + <p> + <c>Request</c> is any term that is passed as one of + the arguments to <c>Module:handle_call/3</c>. + </p> + </desc> + </func> + <func> <name since="">start() -> Result</name> <name since="">start(EventMgrName | Options) -> Result</name> @@ -370,7 +458,7 @@ gen_event:stop -----> Module:terminate/2 manager that is not part of a supervision tree and thus has no supervisor.</p> <p>For a description of the arguments and return values, see - <seealso marker="#start_link/0"><c>start_link/0,1</c></seealso>.</p> + <seemfa marker="#start_link/0"><c>start_link/0,1</c></seemfa>.</p> </desc> </func> @@ -405,8 +493,8 @@ gen_event:stop -----> Module:terminate/2 <item> <p>If <c>EventMgrName={global,GlobalName}</c>, the event manager is registered globally as <c>GlobalName</c> using - <seealso marker="kernel:global#register_name/2"> - <c>global:register_name/2</c></seealso>. + <seemfa marker="kernel:global#register_name/2"> + <c>global:register_name/2</c></seemfa>. If no name is provided, the event manager is not registered.</p> </item> <item> @@ -416,14 +504,14 @@ gen_event:stop -----> Module:terminate/2 <c>register_name/2</c>, <c>unregister_name/1</c>, <c>whereis_name/1</c>, and <c>send/2</c>, which are to behave as the corresponding functions in - <seealso marker="kernel:global"><c>global</c></seealso>. + <seeerl marker="kernel:global"><c>global</c></seeerl>. Thus, <c>{via,global,GlobalName}</c> is a valid reference.</p> </item> <item> <p>If option <c>{hibernate_after,HibernateAfterTimeout}</c> is present, the <c>gen_event</c> process awaits any message for <c>HibernateAfterTimeout</c> milliseconds and if no message is received, the process goes into hibernation automatically - (by calling <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>).</p> + (by calling <seemfa marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa>).</p> </item> </list> <p>If the event manager is successfully created, the function @@ -436,6 +524,40 @@ gen_event:stop -----> Module:terminate/2 </func> <func> + <name since="OTP 23.0">start_monitor() -> Result</name> + <name since="OTP 23.0">start_monitor(EventMgrName | Options) -> Result</name> + <name since="OTP 23.0">start_monitor(EventMgrName, Options) -> Result</name> + <fsummary>Create a stand-alone event manager process.</fsummary> + <type> + <v>EventMgrName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}</v> + <v> Name = atom()</v> + <v> GlobalName = ViaName = term()</v> + <v>Options = [Option]</v> + <v> Option = {debug,Dbgs} | {timeout,Time} | {hibernate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}</v> + <v> Dbgs = [Dbg]</v> + <v> Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}</v> + <v> SOpts = [term()]</v> + <v>Result = {ok,{Pid,Mon}} | {error,{already_started,Pid}}</v> + <v> Pid = pid()</v> + </type> + <desc> + <p>Creates a stand-alone event manager process, that is, an event + manager that is not part of a supervision tree (and thus has + no supervisor) and atomically sets up a monitor to + the newly created process.</p> + <p>For a description of the arguments and return values, see + <seemfa marker="#start_link/0"><c>start_link/0,1</c></seemfa>. + Note that the return value on successful start differs from + <c>start_link/3,4</c>. <c>start_monitor/3,4</c> will return + <c>{ok,{Pid,Mon}}</c> where <c>Pid</c> is the process identifier + of the process, and <c>Mon</c> is a reference to the monitor + set up to monitor the process. If the start is not successful, + the caller will be blocked until the <c>DOWN</c> message has + been received and removed from the message queue.</p> + </desc> + </func> + + <func> <name since="">stop(EventMgrRef) -> ok</name> <name since="OTP 18.0">stop(EventMgrRef, Reason, Timeout) -> ok</name> <fsummary>Terminate a generic event manager.</fsummary> @@ -451,14 +573,14 @@ gen_event:stop -----> Module:terminate/2 <p>Orders event manager <c>EventMgrRef</c> to exit with the specifies <c>Reason</c> and waits for it to terminate. Before terminating, <c>gen_event</c> calls - <seealso marker="#Module:terminate/2"> - <c>Module:terminate(stop,...)</c></seealso> + <seemfa marker="#Module:terminate/2"> + <c>Module:terminate(stop,...)</c></seemfa> for each installed event handler.</p> <p>The function returns <c>ok</c> if the event manager terminates with the expected reason. Any other reason than <c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c> causes an error report to be issued using - <seealso marker="kernel:logger"><c>logger(3)</c></seealso>. + <seeerl marker="kernel:logger"><c>logger(3)</c></seeerl>. The default <c>Reason</c> is <c>normal</c>.</p> <p><c>Timeout</c> is an integer greater than zero that specifies how many milliseconds to wait for the event manager to @@ -469,7 +591,7 @@ gen_event:stop -----> Module:terminate/2 <p>If the process does not exist, a <c>noproc</c> exception is raised.</p> <p>For a description of <c>EventMgrRef</c>, see - <seealso marker="#add_handler/3"><c>add_handler/3</c></seealso>.</p> + <seemfa marker="#add_handler/3"><c>add_handler/3</c></seemfa>.</p> </desc> </func> @@ -493,7 +615,7 @@ gen_event:stop -----> Module:terminate/2 <p>Replaces an old event handler with a new event handler in event manager <c>EventMgrRef</c>.</p> <p>For a description of the arguments, see - <seealso marker="#add_handler/3"><c>add_handler/3</c></seealso>.</p> + <seemfa marker="#add_handler/3"><c>add_handler/3</c></seemfa>.</p> <p>First the old event handler <c>Handler1</c> is deleted. The event manager calls <c>Module1:terminate(Args1, ...)</c>, where <c>Module1</c> is the callback module of <c>Handler1</c>, @@ -541,7 +663,50 @@ gen_event:stop -----> Module:terminate/2 in the same way as <c>swap_handler/3</c>, but also supervises the connection between <c>Handler2</c> and the calling process.</p> <p>For a description of the arguments and return values, see - <seealso marker="#swap_handler/3"><c>swap_handler/3</c></seealso>.</p> + <seemfa marker="#swap_handler/3"><c>swap_handler/3</c></seemfa>.</p> + </desc> + </func> + + <func> + <name since="OTP-23">wait_response(RequestId, Timeout) -> Result</name> + <fsummary>Wait for a reply from a server.</fsummary> + <type> + <v>RequestId = request_id()</v> + <v>Reply = term()</v> + <v>Timeout = timeout()</v> + <v>Result = {reply, Reply} | timeout | {error, Error}</v> + <v>Reply = Error = term()</v> + </type> + <desc> + <p> + This function is used to wait for a reply of a request made with + <seemfa marker="#send_request/3"><c>send_request/3</c></seemfa> + from the event manager. This function must be called from the same + process from which <seemfa marker="#send_request/3"><c>send_request/3</c></seemfa> + was made. + </p> + <p> + <c>Timeout</c> is an integer greater then or equal to zero + that specifies how many milliseconds to wait for an reply, or + the atom <c>infinity</c> to wait indefinitely. + If no reply is received within the specified + time, the function returns <c>timeout</c> and no cleanup is + done, and thus the function must be invoked repeatedly until a + reply is returned. + </p> + <p> + The return value <c>Reply</c> is defined in the return value + of <c>Module:handle_call/3</c>. + </p> + <p> + If the specified event handler is not + installed, the function returns <c>{error,bad_module}</c>. If + the callback function fails with <c>Reason</c> or returns an + unexpected value <c>Term</c>, this function returns + <c>{error,{'EXIT',Reason}}</c> or <c>{error,Term}</c>, + respectively. If the event manager dies before or during the + request this function returns <c>{error,{Reason, EventMgrRef}}</c>. + </p> </desc> </func> @@ -562,18 +727,19 @@ gen_event:stop -----> Module:terminate/2 <p>Returns a list of all event handlers installed in event manager <c>EventMgrRef</c>.</p> <p>For a description of <c>EventMgrRef</c> and <c>Handler</c>, see - <seealso marker="#add_handler/3"><c>add_handler/3</c></seealso>.</p> + <seemfa marker="#add_handler/3"><c>add_handler/3</c></seemfa>.</p> </desc> </func> </funcs> - <section> - <title>Callback Functions</title> - <p>The following functions are to be exported from a <c>gen_event</c> - callback module.</p> - </section> + <funcs> + <fsdescription> + <title>Callback Functions</title> + <p>The following functions are to be exported from a <c>gen_event</c> + callback module.</p> + </fsdescription> <func> <name since="">Module:code_change(OldVsn, State, Extra) -> {ok, NewState}</name> <fsummary>Update the internal state during upgrade/downgrade.</fsummary> @@ -596,8 +762,8 @@ gen_event:stop -----> Module:terminate/2 upgrade/downgrade, that is, when the instruction <c>{update,Module,Change,...}</c>, where <c>Change={advanced,Extra}</c>, is specified in the <c>.appup</c> - file. For more information, see <seealso - marker="doc/design_principles:users_guide">OTP Design Principles</seealso>.</p> + file. For more information, see <seeguide + marker="system/design_principles:index">OTP Design Principles</seeguide>.</p> <p>For an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and for a downgrade, <c>OldVsn</c> is <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c> attribute(s) of the old version of the callback module @@ -630,8 +796,8 @@ gen_event:stop -----> Module:terminate/2 <p>This function is called by a <c>gen_event</c> process in the following situations:</p> <list type="bulleted"> - <item>One of <seealso marker="sys#get_status/1"> - <c>sys:get_status/1,2</c></seealso> + <item>One of <seemfa marker="sys#get_status/1"> + <c>sys:get_status/1,2</c></seemfa> is invoked to get the <c>gen_event</c> status. <c>Opt</c> is set to the atom <c>normal</c> for this case.</item> <item>The event handler terminates abnormally and <c>gen_event</c> @@ -684,14 +850,14 @@ gen_event:stop -----> Module:terminate/2 </type> <desc> <p>Whenever an event manager receives a request sent using - <seealso marker="#call/3"><c>call/3,4</c></seealso>, + <seemfa marker="#call/3"><c>call/3,4</c></seemfa>, this function is called for the specified event handler to handle the request.</p> <p><c>Request</c> is the <c>Request</c> argument of <c>call/3,4</c>.</p> <p><c>State</c> is the internal state of the event handler.</p> <p>The return values are the same as for - <seealso marker="#Module:handle_event/2"> - <c>Module:handle_event/2</c></seealso> + <seemfa marker="#Module:handle_event/2"> + <c>Module:handle_event/2</c></seemfa> except that they also contain a term <c>Reply</c>, which is the reply to the client as the return value of <c>call/3,4</c>.</p> </desc> @@ -714,8 +880,8 @@ gen_event:stop -----> Module:terminate/2 </type> <desc> <p>Whenever an event manager receives an event sent using - <seealso marker="#notify/2"><c>notify/2</c></seealso> or - <seealso marker="#sync_notify/2"><c>sync_notify/2</c></seealso>, + <seemfa marker="#notify/2"><c>notify/2</c></seemfa> or + <seemfa marker="#sync_notify/2"><c>sync_notify/2</c></seemfa>, this function is called for each installed event handler to handle the event.</p> <p><c>Event</c> is the <c>Event</c> argument of @@ -731,8 +897,8 @@ gen_event:stop -----> Module:terminate/2 <item> <p>If <c>{ok,NewState,hibernate}</c> is returned, the event manager also goes into hibernation (by calling - <seealso marker="proc_lib#hibernate/3"> - <c>proc_lib:hibernate/3</c></seealso>), waiting for the next + <seemfa marker="proc_lib#hibernate/3"> + <c>proc_lib:hibernate/3</c></seemfa>), waiting for the next event to occur. It is sufficient that one of the event handlers return <c>{ok,NewState,hibernate}</c> for the whole event manager process to hibernate.</p> @@ -743,7 +909,7 @@ gen_event:stop -----> Module:terminate/2 first calling <c>Module:terminate(Args1,NewState)</c> and then <c>Module2:init({Args2,Term})</c>, where <c>Term</c> is the return value of <c>Module:terminate/2</c>. For more information, see - <seealso marker="#swap_handler/3"><c>swap_handler/3</c></seealso>. + <seemfa marker="#swap_handler/3"><c>swap_handler/3</c></seemfa>. </p> </item> <item> @@ -782,8 +948,8 @@ gen_event:stop -----> Module:terminate/2 a synchronous request (or a system message).</p> <p><c>Info</c> is the received message.</p> <p>For a description of <c>State</c> and possible return values, see - <seealso marker="#Module:handle_event/2"> - <c>Module:handle_event/2</c></seealso>.</p> + <seemfa marker="#Module:handle_event/2"> + <c>Module:handle_event/2</c></seemfa>.</p> </desc> </func> @@ -800,26 +966,26 @@ gen_event:stop -----> Module:terminate/2 <p>Whenever a new event handler is added to an event manager, this function is called to initialize the event handler.</p> <p>If the event handler is added because of a call to - <seealso marker="#add_handler/3"><c>add_handler/3</c></seealso> or - <seealso marker="#add_sup_handler/3"> - <c>add_sup_handler/3</c></seealso>, <c>InitArgs</c> is + <seemfa marker="#add_handler/3"><c>add_handler/3</c></seemfa> or + <seemfa marker="#add_sup_handler/3"> + <c>add_sup_handler/3</c></seemfa>, <c>InitArgs</c> is the <c>Args</c> argument of these functions.</p> <p>If the event handler replaces another event handler because of a call to - <seealso marker="#swap_handler/3"><c>swap_handler/3</c></seealso> or - <seealso marker="#swap_sup_handler/3"> - <c>swap_sup_handler/3</c></seealso>, or because of a <c>swap</c> + <seemfa marker="#swap_handler/3"><c>swap_handler/3</c></seemfa> or + <seemfa marker="#swap_sup_handler/3"> + <c>swap_sup_handler/3</c></seemfa>, or because of a <c>swap</c> return tuple from one of the other callback functions, <c>InitArgs</c> is a tuple <c>{Args,Term}</c>, where <c>Args</c> is the argument provided in the function call/return tuple and <c>Term</c> is the result of terminating the old event handler, see - <seealso marker="#swap_handler/3"><c>swap_handler/3</c></seealso>.</p> + <seemfa marker="#swap_handler/3"><c>swap_handler/3</c></seemfa>.</p> <p>If successful, the function returns <c>{ok,State}</c> or <c>{ok,State,hibernate}</c>, where <c>State</c> is the initial internal state of the event handler.</p> <p>If <c>{ok,State,hibernate}</c> is returned, the event - manager goes into hibernation (by calling <seealso - marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>), + manager goes into hibernation (by calling <seemfa + marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa>), waiting for the next event to occur.</p> </desc> </func> @@ -840,13 +1006,13 @@ gen_event:stop -----> Module:terminate/2 </note> <p>Whenever an event handler is deleted from an event manager, this function is called. It is to be the opposite of - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> and do any necessary cleaning up.</p> <p>If the event handler is deleted because of a call to - <seealso marker="#delete_handler/3"><c>delete_handler/3</c></seealso>, - <seealso marker="#swap_handler/3"><c>swap_handler/3</c></seealso>, or - <seealso marker="#swap_sup_handler/3"> - <c>swap_sup_handler/3</c></seealso>, <c>Arg</c> is + <seemfa marker="#delete_handler/3"><c>delete_handler/3</c></seemfa>, + <seemfa marker="#swap_handler/3"><c>swap_handler/3</c></seemfa>, or + <seemfa marker="#swap_sup_handler/3"> + <c>swap_sup_handler/3</c></seemfa>, <c>Arg</c> is the <c>Args</c> argument of this function call.</p> <p><c>Arg={stop,Reason}</c> if the event handler has a supervised connection to a process that has terminated with reason @@ -879,7 +1045,7 @@ gen_event:stop -----> Module:terminate/2 <section> <title>See Also</title> - <p><seealso marker="supervisor"><c>supervisor(3)</c></seealso>, - <seealso marker="sys"><c>sys(3)</c></seealso></p> + <p><seeerl marker="supervisor"><c>supervisor(3)</c></seeerl>, + <seeerl marker="sys"><c>sys(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml index 7187630b43..03fce5aae4 100644 --- a/lib/stdlib/doc/src/gen_fsm.xml +++ b/lib/stdlib/doc/src/gen_fsm.xml @@ -32,14 +32,14 @@ <modulesummary>Deprecated and replaced by gen_statem </modulesummary> <description> - <p> Deprecated and replaced by <seealso marker="gen_statem"><c>gen_statem</c></seealso> </p> + <p> Deprecated and replaced by <seeerl marker="gen_statem"><c>gen_statem</c></seeerl> </p> </description> <section> <marker id="Migration to gen_statem"/> <title>Migration to gen_statem</title> <p>Here follows a simple example of turning a gen_fsm into - a <seealso marker="gen_statem"><c>gen_statem</c></seealso>. The example comes + a <seeerl marker="gen_statem"><c>gen_statem</c></seeerl>. The example comes from the previous Users Guide for <c>gen_fsm</c> </p> <code type="erl"> diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index a4554d7657..4abb91439e 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -36,8 +36,8 @@ this module has a standard set of interface functions and includes functionality for tracing and error reporting. It also fits into an OTP supervision tree. For more information, see section - <seealso marker="doc/design_principles:gen_server_concepts"> - gen_server Behaviour</seealso> in OTP Design Principles.</p> + <seeguide marker="system/design_principles:gen_server_concepts"> + gen_server Behaviour</seeguide> in OTP Design Principles.</p> <p>A <c>gen_server</c> process assumes all specific parts to be located in a callback module exporting a predefined set of functions. @@ -48,11 +48,13 @@ gen_server module Callback module ----------------- --------------- gen_server:start +gen_server:start_monitor gen_server:start_link -----> Module:init/1 gen_server:stop -----> Module:terminate/2 gen_server:call +gen_server:send_request gen_server:multi_call -----> Module:handle_call/3 gen_server:cast @@ -70,7 +72,7 @@ gen_server:abcast -----> Module:handle_cast/2 <c>gen_server</c> process terminates.</p> <p>A <c>gen_server</c> process handles system messages as described in - <seealso marker="sys"><c>sys(3)</c></seealso>. The <c>sys</c> module + <seeerl marker="sys"><c>sys(3)</c></seeerl>. The <c>sys</c> module can be used for debugging a <c>gen_server</c> process.</p> <p>Notice that a <c>gen_server</c> process does not trap exit signals @@ -82,8 +84,8 @@ gen_server:abcast -----> Module:handle_cast/2 arguments are specified.</p> <p>The <c>gen_server</c> process can go into hibernation - (see <seealso marker="erts:erlang#hibernate/3"> - <c>erlang:hibernate/3</c></seealso>) if a callback + (see <seemfa marker="erts:erlang#hibernate/3"> + <c>erlang:hibernate/3</c></seemfa>) if a callback function specifies <c>'hibernate'</c> instead of a time-out value. This can be useful if the server is expected to be idle for a long time. However, use this feature with care, as hibernation @@ -116,10 +118,10 @@ gen_server:abcast -----> Module:handle_cast/2 returns immediately and ignores nodes that do not exist, or where the <c>gen_server</c> <c>Name</c> does not exist. The <c>gen_server</c> processes call - <seealso marker="#Module:handle_cast/2"> - <c>Module:handle_cast/2</c></seealso> to handle the request.</p> + <seemfa marker="#Module:handle_cast/2"> + <c>Module:handle_cast/2</c></seemfa> to handle the request.</p> <p>For a description of the arguments, see - <seealso marker="#multi_call/2"><c>multi_call/2,3,4</c></seealso>.</p> + <seemfa marker="#multi_call/2"><c>multi_call/2,3,4</c></seemfa>.</p> </desc> </func> @@ -141,8 +143,8 @@ gen_server:abcast -----> Module:handle_cast/2 <c>gen_server</c> process by sending a request and waiting until a reply arrives or a time-out occurs. The <c>gen_server</c> process calls - <seealso marker="#Module:handle_call/3"> - <c>Module:handle_call/3</c></seealso> to handle the request.</p> + <seemfa marker="#Module:handle_call/3"> + <c>Module:handle_call/3</c></seemfa> to handle the request.</p> <p><c>ServerRef</c> can be any of the following:</p> <list type="bulleted"> <item>The pid</item> @@ -155,8 +157,8 @@ gen_server:abcast -----> Module:handle_cast/2 <item><c>{via,Module,ViaName}</c>, if the <c>gen_server</c> process is registered through an alternative process registry</item> </list> - <p><c>Request</c> is any term that is passed as one of - the arguments to <c>Module:handle_call/3</c>.</p> + <p><c>Request</c> is any term that is passed as the + first argument to <c>Module:handle_call/3</c>.</p> <p><c>Timeout</c> is an integer greater than zero that specifies how many milliseconds to wait for a reply, or the atom <c>infinity</c> to wait indefinitely. Defaults to @@ -190,16 +192,53 @@ gen_server:abcast -----> Module:handle_cast/2 and returns <c>ok</c> immediately, ignoring if the destination node or <c>gen_server</c> process does not exist. The <c>gen_server</c> process calls - <seealso marker="#Module:handle_cast/2"> - <c>Module:handle_cast/2</c></seealso> to handle the request.</p> + <seemfa marker="#Module:handle_cast/2"> + <c>Module:handle_cast/2</c></seemfa> to handle the request.</p> <p>For a description of <c>ServerRef</c>, see - <seealso marker="#call/2"><c>call/2,3</c></seealso>.</p> + <seemfa marker="#call/2"><c>call/2,3</c></seemfa>.</p> <p><c>Request</c> is any term that is passed as one of the arguments to <c>Module:handle_cast/2</c>.</p> </desc> </func> <func> + <name since="OTP-23">check_response(Msg, RequestId) -> Result</name> + <fsummary>Check if a message is a reply from a server.</fsummary> + <type> + <v>RequestId = term()</v> + <v>Result = {reply, Reply} | no_reply | {error, {Reason, ServerRef}}</v> + <v>Msg = Reply = term()</v> + <v>Timeout = timeout()</v> + <v>Reason = term()</v> + <v>ServerRef = Name | {Name,Node} | {global,GlobalName}</v> + <v> | {via,Module,ViaName} | pid()</v> + <v> Node = atom()</v> + <v> GlobalName = ViaName = term()</v> + </type> + <desc> + <p> + This function is used to check if a previously received + message, for example by <c>receive</c> or + <c>handle_info/2</c>, is a result of a request made with + <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>. + If <c>Msg</c> is a reply to the handle <c>RequestId</c> + the result of the request is returned in <c>Reply</c>. + Otherwise returns <c>no_reply</c> and no cleanup is done, and + thus the function must be invoked repeatedly until a reply + is returned. + </p> + <p> + The return value <c>Reply</c> is defined in the return value + of <c>Module:handle_call/3</c>. + </p> + <p> + The function returns an error if the <c>gen_server</c> + dies before or during this request. + </p> + </desc> + </func> + + <func> <name since="">enter_loop(Module, Options, State)</name> <name since="">enter_loop(Module, Options, State, ServerName)</name> <name since="">enter_loop(Module, Options, State, Timeout)</name> @@ -225,20 +264,20 @@ gen_server:abcast -----> Module:handle_cast/2 process receive loop and becomes a <c>gen_server</c> process. The process <em>must</em> have been started using one of the start functions in - <seealso marker="proc_lib"><c>proc_lib(3)</c></seealso>. The user is + <seeerl marker="proc_lib"><c>proc_lib(3)</c></seeerl>. The user is responsible for any initialization of the process, including registering a name for it.</p> <p>This function is useful when a more complex initialization procedure is needed than the <c>gen_server</c> process behavior provides.</p> <p><c>Module</c>, <c>Options</c>, and <c>ServerName</c> have the same meanings as when calling - <seealso marker="#start_link/3"><c>start[_link]/3,4</c></seealso>. + <seemfa marker="#start_link/3"><c>start[_link|_monitor]/3,4</c></seemfa>. However, if <c>ServerName</c> is specified, the process must have been registered accordingly <em>before</em> this function is called.</p> <p><c>State</c> and <c>Timeout</c> have the same meanings as in the return value of - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>. + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>. The callback module <c>Module</c> does not need to export an <c>init/1</c> function.</p> <p>The function fails if the calling process was not started by a @@ -268,8 +307,8 @@ gen_server:abcast -----> Module:handle_cast/2 registered as <c>Name</c> at the specified nodes by first sending a request to every node and then waits for the replies. The <c>gen_server</c> process calls - <seealso marker="#Module:handle_call/3"> - <c>Module:handle_call/3</c></seealso> to handle the request.</p> + <seemfa marker="#Module:handle_call/3"> + <c>Module:handle_call/3</c></seemfa> to handle the request.</p> <p>The function returns a tuple <c>{Replies,BadNodes}</c>, where <c>Replies</c> is a list of <c>{Node,Reply}</c> and <c>BadNodes</c> is a list of node that either did not exist, @@ -280,8 +319,8 @@ gen_server:abcast -----> Module:handle_cast/2 <c>[node()|nodes()]</c>.</p> <p><c>Name</c> is the locally registered name of each <c>gen_server</c> process.</p> - <p><c>Request</c> is any term that is passed as one of - the arguments to <c>Module:handle_call/3</c>.</p> + <p><c>Request</c> is any term that is passed as the first + argument to <c>Module:handle_call/3</c>.</p> <p><c>Timeout</c> is an integer greater than zero that specifies how many milliseconds to wait for each reply, or the atom <c>infinity</c> to wait indefinitely. Defaults @@ -307,27 +346,73 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name since="">reply(Client, Reply) -> Result</name> + <name since="">reply(Client, Reply) -> ok</name> <fsummary>Send a reply to a client.</fsummary> <type> <v>Client - see below</v> <v>Reply = term()</v> - <v>Result = term()</v> </type> <desc> <p>This function can be used by a <c>gen_server</c> process to explicitly send a reply to a client that called - <seealso marker="#call/2"><c>call/2,3</c></seealso> or - <seealso marker="#multi_call/2"><c>multi_call/2,3,4</c></seealso>, + <seemfa marker="#call/2"><c>call/2,3</c></seemfa> or + <seemfa marker="#multi_call/2"><c>multi_call/2,3,4</c></seemfa>, when the reply cannot be defined in the return value of - <seealso marker="#Module:handle_call/3"> - <c>Module:handle_call/3</c></seealso>.</p> + <seemfa marker="#Module:handle_call/3"> + <c>Module:handle_call/3</c></seemfa>.</p> <p><c>Client</c> must be the <c>From</c> argument provided to the callback function. <c>Reply</c> is any term given back to the client as the return value of <c>call/2,3</c> or <c>multi_call/2,3,4</c>.</p> - <p>The return value <c>Result</c> is not further defined, and - is always to be ignored.</p> + </desc> + </func> + + <func> + <name since="OTP-23">send_request(ServerRef, Request) -> RequestId</name> + <fsummary>Sends a request to a generic server.</fsummary> + <type> + <v>ServerRef = Name | {Name,Node} | {global,GlobalName}</v> + <v> | {via,Module,ViaName} | pid()</v> + <v> Node = atom()</v> + <v> GlobalName = ViaName = term()</v> + <v>RequestId = term()</v> + <v>Timeout = int()>0 | infinity</v> + <v>Request = term()</v> + </type> + <desc> + <p> + Sends a request to the <c>ServerRef</c> of the + <c>gen_server</c> process and returns a handle <c>RequestId</c>. + The return value <c>RequestId</c> shall later be used with + <seemfa marker="#wait_response/2"> <c>wait_response/2</c></seemfa> or + <seemfa marker="#check_response/2"> <c>check_response/2</c></seemfa> + to fetch the actual result of the request. + </p> + <p> + The call <c>gen_server:wait_response(gen_server:send_request(ServerRef,Request), Timeout)</c> + can be seen as equivalent to + <seemfa marker="#call/3"><c>gen_server:call(Server,Request,Timeout)</c></seemfa>, + ignoring the error handling. + </p> + <p> + The <c>gen_server</c> process calls + <seemfa marker="#Module:handle_call/3"> <c>Module:handle_call/3</c></seemfa> + to handle the request. + </p> + <p><c>ServerRef</c> can be any of the following:</p> + <list type="bulleted"> + <item>The pid</item> + <item><c>Name</c>, if the <c>gen_server</c> process is locally + registered</item> + <item><c>{Name,Node}</c>, if the <c>gen_server</c> process is locally + registered at another node</item> + <item><c>{global,GlobalName}</c>, if the <c>gen_server</c> process is + globally registered</item> + <item><c>{via,Module,ViaName}</c>, if the <c>gen_server</c> process is + registered through an alternative process registry</item> + </list> + <p><c>Request</c> is any term that is passed as the first + argument to <c>Module:handle_call/3</c>.</p> </desc> </func> @@ -356,7 +441,7 @@ gen_server:abcast -----> Module:handle_cast/2 <c>gen_server</c> process that is not part of a supervision tree and thus has no supervisor.</p> <p>For a description of arguments and return values, see - <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>.</p> + <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>.</p> </desc> </func> @@ -387,7 +472,7 @@ gen_server:abcast -----> Module:handle_cast/2 the supervisor. For example, it ensures that the <c>gen_server</c> process is linked to the supervisor.</p> <p>The <c>gen_server</c> process calls - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> to + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> to initialize. To ensure a synchronized startup procedure, <c>start_link/3,4</c> does not return until <c>Module:init/1</c> has returned.</p> @@ -399,8 +484,8 @@ gen_server:abcast -----> Module:handle_cast/2 <item> <p>If <c>ServerName={global,GlobalName}</c>, the <c>gen_server</c> process id registered globally as <c>GlobalName</c> using - <seealso marker="kernel:global#register_name/2"> - <c>global:register_name/2</c></seealso> If no name is + <seemfa marker="kernel:global#register_name/2"> + <c>global:register_name/2</c></seemfa> If no name is provided, the <c>gen_server</c> process is not registered.</p> </item> <item> @@ -410,14 +495,14 @@ gen_server:abcast -----> Module:handle_cast/2 <c>register_name/2</c>, <c>unregister_name/1</c>, <c>whereis_name/1</c>, and <c>send/2</c>, which are to behave like the corresponding functions in - <seealso marker="kernel:global"><c>global</c></seealso>. + <seeerl marker="kernel:global"><c>global</c></seeerl>. Thus, <c>{via,global,GlobalName}</c> is a valid reference.</p> </item> </list> <p><c>Module</c> is the name of the callback module.</p> <p><c>Args</c> is any term that is passed as the argument to - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>.</p> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>.</p> <list type="bulleted"> <item> <p>If option <c>{timeout,Time}</c> is present, the <c>gen_server</c> @@ -429,21 +514,21 @@ gen_server:abcast -----> Module:handle_cast/2 <p>If option <c>{hibernate_after,HibernateAfterTimeout}</c> is present, the <c>gen_server</c> process awaits any message for <c>HibernateAfterTimeout</c> milliseconds and if no message is received, the process goes into hibernation automatically - (by calling <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>).</p> + (by calling <seemfa marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa>).</p> </item> <item> <p>If option <c>{debug,Dbgs}</c> is present, the corresponding <c>sys</c> function is called for each item in <c>Dbgs</c>; see - <seealso marker="sys"><c>sys(3)</c></seealso>.</p> + <seeerl marker="sys"><c>sys(3)</c></seeerl>.</p> </item> <item> <p>If option <c>{spawn_opt,SOpts}</c> is present, <c>SOpts</c> is passed as option list to the <c>spawn_opt</c> BIF, which is used to spawn the <c>gen_server</c> process; see - <seealso marker="erts:erlang#spawn_opt/2"> - <c>spawn_opt/2</c></seealso>.</p> + <seemfa marker="erts:erlang#spawn_opt/2"> + <c>spawn_opt/2</c></seemfa>.</p> </item> </list> <note> @@ -466,6 +551,43 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> + <name since="OTP 23.0">start_monitor(Module, Args, Options) -> Result</name> + <name since="OTP 23.0">start_monitor(ServerName, Module, Args, Options) -> Result</name> + <fsummary>Create a standalone <c>gen_server</c> process.</fsummary> + <type> + <v>ServerName = {local,Name} | {global,GlobalName}</v> + <v> | {via,Module,ViaName}</v> + <v> Name = atom()</v> + <v> GlobalName = ViaName = term()</v> + <v>Module = atom()</v> + <v>Args = term()</v> + <v>Options = [Option]</v> + <v> Option = {debug,Dbgs} | {timeout,Time} | {hibernate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}</v> + <v> Dbgs = [Dbg]</v> + <v> Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}</v> + <v> SOpts = [term()]</v> + <v>Result = {ok,{Pid,Mon}} | ignore | {error,Error}</v> + <v> Pid = pid()</v> + <v> Error = {already_started,Pid} | term()</v> + </type> + <desc> + <p>Creates a standalone <c>gen_server</c> process, that is, a + <c>gen_server</c> process that is not part of a supervision tree + (and thus has no supervisor) and atomically sets up a monitor to + the newly created server.</p> + <p>For a description of arguments and return values, see + <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>. + Note that the return value on successful start differs from + <c>start_link/3,4</c>. <c>start_monitor/3,4</c> will return + <c>{ok,{Pid,Mon}}</c> where <c>Pid</c> is the process identifier + of the server, and <c>Mon</c> is a reference to the monitor + set up to monitor the server. If the start is not successful, + the caller will be blocked until the <c>DOWN</c> message has + been received and removed from the message queue.</p> + </desc> + </func> + + <func> <name since="OTP 18.0">stop(ServerRef) -> ok</name> <name since="OTP 18.0">stop(ServerRef, Reason, Timeout) -> ok</name> <fsummary>Synchronously stop a generic server.</fsummary> @@ -480,13 +602,13 @@ gen_server:abcast -----> Module:handle_cast/2 <desc> <p>Orders a generic server to exit with the specified <c>Reason</c> and waits for it to terminate. The <c>gen_server</c> process calls - <seealso marker="#Module:terminate/2"> - <c>Module:terminate/2</c></seealso> before exiting.</p> + <seemfa marker="#Module:terminate/2"> + <c>Module:terminate/2</c></seemfa> before exiting.</p> <p>The function returns <c>ok</c> if the server terminates with the expected reason. Any other reason than <c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c> causes an error report to be issued using - <seealso marker="kernel:logger"><c>logger(3)</c></seealso>. + <seeerl marker="kernel:logger"><c>logger(3)</c></seeerl>. The default <c>Reason</c> is <c>normal</c>.</p> <p><c>Timeout</c> is an integer greater than zero that specifies how many milliseconds to wait for the server to @@ -498,15 +620,59 @@ gen_server:abcast -----> Module:handle_cast/2 is raised.</p> </desc> </func> + + <func> + <name since="OTP-23">wait_response(RequestId, Timeout) -> Result</name> + <fsummary>Wait for a reply from a server.</fsummary> + <type> + <v>RequestId = term()</v> + <v>Result = {reply, Reply} | timeout | {error, {Reason, ServerRef}}</v> + <v>Reply = term()</v> + <v>Timeout = timeout()</v> + <v>Reason = term()</v> + <v>ServerRef = Name | {Name,Node} | {global,GlobalName}</v> + <v> | {via,Module,ViaName} | pid()</v> + <v> Node = atom()</v> + <v> GlobalName = ViaName = term()</v> + </type> + <desc> + <p> + This function is used to wait for a reply of a request made with + <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa> + from the <c>gen_server</c> process. This function must be called + from the same process from which + <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa> + was made. + </p> + <p> + <c>Timeout</c> is an integer greater then or equal to zero + that specifies how many milliseconds to wait for an reply, or + the atom <c>infinity</c> to wait indefinitely. + If no reply is received within the specified + time, the function returns <c>timeout</c> and no cleanup is + done, and thus the function can be invoked repeatedly until a + reply is returned. + </p> + <p> + The return value <c>Reply</c> is defined in the return value + of <c>Module:handle_call/3</c>. + </p> + <p> + The function returns an error if the <c>gen_server</c> + dies before or during this request. + </p> + </desc> + </func> </funcs> - <section> - <title>Callback Functions</title> - <p>The following functions - are to be exported from a <c>gen_server</c> callback module.</p> - </section> + <funcs> + <fsdescription> + <title>Callback Functions</title> + <p>The following functions + are to be exported from a <c>gen_server</c> callback module.</p> + </fsdescription> <func> <name since="">Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error, Reason}</name> <fsummary>Update the internal state during upgrade/downgrade.</fsummary> @@ -530,8 +696,8 @@ gen_server:abcast -----> Module:handle_cast/2 that is, when the instruction <c>{update,Module,Change,...}</c>, where <c>Change={advanced,Extra}</c>, is specifed in the <c>appup</c> file. For more information, see section - <seealso marker="doc/design_principles:release_handling#instr"> - Release Handling Instructions</seealso> in OTP Design Principles.</p> + <seeguide marker="system/design_principles:release_handling#instr"> + Release Handling Instructions</seeguide> in OTP Design Principles.</p> <p>For an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and for a downgrade, <c>OldVsn</c> is <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c> @@ -570,8 +736,8 @@ gen_server:abcast -----> Module:handle_cast/2 following situations:</p> <list type="bulleted"> <item> - <p>One of <seealso marker="sys#get_status/1"> - <c>sys:get_status/1,2</c></seealso> + <p>One of <seemfa marker="sys#get_status/1"> + <c>sys:get_status/1,2</c></seemfa> is invoked to get the <c>gen_server</c> status. <c>Opt</c> is set to the atom <c>normal</c>.</p> </item> @@ -631,8 +797,8 @@ gen_server:abcast -----> Module:handle_cast/2 </type> <desc> <p>Whenever a <c>gen_server</c> process receives a request sent using - <seealso marker="#call/2"><c>call/2,3</c></seealso> or - <seealso marker="#multi_call/2"><c>multi_call/2,3,4</c></seealso>, + <seemfa marker="#call/2"><c>call/2,3</c></seemfa> or + <seemfa marker="#multi_call/2"><c>multi_call/2,3,4</c></seemfa>, this function is called to handle the request.</p> <p><c>Request</c> is the <c>Request</c> argument provided to <c>call</c> or <c>multi_call</c>.</p> @@ -651,7 +817,7 @@ gen_server:abcast -----> Module:handle_cast/2 continues executing with the possibly updated internal state <c>NewState</c>.</p> <p>For a description of <c>Timeout</c> and <c>hibernate</c>, see - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>.</p> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>.</p> </item> <item> <p>If <c>{noreply,NewState}</c> is returned, @@ -659,7 +825,7 @@ gen_server:abcast -----> Module:handle_cast/2 <c>{noreply,NewState,hibernate}</c>, the <c>gen_server</c> process continues executing with <c>NewState</c>. Any reply to <c>From</c> must be specified explicitly using - <seealso marker="#reply/2"><c>reply/2</c></seealso>.</p> + <seemfa marker="#reply/2"><c>reply/2</c></seemfa>.</p> </item> <item> <p>If <c>{stop,Reason,Reply,NewState}</c> is returned, @@ -668,7 +834,7 @@ gen_server:abcast -----> Module:handle_cast/2 <item> <p>If <c>{stop,Reason,NewState}</c> is returned, any reply to <c>From</c> must be specified explicitly using - <seealso marker="#reply/2"><c>reply/2</c></seealso>. + <seemfa marker="#reply/2"><c>reply/2</c></seemfa>. The <c>gen_server</c> process then calls <c>Module:terminate(Reason,NewState)</c> and terminates.</p> </item> @@ -693,12 +859,12 @@ gen_server:abcast -----> Module:handle_cast/2 </type> <desc> <p>Whenever a <c>gen_server</c> process receives a request sent using - <seealso marker="#cast/2"><c>cast/2</c></seealso> or - <seealso marker="#abcast/2"><c>abcast/2,3</c></seealso>, + <seemfa marker="#cast/2"><c>cast/2</c></seemfa> or + <seemfa marker="#abcast/2"><c>abcast/2,3</c></seemfa>, this function is called to handle the request.</p> <p>For a description of the arguments and possible return values, see - <seealso marker="#Module:handle_call/3"> - <c>Module:handle_call/3</c></seealso>.</p> + <seemfa marker="#Module:handle_call/3"> + <c>Module:handle_call/3</c></seemfa>.</p> </desc> </func> @@ -732,8 +898,8 @@ gen_server:abcast -----> Module:handle_cast/2 initialization or for splitting the work in a callback in multiple steps, updating the process state along the way.</p> <p>For a description of the other arguments and possible return values, - see <seealso marker="#Module:handle_call/3"> - <c>Module:handle_call/3</c></seealso>.</p> + see <seemfa marker="#Module:handle_call/3"> + <c>Module:handle_call/3</c></seemfa>.</p> </desc> </func> @@ -764,8 +930,8 @@ gen_server:abcast -----> Module:handle_cast/2 <p><c>Info</c> is either the atom <c>timeout</c>, if a time-out has occurred, or the received message.</p> <p>For a description of the other arguments and possible return values, - see <seealso marker="#Module:handle_call/3"> - <c>Module:handle_call/3</c></seealso>.</p> + see <seemfa marker="#Module:handle_call/3"> + <c>Module:handle_call/3</c></seemfa>.</p> </desc> </func> @@ -782,8 +948,9 @@ gen_server:abcast -----> Module:handle_cast/2 </type> <desc> <p>Whenever a <c>gen_server</c> process is started using - <seealso marker="#start/3"><c>start/3,4</c></seealso> or - <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>, + <seemfa marker="#start/3"><c>start/3,4</c></seemfa>, + <seemfa marker="#start_monitor/3"><c>start_monitor/3,4</c></seemfa>, + or <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>, this function is called by the new process to initialize.</p> <p><c>Args</c> is the <c>Args</c> argument provided to the start function.</p> @@ -795,15 +962,15 @@ gen_server:abcast -----> Module:handle_cast/2 unless a request or a message is received within <c>Timeout</c> milliseconds. A time-out is represented by the atom <c>timeout</c>, which is to be handled by the - <seealso marker="#Module:handle_info/2"> - <c>Module:handle_info/2</c></seealso> callback function. The atom + <seemfa marker="#Module:handle_info/2"> + <c>Module:handle_info/2</c></seemfa> callback function. The atom <c>infinity</c> can be used to wait indefinitely, this is the default value.</p> <p>If <c>hibernate</c> is specified instead of a time-out value, the process goes into hibernation when waiting for the next message to arrive (by calling - <seealso marker="proc_lib#hibernate/3"> - <c>proc_lib:hibernate/3</c></seealso>).</p> + <seemfa marker="proc_lib#hibernate/3"> + <c>proc_lib:hibernate/3</c></seemfa>).</p> <p>If the initialization fails, the function is to return <c>{stop,Reason}</c>, where <c>Reason</c> is any term, or <c>ignore</c>.</p> @@ -825,7 +992,7 @@ gen_server:abcast -----> Module:handle_cast/2 </note> <p>This function is called by a <c>gen_server</c> process when it is about to terminate. It is to be the opposite of - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> and do any necessary cleaning up. When it returns, the <c>gen_server</c> process terminates with <c>Reason</c>. The return value is ignored.</p> @@ -860,18 +1027,18 @@ gen_server:abcast -----> Module:handle_cast/2 <c>shutdown</c>, or <c>{shutdown,Term}</c>, the <c>gen_server</c> process is assumed to terminate because of an error and an error report is issued using - <seealso marker="kernel:logger"><c>logger(3)</c></seealso>.</p> + <seeerl marker="kernel:logger"><c>logger(3)</c></seeerl>.</p> </desc> </func> </funcs> <section> <title>See Also</title> - <p><seealso marker="gen_event"><c>gen_event(3)</c></seealso>, - <seealso marker="gen_statem"><c>gen_statem(3)</c></seealso>, - <seealso marker="proc_lib"><c>proc_lib(3)</c></seealso>, - <seealso marker="supervisor"><c>supervisor(3)</c></seealso>, - <seealso marker="sys"><c>sys(3)</c></seealso></p> + <p><seeerl marker="gen_event"><c>gen_event(3)</c></seeerl>, + <seeerl marker="gen_statem"><c>gen_statem(3)</c></seeerl>, + <seeerl marker="proc_lib"><c>proc_lib(3)</c></seeerl>, + <seeerl marker="supervisor"><c>supervisor(3)</c></seeerl>, + <seeerl marker="sys"><c>sys(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index c12ad2deef..fa3f20535d 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -34,7 +34,7 @@ <p> <c>gen_statem</c> provides a generic state machine behaviour that for new code replaces its predecessor - <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> + <seeerl marker="gen_fsm"><c>gen_fsm</c></seeerl> since Erlang/OTP 20.0. The <c>gen_fsm</c> behaviour remains in OTP "as is". </p> @@ -42,13 +42,13 @@ <p> If you are new to <c>gen_statem</c> and want an overview of concepts and operation the section - <seealso marker="doc/design_principles:statem"> + <seeguide marker="system/design_principles:statem"> <c>gen_statem</c> Behaviour - </seealso> + </seeguide> located in the User's Guide - <seealso marker="doc/design_principles:users_guide"> + <seeguide marker="system/design_principles:index"> OTP Design Principles - </seealso> + </seeguide> is recommended to read before this reference manual, possibly after the Description section you are reading here. </p> @@ -59,13 +59,13 @@ However, the generated descriptions also reflect the type hierarchy, which sometimes makes it hard to get a good overview. If so, see the section - <seealso marker="doc/design_principles:statem"> + <seeguide marker="system/design_principles:statem"> <c>gen_statem</c> Behaviour - </seealso> + </seeguide> in the - <seealso marker="doc/design_principles:users_guide"> + <seeguide marker="system/design_principles:index"> OTP Design Principles - </seealso> + </seeguide> User's Guide. </p> <note> @@ -74,44 +74,44 @@ <item> In OTP 19.1 a backwards incompatible change of the return tuple from - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> was made and the mandatory callback function - <seealso marker="#Module:callback_mode/0"> + <seemfa marker="#Module:callback_mode/0"> <c>Module:callback_mode/0</c> - </seealso> + </seemfa> was introduced. </item> <item> In OTP 20.0 - <seealso marker="#type-generic_timeout"> + <seetype marker="#generic_timeout"> generic time-outs - </seealso> + </seetype> were added. </item> <item> In OTP 22.1 time-out content - <seealso marker="#type-timeout_update_action"> + <seetype marker="#timeout_update_action"> <c>update</c> - </seealso> + </seetype> and explicit time-out - <seealso marker="#type-timeout_cancel_action"> + <seetype marker="#timeout_cancel_action"> <c>cancel</c> - </seealso> + </seetype> were added. </item> <item> In OTP 22.3 the possibility to change the callback module with actions - <seealso marker="#type-action"><c>change_callback_module</c></seealso>, - <seealso marker="#type-action"><c>push_callback_module</c></seealso> and - <seealso marker="#type-action"><c>pop_callback_module</c></seealso>, + <seetype marker="#action"><c>change_callback_module</c></seetype>, + <seetype marker="#action"><c>push_callback_module</c></seetype> and + <seetype marker="#action"><c>pop_callback_module</c></seetype>, was added. </item> </list> </note> <p> <c>gen_statem</c> has got the same features that - <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> + <seeerl marker="gen_fsm"><c>gen_fsm</c></seeerl> had and adds some really useful: </p> <list type="bulleted"> @@ -133,14 +133,14 @@ <p> Two - <seealso marker="#type-callback_mode"><em>callback modes</em></seealso> + <seetype marker="#callback_mode"><em>callback modes</em></seetype> are supported: </p> <list type="bulleted"> <item> <p> One for finite-state machines - (<seealso marker="gen_fsm"><c>gen_fsm</c></seealso> like), + (<seeerl marker="gen_fsm"><c>gen_fsm</c></seeerl> like), which requires the state to be an atom and uses that state as the name of the current callback function. </p> @@ -154,18 +154,18 @@ </list> <p> The callback model(s) for <c>gen_statem</c> differs from - the one for <seealso marker="gen_fsm"><c>gen_fsm</c></seealso>, + the one for <seeerl marker="gen_fsm"><c>gen_fsm</c></seeerl>, but it is still fairly easy to - <seealso marker="gen_fsm#Migration to gen_statem"> + <seeerl marker="gen_fsm#Migration to gen_statem"> rewrite from - </seealso> <c>gen_fsm</c> to <c>gen_statem</c>. + </seeerl> <c>gen_fsm</c> to <c>gen_statem</c>. </p> <p> A generic state machine server process (<c>gen_statem</c>) implemented using this module has a standard set of interface functions and includes functionality for tracing and error reporting. It also fits into an OTP supervision tree. For more information, see - <seealso marker="doc/design_principles:statem">OTP Design Principles</seealso>. + <seeguide marker="system/design_principles:statem">OTP Design Principles</seeguide>. </p> <p> A <c>gen_statem</c> assumes all specific parts to be located in a @@ -176,6 +176,7 @@ gen_statem module Callback module ----------------- --------------- gen_statem:start +gen_statem:start_monitor gen_statem:start_link -----> Module:init/1 Server start or code change @@ -185,6 +186,7 @@ gen_statem:stop -----> Module:terminate/3 gen_statem:call gen_statem:cast +gen_statem:send_request erlang:send erlang:'!' -----> Module:StateName/3 Module:handle_event/4 @@ -194,7 +196,7 @@ erlang:'!' -----> Module:StateName/3 - -----> Module:code_change/4</pre> <p> Events are of different - <seealso marker="#type-event_type">types</seealso>, + <seetype marker="#event_type">types</seetype>, so the callback functions can know the origin of an event and how to respond. </p> @@ -202,39 +204,39 @@ erlang:'!' -----> Module:StateName/3 If a callback function fails or returns a bad value, the <c>gen_statem</c> terminates, unless otherwise stated. However, an exception of class - <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso> + <seemfa marker="erts:erlang#throw/1"><c>throw</c></seemfa> is not regarded as an error but as a valid return from all callback functions. </p> <marker id="state callback"/> <p> The <em>state callback</em> for a specific - <seealso marker="#type-state">state</seealso> + <seetype marker="#state">state</seetype> in a <c>gen_statem</c> is the callback function that is called for all events in this state. It is selected depending on which - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> that the callback module defines with the callback function - <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>. + <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa>. </p> <p> When the - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> is <c>state_functions</c>, the state must be an atom and is used as the <em>state callback</em> name; see - <seealso marker="#Module:StateName/3"><c>Module:StateName/3</c></seealso>. + <seemfa marker="#Module:StateName/3"><c>Module:StateName/3</c></seemfa>. This co-locates all code for a specific state in one function as the <c>gen_statem</c> engine branches depending on state name. Note the fact that the callback function - <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> + <seemfa marker="#Module:terminate/3"><c>Module:terminate/3</c></seemfa> makes the state name <c>terminate</c> unusable in this mode. </p> <p> When the - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> is <c>handle_event_function</c>, the state can be any term and the <em>state callback</em> name is - <seealso marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seealso>. + <seemfa marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seemfa>. This makes it easy to branch depending on state or event as you desire. Be careful about which events you handle in which states so that you do not accidentally postpone an event @@ -243,10 +245,10 @@ erlang:'!' -----> Module:StateName/3 <p> When <c>gen_statem</c> receives a process message it is converted into an event and the - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> is called with the event as two arguments: type and content. When the - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> has processed the event it returns to <c>gen_statem</c> which does a <em>state transition</em>. If this <em>state transition</em> is to a different state, @@ -254,13 +256,13 @@ erlang:'!' -----> Module:StateName/3 </p> <p> The - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> may return - <seealso marker="#type-action"><em>transition actions</em></seealso> + <seetype marker="#action"><em>transition actions</em></seetype> for <c>gen_statem</c> to execute during the <em>state transition</em>, for example to reply to a - <seealso marker="#call/2"><c>gen_statem:call/2,3</c></seealso>. + <seemfa marker="#call/2"><c>gen_statem:call/2,3</c></seemfa>. </p> <p> One of the possible <em>transition actions</em> @@ -281,17 +283,17 @@ erlang:'!' -----> Module:StateName/3 </p> <p> The - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> can insert events using the - <seealso marker="#type-action"><em>transition actions</em></seealso> + <seetype marker="#action"><em>transition actions</em></seetype> <c>next_event</c> and such an event is inserted in the event queue as the next to call the - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> with. That is, as if it is the oldest incoming event. A dedicated - <seealso marker="#type-event_type"><c>event_type()</c></seealso> + <seetype marker="#event_type"><c>event_type()</c></seetype> <c>internal</c> can be used for such events making them impossible to mistake for external events. </p> @@ -299,15 +301,15 @@ erlang:'!' -----> Module:StateName/3 Inserting an event replaces the trick of calling your own state handling functions that you often would have to resort to in, for example, - <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> + <seeerl marker="gen_fsm"><c>gen_fsm</c></seeerl> to force processing an inserted event before others. </p> <p> The <c>gen_statem</c> engine can automatically make a specialized call to the - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> whenever a new state is entered; see - <seealso marker="#type-state_enter"><c>state_enter()</c></seealso>. + <seetype marker="#state_enter"><c>state_enter()</c></seetype>. This is for writing code common to all state entries. Another way to do it is to explicitly insert an event at the <em>state transition</em>, @@ -325,18 +327,18 @@ erlang:'!' -----> Module:StateName/3 </note> <p> For the details of a <em>state transition</em>, see type - <seealso marker="#type-transition_option"><c>transition_option()</c></seealso>. + <seetype marker="#transition_option"><c>transition_option()</c></seetype>. </p> <p> A <c>gen_statem</c> handles system messages as described in - <seealso marker="sys"><c>sys</c></seealso>. + <seeerl marker="sys"><c>sys</c></seeerl>. The <c>sys</c> module can be used for debugging a <c>gen_statem</c>. </p> <p> Notice that a <c>gen_statem</c> does not trap exit signals automatically, this must be explicitly initiated in the callback module (by calling - <seealso marker="erts:erlang#process_flag/2"><c>process_flag(trap_exit, true)</c></seealso>. + <seemfa marker="erts:erlang#process_flag/2"><c>process_flag(trap_exit, true)</c></seemfa>. </p> <p> Unless otherwise stated, all functions in this module fail if @@ -345,29 +347,30 @@ erlang:'!' -----> Module:StateName/3 </p> <p> The <c>gen_statem</c> process can go into hibernation; see - <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>. + <seemfa marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa>. It is done when a - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> or - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> specifies <c>hibernate</c> in the returned - <seealso marker="#type-action"><c>Actions</c></seealso> + <seetype marker="#action"><c>Actions</c></seetype> list. This feature can be useful to reclaim process heap memory while the server is expected to be idle for a long time. However, use this feature with care, as hibernation can be too costly to use after every event; see - <seealso marker="erts:erlang#hibernate/3"><c>erlang:hibernate/3</c></seealso>. + <seemfa marker="erts:erlang#hibernate/3"><c>erlang:hibernate/3</c></seemfa>. </p> <p> There is also a server start option - <seealso marker="#type-enter_loop_opt"> + <seetype marker="#enter_loop_opt"> <c>{hibernate_after, Timeout}</c> - </seealso> + </seetype> for - <seealso marker="#start/3"><c>start/3,4</c></seealso>, - <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso> or - <seealso marker="#enter_loop/4"><c>enter_loop/4,5,6</c></seealso>, + <seemfa marker="#start/3"><c>start/3,4</c></seemfa>, + <seemfa marker="#start_monitor/3"><c>start_monitor/3,4</c></seemfa>, + <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa> or + <seemfa marker="#enter_loop/4"><c>enter_loop/4,5,6</c></seemfa>, that may be used to automatically hibernate the server. </p> </description> @@ -377,7 +380,7 @@ erlang:'!' -----> Module:StateName/3 <p> The following example shows a simple pushbutton model for a toggling pushbutton implemented with - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> <c>state_functions</c>. You can push the button and it replies if it went on or off, and you can ask for a count of how many times it has been @@ -463,7 +466,7 @@ ok </pre> <p> To compare styles, here follows the same example using - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> <c>handle_event_function</c>, or rather the code to replace after function <c>init/1</c> of the <c>pushbutton.erl</c> example file above: @@ -498,9 +501,9 @@ handle_event(_, _, State, Data) -> <p> Name specification to use when starting a <c>gen_statem</c> server. See - <seealso marker="#start_link/3"><c>start_link/3</c></seealso> + <seemfa marker="#start_link/3"><c>start_link/3</c></seemfa> and - <seealso marker="#type-server_ref"><c>server_ref()</c></seealso> + <seetype marker="#server_ref"><c>server_ref()</c></seetype> below. </p> </desc> @@ -511,8 +514,8 @@ handle_event(_, _, State, Data) -> <p> Server specification to use when addressing a <c>gen_statem</c> server. - See <seealso marker="#call/2"><c>call/2</c></seealso> and - <seealso marker="#type-server_name"><c>server_name()</c></seealso> + See <seemfa marker="#call/2"><c>call/2</c></seemfa> and + <seetype marker="#server_name"><c>server_name()</c></seetype> above. </p> <p>It can be:</p> @@ -534,7 +537,7 @@ handle_event(_, _, State, Data) -> <item> <p> The <c>gen_statem</c> is globally registered in - <seealso marker="kernel:global"><c>global</c></seealso>. + <seeerl marker="kernel:global"><c>global</c></seeerl>. </p> </item> <tag><c>{via,RegMod,ViaName}</c></tag> @@ -547,7 +550,7 @@ handle_event(_, _, State, Data) -> <c>register_name/2</c>, <c>unregister_name/1</c>, <c>whereis_name/1</c>, and <c>send/2</c>, which are to behave like the corresponding functions in - <seealso marker="kernel:global"><c>global</c></seealso>. + <seeerl marker="kernel:global"><c>global</c></seeerl>. Thus, <c>{via,global,GlobalName}</c> is the same as <c>{global,GlobalName}</c>. </p> @@ -561,7 +564,7 @@ handle_event(_, _, State, Data) -> <p> Options that can be used when starting a <c>gen_statem</c> server through, for example, - <seealso marker="#start_link/3"><c>start_link/3</c></seealso>. + <seemfa marker="#start_link/3"><c>start_link/3</c></seemfa>. </p> </desc> </datatype> @@ -569,8 +572,18 @@ handle_event(_, _, State, Data) -> <name name="start_ret"/> <desc> <p> - Return value from the start functions, for example, - <seealso marker="#start_link/3"><c>start_link/3</c></seealso>. + Return value from the <c>start()</c> and <c>start_link()</c> functions, + for example, <seemfa marker="#start_link/3"><c>start_link/3</c></seemfa>. + </p> + </desc> + </datatype> + <datatype> + <name name="start_mon_ret"/> + <desc> + <p> + Return value from the + <seemfa marker="#start_monitor/3"><c>start_monitor()</c></seemfa> + functions. </p> </desc> </datatype> @@ -580,7 +593,7 @@ handle_event(_, _, State, Data) -> <p> Options that can be used when starting a <c>gen_statem</c> server through, - <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>. + <seemfa marker="#enter_loop/4"><c>enter_loop/4-6</c></seemfa>. </p> <taglist> <tag><c>hibernate_after</c></tag> @@ -591,7 +604,7 @@ handle_event(_, _, State, Data) -> any message for <c>HibernateAfterTimeout</c> milliseconds and if no message is received, the process goes into hibernation automatically (by calling - <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>). + <seemfa marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa>). </p> </item> <tag><c>debug</c></tag> @@ -599,7 +612,7 @@ handle_event(_, _, State, Data) -> <p> For every entry in <c><anno>Dbgs</anno></c>, the corresponding function in - <seealso marker="sys"><c>sys</c></seealso> is called. + <seeerl marker="sys"><c>sys</c></seeerl> is called. </p> </item> </taglist> @@ -610,10 +623,10 @@ handle_event(_, _, State, Data) -> <desc> <p> Destination to use when replying through, for example, the - <seealso marker="#type-action"><c>action()</c></seealso> + <seetype marker="#action"><c>action()</c></seetype> <c>{reply,From,Reply}</c> to a process that has called the <c>gen_statem</c> server using - <seealso marker="#call/2"><c>call/2</c></seealso>. + <seemfa marker="#call/2"><c>call/2</c></seemfa>. </p> </desc> </datatype> @@ -622,7 +635,7 @@ handle_event(_, _, State, Data) -> <desc> <p> If the - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> is <c>handle_event_function</c>, the state can be any term. After a <em>state change</em> (<c>NextState =/= State</c>), @@ -635,14 +648,14 @@ handle_event(_, _, State, Data) -> <desc> <p> If the - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> is <c>state_functions</c>, the state must be an atom. After a <em>state change</em> (<c>NextState =/= State</c>), all postponed events are retried. Note that the state <c>terminate</c> is not possible to use since it would collide with the optional callback function - <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso>. + <seemfa marker="#Module:terminate/3"><c>Module:terminate/3</c></seemfa>. </p> </desc> </datatype> @@ -652,7 +665,7 @@ handle_event(_, _, State, Data) -> <p> A term in which the state machine implementation is to store any server data it needs. The difference between - this and the <seealso marker="#type-state"><c>state()</c></seealso> + this and the <seetype marker="#state"><c>state()</c></seetype> itself is that a change in this data does not cause postponed events to be retried. Hence, if a change in this data would change the set of events that @@ -666,14 +679,14 @@ handle_event(_, _, State, Data) -> <desc> <p> There are 3 categories of events: - <seealso marker="#type-external_event_type">external</seealso>, - <seealso marker="#type-timeout_event_type">timeout</seealso>, + <seetype marker="#external_event_type">external</seetype>, + <seetype marker="#timeout_event_type">timeout</seetype>, and <c>internal</c>. </p> <p> <c>internal</c> events can only be generated by the state machine itself through the <em>transition action</em> - <seealso marker="#type-action"><c>next_event</c></seealso>. + <seetype marker="#action"><c>next_event</c></seetype>. </p> </desc> </datatype> @@ -683,11 +696,12 @@ handle_event(_, _, State, Data) -> <p> External events are of 3 types: <c>{call,<anno>From</anno>}</c>, <c>cast</c>, or <c>info</c>. - <seealso marker="#call/2">Calls</seealso> - (synchronous) and - <seealso marker="#cast/2">casts</seealso> - originate from the corresponding API functions. + Type <c>call</c> originates from the API functions + <seemfa marker="#call/2"><c>call/2</c></seemfa> + and <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>. For calls, the event contains whom to reply to. + Type <c>cast</c> originates from the API function + <seemfa marker="#cast/2"><c>cast/2</c></seemfa>. Type <c>info</c> originates from regular process messages sent to the <c>gen_statem</c>. </p> @@ -699,7 +713,7 @@ handle_event(_, _, State, Data) -> <p> There are 3 types of time-out events that the state machine can generate for itself with the corresponding - <seealso marker="#type-timeout_action">timeout_action()</seealso>s. + <seetype marker="#timeout_action">timeout_action()</seetype>s. </p> </desc> </datatype> @@ -708,11 +722,11 @@ handle_event(_, _, State, Data) -> <desc> <p> This is the return type from - <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> + <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa> and selects - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> and whether to do - <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>, + <seetype marker="#state_enter"><em>state enter calls</em></seetype>, or not. </p> </desc> @@ -723,16 +737,16 @@ handle_event(_, _, State, Data) -> <p> The <em>callback mode</em> is selected with the return value from - <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>: + <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa>: </p> <taglist> <tag><c>state_functions</c></tag> <item> <p> The state must be of type - <seealso marker="#type-state_name"><c>state_name()</c></seealso> + <seetype marker="#state_name"><c>state_name()</c></seetype> and one callback function per state, that is, - <seealso marker="#Module:StateName/3"><c>Module:StateName/3</c></seealso>, + <seemfa marker="#Module:StateName/3"><c>Module:StateName/3</c></seemfa>, is used. </p> </item> @@ -740,22 +754,22 @@ handle_event(_, _, State, Data) -> <item> <p> The state can be any term and the callback function - <seealso marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seealso> + <seemfa marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seemfa> is used for all states. </p> </item> </taglist> <p> The function - <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> + <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa> is called when starting the <c>gen_statem</c>, after code change and after changing the callback module with any of the actions - <seealso marker="#type-action"><c>change_callback_module</c></seealso>, - <seealso marker="#type-action"><c>push_callback_module</c></seealso> or - <seealso marker="#type-action"><c>pop_callback_module</c></seealso>. + <seetype marker="#action"><c>change_callback_module</c></seetype>, + <seetype marker="#action"><c>push_callback_module</c></seetype> or + <seetype marker="#action"><c>pop_callback_module</c></seetype>. The result is cached for subsequent calls to - <seealso marker="#state callback">state callbacks</seealso>. + <seeerl marker="#state callback">state callbacks</seeerl>. </p> </desc> </datatype> @@ -766,45 +780,45 @@ handle_event(_, _, State, Data) -> Whether the state machine should use <em>state enter calls</em> or not is selected when starting the <c>gen_statem</c> and after code change using the return value from - <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>. + <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa>. </p> <p> If - <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> + <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa> returns a list containing <c>state_enter</c>, the <c>gen_statem</c> engine will, at every <em>state change</em>, call the - <seealso marker="#state callback">state callback</seealso> + <seeerl marker="#state callback">state callback</seeerl> with arguments <c>(enter, OldState, Data)</c> or <c>(enter, OldState, State, Data)</c>, depending on the - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>. + <seetype marker="#callback_mode"><em>callback mode</em></seetype>. This may look like an event but is really a call performed after the previous - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> returned and before any event is delivered to the new - <seealso marker="#state callback"><em>state callback</em></seealso>. + <seeerl marker="#state callback"><em>state callback</em></seeerl>. See - <seealso marker="#Module:StateName/3"><c>Module:StateName/3</c></seealso> + <seemfa marker="#Module:StateName/3"><c>Module:StateName/3</c></seemfa> and - <seealso marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seealso>. + <seemfa marker="#Module:handle_event/4"><c>Module:handle_event/4</c></seemfa>. Such a call can be repeated by returning a - <seealso marker="#type-state_callback_result"> + <seetype marker="#state_callback_result"> <c>repeat_state</c> - </seealso> + </seetype> or - <seealso marker="#type-state_callback_result"> + <seetype marker="#state_callback_result"> <c>repeat_state_and_data</c> - </seealso> + </seetype> tuple from the <em>state callback</em>. </p> <p> If - <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> + <seemfa marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa> does not return such a list, no <em>state enter calls</em> are done. </p> <p> If - <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso> + <seemfa marker="#Module:code_change/4"><c>Module:code_change/4</c></seemfa> should transform the state, it is regarded as a state rename and not a <em>state change</em>, which will not cause a <em>state enter call</em>. @@ -824,10 +838,10 @@ handle_event(_, _, State, Data) -> <desc> <p> Transition options can be set by - <seealso marker="#type-action">actions</seealso> + <seetype marker="#action">actions</seetype> and modify the <em>state transition</em>. The <em>state transition</em> takes place when the - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> has processed an event and returns. Here are the sequence of steps for a <em>state transition</em>: </p> @@ -835,10 +849,10 @@ handle_event(_, _, State, Data) -> <item> <p> All returned - <seealso marker="#type-action">actions</seealso> + <seetype marker="#action">actions</seetype> are processed in order of appearance. In this step all replies generated by any - <seealso marker="#type-reply_action"><c>reply_action()</c></seealso> + <seetype marker="#reply_action"><c>reply_action()</c></seetype> are sent. Other actions set <c>transition_option()</c>s that come into play in subsequent steps. </p> @@ -846,45 +860,45 @@ handle_event(_, _, State, Data) -> <item> <p> If - <seealso marker="#type-state_enter"> + <seetype marker="#state_enter"> <em>state enter calls</em> - </seealso> + </seetype> are used, and either it is the initial state or one of the callback results - <seealso marker="#type-state_callback_result"> + <seetype marker="#state_callback_result"> <c>repeat_state_and_data</c> - </seealso> + </seetype> or - <seealso marker="#type-state_callback_result"> + <seetype marker="#state_callback_result"> <c>repeat_state_and_data</c> - </seealso> + </seetype> is used the <c>gen_statem</c> engine calls the current state callback with arguments - <seealso marker="#type-state_enter"><c>(enter, State, Data)</c></seealso> + <seetype marker="#state_enter"><c>(enter, State, Data)</c></seetype> or - <seealso marker="#type-state_enter"><c>(enter, State, State, Data)</c></seealso> - (depending on <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>) + <seetype marker="#state_enter"><c>(enter, State, State, Data)</c></seetype> + (depending on <seetype marker="#callback_mode"><em>callback mode</em></seetype>) and when it returns starts again from the top of this sequence. </p> <p> If - <seealso marker="#type-state_enter"> + <seetype marker="#state_enter"> <em>state enter calls</em> - </seealso> + </seetype> are used, and the state changes the <c>gen_statem</c> engine calls the new state callback with arguments - <seealso marker="#type-state_enter"><c>(enter, OldState, Data)</c></seealso> + <seetype marker="#state_enter"><c>(enter, OldState, Data)</c></seetype> or - <seealso marker="#type-state_enter"><c>(enter, OldState, State, Data)</c></seealso> - (depending on <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>) + <seetype marker="#state_enter"><c>(enter, OldState, State, Data)</c></seetype> + (depending on <seetype marker="#callback_mode"><em>callback mode</em></seetype>) and when it returns starts again from the top of this sequence. </p> </item> <item> <p> If - <seealso marker="#type-postpone"><c>postpone()</c></seealso> + <seetype marker="#postpone"><c>postpone()</c></seetype> is <c>true</c>, the current event is postponed. </p> @@ -899,7 +913,7 @@ handle_event(_, _, State, Data) -> <item> <p> All events stored with - <seealso marker="#type-action"><c>action()</c></seealso> + <seetype marker="#action"><c>action()</c></seetype> <c>next_event</c> are inserted to be processed before previously queued events. </p> @@ -907,10 +921,10 @@ handle_event(_, _, State, Data) -> <item> <p> Time-out timers - <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso>, - <seealso marker="#type-generic_timeout"><c>generic_timeout()</c></seealso> + <seetype marker="#event_timeout"><c>event_timeout()</c></seetype>, + <seetype marker="#generic_timeout"><c>generic_timeout()</c></seetype> and - <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso> + <seetype marker="#state_timeout"><c>state_timeout()</c></seetype> are handled. Time-outs with zero time are guaranteed to be delivered to the state machine before any external not yet received event so if there is such a time-out requested, @@ -921,23 +935,23 @@ handle_event(_, _, State, Data) -> </p> <p> Any event cancels an - <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso> + <seetype marker="#event_timeout"><c>event_timeout()</c></seetype> so a zero time event time-out is only generated if the event queue is empty. </p> <p> A <em>state change</em> cancels a - <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso> + <seetype marker="#state_timeout"><c>state_timeout()</c></seetype> and any new transition option of this type belongs to the new state, that is; a - <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso> + <seetype marker="#state_timeout"><c>state_timeout()</c></seetype> applies to the state the state machine enters. </p> </item> <item> <p> If there are enqueued events the - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> for the possibly new state is called with the oldest enqueued event, and we start again from the top of this sequence. @@ -948,14 +962,14 @@ handle_event(_, _, State, Data) -> Otherwise the <c>gen_statem</c> goes into <c>receive</c> or hibernation (if - <seealso marker="#type-hibernate"><c>hibernate()</c></seealso> + <seetype marker="#hibernate"><c>hibernate()</c></seetype> is <c>true</c>) to wait for the next message. In hibernation the next non-system event awakens the <c>gen_statem</c>, or rather the next incoming message awakens the <c>gen_statem</c>, but if it is a system event it goes right back into hibernation. When a new message arrives the - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> is called with the corresponding event, and we start again from the top of this sequence. </p> @@ -979,7 +993,7 @@ handle_event(_, _, State, Data) -> <p> If <c>true</c>, hibernates the <c>gen_statem</c> by calling - <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso> + <seemfa marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa> before going into <c>receive</c> to wait for a new external event. </p> @@ -988,9 +1002,9 @@ handle_event(_, _, State, Data) -> If there are enqueued events to process when hibrnation is requested, this is optimized by not hibernating but instead calling - <seealso marker="erts:erlang#garbage_collect/0"> + <seemfa marker="erts:erlang#garbage_collect/0"> <c>erlang:garbage_collect/0</c> - </seealso> + </seemfa> to simulate that the <c>gen_statem</c> entered hibernation and immediately got awakened by an enqueued event. </p> @@ -1002,15 +1016,15 @@ handle_event(_, _, State, Data) -> <desc> <p> Starts a timer set by - <seealso marker="#type-enter_action"><c>enter_action()</c></seealso> + <seetype marker="#enter_action"><c>enter_action()</c></seetype> <c>timeout</c>. When the timer expires an event of - <seealso marker="#type-event_type"><c>event_type()</c></seealso> + <seetype marker="#event_type"><c>event_type()</c></seetype> <c>timeout</c> will be generated. See - <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso> + <seemfa marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seemfa> for how <c>Time</c> and - <seealso marker="#type-timeout_option"><c>Options</c></seealso> + <seetype marker="#timeout_option"><c>Options</c></seetype> are interpreted. Future <c>erlang:start_timer/4</c> <c>Options</c> will not necessarily be supported. </p> @@ -1042,15 +1056,15 @@ handle_event(_, _, State, Data) -> <desc> <p> Starts a timer set by - <seealso marker="#type-enter_action"><c>enter_action()</c></seealso> + <seetype marker="#enter_action"><c>enter_action()</c></seetype> <c>{timeout,Name}</c>. When the timer expires an event of - <seealso marker="#type-event_type"><c>event_type()</c></seealso> + <seetype marker="#event_type"><c>event_type()</c></seetype> <c>{timeout,Name}</c> will be generated. See - <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso> + <seemfa marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seemfa> for how <c>Time</c> and - <seealso marker="#type-timeout_option"><c>Options</c></seealso> + <seetype marker="#timeout_option"><c>Options</c></seetype> are interpreted. Future <c>erlang:start_timer/4</c> <c>Options</c> will not necessarily be supported. </p> @@ -1078,15 +1092,15 @@ handle_event(_, _, State, Data) -> <desc> <p> Starts a timer set by - <seealso marker="#type-enter_action"><c>enter_action()</c></seealso> + <seetype marker="#enter_action"><c>enter_action()</c></seetype> <c>state_timeout</c>. When the timer expires an event of - <seealso marker="#type-event_type"><c>event_type()</c></seealso> + <seetype marker="#event_type"><c>event_type()</c></seetype> <c>state_timeout</c> will be generated. See - <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso> + <seemfa marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seemfa> for how <c>Time</c> and - <seealso marker="#type-timeout_option"><c>Options</c></seealso> + <seetype marker="#timeout_option"><c>Options</c></seetype> are interpreted. Future <c>erlang:start_timer/4</c> <c>Options</c> will not necessarily be supported. </p> @@ -1115,9 +1129,9 @@ handle_event(_, _, State, Data) -> If <c>Abs</c> is <c>true</c> an absolute timer is started, and if it is <c>false</c> a relative, which is the default. See - <seealso marker="erts:erlang#start_timer/4"> + <seemfa marker="erts:erlang#start_timer/4"> <c>erlang:start_timer/4</c> - </seealso> + </seemfa> for details. </p> <p> @@ -1130,26 +1144,26 @@ handle_event(_, _, State, Data) -> <p> These <em>transition actions</em> can be invoked by returning them from the - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> when it is called with an - <seealso marker="#type-event_type">event</seealso>, + <seetype marker="#event_type">event</seetype>, from - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> or by giving them to - <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. + <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa>. </p> <p> Actions are executed in the containing list order. </p> <p> Actions that set - <seealso marker="#type-transition_option"> + <seetype marker="#transition_option"> transition options - </seealso> + </seetype> override any previous of the same type, so the last in the containing list wins. For example, the last - <seealso marker="#type-postpone"><c>postpone()</c></seealso> + <seetype marker="#postpone"><c>postpone()</c></seetype> overrides any previous <c>postpone()</c> in the list. </p> <taglist> @@ -1157,15 +1171,15 @@ handle_event(_, _, State, Data) -> <item> <p> Sets the - <seealso marker="#type-transition_option"> + <seetype marker="#transition_option"> <c>transition_option()</c> - </seealso> - <seealso marker="#type-postpone"><c>postpone()</c></seealso> + </seetype> + <seetype marker="#postpone"><c>postpone()</c></seetype> for this <em>state transition</em>. This action is ignored when returned from - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> or given to - <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>, + <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa>, as there is no event to postpone in those cases. </p> </item> @@ -1173,9 +1187,9 @@ handle_event(_, _, State, Data) -> <item> <p> This action does not set any - <seealso marker="#type-transition_option"> + <seetype marker="#transition_option"> <c>transition_option()</c> - </seealso> + </seetype> but instead stores the specified <c><anno>EventType</anno></c> and <c><anno>EventContent</anno></c> for insertion after all actions have been executed. @@ -1188,7 +1202,7 @@ handle_event(_, _, State, Data) -> </p> <p> An event of type - <seealso marker="#type-event_type"><c>internal</c></seealso> + <seetype marker="#event_type"><c>internal</c></seetype> is to be used when you want to reliably distinguish an event inserted this way from any external event. </p> @@ -1201,19 +1215,19 @@ handle_event(_, _, State, Data) -> Changes the callback module to <c><anno>NewModule</anno></c> which will be used when calling all subsequent - <seealso marker="#state callback">state callbacks</seealso>. + <seeerl marker="#state callback">state callbacks</seeerl>. </p> <p> The <c>gen_statem</c> engine will find out the - <seealso marker="#type-callback_mode"> + <seetype marker="#callback_mode"> <em>callback mode</em> - </seealso> + </seetype> of <c><anno>NewModule</anno></c> by calling - <seealso marker="#Module:callback_mode/0"> + <seemfa marker="#Module:callback_mode/0"> <c>NewModule:callback_mode/0</c> - </seealso> + </seemfa> before the next - <seealso marker="#state callback">state callback</seealso>. + <seeerl marker="#state callback">state callback</seeerl>. </p> <p> Changing the callback module does not affect the @@ -1222,21 +1236,21 @@ handle_event(_, _, State, Data) -> Be aware that all relevant callback functions in <c><anno>NewModule</anno></c> such as the - <seealso marker="#state callback">state callback</seealso>, - <seealso marker="#Module:code_change/4"><c><anno>NewModule</anno>:code_change/4</c></seealso>, - <seealso marker="#Module:format_status/2"> + <seeerl marker="#state callback">state callback</seeerl>, + <seemfa marker="#Module:code_change/4"><c><anno>NewModule</anno>:code_change/4</c></seemfa>, + <seemfa marker="#Module:format_status/2"> <c><anno>NewModule</anno>:format_status/2</c> - </seealso> + </seemfa> and - <seealso marker="#Module:terminate/3"> + <seemfa marker="#Module:terminate/3"> <c><anno>NewModule</anno>:terminate/3</c> - </seealso> + </seemfa> must be able to handle the state and data from the old module. </p> </item> <tag> - <c>push_callback_module</c><br /> + <c>push_callback_module</c> </tag> <item> <p> @@ -1270,21 +1284,21 @@ handle_event(_, _, State, Data) -> <p> These <em>transition actions</em> can be invoked by returning them from the - <seealso marker="#state callback"><em>state callback</em></seealso>, from - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl>, from + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> or by giving them to - <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. + <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa>. </p> <p> Actions are executed in the containing list order. </p> <p> Actions that set - <seealso marker="#type-transition_option">transition options</seealso> + <seetype marker="#transition_option">transition options</seetype> override any previous of the same type, so the last in the containing list wins. For example, the last - <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso> + <seetype marker="#event_timeout"><c>event_timeout()</c></seetype> overrides any previous <c>event_timeout()</c> in the list. </p> <taglist> @@ -1292,8 +1306,8 @@ handle_event(_, _, State, Data) -> <item> <p> Sets the - <seealso marker="#type-transition_option"><c>transition_option()</c></seealso> - <seealso marker="#type-hibernate"><c>hibernate()</c></seealso> + <seetype marker="#transition_option"><c>transition_option()</c></seetype> + <seetype marker="#hibernate"><c>hibernate()</c></seetype> for this <em>state transition</em>. </p> </item> @@ -1306,14 +1320,14 @@ handle_event(_, _, State, Data) -> <p> These <em>transition actions</em> can be invoked by returning them from the - <seealso marker="#state callback"><em>state callback</em></seealso>, from - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl>, from + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> or by giving them to - <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. + <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa>. </p> <p> These time-out actions sets time-out - <seealso marker="#type-transition_option">transition options</seealso>. + <seetype marker="#transition_option">transition options</seetype>. </p> <taglist> <tag><c>Time</c></tag> @@ -1322,7 +1336,7 @@ handle_event(_, _, State, Data) -> Short for <c>{timeout,Time,Time}</c>, that is, the time-out message is the time-out time. This form exists to make the - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> return value <c>{next_state,NextState,NewData,Time}</c> allowed like for <c>gen_fsm</c>. </p> @@ -1331,34 +1345,34 @@ handle_event(_, _, State, Data) -> <item> <p> Sets the - <seealso marker="#type-transition_option"><c>transition_option()</c></seealso> - <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso> + <seetype marker="#transition_option"><c>transition_option()</c></seetype> + <seetype marker="#event_timeout"><c>event_timeout()</c></seetype> to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c> and time-out options - <seealso marker="#type-timeout_option"><c><anno>Options</anno></c></seealso>. + <seetype marker="#timeout_option"><c><anno>Options</anno></c></seetype>. </p> </item> <tag><c>{timeout,<anno>Name</anno>}</c></tag> <item> <p> Sets the - <seealso marker="#type-transition_option"><c>transition_option()</c></seealso> - <seealso marker="#type-generic_timeout"><c>generic_timeout()</c></seealso> + <seetype marker="#transition_option"><c>transition_option()</c></seetype> + <seetype marker="#generic_timeout"><c>generic_timeout()</c></seetype> to <c><anno>Time</anno></c> for <c><anno>Name</anno></c> with <c><anno>EventContent</anno></c> and time-out options - <seealso marker="#type-timeout_option"><c><anno>Options</anno></c></seealso>. + <seetype marker="#timeout_option"><c><anno>Options</anno></c></seetype>. </p> </item> <tag><c>state_timeout</c></tag> <item> <p> Sets the - <seealso marker="#type-transition_option"><c>transition_option()</c></seealso> - <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso> + <seetype marker="#transition_option"><c>transition_option()</c></seetype> + <seetype marker="#state_timeout"><c>state_timeout()</c></seetype> to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c> and time-out options - <seealso marker="#type-timeout_option"><c><anno>Options</anno></c></seealso>. + <seetype marker="#timeout_option"><c><anno>Options</anno></c></seetype>. </p> </item> </taglist> @@ -1369,9 +1383,9 @@ handle_event(_, _, State, Data) -> <desc> <p> This is a shorter and clearer form of - <seealso marker="#type-timeout_action"> + <seetype marker="#timeout_action"> timeout_action() - </seealso> + </seetype> with <c>Time = infinity</c> which cancels a time-out. </p> </desc> @@ -1382,9 +1396,9 @@ handle_event(_, _, State, Data) -> <p> Updates a time-out with a new <c>EventContent</c>. See - <seealso marker="#type-timeout_action"> + <seetype marker="#timeout_action"> timeout_action() - </seealso> + </seetype> for how to start a time-out. </p> <p> @@ -1400,31 +1414,31 @@ handle_event(_, _, State, Data) -> <p> This <em>transition action</em> can be invoked by returning it from the - <seealso marker="#state callback"><em>state callback</em></seealso>, from - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl>, from + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> or by giving it to - <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. + <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa>. </p> <p> It does not set any - <seealso marker="#type-transition_option"> + <seetype marker="#transition_option"> <c>transition_option()</c> - </seealso> + </seetype> but instead replies to a caller waiting for a reply in - <seealso marker="#call/2"><c>call/2</c></seealso>. + <seemfa marker="#call/2"><c>call/2</c></seemfa>. <c><anno>From</anno></c> must be the term from argument - <seealso marker="#type-event_type"><c>{call,<anno>From</anno>}</c></seealso> + <seetype marker="#event_type"><c>{call,<anno>From</anno>}</c></seetype> in a call to a - <seealso marker="#state callback"><em>state callback</em></seealso>. + <seeerl marker="#state callback"><em>state callback</em></seeerl>. </p> <p> Note that using this action from - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> or - <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso> + <seemfa marker="#enter_loop/5"><c>enter_loop/5,6</c></seemfa> would be weird on the border of witchcraft since there has been no earlier call to a - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> in this server. </p> </desc> @@ -1435,16 +1449,16 @@ handle_event(_, _, State, Data) -> <p> For a succesful initialization, <c><anno>State</anno></c> is the initial - <seealso marker="#type-state"><c>state()</c></seealso> + <seetype marker="#state"><c>state()</c></seetype> and <c><anno>Data</anno></c> the initial server - <seealso marker="#type-data"><c>data()</c></seealso> + <seetype marker="#data"><c>data()</c></seetype> of the <c>gen_statem</c>. </p> <p> - The <seealso marker="#type-action"><c>Actions</c></seealso> + The <seetype marker="#action"><c>Actions</c></seetype> are executed when entering the first - <seealso marker="#type-state">state</seealso> just as for a - <seealso marker="#state callback"><em>state callback</em></seealso>, + <seetype marker="#state">state</seetype> just as for a + <seeerl marker="#state callback"><em>state callback</em></seeerl>, except that the action <c>postpone</c> is forced to <c>false</c> since there is no event to postpone. </p> @@ -1452,7 +1466,7 @@ handle_event(_, _, State, Data) -> For an unsuccesful initialization, <c>{stop,<anno>Reason</anno>}</c> or <c>ignore</c> should be used; see - <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>. + <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>. </p> </desc> </datatype> @@ -1463,7 +1477,7 @@ handle_event(_, _, State, Data) -> <c><anno>State</anno></c> is the current state and it cannot be changed since the state callback was called with a - <seealso marker="#type-state_enter"><em>state enter call</em></seealso>. + <seetype marker="#state_enter"><em>state enter call</em></seetype>. </p> <taglist> <tag><c>next_state</c></tag> @@ -1484,13 +1498,13 @@ handle_event(_, _, State, Data) -> <desc> <p> <c><anno>StateType</anno></c> is - <seealso marker="#type-state_name"><c>state_name()</c></seealso> + <seetype marker="#state_name"><c>state_name()</c></seetype> if - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> is <c>state_functions</c>, or - <seealso marker="#type-state"><c>state()</c></seealso> + <seetype marker="#state"><c>state()</c></seetype> if - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> is <c>handle_event_function</c>. </p> <taglist> @@ -1514,11 +1528,11 @@ handle_event(_, _, State, Data) -> <desc> <p> <c><anno>ActionType</anno></c> is - <seealso marker="#type-enter_action"><c>enter_action()</c></seealso> + <seetype marker="#enter_action"><c>enter_action()</c></seetype> if the state callback was called with a - <seealso marker="#type-state_enter"><em>state enter call</em></seealso> + <seetype marker="#state_enter"><em>state enter call</em></seetype> and - <seealso marker="#type-action"><c>action()</c></seealso> + <seetype marker="#action"><c>action()</c></seetype> if the state callback was called with an event. </p> <taglist> @@ -1540,9 +1554,9 @@ handle_event(_, _, State, Data) -> <item> <p> If the <c>gen_statem</c> runs with - <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>, + <seetype marker="#state_enter"><em>state enter calls</em></seetype>, the <em>state enter call</em> is repeated, see type - <seealso marker="#type-transition_option"><c>transition_option()</c></seealso>, + <seetype marker="#transition_option"><c>transition_option()</c></seetype>, other than that <c>repeat_state</c> is the same as <c>keep_state</c>. </p> @@ -1558,7 +1572,7 @@ handle_event(_, _, State, Data) -> <item> <p> Terminates the <c>gen_statem</c> by calling - <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> + <seemfa marker="#Module:terminate/3"><c>Module:terminate/3</c></seemfa> with <c>Reason</c> and <c><anno>NewData</anno></c>, if specified. </p> @@ -1568,7 +1582,7 @@ handle_event(_, _, State, Data) -> <p> Sends all <c><anno>Replies</anno></c>, then terminates the <c>gen_statem</c> by calling - <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> + <seemfa marker="#Module:terminate/3"><c>Module:terminate/3</c></seemfa> with <c>Reason</c> and <c><anno>NewData</anno></c>, if specified. </p> @@ -1580,6 +1594,16 @@ handle_event(_, _, State, Data) -> </p> </desc> </datatype> + + <datatype> + <name name="request_id"/> + <desc> + <p> + A request handle, see <seemfa marker="#send_request/2"> <c>send_request/2</c> </seemfa> + for details. + </p> + </desc> + </datatype> </datatypes> <funcs> @@ -1590,22 +1614,22 @@ handle_event(_, _, State, Data) -> <desc> <p> Makes a synchronous call to the <c>gen_statem</c> - <seealso marker="#type-server_ref"><c><anno>ServerRef</anno></c></seealso> + <seetype marker="#server_ref"><c><anno>ServerRef</anno></c></seetype> by sending a request and waiting until its reply arrives. The <c>gen_statem</c> calls the - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> with - <seealso marker="#type-event_type"><c>event_type()</c></seealso> + <seetype marker="#event_type"><c>event_type()</c></seetype> <c>{call,From}</c> and event content <c><anno>Request</anno></c>. </p> <p> A <c><anno>Reply</anno></c> is generated when a - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> returns with <c>{reply,From,<anno>Reply</anno>}</c> as one - <seealso marker="#type-action"><c>action()</c></seealso>, + <seetype marker="#action"><c>action()</c></seetype>, and that <c><anno>Reply</anno></c> becomes the return value of this function. </p> @@ -1666,14 +1690,14 @@ handle_event(_, _, State, Data) -> <desc> <p> Sends an asynchronous event to the <c>gen_statem</c> - <seealso marker="#type-server_ref"><c><anno>ServerRef</anno></c></seealso> + <seetype marker="#server_ref"><c><anno>ServerRef</anno></c></seetype> and returns <c>ok</c> immediately, ignoring if the destination node or <c>gen_statem</c> does not exist. The <c>gen_statem</c> calls the - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> with - <seealso marker="#type-event_type"><c>event_type()</c></seealso> + <seetype marker="#event_type"><c>event_type()</c></seetype> <c>cast</c> and event content <c><anno>Msg</anno></c>. </p> @@ -1681,14 +1705,45 @@ handle_event(_, _, State, Data) -> </func> <func> + <name name="check_response" arity="2" since="OTP-23"/> + <fsummary>Check if a message is a reply from a server.</fsummary> + <desc> + <p> + This function is used to check if a previously received + message, for example by <c>receive</c> or + <c>handle_info/2</c>, is a result of a request made with + <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa>. + If <c>Msg</c> is a reply to the handle <c>RequestId</c> + the result of the request is returned in <c>Reply</c>. + Otherwise returns <c>no_reply</c> and no cleanup is done, and + thus the function shall be invoked repeatedly until a reply + is returned. + </p> + <p> + The return value <c><anno>Reply</anno></c> is generated when a + <seeerl marker="#state callback"><em>state callback</em></seeerl> + returns with + <c>{reply,From,<anno>Reply</anno>}</c> as one + <seetype marker="#action"><c>action()</c></seetype>, + and that <c><anno>Reply</anno></c> becomes the return value + of this function. + </p> + <p> + The function returns an error if the <c>gen_statem</c> + dies before or during this request. + </p> + </desc> + </func> + + <func> <name name="enter_loop" arity="4" since="OTP 19.1"/> <fsummary>Enter the <c>gen_statem</c> receive loop.</fsummary> <desc> <p> The same as - <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso> + <seemfa marker="#enter_loop/6"><c>enter_loop/6</c></seemfa> with <c>Actions = []</c> except that no - <seealso marker="#type-server_name"><c>server_name()</c></seealso> + <seetype marker="#server_name"><c>server_name()</c></seetype> must have been registered. This creates an anonymous server. </p> </desc> @@ -1701,16 +1756,16 @@ handle_event(_, _, State, Data) -> <p> If <c><anno>Server_or_Actions</anno></c> is a <c>list()</c>, the same as - <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso> + <seemfa marker="#enter_loop/6"><c>enter_loop/6</c></seemfa> except that no - <seealso marker="#type-server_name"><c>server_name()</c></seealso> + <seetype marker="#server_name"><c>server_name()</c></seetype> must have been registered and <c>Actions = <anno>Server_or_Actions</anno></c>. This creates an anonymous server. </p> <p> Otherwise the same as - <seealso marker="#enter_loop/6"><c>enter_loop/6</c></seealso> + <seemfa marker="#enter_loop/6"><c>enter_loop/6</c></seemfa> with <c>Server = <anno>Server_or_Actions</anno></c> and <c>Actions = []</c>. @@ -1729,7 +1784,7 @@ handle_event(_, _, State, Data) -> a <c>gen_statem</c> server. The process <em>must</em> have been started using one of the start functions in - <seealso marker="proc_lib"><c>proc_lib</c></seealso>. + <seeerl marker="proc_lib"><c>proc_lib</c></seeerl>. The user is responsible for any initialization of the process, including registering a name for it. </p> @@ -1741,18 +1796,18 @@ handle_event(_, _, State, Data) -> <p> <c><anno>Module</anno></c>, <c><anno>Opts</anno></c> have the same meaning as when calling - <seealso marker="#start_link/3"><c>start[_link]/3,4</c></seealso>. + <seemfa marker="#start_link/3"><c>start[_link|_monitor]/3,4</c></seemfa>. </p> <p> If <c><anno>Server</anno></c> is <c>self()</c> an anonymous server is created just as when using - <seealso marker="#start_link/3"><c>start[_link]/3</c></seealso>. + <seemfa marker="#start_link/3"><c>start[_link|_monitor]/3</c></seemfa>. If <c><anno>Server</anno></c> is a - <seealso marker="#type-server_name"><c>server_name()</c></seealso> + <seetype marker="#server_name"><c>server_name()</c></seetype> a named server is created just as when using - <seealso marker="#start_link/4"><c>start[_link]/4</c></seealso>. + <seemfa marker="#start_link/4"><c>start[_link|_monitor]/4</c></seemfa>. However, the - <seealso marker="#type-server_name"><c>server_name()</c></seealso> + <seetype marker="#server_name"><c>server_name()</c></seetype> name must have been registered accordingly <em>before</em> this function is called. </p> @@ -1760,17 +1815,17 @@ handle_event(_, _, State, Data) -> <c><anno>State</anno></c>, <c><anno>Data</anno></c>, and <c><anno>Actions</anno></c> have the same meanings as in the return value of - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>. + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>. Also, the callback module does not need to export a - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> function. </p> <p> The function fails if the calling process was not started by a - <seealso marker="proc_lib"><c>proc_lib</c></seealso> + <seeerl marker="proc_lib"><c>proc_lib</c></seeerl> start function, or if it is not registered according to - <seealso marker="#type-server_name"><c>server_name()</c></seealso>. + <seetype marker="#server_name"><c>server_name()</c></seetype>. </p> </desc> </func> @@ -1783,32 +1838,74 @@ handle_event(_, _, State, Data) -> <p> This function can be used by a <c>gen_statem</c> to explicitly send a reply to a process that waits in - <seealso marker="#call/2"><c>call/2</c></seealso> + <seemfa marker="#call/2"><c>call/2</c></seemfa> when the reply cannot be defined in the return value of a - <seealso marker="#state callback"><em>state callback</em></seealso>. + <seeerl marker="#state callback"><em>state callback</em></seeerl>. </p> <p> <c><anno>From</anno></c> must be the term from argument - <seealso marker="#type-event_type"><c>{call,<anno>From</anno>}</c></seealso> + <seetype marker="#event_type"><c>{call,<anno>From</anno>}</c></seetype> to the - <seealso marker="#state callback"><em>state callback</em></seealso>. + <seeerl marker="#state callback"><em>state callback</em></seeerl>. A reply or multiple replies canalso be sent using one or several - <seealso marker="#type-reply_action"><c>reply_action()</c></seealso>s + <seetype marker="#reply_action"><c>reply_action()</c></seetype>s from a - <seealso marker="#state callback"><em>state callback</em></seealso>. + <seeerl marker="#state callback"><em>state callback</em></seeerl>. </p> <note> <p> A reply sent with this function is not visible - in <seealso marker="sys"><c>sys</c></seealso> debug output. + in <seeerl marker="sys"><c>sys</c></seeerl> debug output. </p> </note> </desc> </func> <func> + <name name="send_request" arity="2" since="OTP-23"/> + <fsummary>Send a request to a <c>gen_statem</c>.</fsummary> + <desc> + <p> + Sends a request to the <c>gen_statem</c> + <seetype marker="#server_ref"><c><anno>ServerRef</anno></c></seetype> + and returns a handle <c><anno>RequestId</anno></c>. + </p> + <p> + The return value <c><anno>RequestId</anno></c> shall later be used with + <seemfa marker="#wait_response/2"> <c>wait_response/1,2</c></seemfa> or + <seemfa marker="#check_response/2"> <c>check_response/2</c></seemfa> + to fetch the actual result of the request. + </p> + <p> + The call <c>gen_statem:wait_response(gen_statem:send_request(ServerRef,Request), Timeout)</c> + can be seen as equivalent to + <seemfa marker="#call/3"><c>gen_statem:call(Server,Request,Timeout)</c></seemfa>, + ignoring the error handling. + </p> + <p> + The <c>gen_statem</c> calls the + <seeerl marker="#state callback"><em>state callback</em></seeerl> + with + <seetype marker="#event_type"><c>event_type()</c></seetype> + <c>{call,From}</c> and event content + <c><anno>Request</anno></c>. + </p> + <p> + A <c>Reply</c> is generated when a + <seeerl marker="#state callback"><em>state callback</em></seeerl> + returns with + <c>{reply,From,Reply}</c> as one + <seetype marker="#action"><c>action()</c></seetype>, + and that <c>Reply</c> becomes the return value + of <seemfa marker="#wait_response/2"> <c>wait_response/1,2</c></seemfa> or + <seemfa marker="#check_response/2"> <c>check_response/2</c></seemfa> function. + </p> + </desc> + </func> + + <func> <name name="start" arity="3" since="OTP 19.0"/> <name name="start" arity="4" since="OTP 19.0"/> <fsummary>Create a standalone <c>gen_statem</c> process.</fsummary> @@ -1816,7 +1913,7 @@ handle_event(_, _, State, Data) -> <p> Creates a standalone <c>gen_statem</c> process according to OTP design principles (using - <seealso marker="proc_lib"><c>proc_lib</c></seealso> + <seeerl marker="proc_lib"><c>proc_lib</c></seeerl> primitives). As it does not get linked to the calling process, this start function cannot be used by a supervisor @@ -1824,7 +1921,7 @@ handle_event(_, _, State, Data) -> </p> <p> For a description of arguments and return values, see - <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>. + <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>. </p> </desc> </func> @@ -1838,7 +1935,7 @@ handle_event(_, _, State, Data) -> Creates a <c>gen_statem</c> process according to OTP design principles (using - <seealso marker="proc_lib"><c>proc_lib</c></seealso> + <seeerl marker="proc_lib"><c>proc_lib</c></seeerl> primitives) that is linked to the calling process. This is essential when the <c>gen_statem</c> must be part of @@ -1846,15 +1943,15 @@ handle_event(_, _, State, Data) -> </p> <p> The <c>gen_statem</c> process calls - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> to initialize the server. To ensure a synchronized startup procedure, <c>start_link/3,4</c> does not return until - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> has returned. </p> <p> <c><anno>ServerName</anno></c> specifies the - <seealso marker="#type-server_name"><c>server_name()</c></seealso> + <seetype marker="#server_name"><c>server_name()</c></seetype> to register for the <c>gen_statem</c>. If the <c>gen_statem</c> is started with <c>start_link/3</c>, no <c><anno>ServerName</anno></c> is provided and @@ -1864,53 +1961,53 @@ handle_event(_, _, State, Data) -> <p> <c><anno>Args</anno></c> is an arbitrary term that is passed as the argument to - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>. + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa>. </p> <list type="bulleted"> <item> <p> If option - <seealso marker="#type-start_opt"> + <seetype marker="#start_opt"> <c>{timeout,Time}</c> - </seealso> + </seetype> is present in <c><anno>Opts</anno></c>, the <c>gen_statem</c> is allowed to spend <c>Time</c> milliseconds initializing or it terminates and the start function returns - <seealso marker="#type-start_ret"><c>{error,timeout}</c></seealso>. + <seetype marker="#start_ret"><c>{error,timeout}</c></seetype>. </p> </item> <item> <p>If option - <seealso marker="#type-enter_loop_opt"> + <seetype marker="#enter_loop_opt"> <c>{hibernate_after,HibernateAfterTimeout}</c> - </seealso> + </seetype> is present, the <c>gen_statem</c> process awaits any message for <c>HibernateAfterTimeout</c> milliseconds and if no message is received, the process goes into hibernation automatically - (by calling <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>). + (by calling <seemfa marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa>). </p> </item> <item> <p> If option - <seealso marker="#type-enter_loop_opt"> + <seetype marker="#enter_loop_opt"> <c>{debug,Dbgs}</c> - </seealso> + </seetype> is present in <c><anno>Opts</anno></c>, debugging through - <seealso marker="sys"><c>sys</c></seealso> is activated. + <seeerl marker="sys"><c>sys</c></seeerl> is activated. </p> </item> <item> <p> If option - <seealso marker="#type-start_opt"> + <seetype marker="#start_opt"> <c>{spawn_opt,SpawnOpts}</c> - </seealso> + </seetype> is present in <c><anno>Opts</anno></c>, <c>SpawnOpts</c> is passed as option list to - <seealso marker="erts:erlang#spawn_opt/2"><c>erlang:spawn_opt/2</c></seealso>, + <seemfa marker="erts:erlang#spawn_opt/2"><c>erlang:spawn_opt/2</c></seemfa>, which is used to spawn the <c>gen_statem</c> process. </p> </item> @@ -1925,39 +2022,68 @@ handle_event(_, _, State, Data) -> <p> If the <c>gen_statem</c> is successfully created and initialized, this function returns - <seealso marker="#type-start_ret"><c>{ok,Pid}</c></seealso>, + <seetype marker="#start_ret"><c>{ok,Pid}</c></seetype>, where <c>Pid</c> is the <c>pid()</c> of the <c>gen_statem</c>. If a process with the specified <c><anno>ServerName</anno></c> exists already, this function returns - <seealso marker="#type-start_ret"><c>{error,{already_started,Pid}}</c></seealso>, + <seetype marker="#start_ret"><c>{error,{already_started,Pid}}</c></seetype>, where <c>Pid</c> is the <c>pid()</c> of that process. </p> <p> If <c>Module:init/1</c> fails with <c>Reason</c>, this function returns - <seealso marker="#type-start_ret"><c>{error,Reason}</c></seealso>. + <seetype marker="#start_ret"><c>{error,Reason}</c></seetype>. If <c>Module:init/1</c> returns - <seealso marker="#type-start_ret"><c>{stop,Reason}</c></seealso> + <seetype marker="#start_ret"><c>{stop,Reason}</c></seetype> or - <seealso marker="#type-start_ret"><c>ignore</c></seealso>, + <seetype marker="#start_ret"><c>ignore</c></seetype>, the process is terminated and this function returns - <seealso marker="#type-start_ret"><c>{error,Reason}</c></seealso> + <seetype marker="#start_ret"><c>{error,Reason}</c></seetype> or - <seealso marker="#type-start_ret"><c>ignore</c></seealso>, + <seetype marker="#start_ret"><c>ignore</c></seetype>, respectively. </p> </desc> </func> <func> + <name name="start_monitor" arity="3" since="OTP 23.0"/> + <name name="start_monitor" arity="4" since="OTP 23.0"/> + <fsummary>Create a standalone <c>gen_statem</c> process.</fsummary> + <desc> + <p> + Creates a standalone <c>gen_statem</c> process according to + OTP design principles (using + <seeerl marker="proc_lib"><c>proc_lib</c></seeerl> + primitives) and atomically sets up a monitor to + the newly created process. + As it does not get linked to the calling process, + this start function cannot be used by a supervisor + to start a child. + </p> + <p> + For a description of arguments and return values, see + <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>. + Note that the return value on successful start differs from + <c>start_link/3,4</c>. <c>start_monitor/3,4</c> will return + <c>{ok,{Pid,Mon}}</c> where <c>Pid</c> is the process identifier + of the process, and <c>Mon</c> is a reference to the monitor + set up to monitor the process. If the start is not successful, + the caller will be blocked until the <c>DOWN</c> message has + been received and removed from the message queue. + </p> + </desc> + </func> + + <func> <name name="stop" arity="1" since="OTP 19.0"/> <fsummary>Synchronously stop a generic server.</fsummary> <desc> <p> The same as - <seealso marker="#stop/3"><c>stop(<anno>ServerRef</anno>, normal, infinity)</c></seealso>. + <seemfa marker="#stop/3"><c>stop(<anno>ServerRef</anno>, normal, infinity)</c></seemfa>. </p> </desc> </func> @@ -1968,11 +2094,11 @@ handle_event(_, _, State, Data) -> <desc> <p> Orders the <c>gen_statem</c> - <seealso marker="#type-server_ref"><c><anno>ServerRef</anno></c></seealso> + <seetype marker="#server_ref"><c><anno>ServerRef</anno></c></seetype> to exit with the specified <c><anno>Reason</anno></c> and waits for it to terminate. The <c>gen_statem</c> calls - <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> + <seemfa marker="#Module:terminate/3"><c>Module:terminate/3</c></seemfa> before exiting. </p> <p> @@ -1980,7 +2106,7 @@ handle_event(_, _, State, Data) -> with the expected reason. Any other reason than <c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c> causes an error report to be issued through - <seealso marker="kernel:logger"><c>logger(3)</c></seealso>. + <seeerl marker="kernel:logger"><c>logger(3)</c></seeerl>. The default <c><anno>Reason</anno></c> is <c>normal</c>. </p> <p> @@ -1997,17 +2123,57 @@ handle_event(_, _, State, Data) -> </p> </desc> </func> + + <func> + <name name="wait_response" arity="1" since="OTP-23"/> + <name name="wait_response" arity="2" since="OTP-23"/> + <fsummary>Wait for a reply from a server.</fsummary> + <desc> + <p> + This function is used to wait for a reply of a request made with + <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa> + from the <c>gen_statem</c> process. This function must be called + from the same process from which + <seemfa marker="#send_request/2"><c>send_request/2</c></seemfa> + was made. + </p> + <p> + <c>Timeout</c> is an integer greater then or equal to zero + that specifies how many milliseconds to wait for an reply, or + the atom <c>infinity</c> to wait indefinitely. Defaults to + <c>infinity</c>. + If no reply is received within the specified + time, the function returns <c>timeout</c> and no cleanup is + done, and thus the function can be invoked repeatedly until a + reply is returned. + </p> + <p> + The return value <c><anno>Reply</anno></c> is generated when a + <seeerl marker="#state callback"><em>state callback</em></seeerl> + returns with + <c>{reply,From,<anno>Reply</anno>}</c> as one + <seetype marker="#action"><c>action()</c></seetype>, + and that <c><anno>Reply</anno></c> becomes the return value + of this function. + </p> + <p> + The function returns an error if the <c>gen_statem</c> + dies before or during this function call. + </p> + </desc> + </func> </funcs> - <section> - <title>Callback Functions</title> - <p> - The following functions are to be exported from a - <c>gen_statem</c> callback module. - </p> - </section> + <funcs> + <fsdescription> + <title>Callback Functions</title> + <p> + The following functions are to be exported from a + <c>gen_statem</c> callback module. + </p> + </fsdescription> <func> <name since="OTP 19.1">Module:callback_mode() -> CallbackMode</name> <fsummary> @@ -2016,49 +2182,49 @@ handle_event(_, _, State, Data) -> <type> <v> CallbackMode = - <seealso marker="#type-callback_mode">callback_mode()</seealso> | - [ <seealso marker="#type-callback_mode">callback_mode()</seealso> - | <seealso marker="#type-state_enter">state_enter()</seealso> ] + <seetype marker="#callback_mode">callback_mode()</seetype> | + [ <seetype marker="#callback_mode">callback_mode()</seetype> + | <seetype marker="#state_enter">state_enter()</seetype> ] </v> </type> <desc> <p> This function is called by a <c>gen_statem</c> when it needs to find out the - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> of the callback module. The value is cached by <c>gen_statem</c> for efficiency reasons, so this function is only called once after server start, after code change, and after changing the callback module, but before the first - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> in the current callback module's code version is called. More occasions may be added in future versions of <c>gen_statem</c>. </p> <p> Server start happens either when - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> returns or when - <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso> + <seemfa marker="#enter_loop/4"><c>enter_loop/4-6</c></seemfa> is called. Code change happens when - <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso> + <seemfa marker="#Module:code_change/4"><c>Module:code_change/4</c></seemfa> returns. A change of the callback module happens when a - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> returns any of the actions - <seealso marker="#type-action"><c>change_callback_module</c></seealso>, - <seealso marker="#type-action"><c>push_callback_module</c></seealso> or - <seealso marker="#type-action"><c>pop_callback_module</c></seealso>. + <seetype marker="#action"><c>change_callback_module</c></seetype>, + <seetype marker="#action"><c>push_callback_module</c></seetype> or + <seetype marker="#action"><c>pop_callback_module</c></seetype>. </p> <p> The <c>CallbackMode</c> is either just - <seealso marker="#type-callback_mode"><c>callback_mode()</c></seealso> + <seetype marker="#callback_mode"><c>callback_mode()</c></seetype> or a list containing - <seealso marker="#type-callback_mode"><c>callback_mode()</c></seealso> + <seetype marker="#callback_mode"><c>callback_mode()</c></seetype> and possibly the atom - <seealso marker="#type-state_enter"><c>state_enter</c></seealso>. + <seetype marker="#state_enter"><c>state_enter</c></seetype>. </p> <note> <p> @@ -2084,11 +2250,11 @@ handle_event(_, _, State, Data) -> <v>Result = {ok,NewState,NewData} | Reason</v> <v> OldState = NewState = - <seealso marker="#type-state">state()</seealso> + <seetype marker="#state">state()</seetype> </v> <v> OldData = NewData = - <seealso marker="#type-data">data()</seealso> + <seetype marker="#data">data()</seetype> </v> <v>Reason = term()</v> </type> @@ -2108,9 +2274,9 @@ handle_event(_, _, State, Data) -> update its internal state during a release upgrade/downgrade, that is, when the instruction <c>{update,Module,Change,...}</c>, where <c>Change = {advanced,Extra}</c>, is specified in the - <seealso marker="sasl:appup"><c>appup</c></seealso> + <seefile marker="sasl:appup"><c>appup</c></seefile> file. For more information, see - <seealso marker="doc/design_principles:release_handling#instr">OTP Design Principles</seealso>. + <seeguide marker="system/design_principles:release_handling#instr">OTP Design Principles</seeguide>. </p> <p> For an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and @@ -2148,20 +2314,20 @@ handle_event(_, _, State, Data) -> Also note when upgrading a <c>gen_statem</c>, this function and hence the <c>Change = {advanced,Extra}</c> parameter in the - <seealso marker="sasl:appup"><c>appup</c></seealso> file + <seefile marker="sasl:appup"><c>appup</c></seefile> file is not only needed to update the internal state or to act on the <c>Extra</c> argument. It is also needed if an upgrade or downgrade should change - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>, + <seetype marker="#callback_mode"><em>callback mode</em></seetype>, or else the <em>callback mode</em> after the code change will not be honoured, most probably causing a server crash. </p> <p> If the server changes callback module using any of the actions - <seealso marker="#type-action"><c>change_callback_module</c></seealso>, - <seealso marker="#type-action"><c>push_callback_module</c></seealso> or - <seealso marker="#type-action"><c>pop_callback_module</c></seealso>, + <seetype marker="#action"><c>change_callback_module</c></seetype>, + <seetype marker="#action"><c>push_callback_module</c></seetype> or + <seetype marker="#action"><c>pop_callback_module</c></seetype>, be aware that it is always the current callback module that will get this callback call. That the current callback module handles the current state and data update should be no surprise, @@ -2171,7 +2337,7 @@ handle_event(_, _, State, Data) -> </p> <p> In the supervisor - <seealso marker="doc/design_principles:sup_princ#child-specification">child specification</seealso> + <seeguide marker="system/design_principles:sup_princ#child-specification">child specification</seeguide> there is a list of modules which is recommended to contain only the callback module. For a <c>gen_statem</c> with multiple callback modules @@ -2200,16 +2366,17 @@ handle_event(_, _, State, Data) -> <v>Args = term()</v> <v> Result(StateType) = - <seealso marker="#type-init_result">init_result(StateType)</seealso> + <seetype marker="#init_result">init_result(StateType)</seetype> </v> </type> <desc> <marker id="Module:init-1"/> <p> Whenever a <c>gen_statem</c> is started using - <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso> + <seemfa marker="#start_link/3"><c>start_link/3,4</c></seemfa>, + <seemfa marker="#start_monitor/3"><c>start_monitor/3,4</c></seemfa>, or - <seealso marker="#start/3"><c>start/3,4</c></seealso>, + <seemfa marker="#start/3"><c>start/3,4</c></seemfa>, this function is called by the new process to initialize the implementation state and server data. </p> @@ -2220,9 +2387,9 @@ handle_event(_, _, State, Data) -> <note> <p> Note that if the <c>gen_statem</c> is started through - <seealso marker="proc_lib"><c>proc_lib</c></seealso> + <seeerl marker="proc_lib"><c>proc_lib</c></seeerl> and - <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>, + <seemfa marker="#enter_loop/4"><c>enter_loop/4-6</c></seemfa>, this callback will never be called. Since this callback is not optional it can in that case be implemented as: @@ -2245,11 +2412,11 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> <v>PDict = [{Key, Value}]</v> <v> State = - <seealso marker="#type-state">state()</seealso> + <seetype marker="#state">state()</seetype> </v> <v> Data = - <seealso marker="#type-data">data()</seealso> + <seetype marker="#data">data()</seetype> </v> <v>Key = term()</v> <v>Value = term()</v> @@ -2276,7 +2443,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> <list type="bulleted"> <item> One of - <seealso marker="sys#get_status/1"><c>sys:get_status/1,2</c></seealso> + <seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa> is invoked to get the <c>gen_statem</c> status. <c>Opt</c> is set to the atom <c>normal</c> for this case. </item> @@ -2289,7 +2456,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> This function is useful for changing the form and appearance of the <c>gen_statem</c> status for these cases. A callback module wishing to change the - <seealso marker="sys#get_status/1"><c>sys:get_status/1,2</c></seealso> + <seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa> return value and how its status appears in termination error logs exports an instance of <c>format_status/2</c>, which returns a term @@ -2300,11 +2467,11 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> of the <c>gen_statem</c>. </p> <p> - <seealso marker="#type-state"><c>State</c></seealso> + <seetype marker="#state"><c>State</c></seetype> is the internal state of the <c>gen_statem</c>. </p> <p> - <seealso marker="#type-data"><c>Data</c></seealso> + <seetype marker="#data"><c>Data</c></seetype> is the internal server data of the <c>gen_statem</c>. </p> <p> @@ -2313,7 +2480,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> of the current state and status of the <c>gen_statem</c>. There are no restrictions on the form <c>Status</c> can take, but for the - <seealso marker="sys#get_status/1"><c>sys:get_status/1,2</c></seealso> + <seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa> case (when <c>Opt</c> is <c>normal</c>), the recommended form for the <c>Status</c> value is <c>[{data, [{"State", @@ -2321,7 +2488,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> the <c>gen_statem</c> state. Following this recommendation is not required, but it makes the callback module status consistent with the rest of the - <seealso marker="sys#get_status/1"><c>sys:get_status/1,2</c></seealso> + <seemfa marker="sys#get_status/1"><c>sys:get_status/1,2</c></seemfa> return value. </p> <p> @@ -2350,56 +2517,56 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> <type> <v> EventType = - <seealso marker="#type-event_type">event_type()</seealso> + <seetype marker="#event_type">event_type()</seetype> </v> <v>EventContent = term()</v> <v> State = - <seealso marker="#type-state">state()</seealso> + <seetype marker="#state">state()</seetype> </v> <v> Data = NewData = - <seealso marker="#type-data">data()</seealso> + <seetype marker="#data">data()</seetype> </v> <v> StateEnterResult(StateName) = - <seealso marker="#type-state_enter_result">state_enter_result(StateName)</seealso> + <seetype marker="#state_enter_result">state_enter_result(StateName)</seetype> </v> <v> StateFunctionResult = - <seealso marker="#type-event_handler_result">event_handler_result</seealso>(<seealso marker="#type-state_name">state_name()</seealso>) + <seetype marker="#event_handler_result">event_handler_result</seetype>(<seetype marker="#state_name">state_name()</seetype>) </v> <v> StateEnterResult(State) = - <seealso marker="#type-state_enter_result">state_enter_result(State)</seealso> + <seetype marker="#state_enter_result">state_enter_result(State)</seetype> </v> <v> HandleEventResult = - <seealso marker="#type-event_handler_result">event_handler_result</seealso>(<seealso marker="#type-state">state()</seealso>) + <seetype marker="#event_handler_result">event_handler_result</seetype>(<seetype marker="#state">state()</seetype>) </v> </type> <desc> <p> Whenever a <c>gen_statem</c> receives an event from - <seealso marker="#call/2"><c>call/2</c></seealso>, - <seealso marker="#cast/2"><c>cast/2</c></seealso>, or + <seemfa marker="#call/2"><c>call/2</c></seemfa>, + <seemfa marker="#cast/2"><c>cast/2</c></seemfa>, or as a normal process message, one of these functions is called. If - <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> + <seetype marker="#callback_mode"><em>callback mode</em></seetype> is <c>state_functions</c>, <c>Module:StateName/3</c> is called, and if it is <c>handle_event_function</c>, <c>Module:handle_event/4</c> is called. </p> <p> If <c>EventType</c> is - <seealso marker="#type-event_type"><c>{call,From}</c></seealso>, + <seetype marker="#event_type"><c>{call,From}</c></seetype>, the caller waits for a reply. The reply can be sent from this or from any other - <seealso marker="#state callback"><em>state callback</em></seealso> + <seeerl marker="#state callback"><em>state callback</em></seeerl> by returning with <c>{reply,From,Reply}</c> in - <seealso marker="#type-action"><c>Actions</c></seealso>, in - <seealso marker="#type-reply_action"><c>Replies</c></seealso>, + <seetype marker="#action"><c>Actions</c></seetype>, in + <seetype marker="#reply_action"><c>Replies</c></seetype>, or by calling - <seealso marker="#reply/2"><c>reply(From, Reply)</c></seealso>. + <seemfa marker="#reply/2"><c>reply(From, Reply)</c></seemfa>. </p> <p> If this function returns with a next state that @@ -2415,20 +2582,20 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> <p> For options that can be set and actions that can be done by <c>gen_statem</c> after returning from this function, - see <seealso marker="#type-action"><c>action()</c></seealso>. + see <seetype marker="#action"><c>action()</c></seetype>. </p> <p> When the <c>gen_statem</c> runs with - <seealso marker="#type-state_enter"><em>state enter calls</em></seealso>, + <seetype marker="#state_enter"><em>state enter calls</em></seetype>, these functions are also called with arguments <c>(enter, OldState, ...)</c> during every <em>state change</em>. In this case there are some restrictions on the - <seealso marker="#type-enter_action">actions</seealso> + <seetype marker="#enter_action">actions</seetype> that may be returned: - <seealso marker="#type-postpone"><c>postpone()</c></seealso> + <seetype marker="#postpone"><c>postpone()</c></seetype> is not allowed since a <em>state enter call</em> is not an event so there is no event to postpone, and - <seealso marker="#type-action"><c>{next_event,_,_}</c></seealso> + <seetype marker="#action"><c>{next_event,_,_}</c></seetype> is not allowed since using <em>state enter calls</em> should not affect how events are consumed and produced. You may also not change states from this call. @@ -2451,7 +2618,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> </p> <p> Note the fact that you can use - <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso> + <seemfa marker="erts:erlang#throw/1"><c>throw</c></seemfa> to return the result, which can be useful. For example to bail out with <c>throw(keep_state_and_data)</c> from deep within complex code that cannot @@ -2466,8 +2633,8 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> <fsummary>Clean up before termination.</fsummary> <type> <v>Reason = normal | shutdown | {shutdown,term()} | term()</v> - <v>State = <seealso marker="#type-state">state()</seealso></v> - <v>Data = <seealso marker="#type-data">data()</seealso></v> + <v>State = <seetype marker="#state">state()</seetype></v> + <v>Data = <seetype marker="#data">data()</seetype></v> <v>Ignored = term()</v> </type> <desc> @@ -2479,13 +2646,13 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> <p> This function is called by a <c>gen_statem</c> when it is about to terminate. It is to be the opposite of - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + <seemfa marker="#Module:init/1"><c>Module:init/1</c></seemfa> and do any necessary cleaning up. When it returns, the <c>gen_statem</c> terminates with <c>Reason</c>. The return value is ignored.</p> <p> <c>Reason</c> is a term denoting the stop reason and - <seealso marker="#type-state"><c>State</c></seealso> + <seetype marker="#state"><c>State</c></seetype> is the internal state of the <c>gen_statem</c>. </p> <p> @@ -2493,7 +2660,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> is terminating. If it is because another callback function has returned, a stop tuple <c>{stop,Reason}</c> in - <seealso marker="#type-action"><c>Actions</c></seealso>, + <seetype marker="#action"><c>Actions</c></seetype>, <c>Reason</c> has the value specified in that tuple. If it is because of a failure, <c>Reason</c> is the error reason. </p> @@ -2532,7 +2699,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> <c>shutdown</c>, or <c>{shutdown,Term}</c>, the <c>gen_statem</c> is assumed to terminate because of an error and an error report is issued using - <seealso marker="kernel:logger"><c>logger(3)</c></seealso>. + <seeerl marker="kernel:logger"><c>logger(3)</c></seeerl>. </p> </desc> </func> @@ -2541,12 +2708,12 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> <section> <title>See Also</title> <p> - <seealso marker="gen_event"><c>gen_event(3)</c></seealso>, - <seealso marker="gen_fsm"><c>gen_fsm(3)</c></seealso>, - <seealso marker="gen_server"><c>gen_server(3)</c></seealso>, - <seealso marker="proc_lib"><c>proc_lib(3)</c></seealso>, - <seealso marker="supervisor"><c>supervisor(3)</c></seealso>, - <seealso marker="sys"><c>sys(3)</c></seealso>. + <seeerl marker="gen_event"><c>gen_event(3)</c></seeerl>, + <seeerl marker="gen_fsm"><c>gen_fsm(3)</c></seeerl>, + <seeerl marker="gen_server"><c>gen_server(3)</c></seeerl>, + <seeerl marker="proc_lib"><c>proc_lib(3)</c></seeerl>, + <seeerl marker="supervisor"><c>supervisor(3)</c></seeerl>, + <seeerl marker="sys"><c>sys(3)</c></seeerl>. </p> </section> </erlref> diff --git a/lib/stdlib/doc/src/io.xml b/lib/stdlib/doc/src/io.xml index d69e808586..9fd87d9cf1 100644 --- a/lib/stdlib/doc/src/io.xml +++ b/lib/stdlib/doc/src/io.xml @@ -39,29 +39,29 @@ parameter <c>IoDevice</c>. If included, it must be the pid of a process that handles the I/O protocols. Normally, it is the <c>IoDevice</c> returned by - <seealso marker="kernel:file#open/2"><c>file:open/2</c></seealso>.</p> + <seemfa marker="kernel:file#open/2"><c>file:open/2</c></seemfa>.</p> <p>For a description of the I/O protocols, see section - <seealso marker="io_protocol">The Erlang I/O Protocol</seealso> + <seeguide marker="io_protocol">The Erlang I/O Protocol</seeguide> in the User's Guide.</p> <warning> <p>As from Erlang/OTP R13A, data supplied to function - <seealso marker="#put_chars/2"><c>put_chars/2</c></seealso> - is to be in the <seealso marker="unicode#type-chardata"> - <c>unicode:chardata()</c></seealso> format. This means that programs + <seemfa marker="#put_chars/2"><c>put_chars/2</c></seemfa> + is to be in the <seetype marker="unicode#chardata"> + <c>unicode:chardata()</c></seetype> format. This means that programs supplying binaries to this function must convert them to UTF-8 before trying to output the data on an I/O device.</p> <p>If an I/O device is set in binary mode, functions - <seealso marker="#get_chars/2"><c>get_chars/2,3</c></seealso> and - <seealso marker="#get_line/1"><c>get_line/1,2</c></seealso> + <seemfa marker="#get_chars/2"><c>get_chars/2,3</c></seemfa> and + <seemfa marker="#get_line/1"><c>get_line/1,2</c></seemfa> can return binaries instead of lists. The binaries are, as from Erlang/OTP R13A, encoded in UTF-8.</p> <p>To work with binaries in ISO Latin-1 encoding, use the - <seealso marker="kernel:file"><c>file</c></seealso> module instead.</p> + <seeerl marker="kernel:file"><c>file</c></seeerl> module instead.</p> <p>For conversion functions between character encodings, see the - <seealso marker="stdlib:unicode"><c>unicode</c></seealso> module.</p> + <seeerl marker="stdlib:unicode"><c>unicode</c></seeerl> module.</p> </warning> </description> @@ -71,7 +71,7 @@ <desc> <p>An I/O device, either <c>standard_io</c>, <c>standard_error</c>, a registered name, or a pid handling I/O protocols (returned from - <seealso marker="kernel:file#open/2"><c>file:open/2</c></seealso>). + <seemfa marker="kernel:file#open/2"><c>file:open/2</c></seemfa>). </p> </desc> </datatype> @@ -317,8 +317,8 @@ ok</pre> It defaults to 80. The precision specifies the initial indentation of the term. It defaults to the number of characters printed on this line in the <em>same</em> call to - <seealso marker="#write/1"><c>write/1</c></seealso> or - <seealso marker="#format/1"><c>format/1,2,3</c></seealso>. + <seemfa marker="#write/1"><c>write/1</c></seemfa> or + <seemfa marker="#format/1"><c>format/1,2,3</c></seemfa>. For example, using <c>T</c> above:</p> <pre> 4> <input>io:fwrite("Here T = ~62p~n", [T]).</input> @@ -368,9 +368,9 @@ ok ok</pre> <p>By default, Erlang only detects lists of characters in the Latin-1 range as strings, but the <c>+pc unicode</c> - flag can be used to change this (see <seealso + flag can be used to change this (see <seemfa marker="#printable_range/0"> - <c>printable_range/0</c></seealso> for details). For example:</p> + <c>printable_range/0</c></seemfa> for details). For example:</p> <pre> 10> <input>io:fwrite("~p~n",[[214]]).</input> "Ö" @@ -804,8 +804,8 @@ enter><input>:</input> <input>alan</input> <input>:</input> <input>joe</in <c><anno>Prompt</anno></c>. Starts reading at location <c><anno>StartLocation</anno></c> (<c>1</c>). Argument <c><anno>Options</anno></c> is passed on as argument - <c>Options</c> of function <seealso marker="erl_scan#tokens/4"> - <c>erl_scan:tokens/4</c></seealso>. The data is tokenized and parsed + <c>Options</c> of function <seemfa marker="erl_scan#tokens/4"> + <c>erl_scan:tokens/4</c></seemfa>. The data is tokenized and parsed as if it was a sequence of Erlang expressions until a final dot (<c>.</c>) is reached.</p> <p>The function returns:</p> @@ -856,8 +856,8 @@ enter><input>abc("hey".</input> prompting it with <c><anno>Prompt</anno></c>. Starts reading at location <c><anno>StartLocation</anno></c> (<c>1</c>). Argument <c><anno>Options</anno></c> is passed on as argument - <c>Options</c> of function <seealso marker="erl_scan#tokens/4"> - <c>erl_scan:tokens/4</c></seealso>. The data is tokenized and parsed + <c>Options</c> of function <seemfa marker="erl_scan#tokens/4"> + <c>erl_scan:tokens/4</c></seemfa>. The data is tokenized and parsed as if it was an Erlang form (one of the valid Erlang expressions in an Erlang source file) until a final dot (<c>.</c>) is reached.</p> <p>The function returns:</p> @@ -905,15 +905,15 @@ enter><input>abc("hey".</input> <p>By default, Erlang is started so that only the <c>latin1</c> range of characters indicate that a list of integers is a string.</p> <p>The simplest way to use the setting is to call - <seealso marker="io_lib#printable_list/1"> - <c>io_lib:printable_list/1</c></seealso>, which uses the return + <seemfa marker="io_lib#printable_list/1"> + <c>io_lib:printable_list/1</c></seemfa>, which uses the return value of this function to decide if a list is a string of printable characters.</p> <note> <p>In a future release, this function may return more values and ranges. To avoid compatibility problems, it is recommended to use - function <seealso marker="io_lib#printable_list/1"> - <c>io_lib:printable_list/1</c></seealso>.</p></note> + function <seemfa marker="io_lib#printable_list/1"> + <c>io_lib:printable_list/1</c></seemfa>.</p></note> </desc> </func> @@ -970,8 +970,8 @@ enter><input>abc("hey".</input> with <c><anno>Prompt</anno></c>. Reading starts at location <c><anno>StartLocation</anno></c>. Argument <c><anno>Options</anno></c> is passed on as argument <c>Options</c> - of function <seealso marker="erl_scan#tokens/4"> - <c>erl_scan:tokens/4</c></seealso>.</p> + of function <seemfa marker="erl_scan#tokens/4"> + <c>erl_scan:tokens/4</c></seemfa>.</p> <p>The function returns:</p> <taglist> <tag><c>{ok, Term, <anno>EndLocation</anno>}</c></tag> @@ -1020,8 +1020,8 @@ enter><input>abc("hey".</input> prompting it with <c>Prompt</c>. Reading starts at location <c>StartLocation</c> (<c>1</c>). Argument <c><anno>Options</anno></c> is passed on as argument <c>Options</c> of function - <seealso marker="erl_scan#tokens/4"> - <c>erl_scan:tokens/4</c></seealso>. The data is tokenized as if it + <seemfa marker="erl_scan#tokens/4"> + <c>erl_scan:tokens/4</c></seemfa>. 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.</p> <p>The function returns:</p> @@ -1071,14 +1071,14 @@ enter><input>1.0er.</input> prompting it with <c><anno>Prompt</anno></c>. Starts reading at location <c><anno>StartLocation</anno></c> (<c>1</c>). Argument <c><anno>Options</anno></c> is passed on as argument - <c>Options</c> of function <seealso marker="erl_scan#tokens/4"> - <c>erl_scan:tokens/4</c></seealso>. The data is tokenized as if it + <c>Options</c> of function <seemfa marker="erl_scan#tokens/4"> + <c>erl_scan:tokens/4</c></seemfa>. The data is tokenized as if it was an Erlang form (one of the valid Erlang expressions in an Erlang source file) until a final dot (<c>.</c>) is reached. This last token is also returned.</p> <p>The return values are the same as for - <seealso marker="#scan_erl_exprs/1"> - <c>scan_erl_exprs/1,2,3,4</c></seealso>.</p> + <seemfa marker="#scan_erl_exprs/1"> + <c>scan_erl_exprs/1,2,3,4</c></seemfa>.</p> </desc> </func> @@ -1092,7 +1092,7 @@ enter><input>1.0er.</input> <p>Possible options and values vary depending on the I/O device. For a list of supported options and their current values on a specific I/O device, use function - <seealso marker="#getopts/1"><c>getopts/1</c></seealso>.</p> + <seemfa marker="#getopts/1"><c>getopts/1</c></seemfa>.</p> <p>The options and values supported by the OTP I/O devices are as follows:</p> <taglist> @@ -1102,10 +1102,10 @@ enter><input>1.0er.</input> 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 (for details, see section - <seealso marker="io_protocol">The Erlang I/O Protocol</seealso>) + <seeguide marker="io_protocol">The Erlang I/O Protocol</seeguide>) in the User's Guide). The immediate effect is that - <seealso marker="#get_chars/2"><c>get_chars/2,3</c></seealso> and - <seealso marker="#get_line/1"><c>get_line/1,2</c></seealso> + <seemfa marker="#get_chars/2"><c>get_chars/2,3</c></seemfa> and + <seemfa marker="#get_line/1"><c>get_line/1,2</c></seemfa> return UTF-8 binaries instead of lists of characters for the affected I/O device.</p> <p>By default, all I/O devices in OTP are set in <c>list</c> mode. @@ -1127,7 +1127,7 @@ enter><input>1.0er.</input> like the Erlang shell. This function is called when the user presses the <em>Tab</em> key. The expansion is active when calling line-reading functions, such as - <seealso marker="#get_line/1"><c>get_line/1,2</c></seealso>.</p> + <seemfa marker="#get_line/1"><c>get_line/1,2</c></seemfa>.</p> <p>The function is called with the current line, up to the cursor, as a reversed string. It is to return a three-tuple: <c>{yes|no, string(), [string(), ...]}</c>. The @@ -1190,8 +1190,8 @@ fun("") -> {yes, "quit", []}; <c>{encoding, unicode}</c> on files.</p> <p>The extended encodings are only supported on disk files (opened by function - <seealso marker="kernel:file#open/2"> - <c>file:open/2</c></seealso>).</p> + <seemfa marker="kernel:file#open/2"> + <c>file:open/2</c></seemfa>).</p> </item> </taglist> </desc> diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index 0e743867ba..3b7aea529e 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -33,11 +33,11 @@ <description> <p>This module contains functions for converting to and from strings (lists of characters). They are used for implementing the - functions in the <seealso marker="io"><c>io</c></seealso> module. + functions in the <seeerl marker="io"><c>io</c></seeerl> module. There is no guarantee that the character lists returned from some of the functions are flat, they can be deep lists. Function - <seealso marker="lists#flatten/1"><c>lists:flatten/1</c></seealso> + <seemfa marker="lists#flatten/1"><c>lists:flatten/1</c></seemfa> can be used for flattening deep lists.</p> </description> @@ -48,7 +48,7 @@ <datatype> <name name="continuation"/> <desc><p>A continuation as returned by - <seealso marker="#fread/3"><c>fread/3</c></seealso>.</p> + <seemfa marker="#fread/3"><c>fread/3</c></seemfa>.</p> </desc> </datatype> <datatype> @@ -103,7 +103,7 @@ <fsummary>Build the output text for a preparsed format list.</fsummary> <desc> <p>For details, see - <seealso marker="#scan_format/2"><c>scan_format/2</c></seealso>.</p> + <seemfa marker="#scan_format/2"><c>scan_format/2</c></seemfa>.</p> </desc> </func> @@ -143,7 +143,7 @@ <p>Returns a character list that represents <c><anno>Data</anno></c> formatted in accordance with <c><anno>Format</anno></c>. For a detailed description of the available formatting options, see - <seealso marker="io#fwrite/1"><c>io:fwrite/1,2,3</c></seealso>. + <seemfa marker="io#fwrite/1"><c>io:fwrite/1,2,3</c></seemfa>. If the format string or argument list contains an error, a fault is generated.</p> <p>If and only if the Unicode translation modifier is used in the @@ -163,8 +163,8 @@ <p>Returns a character list that represents <c><anno>Data</anno></c> formatted in accordance with <c><anno>Format</anno></c> in the same way as - <seealso marker="#fwrite/2"><c>fwrite/2</c></seealso> and - <seealso marker="#format/2"><c>format/2</c></seealso>, + <seemfa marker="#fwrite/2"><c>fwrite/2</c></seemfa> and + <seemfa marker="#format/2"><c>format/2</c></seemfa>, but takes an extra argument, a list of options.</p> <p>Valid option:</p> <taglist> @@ -187,7 +187,7 @@ <p>Tries to read <c><anno>String</anno></c> in accordance with the control sequences in <c><anno>Format</anno></c>. For a detailed description of the available formatting options, see - <seealso marker="io#fread/3"><c>io:fread/3</c></seealso>. It is + <seemfa marker="io#fread/3"><c>io:fread/3</c></seemfa>. It is assumed that <c><anno>String</anno></c> contains whole lines.</p> <p>The function returns:</p> <taglist> @@ -331,9 +331,9 @@ printable characters, otherwise <c>false</c>.</p> <p>What is a printable character in this case is determined by startup flag <c>+pc</c> to the Erlang VM; see - <seealso marker="io#printable_range/0"> - <c>io:printable_range/0</c></seealso> and - <seealso marker="erts:erl"><c>erl(1)</c></seealso>.</p> + <seemfa marker="io#printable_range/0"> + <c>io:printable_range/0</c></seemfa> and + <seecom marker="erts:erl"><c>erl(1)</c></seecom>.</p> </desc> </func> @@ -355,12 +355,12 @@ corresponding tuples. This list can be passed to:</p> <list type="bulleted"> <item> - <p><seealso marker="#build_text/1"><c>build_text/1</c></seealso> + <p><seemfa marker="#build_text/1"><c>build_text/1</c></seemfa> to have the same effect as <c>format(Format, Args)</c></p> </item> <item> - <p><seealso marker="#unscan_format/1"> - <c>unscan_format/1</c></seealso> to get the corresponding pair + <p><seemfa marker="#unscan_format/1"> + <c>unscan_format/1</c></seemfa> to get the corresponding pair of <c>Format</c> and <c>Args</c> (with every <c>*</c> and corresponding argument expanded to numeric values)</p> </item> @@ -378,7 +378,7 @@ and a list of arguments.</fsummary> <desc> <p>For details, see - <seealso marker="#scan_format/2"><c>scan_format/2</c></seealso>.</p> + <seemfa marker="#scan_format/2"><c>scan_format/2</c></seemfa>.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/io_protocol.xml b/lib/stdlib/doc/src/io_protocol.xml index 84b5f62c7f..c2292d7d49 100644 --- a/lib/stdlib/doc/src/io_protocol.xml +++ b/lib/stdlib/doc/src/io_protocol.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1999</year> - <year>2016</year> + <year>2019</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -86,7 +86,7 @@ <item> <p><c>ReplyAs</c> can be any datum and is returned in the corresponding <c>io_reply</c>. The - <seealso marker="stdlib:io"><c>io</c></seealso> module monitors the + <seeerl marker="stdlib:io"><c>io</c></seeerl> module monitors the the I/O server and uses the monitor reference as the <c>ReplyAs</c> datum. A more complicated client can have many outstanding I/O requests to the same I/O server and can use different references (or @@ -142,7 +142,7 @@ <item> <p><c>Module</c>, <c>Function</c>, and <c>Args</c> denote a function that is called to produce the data (like - <seealso marker="stdlib:io_lib#format/2"><c>io_lib:format/2</c></seealso>). + <seemfa marker="stdlib:io_lib#format/2"><c>io_lib:format/2</c></seemfa>). </p> <p><c>Args</c> is a list of arguments to the function. The function is to produce data in the specified <c>Encoding</c>. The I/O server is @@ -164,20 +164,10 @@ ok <list type="bulleted"> <item><c>Error</c> describes the error to the client, which can do whatever it wants with it. The - <seealso marker="stdlib:io"><c>io</c></seealso> module typically + <seeerl marker="stdlib:io"><c>io</c></seeerl> module typically returns it "as is".</item> </list> - <p>For backward compatibility, the following <c>Request</c>s are also to be - handled by an I/O server (they are not to be present after - Erlang/OTP R15B):</p> - - <pre> -{put_chars, Characters} -{put_chars, Module, Function, Args}</pre> - - <p>These are to behave as <c>{put_chars, latin1, Characters}</c> and - <c>{put_chars, latin1, Module, Function, Args}</c>, respectively.</p> </section> <section> @@ -327,24 +317,11 @@ eof <item> <p><c>Error</c> describes the error to the client, which can do whatever it wants with it. The - <seealso marker="stdlib:io"><c>io</c></seealso> module typically + <seeerl marker="stdlib:io"><c>io</c></seeerl> module typically returns it as is.</p> </item> </list> - <p>For backward compatibility, the following <c>Request</c>s are also to be - handled by an I/O server (they are not to be present after - Erlang/OTP R15B):</p> - - <pre> -{get_until, Prompt, Module, Function, ExtraArgs} -{get_chars, Prompt, N} -{get_line, Prompt}</pre> - - <p>These are to 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> @@ -363,14 +340,14 @@ eof <p>Notice that 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 - <seealso marker="stdlib:io#fread/2"><c>io:fread/2,3</c></seealso> + <seemfa marker="stdlib:io#fread/2"><c>io:fread/2,3</c></seemfa> request is sent to an I/O server). The client must be prepared for data received as answers to those requests to be in various forms. However, the I/O server is to convert the results to binaries whenever possible (that is, when the function supplied to <c>get_until</c> returns a list). This is done in the example in section - <seealso marker="#example_io_server">An Annotated and Working Example I/O Server</seealso>. + <seeguide marker="#example_io_server">An Annotated and Working Example I/O Server</seeguide>. </p> <p>An I/O server in binary mode affects the data sent to the client, so that @@ -382,7 +359,7 @@ eof <list type="bulleted"> <item><c>Opts</c> is a list of options in the format recognized by the - <seealso marker="stdlib:proplists"><c>proplists</c></seealso> module + <seeerl marker="stdlib:proplists"><c>proplists</c></seeerl> module (and by the I/O server).</item> </list> @@ -554,7 +531,7 @@ loop(State) -> end.</code> <p>The main loop receives messages from the client (which can use the - the <seealso marker="stdlib:io"><c>io</c></seealso> module to send + the <seeerl marker="stdlib:io"><c>io</c></seeerl> module to send requests). For each request, the function <c>request/2</c> is called and a reply is eventually sent using function <c>reply/3</c>.</p> @@ -592,7 +569,7 @@ request({put_chars, Encoding, Module, Function, Args}, State) -> <p>The <c>Encoding</c> says 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 function - <seealso marker="stdlib:unicode#characters_to_list/2"><c>unicode:characters_to_list/2</c></seealso>. + <seemfa marker="stdlib:unicode#characters_to_list/2"><c>unicode:characters_to_list/2</c></seemfa>. The conversion function conveniently accepts the encoding types <c>unicode</c> and <c>latin1</c>, so we can use <c>Encoding</c> directly.</p> @@ -637,24 +614,6 @@ request({requests, Reqs}, State) -> function applying the requests in the list one after another, returning the last result.</p> - <p>We need to handle backward compatibility and the - <seealso marker="kernel:file"><c>file</c></seealso> module (which - uses the old requests until backward compatibility with pre-R13 nodes is - no longer needed). Notice that the I/O server does not work with a simple - <c>file:write/2</c> if these are not added:</p> - - <code> -request({put_chars,Chars}, State) -> - request({put_chars,latin1,Chars}, State); -request({put_chars,M,F,As}, State) -> - request({put_chars,latin1,M,F,As}, State); -request({get_chars,Prompt,N}, State) -> - request({get_chars,latin1,Prompt,N}, State); -request({get_line,Prompt}, State) -> - request({get_line,latin1,Prompt}, State); -request({get_until, Prompt,M,F,As}, State) -> - request({get_until,latin1,Prompt,M,F,As}, State);</code> - <p><c>{error, request}</c> must be returned if the request is not recognized:</p> @@ -910,8 +869,8 @@ apply_update(Table, {Row, Col, List}) -> <p>This concludes the example. It is fully runnable and you can read or write to the I/O server by using, for example, the - <seealso marker="stdlib:io"><c>io</c></seealso> module or even the - <seealso marker="kernel:file"><c>file</c></seealso> module. It is + <seeerl marker="stdlib:io"><c>io</c></seeerl> module or even the + <seeerl marker="kernel:file"><c>file</c></seeerl> 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/lists.xml b/lib/stdlib/doc/src/lists.xml index 2755fb3dce..9261ade998 100644 --- a/lib/stdlib/doc/src/lists.xml +++ b/lib/stdlib/doc/src/lists.xml @@ -281,7 +281,7 @@ flatmap(Fun, List1) -> <name name="foldr" arity="3" since=""/> <fsummary>Fold a function over a list.</fsummary> <desc> - <p>Like <seealso marker="#foldl/3"><c>foldl/3</c></seealso>, but the + <p>Like <seemfa marker="#foldl/3"><c>foldl/3</c></seemfa>, but the list is traversed from right to left.</p> <p><em>Example:</em></p> <pre> @@ -418,7 +418,7 @@ flatmap(Fun, List1) -> otherwise <c>false</c>.</p> <note> <p>This function is retained for backward compatibility. Function - <seealso marker="#keyfind/3"><c>keyfind/3</c></seealso> + <seemfa marker="#keyfind/3"><c>keyfind/3</c></seemfa> is usually more convenient.</p> </note> </desc> @@ -492,8 +492,8 @@ flatmap(Fun, List1) -> <fsummary>Map and fold in one pass.</fsummary> <desc> <p>Combines the operations of - <seealso marker="#map/2"><c>map/2</c></seealso> and - <seealso marker="#foldl/3"><c>foldl/3</c></seealso> into one pass.</p> + <seemfa marker="#map/2"><c>map/2</c></seemfa> and + <seemfa marker="#foldl/3"><c>foldl/3</c></seemfa> into one pass.</p> <p><em>Example:</em></p> <p>Summing the elements in a list and double them at the same time:</p> <pre> @@ -508,8 +508,8 @@ flatmap(Fun, List1) -> <fsummary>Map and fold in one pass.</fsummary> <desc> <p>Combines the operations of - <seealso marker="#map/2"><c>map/2</c></seealso> and - <seealso marker="#foldr/3"><c>foldr/3</c></seealso> into one pass.</p> + <seemfa marker="#map/2"><c>map/2</c></seemfa> and + <seemfa marker="#foldr/3"><c>foldr/3</c></seemfa> into one pass.</p> </desc> </func> @@ -564,8 +564,8 @@ flatmap(Fun, List1) -> <desc> <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> and <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and - <c><anno>List2</anno></c> must be sorted according to the <seealso - marker="#ordering_function">ordering function</seealso> + <c><anno>List2</anno></c> must be sorted according to the <seeerl + marker="#ordering_function">ordering function</seeerl> <c><anno>Fun</anno></c> before evaluating this function. <c><anno>Fun</anno>(<anno>A</anno>, <anno>B</anno>)</c> is to return <c>true</c> if <c><anno>A</anno></c> compares less @@ -653,7 +653,7 @@ c</pre> > <input>lists:partition(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).</input> {[a,b,c,d,e],[1,2,3,4]}</pre> <p>For a different way to partition a list, see - <seealso marker="#splitwith/2"><c>splitwith/2</c></seealso>.</p> + <seemfa marker="#splitwith/2"><c>splitwith/2</c></seemfa>.</p> </desc> </func> @@ -761,8 +761,8 @@ length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr</code> <fsummary>Sort a list.</fsummary> <desc> <p>Returns a list containing the sorted elements of - <c><anno>List1</anno></c>, according to the <seealso - marker="#ordering_function">ordering function</seealso> + <c><anno>List1</anno></c>, according to the <seeerl + marker="#ordering_function">ordering function</seeerl> <c><anno>Fun</anno></c>. <c><anno>Fun</anno>(<anno>A</anno>, <anno>B</anno>)</c> is to return <c>true</c> if <c><anno>A</anno></c> compares less than or equal to <c><anno>B</anno></c> in the @@ -799,7 +799,7 @@ splitwith(Pred, List) -> > <input>lists:splitwith(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).</input> {[a,b],[1,c,d,2,3,4,e]}</pre> <p>For a different way to partition a list, see - <seealso marker="#partition/2"><c>partition/2</c></seealso>.</p> + <seemfa marker="#partition/2"><c>partition/2</c></seemfa>.</p> </desc> </func> @@ -946,8 +946,8 @@ splitwith(Pred, List) -> <desc> <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> and <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and - <c><anno>List2</anno></c> must be sorted according to the <seealso - marker="#ordering_function">ordering function</seealso> + <c><anno>List2</anno></c> must be sorted according to the <seeerl + marker="#ordering_function">ordering function</seeerl> <c>Fun</c> and contain no duplicates before evaluating this function. <c><anno>Fun</anno>(<anno>A</anno>, <anno>B</anno>)</c> is to return <c>true</c> if <c><anno>A</anno></c> compares less than or equal to @@ -1009,8 +1009,8 @@ splitwith(Pred, List) -> <desc> <p>Returns a list containing the sorted elements of <c><anno>List1</anno></c> where all except the first element of the - elements comparing equal according to the <seealso - marker="#ordering_function">ordering function</seealso> + elements comparing equal according to the <seeerl + marker="#ordering_function">ordering function</seeerl> <c><anno>Fun</anno></c> have been deleted. <c><anno>Fun</anno>(A, B)</c> is to return <c>true</c> if <c>A</c> compares less than or equal to diff --git a/lib/stdlib/doc/src/log_mf_h.xml b/lib/stdlib/doc/src/log_mf_h.xml index b7c19bbdec..61b871227c 100644 --- a/lib/stdlib/doc/src/log_mf_h.xml +++ b/lib/stdlib/doc/src/log_mf_h.xml @@ -41,7 +41,7 @@ in any <c>gen_event</c> process. It logs onto disk all events that are sent to an event manager. Each event is written as a binary, which makes the logging very fast. However, a tool such as the Report Browser - (<seealso marker="sasl:rb"><c>rb(3)</c></seealso>) must be used to read + (<seeerl marker="sasl:rb"><c>rb(3)</c></seeerl>) must be used to read the files. The events are written to multiple files. When all files have been used, the first one is reused and overwritten. The directory location, the number of files, and the size of each file are configurable. @@ -52,8 +52,8 @@ <datatypes> <datatype> <name name="args"/> - <desc><p>Term to be sent to <seealso marker="gen_event#add_handler/3"> - <c>gen_event:add_handler/3</c></seealso>.</p> + <desc><p>Term to be sent to <seemfa marker="gen_event#add_handler/3"> + <c>gen_event:add_handler/3</c></seemfa>.</p> </desc> </datatype> </datatypes> @@ -80,8 +80,8 @@ <section> <title>See Also</title> - <p><seealso marker="gen_event"><c>gen_event(3)</c></seealso>, - <seealso marker="sasl:rb"><c>rb(3)</c></seealso></p> + <p><seeerl marker="gen_event"><c>gen_event(3)</c></seeerl>, + <seeerl marker="sasl:rb"><c>rb(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml index 8e88882b56..c445149f3b 100644 --- a/lib/stdlib/doc/src/maps.xml +++ b/lib/stdlib/doc/src/maps.xml @@ -39,11 +39,11 @@ <desc> <p>An iterator representing the associations in a map with keys of type <c><anno>Key</anno></c> and values of type <c><anno>Value</anno></c>.</p> - <p>Created using <seealso marker="#iterator-1"><c>maps:iterator/1</c></seealso>.</p> - <p>Consumed by <seealso marker="#next-1"><c>maps:next/1</c></seealso>, - <seealso marker="#filter-2"><c>maps:filter/2</c></seealso>, - <seealso marker="#fold-3"><c>maps:fold/3</c></seealso> and - <seealso marker="#map-2"><c>maps:map/2</c></seealso>.</p> + <p>Created using <seemfa marker="#iterator/1"><c>maps:iterator/1</c></seemfa>.</p> + <p>Consumed by <seemfa marker="#next/1"><c>maps:next/1</c></seemfa>, + <seemfa marker="#filter/2"><c>maps:filter/2</c></seemfa>, + <seemfa marker="#fold/3"><c>maps:fold/3</c></seemfa> and + <seemfa marker="#map/2"><c>maps:map/2</c></seemfa>.</p> </desc> </datatype> @@ -197,7 +197,7 @@ false</code> <fsummary>Create a map iterator.</fsummary> <desc> <p>Returns a map iterator <c><anno>Iterator</anno></c> that can - be used by <seealso marker="#next-1"><c>maps:next/1</c></seealso> + be used by <seemfa marker="#next/1"><c>maps:next/1</c></seemfa> to traverse the key-value associations in a map. When iterating over a map, the memory usage is guaranteed to be bounded no matter the size of the map.</p> diff --git a/lib/stdlib/doc/src/math.xml b/lib/stdlib/doc/src/math.xml index b2f4a4eb12..59a05a4e5a 100644 --- a/lib/stdlib/doc/src/math.xml +++ b/lib/stdlib/doc/src/math.xml @@ -42,8 +42,8 @@ <note> <p>Not all functions are provided on all platforms. In particular, - the <seealso marker="#erf/1"><c>erf/1</c></seealso> and - <seealso marker="#erfc/1"><c>erfc/1</c></seealso> functions + the <seemfa marker="#erf/1"><c>erf/1</c></seemfa> and + <seemfa marker="#erfc/1"><c>erfc/1</c></seemfa> functions are not provided on Windows.</p> </note> </description> diff --git a/lib/stdlib/doc/src/ms_transform.xml b/lib/stdlib/doc/src/ms_transform.xml index 7e156e2110..bde9223eb0 100644 --- a/lib/stdlib/doc/src/ms_transform.xml +++ b/lib/stdlib/doc/src/ms_transform.xml @@ -38,19 +38,19 @@ <description> <marker id="top"></marker> <p>This module provides the parse transformation that makes calls to - <seealso marker="ets"><c>ets</c></seealso> and - <seealso marker="runtime_tools:dbg#fun2ms/1"><c>dbg:fun2ms/1</c></seealso> + <seeerl marker="ets"><c>ets</c></seeerl> and + <seemfa marker="runtime_tools:dbg#fun2ms/1"><c>dbg:fun2ms/1</c></seemfa> translate into literal match specifications. It also provides the back end for the same functions when called from the Erlang shell.</p> <p>The translation from funs to match specifications is accessed through the two "pseudo functions" - <seealso marker="ets#fun2ms/1"><c>ets:fun2ms/1</c></seealso> and - <seealso marker="runtime_tools:dbg#fun2ms/1"><c>dbg:fun2ms/1</c></seealso>.</p> + <seemfa marker="ets#fun2ms/1"><c>ets:fun2ms/1</c></seemfa> and + <seemfa marker="runtime_tools:dbg#fun2ms/1"><c>dbg:fun2ms/1</c></seemfa>.</p> <p>As everyone trying to use - <seealso marker="ets#select/1"><c>ets:select/2</c></seealso> or - <seealso marker="runtime_tools:dbg"><c>dbg</c></seealso> seems to end up + <seemfa marker="ets#select/1"><c>ets:select/2</c></seemfa> or + <seeerl marker="runtime_tools:dbg"><c>dbg</c></seeerl> seems to end up reading this manual page, this description is an introduction to the concept of match specifications.</p> @@ -59,7 +59,7 @@ <p>Match specifications are used more or less as filters. They resemble usual Erlang matching in a list comprehension or in a fun used with - <seealso marker="lists#foldl/3"><c>lists:foldl/3</c></seealso>, and so on. + <seemfa marker="lists#foldl/3"><c>lists:foldl/3</c></seemfa>, and so on. However, the syntax of pure match specifications is awkward, as they are made up purely by Erlang terms, and the language has no syntax to make the match specifications more readable.</p> @@ -77,11 +77,11 @@ <section> <title>Example 1</title> - <p>Using <seealso marker="ets#select/2"><c>ets:select/2</c></seealso> + <p>Using <seemfa marker="ets#select/2"><c>ets:select/2</c></seemfa> and a match specification, one can filter out rows of a table and construct a list of tuples containing relevant parts of the data in these rows. - One can use <seealso marker="ets#foldl/3"><c>ets:foldl/3</c></seealso> + One can use <seemfa marker="ets#foldl/3"><c>ets:foldl/3</c></seemfa> instead, but the <c>ets:select/2</c> call is far more efficient. Without the translation provided by <c>ms_transform</c>, one must struggle with writing match specifications terms @@ -127,8 +127,8 @@ ets:new(emp_tab, [{keypos,#emp.empno},named_table,ordered_set]).</code> but it is still unreadable, and one has little control over the returned result. It is always a list of lists.</p> - <p><seealso marker="ets#foldl/3"><c>ets:foldl/3</c></seealso> or - <seealso marker="ets#foldr/3"><c>ets:foldr/3</c></seealso> can be used to avoid the nested lists:</p> + <p><seemfa marker="ets#foldl/3"><c>ets:foldl/3</c></seemfa> or + <seemfa marker="ets#foldr/3"><c>ets:foldr/3</c></seemfa> can be used to avoid the nested lists:</p> <code type="none"> ets:foldr(fun(#emp{empno = E, dept = sales},Acc) -> [E | Acc]; @@ -262,8 +262,8 @@ ets:select(emp_tab, ets:fun2ms( mention that variable A is simply translated into '$_'. Alternatively, pseudo function <c>object/0</c> also returns the whole matched object, see section - <seealso marker="#warnings_and_restrictions"> - Warnings and Restrictions</seealso>.</p> + <seeerl marker="#warnings_and_restrictions"> + Warnings and Restrictions</seeerl>.</p> </section> <section> @@ -339,12 +339,12 @@ ets:select(emp_tab, ets:fun2ms( <section> <title>Useful BIFs</title> <p>What more can you do? A simple answer is: see the documentation of - <seealso marker="erts:match_spec">match specifications</seealso> + <seeguide marker="erts:match_spec">match specifications</seeguide> in ERTS User's Guide. However, the following is a brief overview of the most useful "built-in functions" that you can use when the fun is to be translated into a match specification by - <seealso marker="ets#fun2ms/1"> <c>ets:fun2ms/1</c></seealso>. It is not + <seemfa marker="ets#fun2ms/1"> <c>ets:fun2ms/1</c></seemfa>. It is not possible to call other functions than those allowed in match specifications. No "usual" Erlang code can be executed by the fun that is translated by <c>ets:fun2ms/1</c>. The fun is limited @@ -423,8 +423,8 @@ ets:select(emp_tab, ets:fun2ms( <section> <title>Example with dbg</title> <p>This section describes the slightly different match specifications - translated by <seealso marker="runtime_tools:dbg#fun2ms/1"> - <c>dbg:fun2ms/1</c></seealso>.</p> + translated by <seemfa marker="runtime_tools:dbg#fun2ms/1"> + <c>dbg:fun2ms/1</c></seemfa>.</p> <p>The same reasons for using the parse transformation apply to <c>dbg</c>, maybe even more, as filtering using Erlang code is @@ -574,7 +574,7 @@ start(Args) -> <p>This example illustrates the most used calls in match specifications for <c>dbg</c>. The other, more esoteric, calls are listed and explained in - <seealso marker="erts:match_spec">Match specifications in Erlang</seealso> + <seeguide marker="erts:match_spec">Match specifications in Erlang</seeguide> in ERTS User's Guide, as they are beyond the scope of this description.</p> </section> @@ -725,7 +725,7 @@ ets:select(Table, [{{'$1',test,'$2'},[],['$_']}]).</code> time, so runtime performance is not affected by using these pseudo functions.</p> <p>For more information about match specifications, see the - <seealso marker="erts:match_spec">Match specifications in Erlang</seealso> + <seeguide marker="erts:match_spec">Match specifications in Erlang</seeguide> in ERTS User's Guide.</p> </section> @@ -752,12 +752,12 @@ ets:select(Table, [{{'$1',test,'$2'},[],['$_']}]).</code> transformation if and when header file <c>ms_transform.hrl</c> is included in the source code.</p> <p>For information about how to use this parse transformation, see - <seealso marker="ets"><c>ets</c></seealso> and - <seealso marker="runtime_tools:dbg#fun2ms/1"> - <c>dbg:fun2ms/1</c></seealso>.</p> + <seeerl marker="ets"><c>ets</c></seeerl> and + <seemfa marker="runtime_tools:dbg#fun2ms/1"> + <c>dbg:fun2ms/1</c></seemfa>.</p> <p>For a description of match specifications, see section - <seealso marker="erts:match_spec"> - Match Specification in Erlang</seealso> in ERTS User's Guide.</p> + <seeguide marker="erts:match_spec"> + Match Specification in Erlang</seeguide> in ERTS User's Guide.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index f958bb796f..9c60fb860f 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -31,14 +31,406 @@ </header> <p>This document describes the changes made to the STDLIB application.</p> +<section><title>STDLIB 3.14.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Handle maps in <c>erl_parse:tokens()</c>.</p> + <p> + Own Id: OTP-16978</p> + </item> + <item> + <p> + The erlang shell function <c>rr</c> has been fixed to be + able to read records from files within a code archive.</p> + <p> + Own Id: OTP-17182 Aux Id: PR-3002 </p> + </item> + <item> + <p>If <c>beam_lib</c> is asked to return abstract code + for a BEAM file produced by Elixir and Elixir is not + installed on the computer, <c>beam_lib</c> will no longer + crash, but will return an error tuple. The + <c>cover:compile_beam()</c> and + <c>cover:compile_beam_directory()</c> functions have been + updated to also return an error tuple in that + situation.</p> + <p> + Own Id: OTP-17194 Aux Id: GH-4353 </p> + </item> + <item> + <p> + Correct example module <c>erl_id_trans</c> regarding the + <c>{char, C}</c> type.</p> + <p> + Own Id: OTP-17273</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.14</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + This change fixes the handling of deep lists in the path + component when using uri_string:recompose/1.</p> + <p> + Own Id: OTP-16941</p> + </item> + <item> + <p> + Fix <seeerl + marker="shell_docs"><c>shell_docs</c></seeerl> to clear + shell decorations (bold/underline) when paginating + output.</p> + <p> + Fix various small renderings issues when integrating + <seeerl marker="shell_docs"><c>shell_docs</c></seeerl> + with edoc.</p> + <p> + Own Id: OTP-17047</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Improved the API and documentation of the uri_string + module.</p> + <p> + Added a new chapter to the Users Guide about Uniform + Resource Identifiers and their handling with the new API.</p> + <p> + Added two new API functions: + uri_string:allowed_characters/0 and + uri_string:percent_decode/1.</p> + <p> + This change has been marked as potentially incompatible + as uri_string:normalize/2 used to decode percent-encoded + character triplets that corresponded to characters not in + the reserved set. After this change, + uri_string:normalize/2 will only decode those + percent-encoded triplets that correspond to characters in + the unreserved set (ALPHA / DIGIT / "-" / "." / "_" / + "~").</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-16460</p> + </item> + <item> + <p> + The <c>shell_docs</c> module has been expanded with the + possibility to configure unicode, ansi and column size + for the rendered text.</p> + <p> + Own Id: OTP-16990</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.13.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>The functions <c>digraph:in_edges/2</c> and + <c>digraph:out_edges/2</c> would return false edges if + called for a vertex that had a '_' atom in its name + term.</p> + <p> + Own Id: OTP-16655</p> + </item> + <item> + <p><c>filelib:wildcard("not-a-directory/..")</c> should + return an empty list. On Windows it returned + <c>"not-a-directory/.."</c>.</p> + <p> + Own Id: OTP-16700</p> + </item> + <item> + <p> + Fix the typespec of shell_docs:render to use the correct + type for an MFA.</p> + <p> + Own Id: OTP-16739</p> + </item> + <item> + <p> + Fix uri_string:recompose/1 when host is present but input + path is not absolute.</p> + <p> + This change prevents the recompose operation to change + the top level domain of the host when the path does not + start with a slash.</p> + <p> + Own Id: OTP-16751 Aux Id: ERL-1283 </p> + </item> + <item> + <p>The <c>epp</c> module would return a badly formed + error term when an '<c>if</c>' preprocessor directive + referenced an undefined symbol. <c>epp:format_error/1</c> + would crash when called with the bad error term.</p> + <p> + Own Id: OTP-16816 Aux Id: ERL-1310 </p> + </item> + <item> + <p> + <c>lists:sublist(List, Start, Len)</c> failed with an + exception if <c>Start > length(List) + 1</c> even + though it is explicitly documented that "It is not an + error for <c>Start+Len</c> to exceed the length of the + list".</p> + <p> + Own Id: OTP-16830 Aux Id: ERL-1334, PR-2718 </p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.13.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>When a temporary child of a <c>simple_one_for_one + supervisor</c> died, the internal state of the supervisor + would be corrupted in a way that would cause the + supervisor to retain the start arguments for subsequent + children started by the supervisor, causing unnecessary + growth of the supervisor's heap. There state corruption + could potentially cause other problems as well.</p> + <p> + Own Id: OTP-16804</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.13</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Compiling a match specification with excessive nesting + caused the runtime system to crash due to scheduler stack + exhaustion. Instead of crashing the runtime system, + effected functions will now raise a <c>system_limit</c> + error exception in this situation.</p> + <p> + Own Id: OTP-16431 Aux Id: ERL-592 </p> + </item> + <item> + <p> Initialization of record fields using <c>_</c> is no + longer allowed if the number of affected fields is zero. + </p> + <p> + Own Id: OTP-16516</p> + </item> + <item> + <p> Fix bugs in <c>eval_bits</c>. </p> + <p> + Own Id: OTP-16545</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Improved the printout of single line logger events for + most of the OTP behaviours in STDLIB and Kernel. This + includes <c>proc_lib</c>, <c>gen_server</c>, + <c>gen_event</c>, <c>gen_statem</c>, <c>gen_fsm</c>, + <c>supervisor</c>, <c>supervisor_bridge</c> and + <c>application</c>.</p> + <p> + Improved the <seeerl + marker="kernel:logger_formatter#chars_limit"><c>chars_limit</c></seeerl> + and <seeerl + marker="kernel:logger_formatter#depth"><c>depth</c></seeerl> + handling in <c>proc_lib</c> and when formatting of + exceptions.</p> + <p> + Own Id: OTP-15299</p> + </item> + <item> + <p> + Remove usage and documentation of old requests of the + I/O-protocol.</p> + <p> + Own Id: OTP-15695</p> + </item> + <item> + <p>Improved ETS scalability of concurrent calls that + change the size of a table, like <c>ets:insert/2</c> and + <c>ets:delete/2</c>.</p> <p>This performance feature was + implemented for <c>ordered_set</c> in OTP 22.0 and does + now apply for all ETS table types.</p> <p>The improved + scalability may come at the cost of longer latency of + <c>ets:info(T,size)</c> and <c>ets:info(T,memory)</c>. A + new table option <c>decentralized_counters</c> has + therefore been added. It is default <c>true</c> for + <c>ordered_set</c> with <c>write_concurrency</c> enabled + and default <c>false</c> for all other table types.</p> + <p> + Own Id: OTP-15744 Aux Id: OTP-15623, PR-2229 </p> + </item> + <item> + <p> Handle Unicode filenames in the <c>zip</c> module. + </p> + <p> + Own Id: OTP-16005 Aux Id: ERL-1003, ERL-1150 </p> + </item> + <item> + <p> + Unicode support was updated to the Unicode 12.1 standard.</p> + <p> + Own Id: OTP-16073 Aux Id: PR-2339 </p> + </item> + <item> + <p> + All of the modules <seemfa + marker="stdlib:proc_lib#start_monitor/3"><c>proc_lib</c></seemfa>, + <seemfa + marker="stdlib:gen_server#start_monitor/3"><c>gen_server</c></seemfa>, + <seemfa + marker="stdlib:gen_statem#start_monitor/3"><c>gen_statem</c></seemfa>, + and <seemfa + marker="stdlib:gen_event#start_monitor/0"><c>gen_event</c></seemfa> + have been extended with a <c>start_monitor()</c> + function. For more information, see the documentation of + <c>start_monitor()</c> for these modules.</p> + <p> + Own Id: OTP-16120 Aux Id: ERIERL-402, PR-2427 </p> + </item> + <item> + <p> + Updates for new <c>erlang:term_to_iovec()</c> BIF.</p> + <p> + Own Id: OTP-16128 Aux Id: OTP-15618 </p> + </item> + <item> + <p>Documented a quirk regarding extraction from file + descriptors in <c>erl_tar</c>.</p> + <p> + Own Id: OTP-16171 Aux Id: ERL-1057 </p> + </item> + <item> + <p> + Added <c>ok</c> as return value to + <c>gen_server:reply/2</c></p> + <p> + Own Id: OTP-16210 Aux Id: PR-2411 </p> + </item> + <item> + <p>New functions have been added to <seeerl + marker="c"><c>c(3)</c></seeerl> for printing embedded + documentation for Erlang modules. The functions are:</p> + <taglist> <tag>h/1,2,3</tag> <item>Print the + documentation for a Module:Function/Arity.</item> + <tag>ht/1,2,3</tag> <item>Print the type documentation + for a Module:Type/Arity.</item> </taglist> <p>The + embedded documentation is created when building the + Erlang/OTP documentation.</p> + <p> + Own Id: OTP-16222</p> + </item> + <item> + <p> Add <c>indent</c> and <c>linewidth</c> to the options + of the <c>erl_pp</c> module's functions. </p> + <p> + Own Id: OTP-16276 Aux Id: PR-2443 </p> + </item> + <item> + <p> + Minor updates due to the new spawn improvements made.</p> + <p> + Own Id: OTP-16368 Aux Id: OTP-15251 </p> + </item> + <item> + <p>The compiler will now raise a warning when inlining is + used in modules that load NIFs.</p> + <p> + Own Id: OTP-16429 Aux Id: ERL-303 </p> + </item> + <item> + <p>Refactored the internal handling of deprecated and + removed functions.</p> + <p> + Own Id: OTP-16469</p> + </item> + <item> + <p> Extend <c>erl_parse:abstract/1,2</c> to handle + external fun expressions (<c>fun M:F/A</c>). </p> + <p> + Own Id: OTP-16480</p> + </item> + <item> + <p>Added <c>filelib:safe_relative_path/2</c> to replace + <c>filename:safe_relative_path/1</c>, which did not + safely handle symbolic links.</p> + <p><c>filename:safe_relative_path/1</c> has been + deprecated.</p> + <p> + Own Id: OTP-16483 Aux Id: PR-2542 </p> + </item> + <item> + <p> + The module <c>shell_docs</c> has been added. The module + contains functions for rendering, validating and + normalizing embedded documentation.</p> + <p> + Own Id: OTP-16500</p> + </item> + <item> + <p> + Module and function auto-completion in the shell now + looks at all available modules instead of only those + loaded. A module is considered available if it either is + loaded already or would be loaded if called.</p> + <p> + The auto-completion has also been expanded to work in the + new <c>h/1,2,3</c> function in <c>c(3)</c>.</p> + <p> + Own Id: OTP-16501 Aux Id: OTP-16494, OTP-16222, + OTP-16406, OTP-16499, OTP-16500, PR-2545, ERL-708 </p> + </item> + <item> + <p>Updated the internal <c>pcre</c> library to + <c>8.44</c>.</p> + <p> + Own Id: OTP-16557</p> + </item> + </list> + </section> + +</section> + <section><title>STDLIB 3.12.1</title> <section><title>Fixed Bugs and Malfunctions</title> <list> <item> <p> - <seealso marker="stdlib:re#run/3">re:run(Subject, RE, - [unicode])</seealso> returned <c>nomatch</c> instead of + <seemfa marker="stdlib:re#run/3">re:run(Subject, RE, + [unicode])</seemfa> returned <c>nomatch</c> instead of failing with a <c>badarg</c> error exception when <c>Subject</c> contained illegal utf8 and <c>RE</c> was passed as a binary. This has been corrected along with @@ -161,10 +553,10 @@ <list> <item> <p> - The functions <seealso - marker="stdlib:unicode#characters_to_list/2"><c>unicode:characters_to_list()</c></seealso> - and <seealso - marker="stdlib:unicode#characters_to_binary/3"><c>unicode:characters_to_binary()</c></seealso> + The functions <seemfa + marker="stdlib:unicode#characters_to_list/2"><c>unicode:characters_to_list()</c></seemfa> + and <seemfa + marker="stdlib:unicode#characters_to_binary/3"><c>unicode:characters_to_binary()</c></seemfa> raised a <c>badarg</c> exception instead of returning an error tuple when passed very large invalid code points as input.</p> @@ -186,8 +578,8 @@ </item> <item> <p> - Fixed erroneous type spec for <seealso - marker="stdlib:binary#list_to_bin/1"><c>binary:list_to_bin/1</c></seealso>. + Fixed erroneous type spec for <seemfa + marker="stdlib:binary#list_to_bin/1"><c>binary:list_to_bin/1</c></seemfa>. Argument type was changed from <c>iodata()</c> to <c>iolist()</c>.</p> <p> @@ -253,8 +645,8 @@ to version 8.43. See <url href="http://pcre.org/original/changelog.txt">http://pcre.org/original/changelog.txt</url> for information about changes made to PCRE. This library - implements major parts of the <seealso - marker="stdlib:re"><c>re</c></seealso> regular + implements major parts of the <seeerl + marker="stdlib:re"><c>re</c></seeerl> regular expressions module.</p> <p> Own Id: OTP-15889</p> @@ -653,6 +1045,27 @@ </section> +<section><title>STDLIB 3.8.2.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + <seemfa marker="stdlib:re#run/3">re:run(Subject, RE, + [unicode])</seemfa> returned <c>nomatch</c> instead of + failing with a <c>badarg</c> error exception when + <c>Subject</c> contained illegal utf8 and <c>RE</c> was + passed as a binary. This has been corrected along with + corrections of reduction counting in <c>re:run()</c> + error cases.</p> + <p> + Own Id: OTP-16553</p> + </item> + </list> + </section> + +</section> + <section><title>STDLIB 3.8.2.3</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -965,18 +1378,18 @@ Own Id: OTP-14019 Aux Id: ERL-550 </p> </item> <item> - <p> File operations used to accept <seealso - marker="kernel:file#type-name_all">filenames</seealso> + <p> File operations used to accept <seetype + marker="kernel:file#name_all">filenames</seetype> containing null characters (integer value zero). This caused the name to be truncated and in some cases arguments to primitive operations to be mixed up. Filenames containing null characters inside the filename are now <em>rejected</em> and will cause primitive file operations to fail. </p> <p> Also environment variable - operations used to accept <seealso - marker="kernel:os#type-env_var_name">names</seealso> and - <seealso - marker="kernel:os#type-env_var_value">values</seealso> of + operations used to accept <seetype + marker="kernel:os#env_var_name">names</seetype> and + <seetype + marker="kernel:os#env_var_value">values</seetype> of environment variables containing null characters (integer value zero). This caused operations to silently produce erroneous results. Environment variable names and values @@ -987,12 +1400,12 @@ character in environment variable names causing various problems. <c>$=</c> characters in environment variable names are now also <em>rejected</em>. </p> <p>Also - <seealso - marker="kernel:os#cmd/1"><c>os:cmd/1</c></seealso> now - reject null characters inside its <seealso - marker="kernel:os#type-os_command">command</seealso>. - </p> <p><seealso - marker="erts:erlang#open_port/2"><c>erlang:open_port/2</c></seealso> + <seemfa + marker="kernel:os#cmd/1"><c>os:cmd/1</c></seemfa> now + reject null characters inside its <seetype + marker="kernel:os#os_command">command</seetype>. + </p> <p><seemfa + marker="erts:erlang#open_port/2"><c>erlang:open_port/2</c></seemfa> will also reject null characters inside the port name from now on.</p> <p> @@ -1073,10 +1486,10 @@ </item> <item> <p>A new logging API is added to Erlang/OTP, see the - <seealso - marker="kernel:logger"><c>logger(3)</c></seealso> manual - page, and section <seealso - marker="kernel:logger_chapter">Logging</seealso> in the + <seeerl + marker="kernel:logger"><c>logger(3)</c></seeerl> manual + page, and section <seeguide + marker="kernel:logger_chapter">Logging</seeguide> in the Kernel User's Guide.</p> <p>Calls to <c>error_logger</c> are automatically redirected to the new API, and legacy error logger event @@ -1662,9 +2075,9 @@ Own Id: OTP-13830</p> </item> <item> - <p>Replaced usage of deprecated symbolic <seealso - marker="erts:erlang#type-time_unit"><c>time - unit</c></seealso> representations.</p> + <p>Replaced usage of deprecated symbolic <seetype + marker="erts:erlang#time_unit"><c>time + unit</c></seetype> representations.</p> <p> Own Id: OTP-13831 Aux Id: OTP-13735 </p> </item> @@ -1909,7 +2322,7 @@ <p> Upgraded the OTP internal PCRE library from version 8.33 to version 8.40. This library is used for implementation - of the <seealso marker="stdlib:re"><c>re</c></seealso> + of the <seeerl marker="stdlib:re"><c>re</c></seeerl> regular expressions module.</p> <p> Besides various bug fixes, the new version allows for @@ -1917,10 +2330,10 @@ feature, the stack size of normal scheduler threads is now by default set to 128 kilo words on all platforms. The stack size of normal scheduler threads can be set - upon system start by passing the <seealso - marker="erts:erl#sched_thread_stack_size"><c>+sss</c></seealso> - command line argument to the <seealso - marker="erts:erl"><c>erl</c></seealso> command.</p> + upon system start by passing the <seecom + marker="erts:erl#sched_thread_stack_size"><c>+sss</c></seecom> + command line argument to the <seecom + marker="erts:erl"><c>erl</c></seecom> command.</p> <p> See <url href="http://pcre.org/original/changelog.txt">http://pcre.org/original/changelog.txt</url> @@ -2892,10 +3305,10 @@ Earlier, supervisor flags and child specs were given as tuples. While this is kept for backwards compatibility, it is now also allowed to give these parameters as maps, - see <seealso - marker="stdlib:supervisor#sup_flags">sup_flags</seealso> - and <seealso - marker="stdlib:supervisor#child_spec">child_spec</seealso>.</p> + see <seeerl + marker="stdlib:supervisor#sup_flags">sup_flags</seeerl> + and <seeerl + marker="stdlib:supervisor#child_spec">child_spec</seeerl>.</p> <p> Own Id: OTP-11043</p> </item> @@ -3648,10 +4061,10 @@ 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> + The <seemfa + marker="erts:erlang#garbage_collect/2"><c>garbage_collect/2</c></seemfa>, + and <seemfa + marker="erts:erlang#check_process_code/3"><c>check_process_code/3</c></seemfa> BIFs have been introduced. Both taking an option list as last argument. Using these, one can issue asynchronous requests.</p> @@ -3706,8 +4119,8 @@ </taglist> <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> + <seeguide marker="system/reference_manual:expressions#map_expressions"> + Reference Manual</seeguide>.</p> <p> The current implementation is without the following features:</p> @@ -5508,15 +5921,15 @@ lines. The reader optimized rwlock implementation is used by miscellaneous rwlocks in the runtime system that are known to be read-locked frequently, and can be enabled on - ETS tables by passing the <seealso + ETS tables by passing the <seeerl marker="stdlib:ets#new_2_read_concurrency">{read_concurrency, - true}</seealso> option upon table creation. See the - documentation of <seealso - marker="stdlib:ets#new/2">ets:new/2</seealso> for more + true}</seeerl> option upon table creation. See the + documentation of <seemfa + marker="stdlib:ets#new/2">ets:new/2</seemfa> for more information. The reader optimized rwlock implementation can be fine tuned when starting the runtime system. For - more information, see the documentation of the <seealso - marker="erts:erl#+rg">+rg</seealso> command line argument + more information, see the documentation of the <seecom + marker="erts:erl#+rg">+rg</seecom> command line argument of <c>erl</c>.</p> <p> There is also a new implementation of rwlocks that is not @@ -5558,8 +5971,8 @@ utilize optimized native atomic operations on more 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#Advanced-configuration-and-build-of-ErlangOTP">--with-libatomic_ops=PATH</seealso> + <c>libatomic_ops</c> library. Use the <seeguide + marker="system/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP">--with-libatomic_ops=PATH</seeguide> <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: @@ -5576,8 +5989,8 @@ library will now use instructions that first appeared on 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#Advanced-configuration-and-build-of-ErlangOTP">--enable-ethread-pre-pentium4-compatibility</seealso> + need to pass the <seeguide + marker="system/installation_guide:INSTALL#Advanced-configuration-and-build-of-ErlangOTP">--enable-ethread-pre-pentium4-compatibility</seeguide> <c>configure</c> command line argument when configuring the system.</p> <p> @@ -6100,10 +6513,10 @@ regarding <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_event</c> behavior when handling <c>'EXIT'</c> messages from the parent process. For more information - see the <seealso - marker="gen_server">gen_server(3)</seealso>, <seealso - marker="gen_fsm">gen_fsm(3)</seealso>, and <seealso - marker="gen_event">gen_event(3)</seealso> documentation.</p> + see the <seeerl + marker="gen_server">gen_server(3)</seeerl>, <seeerl + marker="gen_fsm">gen_fsm(3)</seeerl>, and <seeerl + marker="gen_event">gen_event(3)</seeerl> documentation.</p> <p> Own Id: OTP-8255 Aux Id: seq11419 </p> </item> diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml index d5ceca9e0c..796cb42ede 100644 --- a/lib/stdlib/doc/src/orddict.xml +++ b/lib/stdlib/doc/src/orddict.xml @@ -41,7 +41,7 @@ ordered after the keys in the <em>Erlang term order</em>.</p> <p>This module provides the same interface as the - <seealso marker="dict"><c>dict(3)</c></seealso> module + <seeerl marker="dict"><c>dict(3)</c></seeerl> module but with a defined representation. One difference is that while <c>dict</c> considers two keys as different if they do not match (<c>=:=</c>), this module considers two keys as @@ -52,7 +52,7 @@ <datatype> <name name="orddict" n_vars="2"/> <desc><p>Dictionary as returned by - <seealso marker="#new/0"><c>new/0</c></seealso>.</p></desc> + <seemfa marker="#new/0"><c>new/0</c></seemfa>.</p></desc> </datatype> <datatype> <name name="orddict" n_vars="0"/> @@ -68,7 +68,7 @@ of values associated with <c><anno>Key</anno></c>. An exception is generated if the initial value associated with <c><anno>Key</anno></c> is not a list of values.</p> - <p>See also section <seealso marker="#notes">Notes</seealso>.</p> + <p>See also section <seeerl marker="#notes">Notes</seeerl>.</p> </desc> </func> @@ -80,7 +80,7 @@ the current list of values associated with <c><anno>Key</anno></c>. An exception is generated if the initial value associated with <c><anno>Key</anno></c> is not a list of values.</p> - <p>See also section <seealso marker="#notes">Notes</seealso>.</p> + <p>See also section <seeerl marker="#notes">Notes</seeerl>.</p> </desc> </func> @@ -100,7 +100,7 @@ in dictionary <c><anno>Orddict</anno></c>. This function assumes that the <c><anno>Key</anno></c> is present in the dictionary. An exception is generated if <c><anno>Key</anno></c> is not in the dictionary.</p> - <p>See also section <seealso marker="#notes">Notes</seealso>.</p> + <p>See also section <seeerl marker="#notes">Notes</seeerl>.</p> </desc> </func> @@ -140,7 +140,7 @@ <c>{ok, <anno>Value</anno>}</c>, where <c><anno>Value</anno></c> is the value associated with <c><anno>Key</anno></c>, or <c>error</c> if the key is not present in the dictionary.</p> - <p>See also section <seealso marker="#notes">Notes</seealso>.</p> + <p>See also section <seeerl marker="#notes">Notes</seeerl>.</p> </desc> </func> @@ -312,8 +312,8 @@ update_counter(Key, Incr, D) -> <section> <title>See Also</title> - <p><seealso marker="dict"><c>dict(3)</c></seealso>, - <seealso marker="gb_trees"><c>gb_trees(3)</c></seealso></p> + <p><seeerl marker="dict"><c>dict(3)</c></seeerl>, + <seeerl marker="gb_trees"><c>gb_trees(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/ordsets.xml b/lib/stdlib/doc/src/ordsets.xml index fbe334c009..1b16f45a7d 100644 --- a/lib/stdlib/doc/src/ordsets.xml +++ b/lib/stdlib/doc/src/ordsets.xml @@ -43,7 +43,7 @@ according to the <em>Erlang term order</em>.</p> <p>This module provides the same interface as the - <seealso marker="sets"><c>sets(3)</c></seealso> module + <seeerl marker="sets"><c>sets(3)</c></seeerl> module but with a defined representation. One difference is that while <c>sets</c> considers two elements as different if they do not match (<c>=:=</c>), this module considers two elements as @@ -54,7 +54,7 @@ <datatype> <name name="ordset" n_vars="1"/> <desc><p>As returned by - <seealso marker="#new/0"><c>new/0</c></seealso>.</p></desc> + <seemfa marker="#new/0"><c>new/0</c></seemfa>.</p></desc> </datatype> </datatypes> @@ -222,8 +222,8 @@ <section> <title>See Also</title> - <p><seealso marker="gb_sets"><c>gb_sets(3)</c></seealso>, - <seealso marker="sets"><c>sets(3)</c></seealso></p> + <p><seeerl marker="gb_sets"><c>gb_sets(3)</c></seeerl>, + <seeerl marker="sets"><c>sets(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/part.xml b/lib/stdlib/doc/src/part.xml index 93c47405bf..b6a2f16b57 100644 --- a/lib/stdlib/doc/src/part.xml +++ b/lib/stdlib/doc/src/part.xml @@ -37,5 +37,6 @@ <xi:include href="introduction.xml"/> <xi:include href="io_protocol.xml"/> <xi:include href="unicode_usage.xml"/> + <xi:include href="uri_string_usage.xml"/> </part> diff --git a/lib/stdlib/doc/src/pool.xml b/lib/stdlib/doc/src/pool.xml index e17aff1b5b..ac67df2a2f 100644 --- a/lib/stdlib/doc/src/pool.xml +++ b/lib/stdlib/doc/src/pool.xml @@ -47,7 +47,7 @@ processes in the Erlang runtime system.</p> <p>The slave nodes are started with the - <seealso marker="slave"><c>slave(3)</c></seealso> module. This + <seeerl marker="slave"><c>slave(3)</c></seeerl> module. This effects terminal I/O, file I/O, and code loading.</p> <p>If the master node fails, the entire pool exits.</p> </description> @@ -106,10 +106,10 @@ <desc> <p>Starts a new pool. The file <c>.hosts.erlang</c> is read to find host names where the pool nodes can be started; see - section <seealso marker="#files">Files</seealso>. The + section <seeerl marker="#files">Files</seeerl>. The startup procedure fails if the file is not found.</p> <p>The slave nodes are started with - <seealso marker="slave#start/2"><c>slave:start/2,3</c></seealso>, + <seemfa marker="slave#start/2"><c>slave:start/2,3</c></seemfa>, passing along <c><anno>Name</anno></c> and, if provided, <c><anno>Args</anno></c>. <c><anno>Name</anno></c> is used as the first part of the node names, <c><anno>Args</anno></c> is used to @@ -135,8 +135,8 @@ <title>Files</title> <p><c>.hosts.erlang</c> is used to pick hosts where nodes can be started. For information about format and location of this file, see - <seealso marker="kernel:net_adm#host_file/0"> - <c>net_adm:host_file/0</c></seealso>.</p> + <seemfa marker="kernel:net_adm#host_file/0"> + <c>net_adm:host_file/0</c></seemfa>.</p> <p><c>$HOME/.erlang.slave.out.HOST</c> is used for all extra I/O that can come from the slave nodes on standard I/O. If the startup procedure does not work, this file can indicate the reason.</p> diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index 2c83005a56..aa649a280a 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -33,15 +33,15 @@ adhering to the OTP design principles.</modulesummary> <description> <p>This module is used to start processes adhering to - the <seealso marker="doc/design_principles:des_princ"> - OTP Design Principles</seealso>. Specifically, the functions in this + the <seeguide marker="system/design_principles:des_princ"> + OTP Design Principles</seeguide>. Specifically, the functions in this module are used by the OTP standard behaviors (for example, <c>gen_server</c> and <c>gen_statem</c>) when starting new processes. The functions can also be used to start <em>special processes</em>, user-defined processes that comply to the OTP design principles. For an example, - see section <seealso marker="doc/design_principles:spec_proc"> - sys and proc_lib</seealso> in OTP Design Principles.</p> + see section <seeguide marker="system/design_principles:spec_proc"> + sys and proc_lib</seeguide> in OTP Design Principles.</p> <p>Some useful information is initialized when a process starts. @@ -62,7 +62,7 @@ is generated, which is written to terminal by the default logger handler setup by Kernel. For more information about how crash reports were logged prior to Erlang/OTP 21.0, see - <seealso marker="sasl:error_logging">SASL Error Logging</seealso> + <seeguide marker="sasl:error_logging">SASL Error Logging</seeguide> in the SASL User's Guide.</p> <p>Unlike in "plain Erlang", <c>proc_lib</c> processes will not generate @@ -81,18 +81,16 @@ <datatype> <name name="spawn_option"/> <desc> - <p>See <seealso marker="erts:erlang#spawn_opt/4"> - <c>erlang:spawn_opt/2,3,4,5</c></seealso>.</p> + <p>See <seemfa marker="erts:erlang#spawn_opt/4"> + <c>erlang:spawn_opt/2,3,4,5</c></seemfa>.</p> </desc> </datatype> <datatype> - <name name="priority_level"/> - </datatype> - <datatype> - <name name="max_heap_size"/> + <name name="start_spawn_option"/> <desc> - <p>See <seealso marker="erts:erlang#process_flag_max_heap_size"> - erlang:process_flag(max_heap_size, MaxHeapSize)</seealso>.</p> + <p>A restricted set of <seetype marker="#spawn_option">spawn + options</seetype>. Most notably <c>monitor</c> is <em>not</em> part + of these options.</p> </desc> </datatype> <datatype> @@ -105,8 +103,8 @@ <name name="format" arity="1" since=""/> <fsummary>Format a crash report.</fsummary> <desc> - <p>Equivalent to <seealso marker="#format/2"> - <c>format(<anno>CrashReport</anno>, latin1)</c></seealso>.</p> + <p>Equivalent to <seemfa marker="#format/2"> + <c>format(<anno>CrashReport</anno>, latin1)</c></seemfa>.</p> </desc> </func> @@ -118,8 +116,8 @@ <p>This function is deprecated in the sense that the <c>error_logger</c> is no longer the preferred interface for logging in Erlang/OTP. A - new <seealso marker="kernel:logger_chapter">logging - API</seealso> was added in Erlang/OTP 21.0, but + new <seeguide marker="kernel:logger_chapter">logging + API</seeguide> was added in Erlang/OTP 21.0, but legacy <c>error_logger</c> handlers can still be used. New Logger handlers do not need to use this function, since the formatting callback (<c>report_cb</c>) is included as @@ -128,8 +126,8 @@ <p>This function can be used by a user-defined legacy <c>error_logger</c> event handler to format a crash report. The crash report is sent using - <seealso marker="kernel:logger"> - <c>logger(3)</c></seealso>, and the event to be handled is of the format + <seeerl marker="kernel:logger"> + <c>logger(3)</c></seeerl>, and the event to be handled is of the format <c>{error_report, GL, {Pid, crash_report, <anno>CrashReport</anno>}}</c>, where <c>GL</c> is the group leader pid of process @@ -145,8 +143,8 @@ <p>This function is deprecated in the sense that the <c>error_logger</c> is no longer the preferred interface for logging in Erlang/OTP. A - new <seealso marker="kernel:logger_chapter">logging - API</seealso> was added in Erlang/OTP 21.0, but + new <seeguide marker="kernel:logger_chapter">logging + API</seeguide> was added in Erlang/OTP 21.0, but legacy <c>error_logger</c> handlers can still be used. New Logger handlers do not need to used this function, since the formatting callback (<c>report_cb</c>) is included as @@ -166,8 +164,8 @@ <fsummary>Hibernate a process until a message is sent to it.</fsummary> <desc> <p>This function does the same as (and does call) the - <seealso marker="erts:erlang#hibernate/3"> - <c>hibernate/3</c></seealso> BIF, + <seemfa marker="erts:erlang#hibernate/3"> + <c>hibernate/3</c></seemfa> BIF, but ensures that exception handling and logging continues to work as expected when the process wakes up.</p> <p>Always use this function instead of the BIF for processes started @@ -181,7 +179,7 @@ <fsummary>Used by a process when it has started.</fsummary> <desc> <p>This function must be used by a process that has been started by - a <seealso marker="#start/3"><c>start[_link]/3,4,5</c></seealso> + a <seemfa marker="#start/3"><c>start[_link]/3,4,5</c></seemfa> function. It tells <c><anno>Parent</anno></c> that the process has initialized itself, has started, or has failed to initialize itself.</p> @@ -257,7 +255,7 @@ init(Parent) -> <desc> <p>Spawns a new process and initializes it as described in the beginning of this manual page. The process is spawned using the - <seealso marker="erts:erlang#spawn/1"><c>spawn</c></seealso> BIFs.</p> + <seemfa marker="erts:erlang#spawn/1"><c>spawn</c></seemfa> BIFs.</p> </desc> </func> @@ -275,7 +273,7 @@ init(Parent) -> <desc> <p>Spawns a new process and initializes it as described in the beginning of this manual page. The process is spawned using the - <seealso marker="erts:erlang#spawn_link/1"><c>spawn_link</c></seealso> + <seemfa marker="erts:erlang#spawn_link/1"><c>spawn_link</c></seemfa> BIFs.</p> </desc> </func> @@ -295,8 +293,31 @@ init(Parent) -> <desc> <p>Spawns a new process and initializes it as described in the beginning of this manual page. The process is spawned using the - <seealso marker="erts:erlang#spawn_opt/2"><c>spawn_opt</c></seealso> + <seemfa marker="erts:erlang#spawn_opt/2"><c>erlang:spawn_opt</c></seemfa> BIFs.</p> + </desc> + </func> + + <func> + <name name="start" arity="3" since=""/> + <name name="start" arity="4" since=""/> + <name name="start" arity="5" since=""/> + <fsummary>Start a new process synchronously.</fsummary> + <desc> + <p>Starts a new process synchronously. Spawns the process and + waits for it to start. When the process has started, it + <em>must</em> call + <seemfa marker="#init_ack/2"><c>init_ack(Parent, Ret)</c></seemfa> + or <seemfa marker="#init_ack/1"><c>init_ack(Ret)</c></seemfa>, + where <c>Parent</c> is the process that evaluates this + function. At this time, <c>Ret</c> is returned.</p> + <p>If <c><anno>Time</anno></c> is specified as an integer, this + function waits for <c><anno>Time</anno></c> milliseconds for the + new process to call <c>init_ack</c>, or <c>Ret = {error, timeout}</c> + will be returned, and the process is killed.</p> + <p>Argument <c><anno>SpawnOpts</anno></c>, if specified, is passed + as the last argument to the <seemfa marker="erts:erlang#spawn_opt/2"> + <c>spawn_opt/2,3,4,5</c></seemfa> BIF.</p> <note> <p>Using spawn option <c>monitor</c> is not allowed. It causes the function to fail with reason @@ -306,32 +327,71 @@ init(Parent) -> </func> <func> - <name name="start" arity="3" since=""/> - <name name="start" arity="4" since=""/> - <name name="start" arity="5" since=""/> <name name="start_link" arity="3" since=""/> <name name="start_link" arity="4" since=""/> <name name="start_link" arity="5" since=""/> <fsummary>Start a new process synchronously.</fsummary> <desc> - <p>Starts a new process synchronously. Spawns the process and - waits for it to start. When the process has started, it + <p> + Starts a new process synchronously. Spawns the process and + waits for it to start. A link is atomically set on the + newly spawned process. When the process has started, it + <em>must</em> call + <seemfa marker="#init_ack/2"><c>init_ack(Parent, Ret)</c></seemfa> + or <seemfa marker="#init_ack/1"><c>init_ack(Ret)</c></seemfa>, + where <c>Parent</c> is the process that evaluates this + function. At this time, <c>Ret</c> is returned.</p> + <p>If <c><anno>Time</anno></c> is specified as an integer, this + function waits for <c><anno>Time</anno></c> milliseconds for the + new process to call <c>init_ack</c>, or <c>Ret = {error, timeout}</c> + will be returned, and the process is killed.</p> + <p>If the process crashes before it has called <c>init_ack/1,2</c>, + <c>Ret = {error, <anno>Reason</anno>}</c> will be returned if + the calling process traps exits.</p> + <p>Argument <c><anno>SpawnOpts</anno></c>, if specified, is passed + as the last argument to the <seemfa marker="erts:erlang#spawn_opt/2"> + <c>spawn_opt/2,3,4,5</c></seemfa> BIF.</p> + <note> + <p>Using spawn option <c>monitor</c> is not + allowed. It causes the function to fail with reason + <c>badarg</c>.</p> + </note> + </desc> + </func> + + <func> + <name name="start_monitor" arity="3" since="OTP 23.0"/> + <name name="start_monitor" arity="4" since="OTP 23.0"/> + <name name="start_monitor" arity="5" since="OTP 23.0"/> + <fsummary>Start a new process synchronously.</fsummary> + <desc> + <p> + Starts a new process synchronously. Spawns the process and + waits for it to start. A monitor is atomically set on the + newly spawned process. When the process has started, it <em>must</em> call - <seealso marker="#init_ack/2"><c>init_ack(Parent, Ret)</c></seealso> - or <seealso marker="#init_ack/1"><c>init_ack(Ret)</c></seealso>, + <seemfa marker="#init_ack/2"><c>init_ack(Parent, Ret)</c></seemfa> + or <seemfa marker="#init_ack/1"><c>init_ack(Ret)</c></seemfa>, where <c>Parent</c> is the process that evaluates this function. At this time, <c>Ret</c> is returned.</p> - <p>If function <c>start_link/3,4,5</c> is used and - the process crashes before it has called <c>init_ack/1,2</c>, - <c>{error, <anno>Reason</anno>}</c> is returned if the calling - process traps exits.</p> <p>If <c><anno>Time</anno></c> is specified as an integer, this function waits for <c><anno>Time</anno></c> milliseconds for the - new process to call <c>init_ack</c>, or <c>{error, timeout}</c> is - returned, and the process is killed.</p> + new process to call <c>init_ack</c>, or <c>Ret = {error, timeout}</c> + will be returned, and the process is killed.</p> + <p> + The return value is <c>{Ret, Mon}</c> where <c>Ret</c> corresponds + to the <c>Ret</c> argument in the call to <c>init_ack()</c>, and + <c>Mon</c> is the monitor reference of the monitor that has been + set up. + </p> + <p> + A <c>'DOWN'</c> message will be delivered to the caller if + this function returns, and the spawned process terminates. This is + true also in the case when the operation times out. + </p> <p>Argument <c><anno>SpawnOpts</anno></c>, if specified, is passed - as the last argument to the <seealso marker="erts:erlang#spawn_opt/2"> - <c>spawn_opt/2,3,4,5</c></seealso> BIF.</p> + as the last argument to the <seemfa marker="erts:erlang#spawn_opt/2"> + <c>spawn_opt/2,3,4,5</c></seemfa> BIF.</p> <note> <p>Using spawn option <c>monitor</c> is not allowed. It causes the function to fail with reason @@ -345,8 +405,8 @@ init(Parent) -> <fsummary>Terminate a process synchronously.</fsummary> <type variable="Process"/> <desc> - <p>Equivalent to <seealso marker="#stop/3"> - <c>stop(Process, normal, infinity)</c></seealso>.</p> + <p>Equivalent to <seemfa marker="#stop/3"> + <c>stop(Process, normal, infinity)</c></seemfa>.</p> </desc> </func> @@ -368,9 +428,9 @@ init(Parent) -> <c>terminate</c> system message, and requires that the process handles system messages correctly. For information about system messages, see - <seealso marker="sys"><c>sys(3)</c></seealso> and section - <seealso marker="doc/design_principles:spec_proc"> - sys and proc_lib</seealso> in OTP Design Principles.</p> + <seeerl marker="sys"><c>sys(3)</c></seeerl> and section + <seeguide marker="system/design_principles:spec_proc"> + sys and proc_lib</seeguide> in OTP Design Principles.</p> </desc> </func> @@ -380,8 +440,8 @@ init(Parent) -> <c>proc_lib</c>spawned process.</fsummary> <desc> <p>This function is used by functions - <seealso marker="c#i/0"><c>c:i/0</c></seealso> and - <seealso marker="c#regs/0"><c>c:regs/0</c></seealso> + <seemfa marker="c#i/0"><c>c:i/0</c></seemfa> and + <seemfa marker="c#regs/0"><c>c:regs/0</c></seemfa> to present process information.</p> <p>This function extracts the initial call of a process that was started using one of the spawn or start functions in this module, @@ -414,10 +474,10 @@ init(Parent) -> <section> <title>See Also</title> - <p><seealso marker="kernel:error_logger"> - <c>error_logger(3)</c></seealso></p> - <p><seealso marker="kernel:logger"> - <c>logger(3)</c></seealso></p> + <p><seeerl marker="kernel:error_logger"> + <c>error_logger(3)</c></seeerl></p> + <p><seeerl marker="kernel:logger"> + <c>logger(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/proplists.xml b/lib/stdlib/doc/src/proplists.xml index 6dedaf79b5..f59b6eda17 100644 --- a/lib/stdlib/doc/src/proplists.xml +++ b/lib/stdlib/doc/src/proplists.xml @@ -70,7 +70,7 @@ <fsummary></fsummary> <desc> <p>Similar to - <seealso marker="#get_all_values/2"><c>get_all_values/2</c></seealso>, + <seemfa marker="#get_all_values/2"><c>get_all_values/2</c></seemfa>, but each value is wrapped in a list unless it is already itself a list. The resulting list of lists is concatenated. This is often useful for "incremental" options.</p> @@ -90,8 +90,8 @@ append_values(a, [{a, [1,2]}, {b, 0}, {a, 3}, {c, -1}, {a, [4]}])</code> <p>Minimizes the representation of all entries in the list. This is equivalent to <c><![CDATA[[property(P) || P <- ListIn]]]></c>.</p> <p>See also - <seealso marker="#property/1"><c>property/1</c></seealso>, - <seealso marker="#unfold/1"><c>unfold/1</c></seealso>.</p> + <seemfa marker="#property/1"><c>property/1</c></seemfa>, + <seemfa marker="#unfold/1"><c>unfold/1</c></seemfa>.</p> </desc> </func> @@ -133,7 +133,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> <c><anno>Expansions</anno></c> contains more than one property with the same key, only the first occurrence is used.</p> <p>See also - <seealso marker="#normalize/2"><c>normalize/2</c></seealso>.</p> + <seemfa marker="#normalize/2"><c>normalize/2</c></seemfa>.</p> </desc> </func> @@ -142,7 +142,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> <fsummary></fsummary> <desc> <p>Similar to - <seealso marker="#get_value/2"><c>get_value/2</c></seealso>, + <seemfa marker="#get_value/2"><c>get_value/2</c></seemfa>, but returns the list of values for <em>all</em> entries <c>{Key, Value}</c> in <c><anno>List</anno></c>. If no such entry exists, the result is the empty list.</p> @@ -158,8 +158,8 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> <c>{<anno>Key</anno>, true}</c>, this function returns <c>true</c>, otherwise <c>false</c>.</p> <p>See also - <seealso marker="#get_value/2"><c>get_value/2</c></seealso>, - <seealso marker="#lookup/2"><c>lookup/2</c></seealso>.</p> + <seemfa marker="#get_value/2"><c>get_value/2</c></seemfa>, + <seemfa marker="#lookup/2"><c>lookup/2</c></seemfa>.</p> </desc> </func> @@ -191,10 +191,10 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> this function returns the corresponding <c>Value</c>, otherwise <c><anno>Default</anno></c>.</p> <p>See also - <seealso marker="#get_all_values/2"><c>get_all_values/2</c></seealso>, - <seealso marker="#get_bool/2"><c>get_bool/2</c></seealso>, - <seealso marker="#get_value/2"><c>get_value/2</c></seealso>, - <seealso marker="#lookup/2"><c>lookup/2</c></seealso>.</p> + <seemfa marker="#get_all_values/2"><c>get_all_values/2</c></seemfa>, + <seemfa marker="#get_bool/2"><c>get_bool/2</c></seemfa>, + <seemfa marker="#get_value/2"><c>get_value/2</c></seemfa>, + <seemfa marker="#lookup/2"><c>lookup/2</c></seemfa>.</p> </desc> </func> @@ -217,9 +217,9 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> <c>none</c>. For an atom <c>A</c> in the list, the tuple <c>{A, true}</c> is the entry associated with <c>A</c>.</p> <p>See also - <seealso marker="#get_bool/2"><c>get_bool/2</c></seealso>, - <seealso marker="#get_value/2"><c>get_value/2</c></seealso>, - <seealso marker="#lookup_all/2"><c>lookup_all/2</c></seealso>.</p> + <seemfa marker="#get_bool/2"><c>get_bool/2</c></seemfa>, + <seemfa marker="#get_value/2"><c>get_value/2</c></seemfa>, + <seemfa marker="#lookup_all/2"><c>lookup_all/2</c></seemfa>.</p> </desc> </func> @@ -231,7 +231,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> <c><anno>Key</anno></c> in <c><anno>List</anno></c>. If no such entry exists, the result is the empty list.</p> <p>See also - <seealso marker="#lookup/2"><c>lookup/2</c></seealso>.</p> + <seemfa marker="#lookup/2"><c>lookup/2</c></seemfa>.</p> </desc> </func> @@ -241,8 +241,8 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> <desc> <p>Passes <c><anno>ListIn</anno></c> through a sequence of substitution/expansion stages. For an <c>aliases</c> operation, - function <seealso marker="#substitute_aliases/2"> - <c>substitute_aliases/2</c></seealso> is applied using the + function <seemfa marker="#substitute_aliases/2"> + <c>substitute_aliases/2</c></seemfa> is applied using the specified list of aliases:</p> <list type="bulleted"> <item> @@ -251,19 +251,19 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </item> <item> <p>For an <c>expand</c> operation, function - <seealso marker="#expand/2"><c>expand/2</c></seealso> + <seemfa marker="#expand/2"><c>expand/2</c></seemfa> is applied using the specified list of expansions.</p> </item> </list> <p>The final result is automatically compacted (compare - <seealso marker="#compact/1"><c>compact/1</c></seealso>).</p> + <seemfa marker="#compact/1"><c>compact/1</c></seemfa>).</p> <p>Typically you want to substitute negations first, then aliases, then perform one or more expansions (sometimes you want to pre-expand particular entries before doing the main expansion). You might want to substitute negations and/or aliases repeatedly, to allow such forms in the right-hand side of aliases and expansion lists.</p> - <p>See also <seealso marker="#substitute_negations/2"> - <c>substitute_negations/2</c></seealso>.</p> + <p>See also <seemfa marker="#substitute_negations/2"> + <c>substitute_negations/2</c></seemfa>.</p> </desc> </func> @@ -276,7 +276,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> <c>Key</c> is an atom, <c>Key</c> is returned, otherwise the whole term <c><anno>PropertyIn</anno></c> is returned.</p> <p>See also - <seealso marker="#property/2"><c>property/2</c></seealso>.</p> + <seemfa marker="#property/2"><c>property/2</c></seemfa>.</p> </desc> </func> @@ -289,7 +289,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> is <c>true</c> and <c><anno>Key</anno></c> is an atom, otherwise a tuple <c>{<anno>Key</anno>, <anno>Value</anno>}</c> is returned.</p> <p>See also - <seealso marker="#property/1"><c>property/1</c></seealso>.</p> + <seemfa marker="#property/1"><c>property/1</c></seemfa>.</p> </desc> </func> @@ -330,9 +330,9 @@ split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])</code> with <c>{colour, ...}</c>, and all atoms <c>color</c> with <c>colour</c>.</p> <p>See also - <seealso marker="#normalize/2"><c>normalize/2</c></seealso>, - <seealso marker="#substitute_negations/2"> - <c>substitute_negations/2</c></seealso>.</p> + <seemfa marker="#normalize/2"><c>normalize/2</c></seemfa>, + <seemfa marker="#substitute_negations/2"> + <c>substitute_negations/2</c></seemfa>.</p> </desc> </func> @@ -348,8 +348,8 @@ split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])</code> <c>{K1, true}</c>, it is replaced with <c>{K2, false}</c>, otherwise with <c>K2</c>, thus changing the name of the option and simultaneously negating the value specified by - <seealso marker="#get_bool/2"> - <c>get_bool(Key, <anno>ListIn</anno>)</c></seealso>. + <seemfa marker="#get_bool/2"> + <c>get_bool(Key, <anno>ListIn</anno>)</c></seemfa>. If the same <c>K1</c> occurs more than once in <c><anno>Negations</anno></c>, only the first occurrence is used.</p> <p>For example, <c>substitute_negations([{no_foo, foo}], L)</c> @@ -357,10 +357,10 @@ split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])</code> <c>{no_foo, true}</c> in <c>L</c> with <c>{foo, false}</c>, and any other tuple <c>{no_foo, ...}</c> with <c>foo</c>.</p> <p>See also - <seealso marker="#get_bool/2"><c>get_bool/2</c></seealso>, - <seealso marker="#normalize/2"><c>normalize/2</c></seealso>, - <seealso marker="#substitute_aliases/2"> - <c>substitute_aliases/2</c></seealso>.</p> + <seemfa marker="#get_bool/2"><c>get_bool/2</c></seemfa>, + <seemfa marker="#normalize/2"><c>normalize/2</c></seemfa>, + <seemfa marker="#substitute_aliases/2"> + <c>substitute_aliases/2</c></seemfa>.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/qlc.xml b/lib/stdlib/doc/src/qlc.xml index 34f7c5bab9..7c3c9e2e70 100644 --- a/lib/stdlib/doc/src/qlc.xml +++ b/lib/stdlib/doc/src/qlc.xml @@ -37,9 +37,9 @@ </modulesummary> <description> <p>This module provides a query interface to - <seealso marker="mnesia:mnesia">Mnesia</seealso>, - <seealso marker="ets">ETS</seealso>, - <seealso marker="dets">Dets</seealso>, + <seeerl marker="mnesia:mnesia">Mnesia</seeerl>, + <seeerl marker="ets">ETS</seeerl>, + <seeerl marker="dets">Dets</seeerl>, and other data structures that provide an iterator style traversal of objects.</p> </description> @@ -49,41 +49,41 @@ <p>This module provides a query interface to <em>QLC tables</em>. Typical QLC tables are Mnesia, ETS, and Dets tables. Support is also provided for user-defined tables, see section - <seealso marker="#implementing_a_qlc_table"> - Implementing a QLC Table</seealso>. + <seeerl marker="#implementing_a_qlc_table"> + Implementing a QLC Table</seeerl>. <marker id="query_list_comprehension"></marker> A <em>query</em> is expressed using <em>Query List Comprehensions</em> (QLCs). The answers to a query are determined by data in QLC tables that fulfill the constraints expressed by the QLCs of the query. QLCs are similar to ordinary list comprehensions as described in - <seealso marker="doc/reference_manual:expressions#lcs"> - Erlang Reference Manual</seealso> and - <seealso marker="doc/programming_examples:list_comprehensions"> - Programming Examples</seealso>, except that variables + <seeguide marker="system/reference_manual:expressions#lcs"> + Erlang Reference Manual</seeguide> and + <seeguide marker="system/programming_examples:list_comprehensions"> + Programming Examples</seeguide>, except that variables introduced in patterns cannot be used in list expressions. In the absence of optimizations and options such as <c>cache</c> and <c>unique</c> (see section - <seealso marker="#common_options">Common Options</seealso>, every + <seeerl marker="#common_options">Common Options</seeerl>, every QLC free of QLC tables evaluates to the same list of answers as the identical ordinary list comprehension.</p> <p>While ordinary list comprehensions evaluate to lists, calling - <seealso marker="#q/1"><c>q/1,2</c></seealso> returns a + <seemfa marker="#q/1"><c>q/1,2</c></seemfa> returns a <marker id="query_handle"></marker><em>query handle</em>. - To obtain all the answers to a query, <seealso marker="#eval/1"> - <c>eval/1,2</c></seealso> is to be called with the + To obtain all the answers to a query, <seemfa marker="#eval/1"> + <c>eval/1,2</c></seemfa> is to be called with the query handle as first argument. Query handles are essentially functional objects (funs) created in the module calling <c>q/1,2</c>. As the funs refer to the module code, be careful not to keep query handles too long if the module code is to be replaced. Code replacement is described in section - <seealso marker="doc/reference_manual:code_loading"> - Compilation and Code Loading</seealso> in the Erlang Reference Manual. + <seeguide marker="system/reference_manual:code_loading"> + Compilation and Code Loading</seeguide> in the Erlang Reference Manual. The list of answers can also be traversed in chunks by use of a <marker id="query_cursor"></marker><em>query cursor</em>. Query cursors are created by calling - <seealso marker="#cursor/1"><c>cursor/1,2</c></seealso> with a query + <seemfa marker="#cursor/1"><c>cursor/1,2</c></seemfa> with a query handle as first argument. Query cursors are essentially Erlang processes. One answer at a time is sent from the query cursor process to the process that created the cursor.</p> @@ -104,13 +104,13 @@ <c><![CDATA[Pattern <- ListExpression]]></c>, where <c>ListExpression</c> is an expression evaluating to a query handle or a list. Query handles are returned from - <seealso marker="#append/1"><c>append/1,2</c></seealso>, - <seealso marker="#keysort/2"><c>keysort/2,3</c></seealso>, - <seealso marker="#q/1"><c>q/1,2</c></seealso>, - <seealso marker="#sort/1"><c>sort/1,2</c></seealso>, - <seealso marker="#string_to_handle/1"> - <c>string_to_handle/1,2,3</c></seealso>, and - <seealso marker="#table/2"><c>table/2</c></seealso>.</p> + <seemfa marker="#append/1"><c>append/1,2</c></seemfa>, + <seemfa marker="#keysort/2"><c>keysort/2,3</c></seemfa>, + <seemfa marker="#q/1"><c>q/1,2</c></seemfa>, + <seemfa marker="#sort/1"><c>sort/1,2</c></seemfa>, + <seemfa marker="#string_to_handle/1"> + <c>string_to_handle/1,2,3</c></seemfa>, and + <seemfa marker="#table/2"><c>table/2</c></seemfa>.</p> </section> <section> @@ -200,10 +200,10 @@ <marker id="common_options"></marker> <title>Common Options</title> <p>The following options are accepted by - <seealso marker="#cursor/2"><c>cursor/2</c></seealso>, - <seealso marker="#eval/2"><c>eval/2</c></seealso>, - <seealso marker="#fold/4"><c>fold/4</c></seealso>, and - <seealso marker="#info/2"><c>info/2</c></seealso>:</p> + <seemfa marker="#cursor/2"><c>cursor/2</c></seemfa>, + <seemfa marker="#eval/2"><c>eval/2</c></seemfa>, + <seemfa marker="#fold/4"><c>fold/4</c></seemfa>, and + <seemfa marker="#info/2"><c>info/2</c></seemfa>:</p> <list type="bulleted"> <item><p><c>{cache_all, Cache}</c>, where <c>Cache</c> is @@ -230,15 +230,15 @@ The values <c>info_msg</c>, <c>warning_msg</c>, and <c>error_msg</c> mean that the function with the corresponding name in module - <seealso marker="kernel:error_logger"><c>error_logger</c></seealso> + <seeerl marker="kernel:error_logger"><c>error_logger</c></seeerl> is called for printing some information (currently the stacktrace).</p> </item> <item><p><c>{tmpdir, TempDirectory}</c> sets the directory used by merge join for temporary files and by option <c>{cache, list}</c>. The option also overrides option <c>tmpdir</c> of - <seealso marker="#keysort/3"><c>keysort/3</c></seealso> and - <seealso marker="#sort/2"><c>sort/2</c></seealso>. + <seemfa marker="#keysort/3"><c>keysort/3</c></seemfa> and + <seemfa marker="#sort/2"><c>sort/2</c></seemfa>. Defaults to <c>""</c>, which means that the directory returned by <c>file:get_cwd()</c> is used.</p> </item> @@ -257,11 +257,11 @@ <p>As mentioned earlier, queries are expressed in the list comprehension syntax as described in section - <seealso marker="doc/reference_manual:expressions">Expressions</seealso> + <seeguide marker="system/reference_manual:expressions">Expressions</seeguide> in Erlang Reference Manual. In the following, some familiarity with list comprehensions is assumed. The examples in section - <seealso marker="doc/programming_examples:list_comprehensions"> - List Comprehensions</seealso> in Programming Examples can get you + <seeguide marker="system/programming_examples:list_comprehensions"> + List Comprehensions</seeguide> in Programming Examples can get you started. Notice that list comprehensions do not add any computational power to the language; anything that can be done with list comprehensions can also be done without them. But they add @@ -277,7 +277,7 @@ <c>Y</c> is introduced in the first generator and used in the second. The ordinary list comprehension is normally to be preferred when there is a choice as to which to use. One difference is that - <seealso marker="#eval/1"><c>eval/1,2</c></seealso> + <seemfa marker="#eval/1"><c>eval/1,2</c></seemfa> collects answers in a list that is finally reversed, while list comprehensions collect answers on the stack that is finally unwound.</p> @@ -285,26 +285,26 @@ <p>What the <c>qlc</c> module primarily adds to list comprehensions is that data can be read from QLC tables in small chunks. A QLC table is created by calling - <seealso marker="#table/2"><c>qlc:table/2</c></seealso>. + <seemfa marker="#table/2"><c>qlc:table/2</c></seemfa>. Usually <c>qlc:table/2</c> is not called directly from the query but through an interface function of some data structure. Erlang/OTP includes a few examples of such functions: - <seealso marker="mnesia:mnesia#table/1"><c>mnesia:table/1,2</c></seealso>, - <seealso marker="ets#table/1"><c>ets:table/1,2</c></seealso>, and - <seealso marker="dets#table/1"><c>dets:table/1,2</c></seealso>. + <seemfa marker="mnesia:mnesia#table/1"><c>mnesia:table/1,2</c></seemfa>, + <seemfa marker="ets#table/1"><c>ets:table/1,2</c></seemfa>, and + <seemfa marker="dets#table/1"><c>dets:table/1,2</c></seemfa>. For a given data structure, many functions can create QLC tables, but common for these functions is that they return a query handle created by - <seealso marker="#table/2"><c>qlc:table/2</c></seealso>. + <seemfa marker="#table/2"><c>qlc:table/2</c></seemfa>. Using the QLC tables provided by Erlang/OTP is usually probably sufficient, but for the more advanced user section - <seealso marker="#implementing_a_qlc_table">Implementing a QLC - Table</seealso> describes the implementation of a function + <seeerl marker="#implementing_a_qlc_table">Implementing a QLC + Table</seeerl> describes the implementation of a function calling <c>qlc:table/2</c>.</p> <p>Besides <c>qlc:table/2</c>, other functions return query handles. They are used more seldom than tables, but are sometimes useful. - <seealso marker="#append/1"><c>qlc:append/1,2</c></seealso> traverses + <seemfa marker="#append/1"><c>qlc:append/1,2</c></seemfa> traverses objects from many tables or lists after each other. If, for example, you want to traverse all answers to a query <c>QH</c> and then finish off by a term <c>{finished}</c>, you can do that by @@ -389,9 +389,9 @@ R.]]></code> the filter is run M*N times.</p> <p>If <c>QH2</c> is a call to the function for - <seealso marker="gb_trees"><c>gb_trees</c></seealso>, as defined - in section <seealso marker="#implementing_a_qlc_table">Implementing - a QLC Table</seealso>, then <c>gb_table:table/1</c>, the + <seeerl marker="gb_trees"><c>gb_trees</c></seeerl>, as defined + in section <seeerl marker="#implementing_a_qlc_table">Implementing + a QLC Table</seeerl>, then <c>gb_table:table/1</c>, the iterator for the gb-tree is initiated for each answer to <c>QH1</c>. The objects of the gb-tree are then returned one by one. This is probably the most efficient way of traversing @@ -432,8 +432,8 @@ R.]]></code> lists is that if the list size exceeds a limit, a temporary file is used. Reading the answers from a file is much slower than copying them from an ETS table. But if the - available RAM memory is scarce, setting the <seealso - marker="#max_list_size">limit</seealso> to some low value is an + available RAM memory is scarce, setting the <seeerl + marker="#max_list_size">limit</seeerl> to some low value is an alternative.</p> <p>Option <c>cache_all</c> can be set to @@ -449,9 +449,9 @@ R.]]></code> <marker id="implementing_a_qlc_table"></marker> <title>Implementing a QLC Table</title> <p>As an example of - how to use function <seealso marker="#table/2"><c>table/2</c></seealso>, - the implementation of a QLC table for the <seealso - marker="gb_trees"><c>gb_trees</c></seealso> module is given:</p> + how to use function <seemfa marker="#table/2"><c>table/2</c></seemfa>, + the implementation of a QLC table for the <seeerl + marker="gb_trees"><c>gb_trees</c></seeerl> module is given:</p> <code type="none"> <![CDATA[-module(gb_table). @@ -529,7 +529,7 @@ gb_iter(I0, N, EFun) -> <c>{Key, Value}</c> pairs, as the traversal function does.</p> <p>The format function is also optional. It is called by - <seealso marker="#info/1"><c>info/1,2</c></seealso> + <seemfa marker="#info/1"><c>info/1,2</c></seemfa> to give feedback at runtime of how the query is to be evaluated. Try to give as good feedback as possible without showing too much details. In the example, at @@ -593,8 +593,8 @@ ets:match_spec_run( exactly as <c>=:=/2</c> would have been handled. However, if it cannot be determined at compile time that some constant is free of integers, and the table uses <c>=:=/2</c> - when comparing keys for equality (see option <seealso - marker="#key_equality">key_equality</seealso>), then the + when comparing keys for equality (see option <seeerl + marker="#key_equality">key_equality</seeerl>), then the <c>qlc</c> module does not try to look up the constant. The reason is that there is in the general case no upper limit on the number of key values that can compare equal to such a @@ -648,8 +648,8 @@ ets:match_spec_run(ets:lookup(#Ref<0.3098908599.2283929601.256211>, <datatypes> <datatype> <name name="abstract_expr"></name> - <desc><p>Parse trees for Erlang expression, see section <seealso - marker="erts:absform">The Abstract Format</seealso> + <desc><p>Parse trees for Erlang expression, see section <seeguide + marker="erts:absform">The Abstract Format</seeguide> in the ERTS User's Guide.</p></desc> </datatype> <datatype> @@ -663,10 +663,10 @@ ets:match_spec_run(ets:lookup(#Ref<0.3098908599.2283929601.256211>, </datatype> <datatype> <name name="match_expression"></name> - <desc><p>Match specification, see section <seealso - marker="erts:match_spec">Match Specifications in Erlang</seealso> - in the ERTS User's Guide and <seealso - marker="ms_transform"><c>ms_transform(3)</c></seealso>.</p></desc> + <desc><p>Match specification, see section <seeguide + marker="erts:match_spec">Match Specifications in Erlang</seeguide> + in the ERTS User's Guide and <seeerl + marker="ms_transform"><c>ms_transform(3)</c></seeerl>.</p></desc> </datatype> <datatype> <name name="no_files"></name> @@ -686,12 +686,12 @@ ets:match_spec_run(ets:lookup(#Ref<0.3098908599.2283929601.256211>, </datatype> <datatype> <name name="query_cursor"></name> - <desc><p>A <seealso marker="#query_cursor">query cursor</seealso>.</p> + <desc><p>A <seeerl marker="#query_cursor">query cursor</seeerl>.</p> </desc> </datatype> <datatype> <name name="query_handle"></name> - <desc><p>A <seealso marker="#query_handle">query handle</seealso>.</p> + <desc><p>A <seeerl marker="#query_handle">query handle</seeerl>.</p> </desc> </datatype> <datatype> @@ -700,8 +700,8 @@ ets:match_spec_run(ets:lookup(#Ref<0.3098908599.2283929601.256211>, <datatype> <name name="query_list_comprehension"></name> <desc><p>A literal - <seealso marker="#query_list_comprehension">query - list comprehension</seealso>.</p></desc> + <seeerl marker="#query_list_comprehension">query + list comprehension</seeerl>.</p></desc> </datatype> <datatype> <name name="spawn_options"></name> @@ -711,8 +711,8 @@ ets:match_spec_run(ets:lookup(#Ref<0.3098908599.2283929601.256211>, </datatype> <datatype> <name name="sort_option"></name> - <desc><p>See <seealso - marker="file_sorter"><c>file_sorter(3)</c></seealso>.</p></desc> + <desc><p>See <seeerl + marker="file_sorter"><c>file_sorter(3)</c></seeerl>.</p></desc> </datatype> <datatype> <name name="tmp_directory"></name> @@ -755,11 +755,11 @@ ets:match_spec_run(ets:lookup(#Ref<0.3098908599.2283929601.256211>, <p>Creates a query cursor and makes the calling process the owner of the cursor. The cursor is to be used as argument to - <seealso marker="#next_answers/1"> - <c>next_answers/1,2</c></seealso> and (eventually) - <seealso marker="#delete_cursor/1"><c>delete_cursor/1</c></seealso>. - Calls <seealso marker="erts:erlang#spawn_opt/2"> - <c>erlang:spawn_opt/2</c></seealso> to spawn and link to + <seemfa marker="#next_answers/1"> + <c>next_answers/1,2</c></seemfa> and (eventually) + <seemfa marker="#delete_cursor/1"><c>delete_cursor/1</c></seemfa>. + Calls <seemfa marker="erts:erlang#spawn_opt/2"> + <c>erlang:spawn_opt/2</c></seemfa> to spawn and link to a process that evaluates the query handle. The value of option <c>spawn_options</c> is used as last argument when calling <c>spawn_opt/2</c>. Defaults to <c>[link]</c>.</p> @@ -958,8 +958,8 @@ end</pre> <desc> <p>Returns a query handle. When evaluating query handle <c><anno>QH2</anno></c>, the answers to query handle - <c><anno>QH1</anno></c> are sorted by <seealso - marker="file_sorter#keysort/4"><c>file_sorter:keysort/4</c></seealso> + <c><anno>QH1</anno></c> are sorted by <seemfa + marker="file_sorter#keysort/4"><c>file_sorter:keysort/4</c></seemfa> according to the options.</p> <p>The sorter uses temporary files only if <c><anno>QH1</anno></c> does not evaluate to a list and the @@ -1004,7 +1004,7 @@ end</pre> <p>When calling <c>qlc:q/1,2</c> from the Erlang shell, the parse transform is automatically called. When this occurs, the fun substituted for the QLC is not compiled but is evaluated by - <seealso marker="erl_eval"><c>erl_eval(3)</c></seealso>. This + <seeerl marker="erl_eval"><c>erl_eval(3)</c></seeerl>. This is also true when expressions are evaluated by <c>file:eval/1,2</c> or in the debugger.</p> <p>To be explicit, this does not work:</p> @@ -1062,7 +1062,7 @@ QH = qlc:q(A), table only. If option <c>unique</c> is combined with option <c>{cache, list}</c>, the answers are sorted twice using - <seealso marker="#keysort/3"><c>keysort/3</c></seealso>; + <seemfa marker="#keysort/3"><c>keysort/3</c></seemfa>; once to remove duplicates and once to restore the order.</p> </item> </list> @@ -1110,14 +1110,14 @@ begin X =:= Y ]) end</pre> - <p><seealso marker="#sort/1"><c>sort/1,2</c></seealso> and - <seealso marker="#keysort/2"><c>keysort/2,3</c></seealso> + <p><seemfa marker="#sort/1"><c>sort/1,2</c></seemfa> and + <seemfa marker="#keysort/2"><c>keysort/2,3</c></seemfa> can also be used for caching answers and for removing duplicates. When sorting answers are cached in a list, possibly stored on a temporary file, and no ETS tables are used.</p> - <p>Sometimes (see <seealso - marker="#table/2"><c>table/2</c></seealso>) traversal + <p>Sometimes (see <seemfa + marker="#table/2"><c>table/2</c></seemfa>) traversal of tables can be done by looking up key values, which is assumed to be fast. Under certain (rare) circumstances there can be too many key values to look up. @@ -1130,8 +1130,8 @@ end</pre> number of keys to look up.</p> <p><em>Example:</em></p> <p>In the following example, using the <c>gb_table</c> module from - section <seealso marker="#implementing_a_qlc_table">Implementing a - QLC Table</seealso>, there are six keys to look up: + section <seeerl marker="#implementing_a_qlc_table">Implementing a + QLC Table</seeerl>, there are six keys to look up: <c>{1,a}</c>, <c>{1,b}</c>, <c>{1,c}</c>, <c>{2,a}</c>, <c>{2,b}</c>, and <c>{2,c}</c>. The reason is that the two elements of key <c>{X, Y}</c> are compared separately.</p> @@ -1207,8 +1207,8 @@ ets:match_spec_run( <desc> <p>Returns a query handle. When evaluating query handle <c><anno>QH2</anno></c>, the answers to query handle - <c><anno>QH1</anno></c> are sorted by <seealso - marker="file_sorter#sort/3"><c>file_sorter:sort/3</c></seealso> + <c><anno>QH1</anno></c> are sorted by <seemfa + marker="file_sorter#sort/3"><c>file_sorter:sort/3</c></seemfa> according to the options.</p> <p>The sorter uses temporary files only if <c><anno>QH1</anno></c> does not evaluate to a list and the @@ -1226,10 +1226,10 @@ ets:match_spec_run( <name name="string_to_handle" arity="3" since=""/> <fsummary>Return a handle for a query list comprehension.</fsummary> <desc> - <p>A string version of <seealso marker="#q/1"><c>q/1,2</c></seealso>. + <p>A string version of <seemfa marker="#q/1"><c>q/1,2</c></seemfa>. When the query handle is evaluated, the fun created by the parse transform is interpreted by - <seealso marker="erl_eval"><c>erl_eval(3)</c></seealso>. + <seeerl marker="erl_eval"><c>erl_eval(3)</c></seeerl>. The query string is to be one single QLC terminated by a period.</p> <p><em>Example:</em></p> <pre> @@ -1283,15 +1283,15 @@ ets:match_spec_run( <p>Modules that can use match specifications for optimized traversal of tables are to call <c>qlc:table/2</c> with an unary <c><anno>TraverseFun</anno></c>. An example is - <seealso marker="ets#table/2"> - <c>ets:table/2</c></seealso>.</p> + <seemfa marker="ets#table/2"> + <c>ets:table/2</c></seemfa>.</p> </item> <item> <p>Other modules can provide a nullary <c><anno>TraverseFun</anno></c>. An example is <c>gb_table:table/1</c> in section - <seealso marker="#implementing_a_qlc_table">Implementing a - QLC Table</seealso>.</p> + <seeerl marker="#implementing_a_qlc_table">Implementing a + QLC Table</seeerl>.</p> </item> </list> </item> @@ -1310,9 +1310,9 @@ ets:match_spec_run( <c><anno>ParentFun</anno></c> is called once just before the call of <c><anno>PreFun</anno></c> in the context of the process calling - <seealso marker="#eval/1"><c>eval/1,2</c></seealso>, - <seealso marker="#fold/3"><c>fold/3,4</c></seealso>, or - <seealso marker="#cursor/1"><c>cursor/1,2</c></seealso>. + <seemfa marker="#eval/1"><c>eval/1,2</c></seemfa>, + <seemfa marker="#fold/3"><c>fold/3,4</c></seemfa>, or + <seemfa marker="#cursor/1"><c>cursor/1,2</c></seemfa>. </p> </item> <item> @@ -1361,7 +1361,7 @@ ets:match_spec_run( chosen. If there is a tie between two indexed positions, the one occurring first in the list returned by <c><anno>InfoFun</anno></c> is chosen. Positions requiring - more than <seealso marker="#max_lookup">max_lookup</seealso> + more than <seeerl marker="#max_lookup">max_lookup</seeerl> lookups are ignored.</p> </item> <item> @@ -1391,7 +1391,7 @@ ets:match_spec_run( </item> <item> <p>Unary callback function <c><anno>FormatFun</anno></c> - is used by <seealso marker="#info/1"><c>info/1,2</c></seealso> + is used by <seemfa marker="#info/1"><c>info/1,2</c></seemfa> for displaying the call that created the query handle of the table. Defaults to <c>undefined</c>, which means that <c>info/1,2</c> displays a call to <c>'$MOD':'$FUN'/0</c>. @@ -1448,9 +1448,9 @@ ets:match_spec_run( </list> <p>For the various options recognized by <c>table/1,2</c> in respective module, see - <seealso marker="ets#table/1"><c>ets(3)</c></seealso>, - <seealso marker="dets#table/1"><c>dets(3)</c></seealso>, and - <seealso marker="mnesia:mnesia#table/1"><c>mnesia(3)</c></seealso>. + <seemfa marker="ets#table/1"><c>ets(3)</c></seemfa>, + <seemfa marker="dets#table/1"><c>dets(3)</c></seemfa>, and + <seemfa marker="mnesia:mnesia#table/1"><c>mnesia(3)</c></seemfa>. </p> </desc> </func> @@ -1458,18 +1458,18 @@ ets:match_spec_run( <section> <title>See Also</title> - <p><seealso marker="dets"><c>dets(3)</c></seealso>, - <seealso marker="erl_eval"><c>erl_eval(3)</c></seealso>, - <seealso marker="erts:erlang"><c>erlang(3)</c></seealso>, - <seealso marker="kernel:error_logger"><c>error_logger(3)</c></seealso>, - <seealso marker="ets"><c>ets(3)</c></seealso>, - <seealso marker="kernel:file"><c>file(3)</c></seealso>, - <seealso marker="file_sorter"><c>file_sorter(3)</c></seealso>, - <seealso marker="mnesia:mnesia"><c>mnesia(3)</c></seealso>, - <seealso marker="shell"><c>shell(3)</c></seealso>, - <seealso marker="doc/reference_manual:users_guide"> - Erlang Reference Manual</seealso>, - <seealso marker="doc/programming_examples:users_guide"> - Programming Examples</seealso></p> + <p><seeerl marker="dets"><c>dets(3)</c></seeerl>, + <seeerl marker="erl_eval"><c>erl_eval(3)</c></seeerl>, + <seeerl marker="erts:erlang"><c>erlang(3)</c></seeerl>, + <seeerl marker="kernel:error_logger"><c>error_logger(3)</c></seeerl>, + <seeerl marker="ets"><c>ets(3)</c></seeerl>, + <seeerl marker="kernel:file"><c>file(3)</c></seeerl>, + <seeerl marker="file_sorter"><c>file_sorter(3)</c></seeerl>, + <seeerl marker="mnesia:mnesia"><c>mnesia(3)</c></seeerl>, + <seeerl marker="shell"><c>shell(3)</c></seeerl>, + <seeguide marker="system/reference_manual:index"> + Erlang Reference Manual</seeguide>, + <seeguide marker="system/programming_examples:index"> + Programming Examples</seeguide></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/queue.xml b/lib/stdlib/doc/src/queue.xml index ef0ce5681f..69b66129fa 100644 --- a/lib/stdlib/doc/src/queue.xml +++ b/lib/stdlib/doc/src/queue.xml @@ -53,11 +53,11 @@ assuming knowledge of the format is running on thin ice.</p> <p>All operations have an amortized O(1) running time, except - <seealso marker="#filter/2"><c>filter/2</c></seealso>, - <seealso marker="#join/2"><c>join/2</c></seealso>, - <seealso marker="#len/1"><c>len/1</c></seealso>, - <seealso marker="#member/2"><c>member/2</c></seealso>, - <seealso marker="#split/2"><c>split/2</c></seealso> that have O(n). + <seemfa marker="#filter/2"><c>filter/2</c></seemfa>, + <seemfa marker="#join/2"><c>join/2</c></seemfa>, + <seemfa marker="#len/1"><c>len/1</c></seemfa>, + <seemfa marker="#member/2"><c>member/2</c></seemfa>, + <seemfa marker="#split/2"><c>split/2</c></seemfa> that have O(n). To minimize the size of a queue minimizing the amount of garbage built by queue operations, the queues do not contain explicit length information, and that is @@ -96,15 +96,13 @@ some with more readable but perhaps less understandable aliases.</p> </description> - <section> - <title>Original API</title> - </section> + <datatypes> <datatype> <name name="queue" n_vars="1"/> <desc><p>As returned by - <seealso marker="#new/0"><c>new/0</c></seealso>.</p></desc> + <seemfa marker="#new/0"><c>new/0</c></seemfa>.</p></desc> </datatype> <datatype> <name name="queue" n_vars="0"/> @@ -112,6 +110,9 @@ </datatypes> <funcs> + <fsdescription> + <title>Original API</title> + </fsdescription> <func> <name name="filter" arity="2" since=""/> <fsummary>Filter a queue.</fsummary> @@ -270,11 +271,12 @@ </func> </funcs> - <section> - <title>Extended API</title> - </section> + <funcs> + <fsdescription> + <title>Extended API</title> + </fsdescription> <func> <name name="drop" arity="1" since=""/> <fsummary>Remove the front item from a queue.</fsummary> @@ -336,11 +338,12 @@ </func> </funcs> - <section> - <title>Okasaki API</title> - </section> + <funcs> + <fsdescription> + <title>Okasaki API</title> + </fsdescription> <func> <name name="cons" arity="2" since=""/> <fsummary>Insert an item at the head of a queue.</fsummary> diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index 5ed67dcaca..ac99736761 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -131,8 +131,8 @@ <p> The default algorithm is <c>exsss</c> (Xorshift116**). If a specific algorithm is - required, ensure to always use <seealso marker="#seed-1"> - <c>seed/1</c></seealso> to initialize the state. + required, ensure to always use <seemfa marker="#seed/1"> + <c>seed/1</c></seemfa> to initialize the state. </p> <p> @@ -179,10 +179,10 @@ variable <c>rand_seed</c> to remember the current state.</p> <p>If a process calls - <seealso marker="#uniform-0"><c>uniform/0</c></seealso>, - <seealso marker="#uniform-1"><c>uniform/1</c></seealso> or - <seealso marker="#uniform_real-0"><c>uniform_real/0</c></seealso> without - setting a seed first, <seealso marker="#seed-1"><c>seed/1</c></seealso> + <seemfa marker="#uniform/0"><c>uniform/0</c></seemfa>, + <seemfa marker="#uniform/1"><c>uniform/1</c></seemfa> or + <seemfa marker="#uniform_real/0"><c>uniform_real/0</c></seemfa> without + setting a seed first, <seemfa marker="#seed/1"><c>seed/1</c></seemfa> is called automatically with the default algorithm and creates a non-constant seed.</p> @@ -236,7 +236,7 @@ SND0 = math:sqrt(-2 * math:log(R5)) * math:cos(math:pi() * R6)</pre> <p>The builtin random number generator algorithms are not cryptographically strong. If a cryptographically strong random number generator is needed, use something like - <seealso marker="crypto:crypto#rand_seed-0"><c>crypto:rand_seed/0</c></seealso>. + <seemfa marker="crypto:crypto#rand_seed/0"><c>crypto:rand_seed/0</c></seemfa>. </p> </note> @@ -353,7 +353,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> <fsummary>Export the random number generation state.</fsummary> <desc><marker id="export_seed-0"/> <p>Returns the random number state in an external format. - To be used with <seealso marker="#seed-1"><c>seed/1</c></seealso>.</p> + To be used with <seemfa marker="#seed/1"><c>seed/1</c></seemfa>.</p> </desc> </func> @@ -362,7 +362,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> <fsummary>Export the random number generation state.</fsummary> <desc><marker id="export_seed_s-1"/> <p>Returns the random number generator state in an external format. - To be used with <seealso marker="#seed-1"><c>seed/1</c></seealso>.</p> + To be used with <seemfa marker="#seed/1"><c>seed/1</c></seemfa>.</p> </desc> </func> @@ -443,7 +443,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </p> <p>Otherwise recreates the exported seed in the process dictionary, and returns the state. See also - <seealso marker="#export_seed-0"><c>export_seed/0</c></seealso>.</p> + <seemfa marker="#export_seed/0"><c>export_seed/0</c></seemfa>.</p> </desc> </func> @@ -466,8 +466,8 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> is an algorithm. </p> <p>Otherwise recreates the exported seed and returns the state. - See also <seealso marker="#export_seed-0"> - <c>export_seed/0</c></seealso>.</p> + See also <seemfa marker="#export_seed/0"> + <c>export_seed/0</c></seemfa>.</p> </desc> </func> @@ -499,7 +499,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> fatal for certain applications. If that is undesired you can use <c>(1.0 - rand:uniform())</c> to get the interval <c>0.0 < <anno>X</anno> =< 1.0</c>, or instead use - <seealso marker="#uniform_real-0"><c>uniform_real/0</c></seealso>. + <seemfa marker="#uniform_real/0"><c>uniform_real/0</c></seemfa>. </p> <p> If neither endpoint is desired you can test and re-try @@ -537,7 +537,7 @@ end.</pre> <p> The generated numbers from this function has got better granularity for small numbers than the regular - <seealso marker="#uniform-0"><c>uniform/0</c></seealso> + <seemfa marker="#uniform/0"><c>uniform/0</c></seemfa> because all bits in the mantissa are random. This property, in combination with the fact that exactly zero is never returned is useful for algoritms doing for example @@ -546,7 +546,7 @@ end.</pre> </note> <p> See - <seealso marker="#uniform_real_s-1"><c>uniform_real_s/1</c></seealso> + <seemfa marker="#uniform_real_s/1"><c>uniform_real_s/1</c></seemfa> for more explanation. </p> </desc> @@ -582,7 +582,7 @@ end.</pre> fatal for certain applications. If that is undesired you can use <c>(1.0 - rand:uniform(State))</c> to get the interval <c>0.0 < <anno>X</anno> =< 1.0</c>, or instead use - <seealso marker="#uniform_real_s-1"><c>uniform_real_s/1</c></seealso>. + <seemfa marker="#uniform_real_s/1"><c>uniform_real_s/1</c></seemfa>. </p> <p> If neither endpoint is desired you can test and re-try @@ -620,7 +620,7 @@ end.</pre> <p> The generated numbers from this function has got better granularity for small numbers than the regular - <seealso marker="#uniform_s-1"><c>uniform_s/1</c></seealso> + <seemfa marker="#uniform_s/1"><c>uniform_s/1</c></seemfa> because all bits in the mantissa are random. This property, in combination with the fact that exactly zero is never returned is useful for algoritms doing for example @@ -650,13 +650,13 @@ end.</pre> <c>0 =< integer(N) < 2.0^53</c> the probability is the same. Compare that with the form of the numbers generated by - <seealso marker="#uniform_s-1"><c>uniform_s/1</c></seealso>. + <seemfa marker="#uniform_s/1"><c>uniform_s/1</c></seemfa>. </p> <p> Having to generate extra random bits for small numbers costs a little performance. This function is about 20% slower than the regular - <seealso marker="#uniform_s-1"><c>uniform_s/1</c></seealso> + <seemfa marker="#uniform_s/1"><c>uniform_s/1</c></seemfa> </p> </desc> </func> diff --git a/lib/stdlib/doc/src/random.xml b/lib/stdlib/doc/src/random.xml index 7566be0aab..30197d31fc 100644 --- a/lib/stdlib/doc/src/random.xml +++ b/lib/stdlib/doc/src/random.xml @@ -53,13 +53,13 @@ <p>This random number generator is not cryptographically strong. If a strong cryptographic random number generator is needed, use one of functions in the - <seealso marker="crypto:crypto"><c>crypto</c></seealso> - module, for example, <seealso marker="crypto:crypto"> - <c>crypto:strong_rand_bytes/1</c></seealso>.</p> + <seeerl marker="crypto:crypto"><c>crypto</c></seeerl> + module, for example, <seeerl marker="crypto:crypto"> + <c>crypto:strong_rand_bytes/1</c></seeerl>.</p> </note> <note> - <p>The improved <seealso marker="rand"><c>rand</c></seealso> + <p>The improved <seeerl marker="rand"><c>rand</c></seeerl> module is to be used instead of this module.</p> </note> </description> @@ -104,14 +104,14 @@ random:seed(erlang:phash2([node()]), erlang:monotonic_time(), erlang:unique_integer())</code> <p>For details, see - <seealso marker="erts:erlang#phash2/1"> - <c>erlang:phash2/1</c></seealso>, - <seealso marker="erts:erlang#node/0"> - <c>erlang:node/0</c></seealso>, - <seealso marker="erts:erlang#monotonic_time/0"> - <c>erlang:monotonic_time/0</c></seealso>, and - <seealso marker="erts:erlang#unique_integer/0"> - <c>erlang:unique_integer/0</c></seealso>.</p> + <seemfa marker="erts:erlang#phash2/1"> + <c>erlang:phash2/1</c></seemfa>, + <seemfa marker="erts:erlang#node/0"> + <c>erlang:node/0</c></seemfa>, + <seemfa marker="erts:erlang#monotonic_time/0"> + <c>erlang:monotonic_time/0</c></seemfa>, and + <seemfa marker="erts:erlang#unique_integer/0"> + <c>erlang:unique_integer/0</c></seemfa>.</p> </desc> </func> @@ -169,10 +169,10 @@ random:seed(erlang:phash2([node()]), <c>random_seed</c> to remember the current seed.</p> <p>If a process calls - <seealso marker="#uniform/0"><c>uniform/0</c></seealso> or - <seealso marker="#uniform/1"><c>uniform/1</c></seealso> + <seemfa marker="#uniform/0"><c>uniform/0</c></seemfa> or + <seemfa marker="#uniform/1"><c>uniform/1</c></seemfa> without setting a seed first, - <seealso marker="#seed/0"><c>seed/0</c></seealso> + <seemfa marker="#seed/0"><c>seed/0</c></seemfa> is called automatically.</p> <p>The implementation changed in Erlang/OTP R15. Upgrading to R15 breaks diff --git a/lib/stdlib/doc/src/re.xml b/lib/stdlib/doc/src/re.xml index 4fd7a6b3d7..11041e63b2 100644 --- a/lib/stdlib/doc/src/re.xml +++ b/lib/stdlib/doc/src/re.xml @@ -40,7 +40,7 @@ <p>This module contains regular expression matching functions for strings and binaries.</p> - <p>The <seealso marker="#regexp_syntax">regular expression</seealso> + <p>The <seeerl marker="#regexp_syntax">regular expression</seeerl> syntax and semantics resemble that of Perl.</p> <p>The matching algorithms of the library are based on the @@ -101,8 +101,8 @@ <p>Compiles a regular expression, with the syntax described below, into an internal format to be used later as a parameter to - <seealso marker="#run/2"><c>run/2</c></seealso> and - <seealso marker="#run/3"><c>run/3</c></seealso>.</p> + <seemfa marker="#run/2"><c>run/2</c></seemfa> and + <seemfa marker="#run/3"><c>run/3</c></seemfa>.</p> <p>Compiling the regular expression before matching is useful if the same expression is to be used in matching against multiple subjects during the lifetime of the program. Compiling once and @@ -281,8 +281,8 @@ the subject up to "A" and never realize that the (*COMMIT) instruction is to have made the matching fail. This option is only relevant if you use "start-of-pattern items", as discussed in - section <seealso marker="#regexp_syntax_details">PCRE Regular Expression - Details</seealso>.</p> + section <seeerl marker="#regexp_syntax_details">PCRE Regular Expression + Details</seeerl>.</p> </item> <tag><c>ucp</c></tag> <item> @@ -330,7 +330,7 @@ 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 specified as - an option to <seealso marker="#run/3"><c>run/3</c></seealso>. + an option to <seemfa marker="#run/3"><c>run/3</c></seemfa>. You can therefore create a name-to-value mapping from the result of <c>run/3</c> like this:</p> <code> @@ -365,7 +365,7 @@ <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 - <seealso marker="#run/3"><c>run/3</c></seealso>, except that option<c> + <seemfa marker="#run/3"><c>run/3</c></seemfa>, except that option<c> capture</c> 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 @@ -402,7 +402,7 @@ re:replace("abcd","c","[\\&]",[{return,list}]).</code> <code> "ab[&]d"</code> <p>As with <c>run/3</c>, compilation errors raise the <c>badarg</c> - exception. <seealso marker="#compile/2"><c>compile/2</c></seealso> + exception. <seemfa marker="#compile/2"><c>compile/2</c></seemfa> can be used to get more information about the error.</p> </desc> </func> @@ -420,8 +420,8 @@ re:replace("abcd","c","[\\&]",[{return,list}]).</code> <name name="run" arity="3" since=""/> <fsummary>Match a subject against regular expression and capture subpatterns.</fsummary> - <type_desc variable="CompileOpt">See <seealso marker="#compile_options"> - <c>compile/2</c></seealso>.</type_desc> + <type_desc variable="CompileOpt">See <seeerl marker="#compile_options"> + <c>compile/2</c></seeerl>.</type_desc> <desc> <p>Executes a regular expression matching, and returns <c>match/{match, <anno>Captured</anno>}</c> or <c>nomatch</c>. The @@ -638,8 +638,8 @@ a?b?</code> before that (each recursive call is also a call, but not conversely). Both limits can however be changed, either by setting limits directly in the regular expression string (see - section <seealso marker="#regexp_syntax_details">PCRE Regular - Eexpression Details</seealso>) or by specifying options to + section <seeerl marker="#regexp_syntax_details">PCRE Regular + Eexpression Details</seeerl>) or by specifying options to <c>run/3</c>.</p> </item> </taglist> @@ -819,8 +819,8 @@ re:run("ABCabcdABC",".*(abcd).*",[]).</code> as if a <c>list()</c> of all the names <em>in alphabetical order</em> was specified. The list of all names can also be retrieved with - <seealso marker="#inspect/2"> - <c>inspect/2</c></seealso>.</p> + <seemfa marker="#inspect/2"> + <c>inspect/2</c></seemfa>.</p> </item> <tag><c>first</c></tag> <item> @@ -902,10 +902,10 @@ re:run("ABCabcdABC",".*(?<FOO>abcd).*",[{capture,['FOO']}]).</code> <p>Returns 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 <seealso marker="erts:erlang#iolist_to_binary/1"> - <c>erlang:iolist_to_binary/1</c></seealso> or - <seealso marker="unicode#characters_to_binary/2"> - <c>unicode:characters_to_binary/2</c></seealso> before + with <seemfa marker="erts:erlang#iolist_to_binary/1"> + <c>erlang:iolist_to_binary/1</c></seemfa> or + <seemfa marker="unicode#characters_to_binary/2"> + <c>unicode:characters_to_binary/2</c></seemfa> before matching). Notice that option <c>unicode</c> results in <em>byte-oriented</em> indexes in a (possibly virtual) <em>UTF-8 encoded</em> binary. A byte index tuple @@ -926,8 +926,8 @@ re:run("ABCabcdABC",".*(?<FOO>abcd).*",[{capture,['FOO']}]).</code> regardless of character encoding). In that case the <c>list</c> capturing can result in the same types of tuples that - <seealso marker="unicode#characters_to_list/2"> - <c>unicode:characters_to_list/2</c></seealso> can return, + <seemfa marker="unicode#characters_to_list/2"> + <c>unicode:characters_to_list/2</c></seemfa> can return, namely three-tuples with tag <c>incomplete</c> or <c>error</c>, the successfully converted characters and the invalid UTF-8 tail of the conversion as a binary. The @@ -987,7 +987,7 @@ re:run("cacb","c(a|b)",[global,{capture,[1],list}]).</code> </item> </taglist> <p>For a descriptions of options only affecting the compilation step, - see <seealso marker="#compile/2"><c>compile/2</c></seealso>.</p> + see <seemfa marker="#compile/2"><c>compile/2</c></seemfa>.</p> </desc> </func> @@ -1003,15 +1003,15 @@ re:run("cacb","c(a|b)",[global,{capture,[1],list}]).</code> <func> <name name="split" arity="3" since=""/> <fsummary>Split a string by tokens specified as a regular expression</fsummary> - <type_desc variable="CompileOpt">See <seealso marker="#compile_options"> - <c>compile/2</c></seealso>.</type_desc> + <type_desc variable="CompileOpt">See <seeerl marker="#compile_options"> + <c>compile/2</c></seeerl>.</type_desc> <desc> <p>Splits the input into parts by finding tokens according to the regular expression supplied. The splitting is basically done by running a global regular expression match and dividing the initial string wherever a match occurs. The matching part of the string is removed from the output.</p> - <p>As in <seealso marker="#run/3"><c>run/3</c></seealso>, an <c>mp()</c> + <p>As in <seemfa marker="#run/3"><c>run/3</c></seemfa>, an <c>mp()</c> compiled with option <c>unicode</c> requires <c><anno>Subject</anno></c> to be a Unicode <c>charlist()</c>. If compilation is done implicitly and the <c>unicode</c> compilation @@ -1187,46 +1187,46 @@ re:split("Erlang","[lg]",[{return,list},{parts,4}]).</code> <p>The reference material is divided into the following sections:</p> <list type="bulleted"> - <item><seealso marker="#sect1">Special Start-of-Pattern Items</seealso> + <item><seeerl marker="#sect1">Special Start-of-Pattern Items</seeerl> </item> - <item><seealso marker="#sect2">Characters and Metacharacters</seealso> + <item><seeerl marker="#sect2">Characters and Metacharacters</seeerl> </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) and \N</seealso> + <item><seeerl marker="#sect3">Backslash</seeerl></item> + <item><seeerl marker="#sect4">Circumflex and Dollar</seeerl></item> + <item><seeerl marker="#sect5">Full Stop (Period, Dot) and \N</seeerl> </item> - <item><seealso marker="#sect6">Matching a Single Data Unit</seealso> + <item><seeerl marker="#sect6">Matching a Single Data Unit</seeerl> </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> - <item><seealso marker="#sect10">Internal Option Setting</seealso></item> - <item><seealso marker="#sect11">Subpatterns</seealso></item> - <item><seealso marker="#sect12">Duplicate Subpattern Numbers</seealso> + <item><seeerl marker="#sect7">Square Brackets and Character + Classes</seeerl></item> + <item><seeerl marker="#sect8">Posix Character Classes</seeerl></item> + <item><seeerl marker="#sect9">Vertical Bar</seeerl></item> + <item><seeerl marker="#sect10">Internal Option Setting</seeerl></item> + <item><seeerl marker="#sect11">Subpatterns</seeerl></item> + <item><seeerl marker="#sect12">Duplicate Subpattern Numbers</seeerl> </item> - <item><seealso marker="#sect13">Named Subpatterns</seealso></item> - <item><seealso marker="#sect14">Repetition</seealso></item> - <item><seealso marker="#sect15">Atomic Grouping and Possessive - Quantifiers</seealso></item> - <item><seealso marker="#sect16">Back References</seealso></item> - <item><seealso marker="#sect17">Assertions</seealso></item> - <item><seealso marker="#sect18">Conditional Subpatterns</seealso></item> - <item><seealso marker="#sect19">Comments</seealso></item> - <item><seealso marker="#sect20">Recursive Patterns</seealso></item> - <item><seealso marker="#sect21">Subpatterns as Subroutines</seealso> + <item><seeerl marker="#sect13">Named Subpatterns</seeerl></item> + <item><seeerl marker="#sect14">Repetition</seeerl></item> + <item><seeerl marker="#sect15">Atomic Grouping and Possessive + Quantifiers</seeerl></item> + <item><seeerl marker="#sect16">Back References</seeerl></item> + <item><seeerl marker="#sect17">Assertions</seeerl></item> + <item><seeerl marker="#sect18">Conditional Subpatterns</seeerl></item> + <item><seeerl marker="#sect19">Comments</seeerl></item> + <item><seeerl marker="#sect20">Recursive Patterns</seeerl></item> + <item><seeerl marker="#sect21">Subpatterns as Subroutines</seeerl> </item> - <item><seealso marker="#sect22">Oniguruma Subroutine Syntax</seealso> + <item><seeerl marker="#sect22">Oniguruma Subroutine Syntax</seeerl> </item> - <item><seealso marker="#sect23">Backtracking Control</seealso></item> + <item><seeerl marker="#sect23">Backtracking Control</seeerl></item> </list> </section> <section> <marker id="sect1"></marker> <title>Special Start-of-Pattern Items</title> - <p>Some options that can be passed to <seealso marker="#compile/2"> - <c>compile/2</c></seealso> can also be set by special items at the start + <p>Some options that can be passed to <seemfa marker="#compile/2"> + <c>compile/2</c></seemfa> 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 can @@ -1236,8 +1236,8 @@ re:split("Erlang","[lg]",[{return,list},{parts,4}]).</code> <p><em>UTF Support</em></p> <p>Unicode support is basically UTF-8 based. To use Unicode characters, you - either call <seealso marker="#compile/2"><c>compile/2</c></seealso> or - <seealso marker="#run/3"><c>run/3</c></seealso> with option + either call <seemfa marker="#compile/2"><c>compile/2</c></seemfa> or + <seemfa marker="#run/3"><c>run/3</c></seemfa> with option <c>unicode</c>, or the pattern must start with one of these special sequences:</p> @@ -1250,7 +1250,7 @@ re:split("Erlang","[lg]",[{return,list},{parts,4}]).</code> lists to UTF-8 is not performed by the <c>re</c> functions. Therefore, using these sequences is not recommended. Add option <c>unicode</c> when running - <seealso marker="#compile/2"><c>compile/2</c></seealso> instead.</p> + <seemfa marker="#compile/2"><c>compile/2</c></seemfa> instead.</p> <p>Some applications that allow their users to supply patterns can wish to restrict them to non-UTF data for security reasons. If option @@ -1297,7 +1297,7 @@ re:split("Erlang","[lg]",[{return,list},{parts,4}]).</code> </taglist> <p>These override the default and the options specified to - <seealso marker="#compile/2"><c>compile/2</c></seealso>. For example, the + <seemfa marker="#compile/2"><c>compile/2</c></seemfa>. For example, the following pattern changes the convention to CR:</p> <code> @@ -1312,13 +1312,13 @@ re:split("Erlang","[lg]",[{return,list},{parts,4}]).</code> 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 section - <seealso marker="#newline_sequences">Newline Sequences</seealso>. A change + <seeerl marker="#newline_sequences">Newline Sequences</seeerl>. A change of the \R setting can be combined with a change of the newline convention.</p> <p><em>Setting Match and Recursion Limits</em></p> - <p>The caller of <seealso marker="#run/3"><c>run/3</c></seealso> can set a + <p>The caller of <seemfa marker="#run/3"><c>run/3</c></seemfa> 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 @@ -2184,7 +2184,7 @@ foo\Kbar</code> they are independent of multiline mode. These three assertions are not affected by options <c>notbol</c> or <c>noteol</c>, which affect only the behavior of the circumflex and dollar metacharacters. However, if argument - <c>startoffset</c> of <seealso marker="#run/3"><c>run/3</c></seealso> is + <c>startoffset</c> of <seemfa marker="#run/3"><c>run/3</c></seemfa> is non-zero, indicating that matching is to start at a point other than the beginning of the subject, \A can never match. The difference between \Z and \z is that \Z matches before a newline at the end of the string and @@ -2218,7 +2218,7 @@ foo\Kbar</code> <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 argument <c>startoffset</c> of - <seealso marker="#run/3"><c>run/3</c></seealso> is non-zero, circumflex + <seemfa marker="#run/3"><c>run/3</c></seemfa> is non-zero, circumflex can never match if option <c>multiline</c> is unset. Inside a character class, circumflex has an entirely different meaning (see below).</p> @@ -2321,8 +2321,8 @@ foo\Kbar</code> (?=[\x{10000}-\x{1fffff}])(\C)(\C)(\C)(\C))</code> <p>A group that starts with (?| resets the capturing parentheses numbers in - each alternative (see section <seealso marker="#sect12">Duplicate - Subpattern Numbers</seealso>). The assertions at the start of each branch + each alternative (see section <seeerl marker="#sect12">Duplicate + Subpattern Numbers</seeerl>). 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 individual bytes of the character are then captured by the appropriate number of groups.</p> @@ -2416,8 +2416,8 @@ foo\Kbar</code> digit. In UTF modes, option <c>ucp</c> affects the meanings of \d, \s, \w and their uppercase partners, just as it does when they appear outside a character class, as described in section - <seealso marker="#generic_character_types">Generic Character - Types</seealso> earlier. The escape sequence \b has a different meaning + <seeerl marker="#generic_character_types">Generic Character + Types</seeerl> earlier. 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 @@ -2572,7 +2572,7 @@ gilbert|sullivan</code> permitted (matching the empty string). The matching process tries each alternative in turn, from left to right, and the first that succeeds is used. If the alternatives are within a subpattern (defined in section - <seealso marker="#sect11">Subpatterns</seealso>), "succeeds" means + <seeerl marker="#sect11">Subpatterns</seeerl>), "succeeds" means matching the remaining main pattern and the alternative in the subpattern.</p> </section> @@ -2607,7 +2607,7 @@ gilbert|sullivan</code> subpattern parentheses), the change applies to the remainder of the pattern that follows.</p> <p>An option change within a subpattern (see section - <seealso marker="#sect11">Subpatterns</seealso>) affects only that part of + <seeerl marker="#sect11">Subpatterns</seeerl>) affects only that part of the subpattern that follows it. So, the following matches abc and aBc and no other strings (assuming <c>caseless</c> is not used):</p> @@ -2632,8 +2632,8 @@ gilbert|sullivan</code> compiling or matching functions are called. Sometimes the pattern can contain special leading sequences, such as (*CRLF), to override what the application has set or what has been defaulted. Details are provided - in section <seealso marker="#newline_sequences"> - Newline Sequences</seealso> earlier.</p> + in section <seeerl marker="#newline_sequences"> + Newline Sequences</seeerl> earlier.</p> <p>The (*UTF8) and (*UCP) leading sequences can be used to set UTF and Unicode property modes. They are equivalent to setting options <c>unicode</c> and <c>ucp</c>, respectively. The (*UTF) sequence is a @@ -2664,7 +2664,7 @@ cat(aract|erpillar|)</code> <p>It sets up the subpattern as a capturing subpattern. That is, when the complete pattern matches, that portion of the subject string that matched the subpattern is passed back to the caller through the - return value of <seealso marker="#run/3"><c>run/3</c></seealso>.</p> + return value of <seemfa marker="#run/3"><c>run/3</c></seemfa>.</p> </item> </taglist> @@ -2776,8 +2776,8 @@ the ((?:red|white) (king|queen))</code> <p>Names consist of up to 32 alphanumeric characters and underscores, but must start with a non-digit. Named capturing parentheses are still allocated numbers as well as names, exactly as if the names were not present. - The <c>capture</c> specification to <seealso marker="#run/3"> - <c>run/3</c></seealso> can use named values if they are present in the + The <c>capture</c> specification to <seemfa marker="#run/3"> + <c>run/3</c></seemfa> can use named values if they are present in the regular expression.</p> <p>By default, a name must be unique within a pattern, but this constraint @@ -2803,7 +2803,7 @@ the ((?:red|white) (king|queen))</code> <p>For capturing named subpatterns which names are not unique, the first matching occurrence (counted from left to right in the subject) is - returned from <seealso marker="#run/3"><c>run/3</c></seealso>, if the name + returned from <seemfa marker="#run/3"><c>run/3</c></seemfa>, if the name is specified in the <c>values</c> part of the <c>capture</c> statement. The <c>all_names</c> capturing value matches all the names in the same way.</p> @@ -2875,8 +2875,8 @@ z{2,4}</code> <p>The quantifier {0} is permitted, causing the expression to behave as if the previous item and the quantifier were not present. This can be useful for subpatterns that are referenced as subroutines from elsewhere in the - pattern (but see also section <seealso marker="#defining_subpatterns"> - Defining Subpatterns for Use by Reference Only</seealso>). Items other + pattern (but see also section <seeerl marker="#defining_subpatterns"> + Defining Subpatterns for Use by Reference Only</seeerl>). Items other than subpatterns that have a {0} quantifier are omitted from the compiled pattern.</p> @@ -3125,8 +3125,8 @@ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</code> subpattern whose number is 10 or more using this syntax, as a sequence such as \50 is interpreted as a character defined in octal. For more details of the handling of digits following a backslash, see section - <seealso marker="#non_printing_characters">Non-Printing - Characters</seealso> earlier. There is no such problem when named + <seeerl marker="#non_printing_characters">Non-Printing + Characters</seeerl> earlier. There is no such problem when named parentheses are used. A back reference to any subpattern is possible using named parentheses (see below).</p> @@ -3156,8 +3156,8 @@ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</code> <p>A back reference matches whatever matched the capturing subpattern in the current subject string, rather than anything matching the subpattern - itself (section <seealso marker="#sect21">Subpattern as - Subroutines</seealso> describes a way of doing that). So, the + itself (section <seeerl marker="#sect21">Subpattern as + Subroutines</seeerl> describes a way of doing that). So, the following pattern matches "sense and sensibility" and "response and responsibility", but not "sense and responsibility":</p> @@ -3202,7 +3202,7 @@ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</code> number. If the pattern continues with a digit character, some delimiter must be used to terminate the back reference. If option <c>extended</c> is set, this can be whitespace. Otherwise an empty comment (see section - <seealso marker="#sect19">Comments</seealso>) can be used.</p> + <seeerl marker="#sect19">Comments</seeerl>) can be used.</p> <p><em>Recursive Back References</em></p> @@ -3463,8 +3463,8 @@ abcd$</code> <p>If the text between the parentheses consists of a sequence of digits, the condition is true if a capturing subpattern of that number has previously matched. If more than one capturing subpattern with the same - number exists (see section <seealso marker="#sect12"> - Duplicate Subpattern Numbers</seealso> earlier), the condition is true if + number exists (see section <seeerl marker="#sect12"> + Duplicate Subpattern Numbers</seeerl> earlier), 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 @@ -3594,8 +3594,8 @@ abcd$</code> 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 section <seealso marker="#newline_conventions"> - Newline Conventions</seealso> earlier.</p> + as described in section <seeerl marker="#newline_conventions"> + Newline Conventions</seeerl> earlier.</p> <p>Notice 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 @@ -3929,8 +3929,8 @@ $re = qr{\( (?: (?>[^()]+) | (?p{$re}) )* \)}x;</code> running of a match, any included backtracking verbs are not processed. processed. You can suppress the start-of-match optimizations by setting option <c>no_start_optimize</c> when calling - <seealso marker="#compile/2"><c>compile/2</c></seealso> or - <seealso marker="#run/3"><c>run/3</c></seealso>, or by starting the + <seemfa marker="#compile/2"><c>compile/2</c></seemfa> or + <seemfa marker="#run/3"><c>run/3</c></seemfa>, or by starting the pattern with (*NO_START_OPT).</p> <p>Experiments with Perl suggest that it too has similar optimizations, @@ -3979,7 +3979,7 @@ A((?:A|B(*ACCEPT)|C)D)</code> <note> <p>In Erlang, there is no interface to retrieve a mark with - <seealso marker="#run/2"><c>run/2,3</c></seealso>, so only the secondary + <seemfa marker="#run/2"><c>run/2,3</c></seemfa>, so only the secondary purpose is relevant to the Erlang programmer.</p> <p>The rest of this section is therefore deliberately not adapted for @@ -4061,7 +4061,7 @@ No match, mark = B</code> (*COMMIT)</code> <p>If (*COMMIT) is the only backtracking verb that is encountered, once it - has been passed, <seealso marker="#run/2"><c>run/2,3</c></seealso> is + has been passed, <seemfa marker="#run/2"><c>run/2,3</c></seemfa> is committed to find a match at the current starting point, or not at all, for example:</p> diff --git a/lib/stdlib/doc/src/ref_man.xml b/lib/stdlib/doc/src/ref_man.xml index 8d61833d1f..d12f537b07 100644 --- a/lib/stdlib/doc/src/ref_man.xml +++ b/lib/stdlib/doc/src/ref_man.xml @@ -84,6 +84,7 @@ <xi:include href="sets.xml"/> <xi:include href="shell.xml"/> <xi:include href="shell_default.xml"/> + <xi:include href="shell_docs.xml"/> <xi:include href="slave.xml"/> <xi:include href="sofs.xml"/> <xi:include href="string.xml"/> diff --git a/lib/stdlib/doc/src/sets.xml b/lib/stdlib/doc/src/sets.xml index 07ce41b7a7..291425c35b 100644 --- a/lib/stdlib/doc/src/sets.xml +++ b/lib/stdlib/doc/src/sets.xml @@ -39,7 +39,7 @@ The representation of a set is undefined.</p> <p>This module provides the same interface as the - <seealso marker="ordsets"><c>ordsets(3)</c></seealso> module + <seeerl marker="ordsets"><c>ordsets(3)</c></seeerl> module but with an undefined representation. One difference is that while this module considers two elements as different if they do not match (<c>=:=</c>), <c>ordsets</c> considers two elements as @@ -50,7 +50,7 @@ <datatype> <name name="set" n_vars="1"/> <desc><p>As returned by - <seealso marker="#new/0"><c>new/0</c></seealso>.</p></desc> + <seemfa marker="#new/0"><c>new/0</c></seemfa>.</p></desc> </datatype> <datatype> <name name="set" n_vars="0"/> @@ -220,8 +220,8 @@ <section> <title>See Also</title> - <p><seealso marker="gb_sets"><c>gb_sets(3)</c></seealso>, - <seealso marker="ordsets"><c>ordsets(3)</c></seealso></p> + <p><seeerl marker="gb_sets"><c>gb_sets(3)</c></seeerl>, + <seeerl marker="ordsets"><c>ordsets(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/shell.xml b/lib/stdlib/doc/src/shell.xml index d0d796655c..62ce63ec33 100644 --- a/lib/stdlib/doc/src/shell.xml +++ b/lib/stdlib/doc/src/shell.xml @@ -44,8 +44,8 @@ values, which can then be incorporated in later commands. How many commands and results to save can be determined by the user, either interactively, by calling - <seealso marker="#history/1"><c>history/1</c></seealso> and - <seealso marker="#results/1"><c>results/1</c></seealso>, + <seemfa marker="#history/1"><c>history/1</c></seemfa> and + <seemfa marker="#results/1"><c>results/1</c></seemfa>, or by setting the application configuration parameters <c>shell_history_length</c> and <c>shell_saved_results</c> for the STDLIB application.</p> @@ -53,8 +53,8 @@ <p>The shell uses a helper process for evaluating commands to protect the history mechanism from exceptions. By default the evaluator process is killed when an exception - occurs, but by calling <seealso marker="#catch_exception/1"> - <c>catch_exception/1</c></seealso> or by + occurs, but by calling <seemfa marker="#catch_exception/1"> + <c>catch_exception/1</c></seemfa> or by setting the application configuration parameter <c>shell_catch_exception</c> for the STDLIB application this behavior can be changed. See also the example below.</p> @@ -119,6 +119,9 @@ <section> <title>Shell Commands</title> + <p>The commands below are the built-in shell commands that are always + available. In most system the commands listed in the <seeerl marker="c">c(3)</seeerl> + module are also available in the shell.</p> <taglist> <tag><c>b()</c></tag> <item> @@ -232,7 +235,7 @@ <p>Reads record definitions from files. Existing definitions of any of the record names read are replaced. <c>Wildcard</c> is a wildcard string as defined in - <seealso marker="filelib"><c>filelib(3)</c></seealso>, + <seeerl marker="filelib"><c>filelib(3)</c></seeerl>, but not an atom.</p> </item> <tag><c>rr(WildcardOrModule, RecordNames)</c></tag> @@ -280,8 +283,8 @@ Eshell V5.3 (abort with ^G) {4,abcd}</pre> <p>Command 3 builds the tuple <c>Descriptor</c>, evaluating the BIF - <seealso marker="erts:erlang#list_to_atom/1"><c>list_to_atom/1</c> - </seealso>.</p> + <seemfa marker="erts:erlang#list_to_atom/1"><c>list_to_atom/1</c> + </seemfa>.</p> <pre> 4> <input>L.</input> @@ -740,8 +743,8 @@ q - quit erlang <p>If you want an Erlang node to have a remote job active from the start (rather than the default local job), start Erlang with flag - <c>-remsh</c>, for example, - <c>erl -sname this_node -remsh other_node@other_host</c></p> + <seecom marker="erts:erl#remsh"><c>-remsh</c></seecom>, for example, + <c>erl -remsh other_node@other_host</c></p> </section> <section> @@ -782,7 +785,7 @@ q - quit erlang <p>These callback functions are called from local and non-local evaluation function handlers, described in the - <seealso marker="erl_eval"><c>erl_eval</c></seealso> + <seeerl marker="erl_eval"><c>erl_eval</c></seeerl> manual page. (Arguments in <c>ArgList</c> are evaluated before the callback functions are called.)</p> @@ -805,8 +808,8 @@ q - quit erlang </item> <item> <p>From a normal shell session, call function - <seealso marker="#start_restricted/1"> - <c>start_restricted/1</c></seealso>. This exits the current evaluator + <seemfa marker="#start_restricted/1"> + <c>start_restricted/1</c></seemfa>. This exits the current evaluator and starts a new one in restricted mode.</p> </item> </list> @@ -842,8 +845,8 @@ q - quit erlang </item> <item> <p>If the restricted shell is activated using - <seealso marker="#start_restricted/1"> - <c>start_restricted/1</c></seealso> and the callback module cannot + <seemfa marker="#start_restricted/1"> + <c>start_restricted/1</c></seemfa> and the callback module cannot be loaded, an error report is sent to the error logger and the call returns <c>{error,Reason}</c>.</p> </item> @@ -855,8 +858,8 @@ q - quit erlang <p>The default shell prompt function displays the name of the node (if the node can be part of a distributed system) and the current command number. The user can customize the prompt - function by calling <seealso marker="#prompt_func/1"> - <c>prompt_func/1</c></seealso> or by setting application + function by calling <seemfa marker="#prompt_func/1"> + <c>prompt_func/1</c></seemfa> or by setting application configuration parameter <c>shell_prompt_func</c> for the STDLIB application.</p> diff --git a/lib/stdlib/doc/src/shell_default.xml b/lib/stdlib/doc/src/shell_default.xml index 75bf89ba8d..18af8b7273 100644 --- a/lib/stdlib/doc/src/shell_default.xml +++ b/lib/stdlib/doc/src/shell_default.xml @@ -48,7 +48,7 @@ 2> <input>c(foo).</input> {ok, foo}</pre> - <p>In command one, module <seealso marker="lists"><c>lists</c></seealso> is + <p>In command one, module <seeerl marker="lists"><c>lists</c></seeerl> is called. In command two, no module name is specified. The shell searches module <c>user_default</c> followed by module <c>shell_default</c> for function <c>c/1</c>.</p> diff --git a/lib/stdlib/doc/src/shell_docs.xml b/lib/stdlib/doc/src/shell_docs.xml new file mode 100644 index 0000000000..bd3e3600f7 --- /dev/null +++ b/lib/stdlib/doc/src/shell_docs.xml @@ -0,0 +1,166 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2020</year><year>2020</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>shell_docs</title> + <prepared>Lukas Larsson</prepared> + <responsible></responsible> + <docno>1</docno> + <approved></approved> + <checked></checked> + <date>2020-02-19</date> + <rev>A</rev> + <file>shell_docs.xml</file> + </header> + <module since="OTP 23.0">shell_docs</module> + <modulesummary>Functions used to render EEP-48 style documentation for a shell.</modulesummary> + <description> + <p>This module can be used to render function and type documentation + to be printed in a shell. It can only render EEP-48 documentation of the format + <c>application/erlang+html</c>. For more information about this format see + <seeguide marker="erl_docgen:doc_storage">Documentation Storage</seeguide> + in Erl_Docgen's User's Guide. + </p> + </description> + + <datatypes> + <datatype> + <name name="docs_v1"/> + <desc> + <p> + The record holding EEP-48 documentation for a module. + You can use <seemfa marker="kernel:code#get_doc/1">code:get_doc/1</seemfa> + to fetch this information from a module. + </p> + </desc> + </datatype> + <datatype> + <name name="config"/> + <desc> + <p> + The configuration of how the documentation should be rendered. + </p> + <taglist> + <tag>encoding</tag> + <item> + Configure the encoding that should be used by + the renderer for graphical details such as bullet-points. + By default <c>shell_docs</c> uses the value returned + by <seemfa marker="io#getopts/0"><c>io:getopts()</c></seemfa>.</item> + <tag>ansi</tag> + <item> + Configure whether <url href="https://en.wikipedia.org/wiki/ANSI_escape_code"> + ansi escape codes</url> should be used to + render graphical details such as bold and underscore. By default + <c>shell_docs</c> will try to determine if the receiving shell + supports ansi escape codes. It is possible to override + the automated check by setting the kernel configuration parameter + <c>shell_docs_ansi</c> to a <c>boolean()</c> value.</item> + <tag>columns</tag> + <item> + Configure how wide the target documentation should be rendered. + By default <c>shell_docs</c> used the value returned by + <seemfa marker="io#columns/0"><c>io:columns()</c></seemfa>. + </item> + </taglist> + </desc> + </datatype> + <datatype> + <name name="chunk_element_block_type"/> + <name name="chunk_element_inline_type"/> + <name name="chunk_element_type"/> + <desc> + <p> + The HTML tags allowed in <c>application/erlang+html</c>. + </p> + </desc> + </datatype> + <datatype> + <name name="chunk_element_attr"/> + <name name="chunk_element_attrs"/> + <name name="chunk_element"/> + <name name="chunk_elements"/> + <desc> + </desc> + </datatype> + </datatypes> + + <funcs> + + <func> + <name name="render" arity="2" since="OTP 23.0"/> + <name name="render" arity="3" clause_i="1" since="OTP 23.2"/> + <name name="render" arity="3" clause_i="2" since="OTP 23.0"/> + <name name="render" arity="4" clause_i="1" since="OTP 23.2"/> + <name name="render" arity="4" clause_i="2" since="OTP 23.0"/> + <name name="render" arity="5" since="OTP 23.2"/> + <fsummary>Render the documentation for a module or function.</fsummary> + <desc> + <p>Render the documentation for a module or function.</p> + </desc> + </func> + <func> + <name name="render_type" arity="2" since="OTP 23.0"/> + <name name="render_type" arity="3" clause_i="1" since="OTP 23.2"/> + <name name="render_type" arity="3" clause_i="2" since="OTP 23.0"/> + <name name="render_type" arity="4" clause_i="1" since="OTP 23.2"/> + <name name="render_type" arity="4" clause_i="2" since="OTP 23.0"/> + <name name="render_type" arity="5" since="OTP 23.2"/> + <fsummary>Render the documentation of a type in a module.</fsummary> + <desc> + <p>Render the documentation of a type in a module.</p> + </desc> + </func> + <func> + <name name="render_callback" arity="2" since="OTP 23.0"/> + <name name="render_callback" arity="3" clause_i="1" since="OTP 23.2"/> + <name name="render_callback" arity="3" clause_i="2" since="OTP 23.0"/> + <name name="render_callback" arity="4" clause_i="1" since="OTP 23.2"/> + <name name="render_callback" arity="4" clause_i="2" since="OTP 23.0"/> + <name name="render_callback" arity="5" since="OTP 23.2"/> + <fsummary>Render the documentation of a callback in a module.</fsummary> + <desc> + <p>Render the documentation of a callback in a module.</p> + </desc> + </func> + + <func> + <name name="validate" arity="1" since="OTP 23.0"/> + <fsummary>Validate the documentation</fsummary> + <desc> + <p>This function can be used to do a basic validation of + the doc content of <c>application/erlang+html</c> format.</p> + </desc> + </func> + + <func> + <name name="normalize" arity="1" since="OTP 23.0"/> + <fsummary>Normalize the documentation</fsummary> + <desc> + <p>This function can be used to do whitespace normalization + of <c>application/erlang+html</c> documentation.</p> + </desc> + </func> + + </funcs> +</erlref> diff --git a/lib/stdlib/doc/src/slave.xml b/lib/stdlib/doc/src/slave.xml index f60e7e1d2f..92bd676691 100644 --- a/lib/stdlib/doc/src/slave.xml +++ b/lib/stdlib/doc/src/slave.xml @@ -51,7 +51,7 @@ <p>An alternative to the <c>ssh</c> program can be specified on the command line to - <seealso marker="erts:erl"><c>erl(1)</c></seealso> as follows:</p> + <seecom marker="erts:erl"><c>erl(1)</c></seecom> as follows:</p> <pre> -rsh Program</pre> @@ -140,7 +140,7 @@ rpc:call(N, slave, pseudo, [node(), [pxw_server]]).</code> <p>Argument <c><anno>Args</anno></c> is used to set <c>erl</c> command-line arguments. If provided, it is passed to the new node and can be used for a variety of purposes; see - <seealso marker="erts:erl"><c>erl(1)</c></seealso>.</p> + <seecom marker="erts:erl"><c>erl(1)</c></seecom>.</p> <p>As an example, suppose that you want to start a slave node at host <c>H</c> with node name <c>Name@H</c> and want the slave node to have the following properties:</p> @@ -197,7 +197,7 @@ slave:start(H, Name, Arg).</code> executing process. If that process terminates, the slave node also terminates.</p> <p>For a description of arguments and return values, see - <seealso marker="#start/1"><c>start/1,2,3</c></seealso>.</p> + <seemfa marker="#start/1"><c>start/1,2,3</c></seemfa>.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/sofs.xml b/lib/stdlib/doc/src/sofs.xml index c2c6675258..9b96c4d39a 100644 --- a/lib/stdlib/doc/src/sofs.xml +++ b/lib/stdlib/doc/src/sofs.xml @@ -273,7 +273,7 @@ <p>If S is an element (T, X) of Sets, then T is a <marker id="valid_type"></marker><em>valid type</em> of X, T is the type of S, and X is the external set of S. - <seealso marker="#from_term/2"><c>from_term/2</c></seealso> creates a + <seemfa marker="#from_term/2"><c>from_term/2</c></seemfa> creates a set from a type and an Erlang term turned into an external set.</p> <p>The sets represented by Sets are the elements of the range of function Set from Sets to Erlang terms and sets of Erlang terms:</p> @@ -288,7 +288,7 @@ </list> <p>When there is no risk of confusion, elements of Sets are identified with the sets they represent. For example, if U is the result of - calling <seealso marker="#union/2"><c>union/2</c></seealso> with S1 + calling <seemfa marker="#union/2"><c>union/2</c></seemfa> with S1 and S2 as arguments, then U is said to be the union of S1 and S2. A more precise formulation is that Set(U) is the union of Set(S1) and Set(S2).</p> @@ -300,8 +300,8 @@ product of two sets R and S, and recall that the relative product of R and S is defined if R is a binary relation to Y and S is a binary relation from Y. The function that implements the - relative product, <seealso marker="#relative_product/2"> - <c>relative_product/2</c></seealso>, checks + relative product, <seemfa marker="#relative_product/2"> + <c>relative_product/2</c></seemfa>, checks that the arguments represent binary relations by matching [{A,B}] against the type of the first argument (Arg1 say), and [{C,D}] against the type of the second argument (Arg2 say). The fact @@ -316,13 +316,13 @@ set.</p> <p>A few functions of this module - (<seealso marker="#drestriction/3"><c>drestriction/3</c></seealso>, - <seealso marker="#family_projection/2"><c>family_projection/2</c></seealso>, - <seealso marker="#partition/2"><c>partition/2</c></seealso>, - <seealso marker="#partition_family/2"><c>partition_family/2</c></seealso>, - <seealso marker="#projection/2"><c>projection/2</c></seealso>, - <seealso marker="#restriction/3"><c>restriction/3</c></seealso>, - <seealso marker="#substitution/2"><c>substitution/2</c></seealso>) + (<seemfa marker="#drestriction/3"><c>drestriction/3</c></seemfa>, + <seemfa marker="#family_projection/2"><c>family_projection/2</c></seemfa>, + <seemfa marker="#partition/2"><c>partition/2</c></seemfa>, + <seemfa marker="#partition_family/2"><c>partition_family/2</c></seemfa>, + <seemfa marker="#projection/2"><c>projection/2</c></seemfa>, + <seemfa marker="#restriction/3"><c>restriction/3</c></seemfa>, + <seemfa marker="#substitution/2"><c>substitution/2</c></seemfa>) accept an Erlang function as a means to modify each element of a given unordered set. <marker id="set_fun"></marker>Such a function, called @@ -377,12 +377,12 @@ fun(S) -> sofs:partition(1, S) end the execution time is in the worst case proportional to the sum of the sizes of the input arguments and the returned value. A few functions execute in constant time: - <seealso marker="#from_external/2"><c>from_external/2</c></seealso>, - <seealso marker="#is_empty_set/1"><c>is_empty_set/1</c></seealso>, - <seealso marker="#is_set/1"><c>is_set/1</c></seealso>, - <seealso marker="#is_sofs_set/1"><c>is_sofs_set/1</c></seealso>, - <seealso marker="#to_external/1"><c>to_external/1</c></seealso> - <seealso marker="#type/1"><c>type/1</c></seealso>.</p> + <seemfa marker="#from_external/2"><c>from_external/2</c></seemfa>, + <seemfa marker="#is_empty_set/1"><c>is_empty_set/1</c></seemfa>, + <seemfa marker="#is_set/1"><c>is_set/1</c></seemfa>, + <seemfa marker="#is_sofs_set/1"><c>is_sofs_set/1</c></seemfa>, + <seemfa marker="#to_external/1"><c>to_external/1</c></seemfa> + <seemfa marker="#type/1"><c>type/1</c></seemfa>.</p> <p>The functions of this module exit the process with a <c>badarg</c>, <c>bad_function</c>, or <c>type_mismatch</c> @@ -399,53 +399,53 @@ fun(S) -> sofs:partition(1, S) end </datatype> <datatype> <name name="binary_relation"></name> - <desc><p>A <seealso marker="#binary_relation">binary - relation</seealso>.</p></desc> + <desc><p>A <seeerl marker="#binary_relation">binary + relation</seeerl>.</p></desc> </datatype> <datatype> <name name="external_set"></name> - <desc><p>An <seealso marker="#external_set">external - set</seealso>.</p></desc> + <desc><p>An <seeerl marker="#external_set">external + set</seeerl>.</p></desc> </datatype> <datatype> <name name="family"></name> - <desc><p>A <seealso marker="#family">family</seealso> (of subsets).</p> + <desc><p>A <seeerl marker="#family">family</seeerl> (of subsets).</p> </desc> </datatype> <datatype> <name name="a_function"></name> - <desc><p>A <seealso marker="#function">function</seealso>.</p></desc> + <desc><p>A <seeerl marker="#function">function</seeerl>.</p></desc> </datatype> <datatype> <name name="ordset"></name> - <desc><p>An <seealso marker="#sets_definition">ordered - set</seealso>.</p></desc> + <desc><p>An <seeerl marker="#sets_definition">ordered + set</seeerl>.</p></desc> </datatype> <datatype> <name name="relation"></name> - <desc><p>An <seealso marker="#n_ary_relation">n-ary relation</seealso>. + <desc><p>An <seeerl marker="#n_ary_relation">n-ary relation</seeerl>. </p></desc> </datatype> <datatype> <name name="a_set"></name> - <desc><p>An <seealso marker="#sets_definition">unordered - set</seealso>.</p></desc> + <desc><p>An <seeerl marker="#sets_definition">unordered + set</seeerl>.</p></desc> </datatype> <datatype> <name name="set_of_sets"></name> - <desc><p>An <seealso marker="#sets_definition">unordered - set</seealso> of unordered sets.</p></desc> + <desc><p>An <seeerl marker="#sets_definition">unordered + set</seeerl> of unordered sets.</p></desc> </datatype> <datatype> <name name="set_fun"></name> - <desc><p>A <seealso marker="#set_fun">SetFun</seealso>.</p></desc> + <desc><p>A <seeerl marker="#set_fun">SetFun</seeerl>.</p></desc> </datatype> <datatype> <name name="spec_fun"></name> </datatype> <datatype> <name name="type"></name> - <desc><p>A <seealso marker="#type">type</seealso>.</p></desc> + <desc><p>A <seeerl marker="#type">type</seeerl>.</p></desc> </datatype> <datatype> <!-- Parameterized opaque types are NYI: --> @@ -460,10 +460,10 @@ fun(S) -> sofs:partition(1, S) end <name name="a_function" arity="2" since=""/> <fsummary>Create a function.</fsummary> <desc> - <p>Creates a <seealso marker="#function">function</seealso>. + <p>Creates a <seeerl marker="#function">function</seeerl>. <c>a_function(F, T)</c> is equivalent to <c>from_term(F, T)</c> if the result is a function. If - no <seealso marker="#type">type</seealso> is explicitly + no <seeerl marker="#type">type</seeerl> is explicitly specified, <c>[{atom, atom}]</c> is used as the function type.</p> </desc> @@ -476,10 +476,10 @@ fun(S) -> sofs:partition(1, S) end <p>Returns the binary relation containing the elements (E, Set) such that Set belongs to <c><anno>SetOfSets</anno></c> and E belongs to Set. If <c>SetOfSets</c> is - a <seealso marker="#partition">partition</seealso> of a set X and + a <seeerl marker="#partition">partition</seeerl> of a set X and R is the equivalence relation in X induced by <c>SetOfSets</c>, then the returned relation is - the <seealso marker="#canonical_map">canonical map</seealso> from + the <seeerl marker="#canonical_map">canonical map</seeerl> from X onto the equivalence classes with respect to R.</p> <pre> 1> <input>Ss = sofs:from_term([[a,b],[b,c]]),</input> @@ -493,7 +493,7 @@ fun(S) -> sofs:partition(1, S) end <name name="composite" arity="2" since=""/> <fsummary>Return the composite of two functions.</fsummary> <desc> - <p>Returns the <seealso marker="#composite">composite</seealso> of + <p>Returns the <seeerl marker="#composite">composite</seeerl> of the functions <c><anno>Function1</anno></c> and <c><anno>Function2</anno></c>.</p> <pre> @@ -510,7 +510,7 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Create the function that maps each element of a set onto another set.</fsummary> <desc> - <p>Creates the <seealso marker="#function">function</seealso> + <p>Creates the <seeerl marker="#function">function</seeerl> that maps each element of set <c>Set</c> onto <c>AnySet</c>.</p> <pre> 1> <input>S = sofs:set([a,b]),</input> @@ -525,7 +525,7 @@ fun(S) -> sofs:partition(1, S) end <name name="converse" arity="1" since=""/> <fsummary>Return the converse of a binary relation.</fsummary> <desc> - <p>Returns the <seealso marker="#converse">converse</seealso> + <p>Returns the <seeerl marker="#converse">converse</seeerl> of the binary relation <c><anno>BinRel1</anno></c>.</p> <pre> 1> <input>R1 = sofs:relation([{1,a},{2,b},{3,a}]),</input> @@ -539,7 +539,7 @@ fun(S) -> sofs:partition(1, S) end <name name="difference" arity="2" since=""/> <fsummary>Return the difference of two sets.</fsummary> <desc> - <p>Returns the <seealso marker="#difference">difference</seealso> of + <p>Returns the <seeerl marker="#difference">difference</seeerl> of the sets <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c>.</p> </desc> </func> @@ -549,14 +549,14 @@ fun(S) -> sofs:partition(1, S) end <name name="digraph_to_family" arity="2" since=""/> <fsummary>Create a family from a directed graph.</fsummary> <desc> - <p>Creates a <seealso marker="#family">family</seealso> from + <p>Creates a <seeerl marker="#family">family</seeerl> from the directed graph <c><anno>Graph</anno></c>. Each vertex a of <c><anno>Graph</anno></c> is represented by a pair (a, {b[1], ..., b[n]}), where the b[i]:s are the out-neighbors of a. If no type is explicitly specified, [{atom, [atom]}] is used as type of the family. It is assumed that <c><anno>Type</anno></c> is - a <seealso marker="#valid_type">valid type</seealso> of the + a <seeerl marker="#valid_type">valid type</seeerl> of the external set of the family.</p> <p>If G is a directed graph, it holds that the vertices and edges of G are the same as the vertices and edges of @@ -568,7 +568,7 @@ fun(S) -> sofs:partition(1, S) end <name name="domain" arity="1" since=""/> <fsummary>Return the domain of a binary relation.</fsummary> <desc> - <p>Returns the <seealso marker="#domain">domain</seealso> of + <p>Returns the <seeerl marker="#domain">domain</seeerl> of the binary relation <c><anno>BinRel</anno></c>.</p> <pre> 1> <input>R = sofs:relation([{1,a},{1,b},{2,b},{2,c}]),</input> @@ -584,7 +584,7 @@ fun(S) -> sofs:partition(1, S) end <desc> <p>Returns the difference between the binary relation <c><anno>BinRel1</anno></c> - and the <seealso marker="#restriction">restriction</seealso> + and the <seeerl marker="#restriction">restriction</seeerl> of <c><anno>BinRel1</anno></c> to <c><anno>Set</anno></c>.</p> <pre> 1> <input>R1 = sofs:relation([{1,a},{2,b},{3,c}]),</input> @@ -621,8 +621,8 @@ fun(S) -> sofs:partition(1, S) end <name name="empty_set" arity="0" since=""/> <fsummary>Return the untyped empty set.</fsummary> <desc> - <p>Returns the <seealso marker="#sets_definition">untyped empty - set</seealso>. <c>empty_set()</c> is equivalent to + <p>Returns the <seeerl marker="#sets_definition">untyped empty + set</seeerl>. <c>empty_set()</c> is equivalent to <c>from_term([], ['_'])</c>.</p> </desc> </func> @@ -631,10 +631,10 @@ fun(S) -> sofs:partition(1, S) end <name name="extension" arity="3" since=""/> <fsummary>Extend the domain of a binary relation.</fsummary> <desc> - <p>Returns the <seealso marker="#extension">extension</seealso> of + <p>Returns the <seeerl marker="#extension">extension</seeerl> of <c><anno>BinRel1</anno></c> such that for each element E in <c><anno>Set</anno></c> that does not belong to the - <seealso marker="#domain">domain</seealso> of + <seeerl marker="#domain">domain</seeerl> of <c><anno>BinRel1</anno></c>, <c><anno>BinRel2</anno></c> contains the pair (E, <c>AnySet</c>).</p> <pre> @@ -652,10 +652,10 @@ fun(S) -> sofs:partition(1, S) end <name name="family" arity="2" since=""/> <fsummary>Create a family of subsets.</fsummary> <desc> - <p>Creates a <seealso marker="#family">family of subsets</seealso>. + <p>Creates a <seeerl marker="#family">family of subsets</seeerl>. <c>family(F, T)</c> is equivalent to <c>from_term(F, T)</c> if the result is a family. If - no <seealso marker="#type">type</seealso> is explicitly + no <seeerl marker="#type">type</seeerl> is explicitly specified, <c>[{atom, [atom]}]</c> is used as the family type.</p> </desc> @@ -666,7 +666,7 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return the difference of two families.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> and <c><anno>Family2</anno></c> - are <seealso marker="#family">families</seealso>, then + are <seeerl marker="#family">families</seeerl>, then <c><anno>Family3</anno></c> is the family such that the index set is equal to the index set of <c><anno>Family1</anno></c>, and <c><anno>Family3</anno></c>[i] is @@ -687,13 +687,13 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return a family of domains.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is - a <seealso marker="#family">family</seealso> + a <seeerl marker="#family">family</seeerl> and <c><anno>Family1</anno></c>[i] is a binary relation for every i in the index set of <c><anno>Family1</anno></c>, then <c><anno>Family2</anno></c> is the family with the same index set as <c><anno>Family1</anno></c> such that <c><anno>Family2</anno></c>[i] is - the <seealso marker="#domain">domain</seealso> of + the <seeerl marker="#domain">domain</seeerl> of <c><anno>Family1</anno>[i]</c>.</p> <pre> 1> <input>FR = sofs:from_term([{a,[{1,a},{2,b},{3,c}]},{b,[]},{c,[{4,d},{5,e}]}]),</input> @@ -708,13 +708,13 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return a family of fields.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is - a <seealso marker="#family">family</seealso> + a <seeerl marker="#family">family</seeerl> and <c><anno>Family1</anno></c>[i] is a binary relation for every i in the index set of <c><anno>Family1</anno></c>, then <c><anno>Family2</anno></c> is the family with the same index set as <c><anno>Family1</anno></c> such that <c><anno>Family2</anno></c>[i] is - the <seealso marker="#field">field</seealso> of + the <seeerl marker="#field">field</seeerl> of <c><anno>Family1</anno></c>[i].</p> <pre> 1> <input>FR = sofs:from_term([{a,[{1,a},{2,b},{3,c}]},{b,[]},{c,[{4,d},{5,e}]}]),</input> @@ -733,13 +733,13 @@ fun(S) -> sofs:partition(1, S) end of sets of sets.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is - a <seealso marker="#family">family</seealso> + a <seeerl marker="#family">family</seeerl> and <c><anno>Family1</anno></c>[i] is a set of sets for every i in the index set of <c><anno>Family1</anno></c>, then <c><anno>Family2</anno></c> is the family with the same index set as <c><anno>Family1</anno></c> such that <c><anno>Family2</anno></c>[i] is - the <seealso marker="#intersection_n">intersection</seealso> + the <seeerl marker="#intersection_n">intersection</seeerl> of <c><anno>Family1</anno></c>[i].</p> <p>If <c><anno>Family1</anno></c>[i] is an empty set for some i, the process exits with a <c>badarg</c> message.</p> @@ -756,7 +756,7 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return the intersection of two families.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> and <c><anno>Family2</anno></c> - are <seealso marker="#family">families</seealso>, + are <seeerl marker="#family">families</seeerl>, then <c><anno>Family3</anno></c> is the family such that the index set is the intersection of <c><anno>Family1</anno></c>:s and <c><anno>Family2</anno></c>:s index sets, @@ -776,7 +776,7 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return a family of modified subsets.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is - a <seealso marker="#family">family</seealso>, + a <seeerl marker="#family">family</seeerl>, then <c><anno>Family2</anno></c> is the family with the same index set as <c><anno>Family1</anno></c> such that <c><anno>Family2</anno></c>[i] is the result of @@ -795,13 +795,13 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return a family of ranges.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is - a <seealso marker="#family">family</seealso> + a <seeerl marker="#family">family</seeerl> and <c><anno>Family1</anno></c>[i] is a binary relation for every i in the index set of <c><anno>Family1</anno></c>, then <c><anno>Family2</anno></c> is the family with the same index set as <c><anno>Family1</anno></c> such that <c><anno>Family2</anno></c>[i] is - the <seealso marker="#range">range</seealso> of + the <seeerl marker="#range">range</seeerl> of <c><anno>Family1</anno></c>[i].</p> <pre> 1> <input>FR = sofs:from_term([{a,[{1,a},{2,b},{3,c}]},{b,[]},{c,[{4,d},{5,e}]}]),</input> @@ -816,15 +816,15 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Select a subset of a family using a predicate.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is - a <seealso marker="#family">family</seealso>, + a <seeerl marker="#family">family</seeerl>, then <c><anno>Family2</anno></c> is - the <seealso marker="#restriction">restriction</seealso> of + the <seeerl marker="#restriction">restriction</seeerl> of <c><anno>Family1</anno></c> to those elements i of the index set for which <c><anno>Fun</anno></c> applied to <c><anno>Family1</anno></c>[i] returns <c>true</c>. If <c><anno>Fun</anno></c> is a tuple <c>{external, Fun2}</c>, then <c>Fun2</c> is applied to - the <seealso marker="#external_set">external set</seealso> + the <seeerl marker="#external_set">external set</seeerl> of <c><anno>Family1</anno></c>[i], otherwise <c><anno>Fun</anno></c> is applied to <c><anno>Family1</anno></c>[i].</p> <pre> @@ -842,17 +842,17 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Create a directed graph from a family.</fsummary> <desc> <p>Creates a directed graph from - <seealso marker="#family">family</seealso> <c><anno>Family</anno></c>. + <seeerl marker="#family">family</seeerl> <c><anno>Family</anno></c>. For each pair (a, {b[1], ..., b[n]}) of <c><anno>Family</anno></c>, vertex a and the edges (a, b[i]) for 1 <= i <= n are added to a newly created directed graph.</p> - <p>If no graph type is specified, <seealso marker="digraph#new/0"> - <c>digraph:new/0</c></seealso> is used for + <p>If no graph type is specified, <seemfa marker="digraph#new/0"> + <c>digraph:new/0</c></seemfa> is used for creating the directed graph, otherwise argument <c><anno>GraphType</anno></c> is passed on as second argument to - <seealso marker="digraph#new/1"><c>digraph:new/1</c></seealso>.</p> + <seemfa marker="digraph#new/1"><c>digraph:new/1</c></seemfa>.</p> <p>It F is a family, it holds that F is a subset of <c>digraph_to_family(family_to_digraph(F), type(F))</c>. Equality holds if <c>union_of_family(F)</c> is a subset of @@ -867,7 +867,7 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Create a binary relation from a family.</fsummary> <desc> <p>If <c><anno>Family</anno></c> is - a <seealso marker="#family">family</seealso>, + a <seeerl marker="#family">family</seeerl>, then <c><anno>BinRel</anno></c> is the binary relation containing all pairs (i, x) such that i belongs to the index set of <c><anno>Family</anno></c> and x belongs @@ -885,13 +885,13 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return the union of a family of sets of sets.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is - a <seealso marker="#family">family</seealso> + a <seeerl marker="#family">family</seeerl> and <c><anno>Family1</anno></c>[i] is a set of sets for each i in the index set of <c><anno>Family1</anno></c>, then <c><anno>Family2</anno></c> is the family with the same index set as <c><anno>Family1</anno></c> such that <c><anno>Family2</anno></c>[i] is - the <seealso marker="#union_n">union</seealso> of + the <seeerl marker="#union_n">union</seeerl> of <c><anno>Family1</anno></c>[i].</p> <pre> 1> <input>F1 = sofs:from_term([{a,[[1,2],[2,3]]},{b,[[]]}]),</input> @@ -908,7 +908,7 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return the union of two families.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> and <c><anno>Family2</anno></c> - are <seealso marker="#family">families</seealso>, + are <seeerl marker="#family">families</seeerl>, then <c><anno>Family3</anno></c> is the family such that the index set is the union of <c><anno>Family1</anno></c>:s and <c><anno>Family2</anno></c>:s index sets, @@ -929,7 +929,7 @@ fun(S) -> sofs:partition(1, S) end <name name="field" arity="1" since=""/> <fsummary>Return the field of a binary relation.</fsummary> <desc> - <p>Returns the <seealso marker="#field">field</seealso> of the + <p>Returns the <seeerl marker="#field">field</seeerl> of the binary relation <c><anno>BinRel</anno></c>.</p> <pre> 1> <input>R = sofs:relation([{1,a},{1,b},{2,b},{2,c}]),</input> @@ -945,12 +945,12 @@ fun(S) -> sofs:partition(1, S) end <name name="from_external" arity="2" since=""/> <fsummary>Create a set.</fsummary> <desc> - <p>Creates a set from the <seealso marker="#external_set">external - set</seealso> <c><anno>ExternalSet</anno></c> and - the <seealso marker="#type">type</seealso> <c><anno>Type</anno></c>. + <p>Creates a set from the <seeerl marker="#external_set">external + set</seeerl> <c><anno>ExternalSet</anno></c> and + the <seeerl marker="#type">type</seeerl> <c><anno>Type</anno></c>. It is assumed that <c><anno>Type</anno></c> is - a <seealso marker="#valid_type">valid - type</seealso> of <c><anno>ExternalSet</anno></c>.</p> + a <seeerl marker="#valid_type">valid + type</seeerl> of <c><anno>ExternalSet</anno></c>.</p> </desc> </func> @@ -958,8 +958,8 @@ fun(S) -> sofs:partition(1, S) end <name name="from_sets" arity="1" clause_i="1" since=""/> <fsummary>Create a set out of a list of sets.</fsummary> <desc> - <p>Returns the <seealso marker="#sets_definition">unordered - set</seealso> containing the sets of list + <p>Returns the <seeerl marker="#sets_definition">unordered + set</seeerl> containing the sets of list <c><anno>ListOfSets</anno></c>.</p> <pre> 1> <input>S1 = sofs:relation([{a,1},{b,2}]),</input> @@ -974,8 +974,8 @@ fun(S) -> sofs:partition(1, S) end <name name="from_sets" arity="1" clause_i="2" since=""/> <fsummary>Create an ordered set out of a tuple of sets.</fsummary> <desc> - <p>Returns the <seealso marker="#sets_definition">ordered - set</seealso> containing the sets of the non-empty tuple + <p>Returns the <seeerl marker="#sets_definition">ordered + set</seeerl> containing the sets of the non-empty tuple <c><anno>TupleOfSets</anno></c>.</p> </desc> </func> @@ -986,12 +986,12 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Create a set.</fsummary> <desc> <p><marker id="from_term"></marker>Creates an element - of <seealso marker="#sets_definition">Sets</seealso> by + of <seeerl marker="#sets_definition">Sets</seeerl> by traversing term <c><anno>Term</anno></c>, sorting lists, removing duplicates, and - deriving or verifying a <seealso marker="#valid_type">valid - type</seealso> for the so obtained external set. An - explicitly specified <seealso marker="#type">type</seealso> + deriving or verifying a <seeerl marker="#valid_type">valid + type</seeerl> for the so obtained external set. An + explicitly specified <seeerl marker="#type">type</seeerl> <c><anno>Type</anno></c> can be used to limit the depth of the traversal; an atomic type stops the traversal, as shown by the following example @@ -1019,14 +1019,14 @@ fun(S) -> sofs:partition(1, S) end <input>sofs:to_external(Ss).</input> [{a,[1,2,3]},{b,[4,5,6]}]</pre> <p>Other functions that create sets are - <seealso marker="#from_external/2"><c>from_external/2</c></seealso> - and <seealso marker="#from_sets/1"><c>from_sets/1</c></seealso>. + <seemfa marker="#from_external/2"><c>from_external/2</c></seemfa> + and <seemfa marker="#from_sets/1"><c>from_sets/1</c></seemfa>. Special cases of <c>from_term/2</c> are - <seealso marker="#a_function/1"><c>a_function/1,2</c></seealso>, - <seealso marker="#empty_set/0"><c>empty_set/0</c></seealso>, - <seealso marker="#family/1"><c>family/1,2</c></seealso>, - <seealso marker="#relation/1"><c>relation/1,2</c></seealso>, and - <seealso marker="#set/1"><c>set/1,2</c></seealso>.</p> + <seemfa marker="#a_function/1"><c>a_function/1,2</c></seemfa>, + <seemfa marker="#empty_set/0"><c>empty_set/0</c></seemfa>, + <seemfa marker="#family/1"><c>family/1,2</c></seemfa>, + <seemfa marker="#relation/1"><c>relation/1,2</c></seemfa>, and + <seemfa marker="#set/1"><c>set/1,2</c></seemfa>.</p> </desc> </func> @@ -1034,7 +1034,7 @@ fun(S) -> sofs:partition(1, S) end <name name="image" arity="2" since=""/> <fsummary>Return the image of a set under a binary relation.</fsummary> <desc> - <p>Returns the <seealso marker="#image">image</seealso> of + <p>Returns the <seeerl marker="#image">image</seeerl> of set <c><anno>Set1</anno></c> under the binary relation <c><anno>BinRel</anno></c>.</p> <pre> @@ -1051,7 +1051,7 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return the intersection of a set of sets.</fsummary> <desc> <p>Returns - the <seealso marker="#intersection_n">intersection</seealso> of + the <seeerl marker="#intersection_n">intersection</seeerl> of the set of sets <c><anno>SetOfSets</anno></c>.</p> <p>Intersecting an empty set of sets exits the process with a <c>badarg</c> message.</p> @@ -1063,7 +1063,7 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return the intersection of two sets.</fsummary> <desc> <p>Returns - the <seealso marker="#intersection">intersection</seealso> of + the <seeerl marker="#intersection">intersection</seeerl> of <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c>.</p> </desc> </func> @@ -1073,7 +1073,7 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return the intersection of a family.</fsummary> <desc> <p>Returns the intersection of - <seealso marker="#family">family</seealso> <c><anno>Family</anno></c>. + <seeerl marker="#family">family</seeerl> <c><anno>Family</anno></c>. </p> <p>Intersecting an empty family exits the process with a <c>badarg</c> message.</p> @@ -1089,7 +1089,7 @@ fun(S) -> sofs:partition(1, S) end <name name="inverse" arity="1" since=""/> <fsummary>Return the inverse of a function.</fsummary> <desc> - <p>Returns the <seealso marker="#inverse">inverse</seealso> + <p>Returns the <seeerl marker="#inverse">inverse</seeerl> of function <c><anno>Function1</anno></c>.</p> <pre> 1> <input>R1 = sofs:relation([{1,a},{2,b},{3,c}]),</input> @@ -1104,8 +1104,8 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Return the inverse image of a set under a binary relation.</fsummary> <desc> - <p>Returns the <seealso marker="#inverse_image">inverse - image</seealso> of <c><anno>Set1</anno></c> under the binary + <p>Returns the <seeerl marker="#inverse_image">inverse + image</seeerl> of <c><anno>Set1</anno></c> under the binary relation <c><anno>BinRel</anno></c>.</p> <pre> 1> <input>R = sofs:relation([{1,a},{2,b},{2,c},{3,d}]),</input> @@ -1121,7 +1121,7 @@ fun(S) -> sofs:partition(1, S) end <fsummary>Test for a function.</fsummary> <desc> <p>Returns <c>true</c> if the binary relation <c><anno>BinRel</anno></c> - is a <seealso marker="#function">function</seealso> or the + is a <seeerl marker="#function">function</seeerl> or the untyped empty set, otherwise <c>false</c>.</p> </desc> </func> @@ -1132,7 +1132,7 @@ fun(S) -> sofs:partition(1, S) end <desc> <p>Returns <c>true</c> if <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c> - are <seealso marker="#disjoint">disjoint</seealso>, otherwise + are <seeerl marker="#disjoint">disjoint</seeerl>, otherwise <c>false</c>.</p> </desc> </func> @@ -1152,7 +1152,7 @@ fun(S) -> sofs:partition(1, S) end <desc> <p>Returns <c>true</c> if <c><anno>AnySet1</anno></c> and <c><anno>AnySet2</anno></c> - are <seealso marker="#equal">equal</seealso>, otherwise + are <seeerl marker="#equal">equal</seeerl>, otherwise <c>false</c>. The following example shows that <c>==/2</c> is used when comparing sets for equality:</p> <pre> @@ -1168,7 +1168,7 @@ true</pre> <fsummary>Test for an unordered set.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>AnySet</anno></c> is - an <seealso marker="#sets_definition">unordered set</seealso>, and + an <seeerl marker="#sets_definition">unordered set</seeerl>, and <c>false</c> if <c><anno>AnySet</anno></c> is an ordered set or an atomic set.</p> </desc> @@ -1179,7 +1179,7 @@ true</pre> <fsummary>Test for an unordered set.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is - an <seealso marker="#sets_definition">unordered set</seealso>, an + an <seeerl marker="#sets_definition">unordered set</seeerl>, an ordered set, or an atomic set, otherwise <c>false</c>.</p> </desc> </func> @@ -1189,7 +1189,7 @@ true</pre> <fsummary>Test two sets for subset.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Set1</anno></c> is - a <seealso marker="#subset">subset</seealso> + a <seeerl marker="#subset">subset</seeerl> of <c><anno>Set2</anno></c>, otherwise <c>false</c>.</p> </desc> </func> @@ -1199,7 +1199,7 @@ true</pre> <fsummary>Test for a type.</fsummary> <desc> <p>Returns <c>true</c> if term <c><anno>Term</anno></c> is - a <seealso marker="#type">type</seealso>.</p> + a <seeerl marker="#type">type</seeerl>.</p> </desc> </func> @@ -1207,8 +1207,8 @@ true</pre> <name name="join" arity="4" since=""/> <fsummary>Return the join of two relations.</fsummary> <desc> - <p>Returns the <seealso marker="#natural_join">natural - join</seealso> of the relations <c><anno>Relation1</anno></c> + <p>Returns the <seeerl marker="#natural_join">natural + join</seeerl> of the relations <c><anno>Relation1</anno></c> and <c><anno>Relation2</anno></c> on coordinates <c><anno>I</anno></c> and <c><anno>J</anno></c>.</p> <pre> @@ -1229,8 +1229,8 @@ true</pre> {R[1], ..., R[n]} of binary relations and <c><anno>BinRel1</anno></c> is a binary relation, then <c><anno>BinRel2</anno></c> is - the <seealso marker="#multiple_relative_product">multiple relative - product</seealso> of the ordered set + the <seeerl marker="#multiple_relative_product">multiple relative + product</seeerl> of the ordered set (R[i], ..., R[n]) and <c><anno>BinRel1</anno></c>.</p> <pre> 1> <input>Ri = sofs:relation([{a,1},{b,2},{c,3}]),</input> @@ -1254,7 +1254,7 @@ true</pre> <name name="partition" arity="1" since=""/> <fsummary>Return the coarsest partition given a set of sets.</fsummary> <desc> - <p>Returns the <seealso marker="#partition">partition</seealso> of + <p>Returns the <seeerl marker="#partition">partition</seeerl> of the union of the set of sets <c><anno>SetOfSets</anno></c> such that two elements are considered equal if they belong to the same elements of <c><anno>SetOfSets</anno></c>.</p> @@ -1271,7 +1271,7 @@ true</pre> <name name="partition" arity="2" since=""/> <fsummary>Return a partition of a set.</fsummary> <desc> - <p>Returns the <seealso marker="#partition">partition</seealso> of + <p>Returns the <seeerl marker="#partition">partition</seeerl> of <c><anno>Set</anno></c> such that two elements are considered equal if the results of applying <c><anno>SetFun</anno></c> are equal.</p> <pre> @@ -1288,7 +1288,7 @@ true</pre> <fsummary>Return a partition of a set.</fsummary> <desc> <p>Returns a pair of sets that, regarded as constituting a - set, forms a <seealso marker="#partition">partition</seealso> of + set, forms a <seeerl marker="#partition">partition</seeerl> of <c><anno>Set1</anno></c>. If the result of applying <c><anno>SetFun</anno></c> to an element of <c><anno>Set1</anno></c> gives an element in <c><anno>Set2</anno></c>, @@ -1310,14 +1310,14 @@ true</pre> <name name="partition_family" arity="2" since=""/> <fsummary>Return a family indexing a partition.</fsummary> <desc> - <p>Returns <seealso marker="#family">family</seealso> + <p>Returns <seeerl marker="#family">family</seeerl> <c><anno>Family</anno></c> where the indexed set is - a <seealso marker="#partition">partition</seealso> + a <seeerl marker="#partition">partition</seeerl> of <c><anno>Set</anno></c> such that two elements are considered equal if the results of applying <c><anno>SetFun</anno></c> are the same value i. This i is the index that <c><anno>Family</anno></c> - maps onto the <seealso marker="#equivalence_class">equivalence - class</seealso>.</p> + maps onto the <seeerl marker="#equivalence_class">equivalence + class</seeerl>.</p> <pre> 1> <input>S = sofs:relation([{a,a,a,a},{a,a,b,b},{a,b,b,b}]),</input> <input>SetFun = {external, fun({A,_,C,_}) -> {A,C} end},</input> @@ -1331,8 +1331,8 @@ true</pre> <name name="product" arity="1" since=""/> <fsummary>Return the Cartesian product of a tuple of sets.</fsummary> <desc> - <p>Returns the <seealso marker="#Cartesian_product_tuple">Cartesian - product</seealso> of the non-empty tuple of sets + <p>Returns the <seeerl marker="#Cartesian_product_tuple">Cartesian + product</seeerl> of the non-empty tuple of sets <c><anno>TupleOfSets</anno></c>. If (x[1], ..., x[n]) is an element of the n-ary relation <c><anno>Relation</anno></c>, then x[i] is drawn from element i of <c><anno>TupleOfSets</anno></c>.</p> @@ -1350,8 +1350,8 @@ true</pre> <name name="product" arity="2" since=""/> <fsummary>Return the Cartesian product of two sets.</fsummary> <desc> - <p>Returns the <seealso marker="#Cartesian_product">Cartesian - product</seealso> of <c><anno>Set1</anno></c> + <p>Returns the <seeerl marker="#Cartesian_product">Cartesian + product</seeerl> of <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c>.</p> <pre> 1> <input>S1 = sofs:set([1,2]),</input> @@ -1373,7 +1373,7 @@ true</pre> applying <c><anno>SetFun</anno></c> to the element.</p> <p>If <c><anno>SetFun</anno></c> is a number i >= 1 and <c><anno>Set1</anno></c> is a relation, then the returned set is - the <seealso marker="#projection">projection</seealso> of + the <seeerl marker="#projection">projection</seeerl> of <c><anno>Set1</anno></c> onto coordinate i.</p> <pre> 1> <input>S1 = sofs:from_term([{1,a},{2,b},{3,a}]),</input> @@ -1387,7 +1387,7 @@ true</pre> <name name="range" arity="1" since=""/> <fsummary>Return the range of a binary relation.</fsummary> <desc> - <p>Returns the <seealso marker="#range">range</seealso> of the + <p>Returns the <seeerl marker="#range">range</seeerl> of the binary relation <c><anno>BinRel</anno></c>.</p> <pre> 1> <input>R = sofs:relation([{1,a},{1,b},{2,b},{2,c}]),</input> @@ -1402,10 +1402,10 @@ true</pre> <name name="relation" arity="2" since=""/> <fsummary>Create a relation.</fsummary> <desc> - <p>Creates a <seealso marker="#relation">relation</seealso>. + <p>Creates a <seeerl marker="#relation">relation</seeerl>. <c>relation(R, T)</c> is equivalent to <c>from_term(R, T)</c>, if T is - a <seealso marker="#type">type</seealso> and the result is a + a <seeerl marker="#type">type</seeerl> and the result is a relation. If <c><anno>Type</anno></c> is an integer N, then <c>[{atom, ..., atom}])</c>, where the tuple size is N, is used as type of the relation. If no type is @@ -1420,11 +1420,11 @@ true</pre> <name name="relation_to_family" arity="1" since=""/> <fsummary>Create a family from a binary relation.</fsummary> <desc> - <p>Returns <seealso marker="#family">family</seealso> + <p>Returns <seeerl marker="#family">family</seeerl> <c><anno>Family</anno></c> such that the index set is equal to - the <seealso marker="#domain">domain</seealso> of the binary + the <seeerl marker="#domain">domain</seeerl> of the binary relation <c><anno>BinRel</anno></c>, and <c><anno>Family</anno></c>[i] - is the <seealso marker="#image">image</seealso> of the set of i + is the <seeerl marker="#image">image</seeerl> of the set of i under <c><anno>BinRel</anno></c>.</p> <pre> 1> <input>R = sofs:relation([{b,1},{c,2},{c,3}]),</input> @@ -1444,13 +1444,13 @@ true</pre> [R[1], ..., R[n]] of binary relations and <c><anno>BinRel1</anno></c> is a binary relation, then <c><anno>BinRel2</anno></c> is the - <seealso marker="#tuple_relative_product">relative product</seealso> + <seeerl marker="#tuple_relative_product">relative product</seeerl> of the ordered set (R[i], ..., R[n]) and <c><anno>BinRel1</anno></c>.</p> <p>If <c><anno>BinRel1</anno></c> is omitted, the relation of equality between the elements of - the <seealso marker="#Cartesian_product_tuple">Cartesian - product</seealso> of the ranges of R[i], + the <seeerl marker="#Cartesian_product_tuple">Cartesian + product</seeerl> of the ranges of R[i], range R[1] × ... × range R[n], is used instead (intuitively, nothing is "lost").</p> <pre> @@ -1470,8 +1470,8 @@ true</pre> <fsummary>Return the relative product of two binary relations.</fsummary> <desc> - <p>Returns the <seealso marker="#relative_product">relative - product</seealso> of the binary relations <c><anno>BinRel1</anno></c> + <p>Returns the <seeerl marker="#relative_product">relative + product</seeerl> of the binary relations <c><anno>BinRel1</anno></c> and <c><anno>BinRel2</anno></c>.</p> </desc> </func> @@ -1481,9 +1481,9 @@ true</pre> <fsummary>Return the relative_product of two binary relations.</fsummary> <desc> - <p>Returns the <seealso marker="#relative_product">relative - product</seealso> of - the <seealso marker="#converse">converse</seealso> of the + <p>Returns the <seeerl marker="#relative_product">relative + product</seeerl> of + the <seeerl marker="#converse">converse</seeerl> of the binary relation <c><anno>BinRel1</anno></c> and the binary relation <c><anno>BinRel2</anno></c>.</p> <pre> @@ -1501,7 +1501,7 @@ true</pre> <name name="restriction" arity="2" since=""/> <fsummary>Return a restriction of a binary relation.</fsummary> <desc> - <p>Returns the <seealso marker="#restriction">restriction</seealso> of + <p>Returns the <seeerl marker="#restriction">restriction</seeerl> of the binary relation <c><anno>BinRel1</anno></c> to <c><anno>Set</anno></c>.</p> <pre> @@ -1534,10 +1534,10 @@ true</pre> <name name="set" arity="2" since=""/> <fsummary>Create a set of atoms or any type of sets.</fsummary> <desc> - <p>Creates an <seealso marker="#sets_definition">unordered - set</seealso>. <c>set(L, T)</c> is equivalent to + <p>Creates an <seeerl marker="#sets_definition">unordered + set</seeerl>. <c>set(L, T)</c> is equivalent to <c>from_term(L, T)</c>, if the result is an unordered - set. If no <seealso marker="#type">type</seealso> is + set. If no <seeerl marker="#type">type</seeerl> is explicitly specified, <c>[atom]</c> is used as the set type.</p> </desc> </func> @@ -1550,7 +1550,7 @@ true</pre> of <c><anno>Set1</anno></c> for which <c><anno>Fun</anno></c> returns <c>true</c>. If <c><anno>Fun</anno></c> is a tuple <c>{external, Fun2}</c>, <c>Fun2</c> is applied to the - <seealso marker="#external_set">external set</seealso> of + <seeerl marker="#external_set">external set</seeerl> of each element, otherwise <c><anno>Fun</anno></c> is applied to each element.</p> <pre> @@ -1568,8 +1568,8 @@ true</pre> <fsummary>Return the strict relation corresponding to a given relation.</fsummary> <desc> - <p>Returns the <seealso marker="#strict_relation">strict - relation</seealso> corresponding to the binary + <p>Returns the <seeerl marker="#strict_relation">strict + relation</seeerl> corresponding to the binary relation <c><anno>BinRel1</anno></c>.</p> <pre> 1> <input>R1 = sofs:relation([{1,1},{1,2},{2,1},{2,2}]),</input> @@ -1604,7 +1604,7 @@ true</pre> [{a,a},{b,b},{c,c}]</pre> <p>Let <c>SetOfSets</c> be a set of sets and <c>BinRel</c> a binary relation. The function that maps each element <c>Set</c> of - <c>SetOfSets</c> onto the <seealso marker="#image">image</seealso> + <c>SetOfSets</c> onto the <seeerl marker="#image">image</seeerl> of <c>Set</c> under <c>BinRel</c> is returned by the following function:</p> <pre> @@ -1614,7 +1614,7 @@ images(SetOfSets, BinRel) -> <p>External unordered sets are represented as sorted lists. So, creating the image of a set under a relation R can traverse all elements of R (to that comes the sorting of results, the - image). In <seealso marker="#image/2"><c>image/2</c></seealso>, + image). In <seemfa marker="#image/2"><c>image/2</c></seemfa>, <c>BinRel</c> is traversed once for each element of <c>SetOfSets</c>, which can take too long. The following efficient function can be used instead under the @@ -1632,8 +1632,8 @@ images2(SetOfSets, BinRel) -> <name name="symdiff" arity="2" since=""/> <fsummary>Return the symmetric difference of two sets.</fsummary> <desc> - <p>Returns the <seealso marker="#symmetric_difference">symmetric - difference</seealso> (or the Boolean sum) + <p>Returns the <seeerl marker="#symmetric_difference">symmetric + difference</seeerl> (or the Boolean sum) of <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c>.</p> <pre> 1> <input>S1 = sofs:set([1,2,3]),</input> @@ -1669,8 +1669,8 @@ images2(SetOfSets, BinRel) -> <name name="to_external" arity="1" since=""/> <fsummary>Return the elements of a set.</fsummary> <desc> - <p>Returns the <seealso marker="#external_set">external - set</seealso> of an atomic, ordered, or unordered set.</p> + <p>Returns the <seeerl marker="#external_set">external + set</seeerl> of an atomic, ordered, or unordered set.</p> </desc> </func> @@ -1689,7 +1689,7 @@ images2(SetOfSets, BinRel) -> <name name="type" arity="1" since=""/> <fsummary>Return the type of a set.</fsummary> <desc> - <p>Returns the <seealso marker="#type">type</seealso> of an + <p>Returns the <seeerl marker="#type">type</seeerl> of an atomic, ordered, or unordered set.</p> </desc> </func> @@ -1698,7 +1698,7 @@ images2(SetOfSets, BinRel) -> <name name="union" arity="1" since=""/> <fsummary>Return the union of a set of sets.</fsummary> <desc> - <p>Returns the <seealso marker="#union_n">union</seealso> of the + <p>Returns the <seeerl marker="#union_n">union</seeerl> of the set of sets <c><anno>SetOfSets</anno></c>.</p> </desc> </func> @@ -1707,7 +1707,7 @@ images2(SetOfSets, BinRel) -> <name name="union" arity="2" since=""/> <fsummary>Return the union of two sets.</fsummary> <desc> - <p>Returns the <seealso marker="#union">union</seealso> of + <p>Returns the <seeerl marker="#union">union</seeerl> of <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c>.</p> </desc> </func> @@ -1716,7 +1716,7 @@ images2(SetOfSets, BinRel) -> <name name="union_of_family" arity="1" since=""/> <fsummary>Return the union of a family.</fsummary> <desc> - <p>Returns the union of <seealso marker="#family">family</seealso> + <p>Returns the union of <seeerl marker="#family">family</seeerl> <c><anno>Family</anno></c>.</p> <pre> 1> <input>F = sofs:family([{a,[0,2,4]},{b,[0,1,2]},{c,[2,3]}]),</input> @@ -1731,10 +1731,10 @@ images2(SetOfSets, BinRel) -> <fsummary>Return the weak relation corresponding to a given relation.</fsummary> <desc> - <p>Returns a subset S of the <seealso marker="#weak_relation">weak - relation</seealso> W + <p>Returns a subset S of the <seeerl marker="#weak_relation">weak + relation</seeerl> W corresponding to the binary relation <c><anno>BinRel1</anno></c>. - Let F be the <seealso marker="#field">field</seealso> of + Let F be the <seeerl marker="#field">field</seeerl> of <c><anno>BinRel1</anno></c>. The subset S is defined so that x S y if x W y for some x in F and for some y in F.</p> @@ -1749,11 +1749,11 @@ images2(SetOfSets, BinRel) -> <section> <title>See Also</title> - <p><seealso marker="dict"><c>dict(3)</c></seealso>, - <seealso marker="digraph"><c>digraph(3)</c></seealso>, - <seealso marker="orddict"><c>orddict(3)</c></seealso>, - <seealso marker="ordsets"><c>ordsets(3)</c></seealso>, - <seealso marker="sets"><c>sets(3)</c></seealso></p> + <p><seeerl marker="dict"><c>dict(3)</c></seeerl>, + <seeerl marker="digraph"><c>digraph(3)</c></seeerl>, + <seeerl marker="orddict"><c>orddict(3)</c></seeerl>, + <seeerl marker="ordsets"><c>ordsets(3)</c></seeerl>, + <seeerl marker="sets"><c>sets(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/specs.xml b/lib/stdlib/doc/src/specs.xml index fd2d625685..9b11a6941c 100644 --- a/lib/stdlib/doc/src/specs.xml +++ b/lib/stdlib/doc/src/specs.xml @@ -51,6 +51,7 @@ <xi:include href="../specs/specs_sets.xml"/> <xi:include href="../specs/specs_shell.xml"/> <xi:include href="../specs/specs_shell_default.xml"/> + <xi:include href="../specs/specs_shell_docs.xml"/> <xi:include href="../specs/specs_slave.xml"/> <xi:include href="../specs/specs_sofs.xml"/> <xi:include href="../specs/specs_string.xml"/> diff --git a/lib/stdlib/doc/src/stdlib_app.xml b/lib/stdlib/doc/src/stdlib_app.xml index f857cc394b..51caf4d14d 100644 --- a/lib/stdlib/doc/src/stdlib_app.xml +++ b/lib/stdlib/doc/src/stdlib_app.xml @@ -40,7 +40,7 @@ <title>Configuration</title> <p>The following configuration parameters are defined for the STDLIB application. For more information about configuration parameters, see the - <seealso marker="kernel:app"><c>app(4)</c></seealso> module in Kernel.</p> + <seefile marker="kernel:app"><c>app(4)</c></seefile> module in Kernel.</p> <taglist> <tag><c>shell_esc = icl | abort</c></tag> @@ -86,9 +86,9 @@ <section> <title>See Also</title> - <p><seealso marker="kernel:app"><c>app(4)</c></seealso>, - <seealso marker="kernel:application"><c>application(3)</c></seealso>, - <seealso marker="shell">shell(3)</seealso></p> + <p><seefile marker="kernel:app"><c>app(4)</c></seefile>, + <seeerl marker="kernel:application"><c>application(3)</c></seeerl>, + <seeerl marker="shell">shell(3)</seeerl></p> </section> </appref> diff --git a/lib/stdlib/doc/src/string.xml b/lib/stdlib/doc/src/string.xml index d102191a57..4735f72943 100644 --- a/lib/stdlib/doc/src/string.xml +++ b/lib/stdlib/doc/src/string.xml @@ -36,8 +36,8 @@ <modulesummary>String processing functions.</modulesummary> <description> <p>This module provides functions for string processing.</p> - <p>A string in this module is represented by <seealso marker="unicode#type-chardata"> - <c>unicode:chardata()</c></seealso>, that is, a list of codepoints, + <p>A string in this module is represented by <seetype marker="unicode#chardata"> + <c>unicode:chardata()</c></seetype>, that is, a list of codepoints, binaries with UTF-8-encoded codepoints (<em>UTF-8 binaries</em>), or a mix of the two.</p> <code> @@ -66,11 +66,11 @@ Grapheme clusters for codepoints of class <c>prepend</c> and non-modern (or decomposed) Hangul is not handled for performance reasons in - <seealso marker="#find/3"><c>find/3</c></seealso>, - <seealso marker="#replace/3"><c>replace/3</c></seealso>, - <seealso marker="#split/2"><c>split/2</c></seealso>, - <seealso marker="#lexemes/2"><c>split/2</c></seealso> and - <seealso marker="#trim/3"><c>trim/3</c></seealso>. + <seemfa marker="#find/3"><c>find/3</c></seemfa>, + <seemfa marker="#replace/3"><c>replace/3</c></seemfa>, + <seemfa marker="#split/2"><c>split/2</c></seemfa>, + <seemfa marker="#lexemes/2"><c>split/2</c></seemfa> and + <seemfa marker="#trim/3"><c>trim/3</c></seemfa>. </p> <p> Splitting and appending strings is to be done on grapheme clusters @@ -80,8 +80,8 @@ </p> <p> Most of the functions expect all input to be normalized to one form, - see for example <seealso marker="unicode#characters_to_nfc_list/1"> - <c>unicode:characters_to_nfc_list/1</c></seealso>. + see for example <seemfa marker="unicode#characters_to_nfc_list/1"> + <c>unicode:characters_to_nfc_list/1</c></seemfa>. </p> <p> Language or locale specific handling of input is not considered @@ -107,10 +107,10 @@ 4> string:lexemes(<<"foo bar">>, " "). [<<"foo">>,<<"bar">>]</code> <p>This module has been reworked in Erlang/OTP 20 to - handle <seealso marker="unicode#type-chardata"> - <c>unicode:chardata()</c></seealso> and operate on grapheme - clusters. The <seealso marker="#oldapi"> <c>old - functions</c></seealso> that only work on Latin-1 lists as input + handle <seetype marker="unicode#chardata"> + <c>unicode:chardata()</c></seetype> and operate on grapheme + clusters. The <seeerl marker="#oldapi"> <c>old + functions</c></seeerl> that only work on Latin-1 lists as input are still available but should not be used, they will be deprecated in a future release. </p> @@ -137,7 +137,7 @@ Converts <c><anno>String</anno></c> to a case-agnostic comparable string. Function <c>casefold/1</c> is preferred over <c>lowercase/1</c> when two strings are to be compared - for equality. See also <seealso marker="#equal/4"><c>equal/4</c></seealso>. + for equality. See also <seemfa marker="#equal/4"><c>equal/4</c></seemfa>. </p> <p><em>Example:</em></p> <pre> @@ -175,16 +175,16 @@ </p> <p> If <c><anno>IgnoreCase</anno></c> is <c>true</c> - the function does <seealso marker="#casefold/1"> - <c>casefold</c>ing</seealso> on the fly before the equality test. + the function does <seemfa marker="#casefold/1"> + <c>casefold</c>ing</seemfa> on the fly before the equality test. </p> <p>If <c><anno>Norm</anno></c> is not <c>none</c> the function applies normalization on the fly before the equality test. There are four available normalization forms: - <seealso marker="unicode#characters_to_nfc_list/1"> <c>nfc</c></seealso>, - <seealso marker="unicode#characters_to_nfd_list/1"> <c>nfd</c></seealso>, - <seealso marker="unicode#characters_to_nfkc_list/1"> <c>nfkc</c></seealso>, and - <seealso marker="unicode#characters_to_nfkd_list/1"> <c>nfkd</c></seealso>. + <seemfa marker="unicode#characters_to_nfc_list/1"> <c>nfc</c></seemfa>, + <seemfa marker="unicode#characters_to_nfd_list/1"> <c>nfd</c></seemfa>, + <seemfa marker="unicode#characters_to_nfkc_list/1"> <c>nfkc</c></seemfa>, and + <seemfa marker="unicode#characters_to_nfkd_list/1"> <c>nfkd</c></seemfa>. </p> <p>By default, <c><anno>IgnoreCase</anno></c> is <c>false</c> and @@ -273,7 +273,7 @@ true</pre> adjacent separator graphemes clusters in <c><anno>String</anno></c> are treated as one. That is, there are no empty strings in the resulting list of lexemes. - See also <seealso marker="#split/3"><c>split/3</c></seealso> which returns + See also <seemfa marker="#split/3"><c>split/3</c></seemfa> which returns empty strings. </p> <p>Notice that <c>[$\r,$\n]</c> is one grapheme cluster.</p> @@ -294,7 +294,7 @@ true</pre> Converts <c><anno>String</anno></c> to lowercase. </p> <p> - Notice that function <seealso marker="#casefold/1"><c>casefold/1</c></seealso> + Notice that function <seemfa marker="#casefold/1"><c>casefold/1</c></seemfa> should be used when converting a string to be tested for equality. </p> @@ -622,7 +622,7 @@ ÖÄÅ</pre> <p> Converts <c><anno>String</anno></c> to uppercase. </p> - <p>See also <seealso marker="#titlecase/1"><c>titlecase/1</c></seealso>.</p> + <p>See also <seemfa marker="#titlecase/1"><c>titlecase/1</c></seemfa>.</p> <p><em>Example:</em></p> <pre> 1> <input>string:uppercase("Michał").</input> @@ -632,22 +632,23 @@ ÖÄÅ</pre> </funcs> - <section> - <marker id="oldapi"/> - <title>Obsolete API functions</title> - <p>Here follows the function of the old API. - These functions only work on a list of Latin-1 characters. - </p> - <note><p> - The functions are kept for backward compatibility, but are - not recommended. - They will be deprecated in a future release. - </p> - <p>Any undocumented functions in <c>string</c> are not to be used.</p> - </note> - </section> + <funcs> + <fsdescription> + <marker id="oldapi"/> + <title>Obsolete API functions</title> + <p>Here follows the function of the old API. + These functions only work on a list of Latin-1 characters. + </p> + <note><p> + The functions are kept for backward compatibility, but are + not recommended. + They will be deprecated in a future release. + </p> + <p>Any undocumented functions in <c>string</c> are not to be used.</p> + </note> + </fsdescription> <func> <name name="centre" arity="2" since=""/> <name name="centre" arity="3" since=""/> @@ -656,9 +657,9 @@ ÖÄÅ</pre> <p>Returns a string, where <c><anno>String</anno></c> is centered in the string and surrounded by blanks or <c><anno>Character</anno></c>. The resulting string has length <c><anno>Number</anno></c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#pad/3"><c>pad/3</c></seealso>. + <seemfa marker="#pad/3"><c>pad/3</c></seemfa>. </p> </desc> </func> @@ -671,9 +672,9 @@ ÖÄÅ</pre> <p>Returns a string consisting of <c><anno>Number</anno></c> characters <c><anno>Character</anno></c>. Optionally, the string can end with string <c><anno>Tail</anno></c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="lists#duplicate/2"><c>lists:duplicate/2</c></seealso>.</p> + <seemfa marker="lists#duplicate/2"><c>lists:duplicate/2</c></seemfa>.</p> </desc> </func> @@ -685,9 +686,9 @@ ÖÄÅ</pre> <p>Returns the index of the first occurrence of <c><anno>Character</anno></c> in <c><anno>String</anno></c>. Returns <c>0</c> if <c><anno>Character</anno></c> does not occur.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#find/2"><c>find/2</c></seealso>.</p> + <seemfa marker="#find/2"><c>find/2</c></seemfa>.</p> </desc> </func> @@ -699,13 +700,13 @@ ÖÄÅ</pre> <c><anno>String2</anno></c> to form a new string <c><anno>String3</anno></c>, which is returned.</p> <p> - This function is <seealso marker="#oldapi">obsolete</seealso>. + This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use <c>[<anno>String1</anno>, <anno>String2</anno>]</c> as <c>Data</c> argument, and call - <seealso marker="unicode#characters_to_list/2"> - <c>unicode:characters_to_list/2</c></seealso> or - <seealso marker="unicode#characters_to_binary/2"> - <c>unicode:characters_to_binary/2</c></seealso> + <seemfa marker="unicode#characters_to_list/2"> + <c>unicode:characters_to_list/2</c></seemfa> or + <seemfa marker="unicode#characters_to_binary/2"> + <c>unicode:characters_to_binary/2</c></seemfa> to flatten the output. </p> </desc> @@ -717,9 +718,9 @@ ÖÄÅ</pre> <desc> <p>Returns a string containing <c><anno>String</anno></c> repeated <c><anno>Number</anno></c> times.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="lists#duplicate/2"><c>lists:duplicate/2</c></seealso>.</p> + <seemfa marker="lists#duplicate/2"><c>lists:duplicate/2</c></seemfa>.</p> </desc> </func> @@ -730,9 +731,9 @@ ÖÄÅ</pre> <p>Returns the length of the maximum initial segment of <c><anno>String</anno></c>, which consists entirely of characters not from <c><anno>Chars</anno></c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#take/3"><c>take/3</c></seealso>.</p> + <seemfa marker="#take/3"><c>take/3</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> > string:cspan("\t abcdef", " \t"). @@ -746,9 +747,9 @@ ÖÄÅ</pre> <desc> <p>Returns a string with the elements of <c><anno>StringList</anno></c> separated by the string in <c><anno>Separator</anno></c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="lists#join/2"><c>lists:join/2</c></seealso>.</p> + <seemfa marker="lists#join/2"><c>lists:join/2</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> > join(["one", "two", "three"], ", "). @@ -766,10 +767,10 @@ ÖÄÅ</pre> fixed. If <c>length(<anno>String</anno>)</c> < <c><anno>Number</anno></c>, then <c><anno>String</anno></c> is padded with blanks or <c><anno>Character</anno></c>s.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#pad/2"><c>pad/2</c></seealso> or - <seealso marker="#pad/3"><c>pad/3</c></seealso>.</p> + <seemfa marker="#pad/2"><c>pad/2</c></seemfa> or + <seemfa marker="#pad/3"><c>pad/3</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> > string:left("Hello",10,$.). @@ -782,9 +783,9 @@ ÖÄÅ</pre> <fsummary>Return the length of a string.</fsummary> <desc> <p>Returns the number of characters in <c><anno>String</anno></c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#length/1"><c>length/1</c></seealso>.</p> + <seemfa marker="#length/1"><c>length/1</c></seemfa>.</p> </desc> </func> @@ -796,9 +797,9 @@ ÖÄÅ</pre> <p>Returns the index of the last occurrence of <c><anno>Character</anno></c> in <c><anno>String</anno></c>. Returns <c>0</c> if <c><anno>Character</anno></c> does not occur.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#find/3"><c>find/3</c></seealso>.</p> + <seemfa marker="#find/3"><c>find/3</c></seemfa>.</p> </desc> </func> @@ -812,9 +813,9 @@ ÖÄÅ</pre> fixed. If the length of <c>(<anno>String</anno>)</c> < <c><anno>Number</anno></c>, then <c><anno>String</anno></c> is padded with blanks or <c><anno>Character</anno></c>s.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#pad/3"><c>pad/3</c></seealso>.</p> + <seemfa marker="#pad/3"><c>pad/3</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> > string:right("Hello", 10, $.). @@ -830,9 +831,9 @@ ÖÄÅ</pre> <c><anno>SubString</anno></c> begins in <c><anno>String</anno></c>. Returns <c>0</c> if <c><anno>SubString</anno></c> does not exist in <c><anno>String</anno></c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#find/3"><c>find/3</c></seealso>.</p> + <seemfa marker="#find/3"><c>find/3</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> > string:rstr(" Hello Hello World World ", "Hello World"). @@ -847,9 +848,9 @@ ÖÄÅ</pre> <p>Returns the length of the maximum initial segment of <c><anno>String</anno></c>, which consists entirely of characters from <c><anno>Chars</anno></c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#take/2"><c>take/2</c></seealso>.</p> + <seemfa marker="#take/2"><c>take/2</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> > string:span("\t abcdef", " \t"). @@ -865,9 +866,9 @@ ÖÄÅ</pre> <c><anno>SubString</anno></c> begins in <c><anno>String</anno></c>. Returns <c>0</c> if <c><anno>SubString</anno></c> does not exist in <c><anno>String</anno></c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#find/2"><c>find/2</c></seealso>.</p> + <seemfa marker="#find/2"><c>find/2</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> > string:str(" Hello Hello World World ", "Hello World"). @@ -887,9 +888,9 @@ ÖÄÅ</pre> or <c>both</c>, indicates from which direction blanks are to be removed. <c>strip/1</c> is equivalent to <c>strip(String, both)</c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#trim/3"><c>trim/3</c></seealso>.</p> + <seemfa marker="#trim/3"><c>trim/3</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> > string:strip("...Hello.....", both, $.). @@ -905,9 +906,9 @@ ÖÄÅ</pre> <p>Returns a substring of <c><anno>String</anno></c>, starting at position <c><anno>Start</anno></c> to the end of the string, or to and including position <c><anno>Stop</anno></c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#slice/3"><c>slice/3</c></seealso>.</p> + <seemfa marker="#slice/3"><c>slice/3</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> sub_string("Hello World", 4, 8). @@ -923,9 +924,9 @@ sub_string("Hello World", 4, 8). <p>Returns a substring of <c><anno>String</anno></c>, starting at position <c><anno>Start</anno></c>, and ending at the end of the string or at length <c><anno>Length</anno></c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#slice/3"><c>slice/3</c></seealso>.</p> + <seemfa marker="#slice/3"><c>slice/3</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> > substr("Hello World", 4, 5). @@ -941,9 +942,9 @@ sub_string("Hello World", 4, 8). <p>Returns the word in position <c><anno>Number</anno></c> of <c><anno>String</anno></c>. Words are separated by blanks or <c><anno>Character</anno></c>s.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#nth_lexeme/3"><c>nth_lexeme/3</c></seealso>.</p> + <seemfa marker="#nth_lexeme/3"><c>nth_lexeme/3</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> > string:sub_word(" Hello old boy !",3,$o). @@ -965,11 +966,11 @@ sub_string("Hello World", 4, 8). <p>The specified string or character is case-converted. Notice that the supported character set is ISO/IEC 8859-1 (also called Latin 1); all values outside this set are unchanged</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso> use - <seealso marker="#lowercase/1"><c>lowercase/1</c></seealso>, - <seealso marker="#uppercase/1"><c>uppercase/1</c></seealso>, - <seealso marker="#titlecase/1"><c>titlecase/1</c></seealso> or - <seealso marker="#casefold/1"><c>casefold/1</c></seealso>.</p> + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl> use + <seemfa marker="#lowercase/1"><c>lowercase/1</c></seemfa>, + <seemfa marker="#uppercase/1"><c>uppercase/1</c></seemfa>, + <seemfa marker="#titlecase/1"><c>titlecase/1</c></seemfa> or + <seemfa marker="#casefold/1"><c>casefold/1</c></seemfa>.</p> </desc> </func> @@ -987,9 +988,9 @@ sub_string("Hello World", 4, 8). adjacent separator characters in <c><anno>String</anno></c> are treated as one. That is, there are no empty strings in the resulting list of tokens.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#lexemes/2"><c>lexemes/2</c></seealso>.</p> + <seemfa marker="#lexemes/2"><c>lexemes/2</c></seemfa>.</p> </desc> </func> @@ -1000,9 +1001,9 @@ sub_string("Hello World", 4, 8). <desc> <p>Returns the number of words in <c><anno>String</anno></c>, separated by blanks or <c><anno>Character</anno></c>.</p> - <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + <p>This function is <seeerl marker="#oldapi">obsolete</seeerl>. Use - <seealso marker="#lexemes/2"><c>lexemes/2</c></seealso>.</p> + <seemfa marker="#lexemes/2"><c>lexemes/2</c></seemfa>.</p> <p><em>Example:</em></p> <code type="none"> > words(" Hello old boy!", $o). diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index f15b1a2dd3..6a44219084 100644 --- a/lib/stdlib/doc/src/supervisor.xml +++ b/lib/stdlib/doc/src/supervisor.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2018</year> + <year>1996</year><year>2019</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -35,16 +35,16 @@ supervises other processes called child processes. A child process can either be another supervisor or a worker process. Worker processes are normally implemented using one of the - <seealso marker="gen_event"><c>gen_event</c></seealso>, - <seealso marker="gen_server"><c>gen_server</c></seealso>, or - <seealso marker="gen_statem"><c>gen_statem</c></seealso> + <seeerl marker="gen_event"><c>gen_event</c></seeerl>, + <seeerl marker="gen_server"><c>gen_server</c></seeerl>, or + <seeerl marker="gen_statem"><c>gen_statem</c></seeerl> behaviors. A supervisor implemented using this module has a standard set of interface functions and include functionality for tracing and error reporting. Supervisors are used to build a hierarchical process structure called a supervision tree, a nice way to structure a fault-tolerant application. For more - information, see <seealso marker="doc/design_principles:sup_princ"> - Supervisor Behaviour</seealso> in OTP Design Principles.</p> + information, see <seeguide marker="system/design_principles:sup_princ"> + Supervisor Behaviour</seeguide> in OTP Design Principles.</p> <p>A supervisor expects the definition of which child processes to supervise to be specified in a callback module exporting a @@ -105,13 +105,13 @@ sup_flags() = #{strategy => strategy(), % optional instances of the same process type, that is, running the same code.</p> <p>Functions - <seealso marker="#delete_child/2"><c>delete_child/2</c></seealso> and - <seealso marker="#restart_child/2"><c>restart_child/2</c></seealso> + <seemfa marker="#delete_child/2"><c>delete_child/2</c></seemfa> and + <seemfa marker="#restart_child/2"><c>restart_child/2</c></seemfa> are invalid for <c>simple_one_for_one</c> supervisors and return <c>{error,simple_one_for_one}</c> if the specified supervisor uses this restart strategy.</p> - <p>Function <seealso marker="#terminate_child/2"> - <c>terminate_child/2</c></seealso> can be used for + <p>Function <seemfa marker="#terminate_child/2"> + <c>terminate_child/2</c></seemfa> can be used for children under <c>simple_one_for_one</c> supervisors by specifying the child's <c>pid()</c> as the second argument. If instead the child specification identifier is used, @@ -149,7 +149,7 @@ child_spec() = #{id => child_id(), % mandatory modules => modules()} % optional</pre> <p>The old tuple format is kept for backwards compatibility, - see <seealso marker="#type-child_spec">child_spec()</seealso>, + see <seetype marker="#child_spec">child_spec()</seetype>, but the map is preferred.</p> <list type="bulleted"> @@ -251,8 +251,8 @@ child_spec() = #{id => child_id(), % mandatory process is an event manager (<c>gen_event</c>) with a dynamic set of callback modules, value <c>dynamic</c> must be used. For more information about release handling, see - <seealso marker="doc/design_principles:release_handling"> - Release Handling</seealso> + <seeguide marker="system/design_principles:release_handling"> + Release Handling</seeguide> in OTP Design Principles.</p> <p>The <c>modules</c> key is optional. If it is not specified, it defaults to <c>[M]</c>, where <c>M</c> comes from the @@ -278,7 +278,7 @@ child_spec() = #{id => child_id(), % mandatory <name name="child_spec"/> <desc><p>The tuple format is kept for backward compatibility only. A map is preferred; see more details - <seealso marker="#child_spec">above</seealso>.</p></desc> + <seeerl marker="#child_spec">above</seeerl>.</p></desc> </datatype> <datatype> <name name="mfargs"/> @@ -300,13 +300,25 @@ child_spec() = #{id => child_id(), % mandatory <name name="shutdown"/> </datatype> <datatype> + <name name="startchild_err"/> + </datatype> + <datatype> + <name name="startchild_ret"/> + </datatype> + <datatype> + <name name="startlink_err"/> + </datatype> + <datatype> + <name name="startlink_ret"/> + </datatype> + <datatype> <name name="strategy"/> </datatype> <datatype> <name name="sup_flags"/> <desc><p>The tuple format is kept for backward compatibility only. A map is preferred; see more details - <seealso marker="#sup_flags">above</seealso>.</p></desc> + <seeerl marker="#sup_flags">above</seeerl>.</p></desc> </datatype> <datatype> <name name="sup_ref"/> @@ -333,8 +345,8 @@ child_spec() = #{id => child_id(), % mandatory <fsummary>Return counts for the number of child specifications, active children, supervisors, and workers.</fsummary> <desc> - <p>Returns a property list (see <seealso marker="proplists"> - <c>proplists</c></seealso>) containing the + <p>Returns a property list (see <seeerl marker="proplists"> + <c>proplists</c></seeerl>) containing the counts for each of the following elements of the supervisor's child specifications and managed processes:</p> <list type="bulleted"> @@ -361,7 +373,7 @@ child_spec() = #{id => child_id(), % mandatory </item> </list> <p>For a description of <c><anno>SupRef</anno></c>, see - <seealso marker="#SupRef"><c>start_child/2</c></seealso>.</p> + <seeerl marker="#SupRef"><c>start_child/2</c></seeerl>.</p> </desc> </func> @@ -372,10 +384,10 @@ child_spec() = #{id => child_id(), % mandatory <p>Tells supervisor <c><anno>SupRef</anno></c> to delete the child specification identified by <c><anno>Id</anno></c>. The corresponding child process must not be running. Use - <seealso marker="#terminate_child/2"> - <c>terminate_child/2</c></seealso> to terminate it.</p> + <seemfa marker="#terminate_child/2"> + <c>terminate_child/2</c></seemfa> to terminate it.</p> <p>For a description of <c><anno>SupRef</anno></c>, see - <seealso marker="#SupRef"><c>start_child/2</c></seealso>.</p> + <seeerl marker="#SupRef"><c>start_child/2</c></seeerl>.</p> <p>If successful, the function returns <c>ok</c>. If the child specification identified by <c><anno>Id</anno></c> exists but the corresponding child process is running or is about to be restarted, @@ -395,7 +407,7 @@ child_spec() = #{id => child_id(), % mandatory by <c>Id</c> under supervisor <c>SupRef</c>. The returned map contains all keys, both mandatory and optional.</p> <p>For a description of <c><anno>SupRef</anno></c>, see - <seealso marker="#SupRef"><c>start_child/2</c></seealso>.</p> + <seeerl marker="#SupRef"><c>start_child/2</c></seeerl>.</p> </desc> </func> @@ -413,7 +425,7 @@ child_spec() = #{id => child_id(), % mandatory is automatically deleted when the child terminates; thus, it is not possible to restart such children.</p> <p>For a description of <c><anno>SupRef</anno></c>, see - <seealso marker="#SupRef"><c>start_child/2</c></seealso>.</p> + <seeerl marker="#SupRef"><c>start_child/2</c></seeerl>.</p> <p>If the child specification identified by <c><anno>Id</anno></c> does not exist, the function returns <c>{error,not_found}</c>. If the child specification @@ -528,8 +540,8 @@ child_spec() = #{id => child_id(), % mandatory <item> <p>If <c><anno>SupName</anno>={global,Name}</c>, the supervisor is registered globally as <c>Name</c> using - <seealso marker="kernel:global#register_name/2"> - <c>global:register_name/2</c></seealso>.</p> + <seemfa marker="kernel:global#register_name/2"> + <c>global:register_name/2</c></seemfa>.</p> </item> <item> <p>If @@ -539,7 +551,7 @@ child_spec() = #{id => child_id(), % mandatory export the functions <c>register_name/2</c>, <c>unregister_name/1</c>, and <c>send/2</c>, which must behave like the corresponding functions in - <seealso marker="kernel:global"><c>global</c></seealso>. Thus, + <seeerl marker="kernel:global"><c>global</c></seeerl>. Thus, <c>{via,global,<anno>Name</anno>}</c> is a valid reference.</p> </item> </list> @@ -596,9 +608,9 @@ child_spec() = #{id => child_id(), % mandatory kept by the supervisor. The child process can later be restarted by the supervisor. The child process can also be restarted explicitly by calling - <seealso marker="#restart_child/2"><c>restart_child/2</c></seealso>. + <seemfa marker="#restart_child/2"><c>restart_child/2</c></seemfa>. Use - <seealso marker="#delete_child/2"><c>delete_child/2</c></seealso> + <seemfa marker="#delete_child/2"><c>delete_child/2</c></seemfa> to remove the child specification.</p> <p>If the child is temporary, the child specification is deleted as soon as the process terminates. This means @@ -616,7 +628,7 @@ child_spec() = #{id => child_id(), % mandatory no child specification with the specified <c><anno>Id</anno></c>, the function returns <c>{error,not_found}</c>.</p> <p>For a description of <c><anno>SupRef</anno></c>, see - <seealso marker="#SupRef"><c>start_child/2</c></seealso>.</p> + <seeerl marker="#SupRef"><c>start_child/2</c></seeerl>.</p> </desc> </func> @@ -629,10 +641,10 @@ child_spec() = #{id => child_id(), % mandatory specifications and child processes belonging to supervisor <c><anno>SupRef</anno></c>.</p> <p>Notice that calling this function when supervising many - childrens under low memory conditions can cause an + children under low memory conditions can cause an out of memory exception.</p> <p>For a description of <c><anno>SupRef</anno></c>, see - <seealso marker="#SupRef"><c>start_child/2</c></seealso>.</p> + <seeerl marker="#SupRef"><c>start_child/2</c></seeerl>.</p> <p>The following information is given for each child specification/process:</p> <list type="bulleted"> @@ -658,13 +670,14 @@ child_spec() = #{id => child_id(), % mandatory </func> </funcs> - <section> - <title>Callback Functions</title> - <p>The following function must be exported from a - <c>supervisor</c> callback module.</p> - </section> + <funcs> + <fsdescription> + <title>Callback Functions</title> + <p>The following function must be exported from a + <c>supervisor</c> callback module.</p> + </fsdescription> <func> <name since="">Module:init(Args) -> Result</name> <fsummary>Return a supervisor specification.</fsummary> @@ -672,13 +685,13 @@ child_spec() = #{id => child_id(), % mandatory <v>Args = term()</v> <v>Result = {ok,{SupFlags,[ChildSpec]}} | ignore</v> <v> SupFlags = - <seealso marker="#type-sup_flags"><c>sup_flags()</c></seealso></v> + <seetype marker="#sup_flags"><c>sup_flags()</c></seetype></v> <v> ChildSpec = - <seealso marker="#type-child_spec"><c>child_spec()</c></seealso></v> + <seetype marker="#child_spec"><c>child_spec()</c></seetype></v> </type> <desc> <p>Whenever a supervisor is started using - <seealso marker="#start_link/2"><c>start_link/2,3</c></seealso>, + <seemfa marker="#start_link/2"><c>start_link/2,3</c></seemfa>, this function is called by the new process to find out about restart strategy, maximum restart intensity, and child specifications.</p> @@ -689,8 +702,8 @@ child_spec() = #{id => child_id(), % mandatory supervisor. <c>[ChildSpec]</c> is a list of valid child specifications defining which child processes the supervisor must start and monitor. See the discussion in section - <seealso marker="#supervision_princ"> - <c>Supervision Principles</c></seealso> earlier.</p> + <seeerl marker="#supervision_princ"> + <c>Supervision Principles</c></seeerl> earlier.</p> <p>Notice that when the restart strategy is <c>simple_one_for_one</c>, the list of child specifications must be a list with one child specification only. @@ -698,24 +711,24 @@ child_spec() = #{id => child_id(), % mandatory No child process is then started during the initialization phase, but all children are assumed to be started dynamically using - <seealso marker="#start_child/2"><c>start_child/2</c></seealso>.</p> + <seemfa marker="#start_child/2"><c>start_child/2</c></seemfa>.</p> <p>The function can also return <c>ignore</c>.</p> <p>Notice that this function can also be called as a part of a code upgrade procedure. Therefore, the function is not to have any side effects. For more information about code upgrade of supervisors, see section - <seealso marker="doc/design_principles:appup_cookbook#sup">Changing - a Supervisor</seealso> in OTP Design Principles.</p> + <seeguide marker="system/design_principles:appup_cookbook#sup">Changing + a Supervisor</seeguide> in OTP Design Principles.</p> </desc> </func> </funcs> <section> <title>See Also</title> - <p><seealso marker="gen_event"><c>gen_event(3)</c></seealso>, - <seealso marker="gen_statem"><c>gen_statem(3)</c></seealso>, - <seealso marker="gen_server"><c>gen_server(3)</c></seealso>, - <seealso marker="sys"><c>sys(3)</c></seealso></p> + <p><seeerl marker="gen_event"><c>gen_event(3)</c></seeerl>, + <seeerl marker="gen_statem"><c>gen_statem(3)</c></seeerl>, + <seeerl marker="gen_server"><c>gen_server(3)</c></seeerl>, + <seeerl marker="sys"><c>sys(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/supervisor_bridge.xml b/lib/stdlib/doc/src/supervisor_bridge.xml index 3280bea610..97d0ae292a 100644 --- a/lib/stdlib/doc/src/supervisor_bridge.xml +++ b/lib/stdlib/doc/src/supervisor_bridge.xml @@ -39,15 +39,15 @@ a supervisor and the subsystem. It behaves like a real supervisor to its own supervisor, but has a different interface than a real supervisor to the subsystem. For more information, see - <seealso marker="doc/design_principles:sup_princ"> - Supervisor Behaviour</seealso> in OTP Design Principles. + <seeguide marker="system/design_principles:sup_princ"> + Supervisor Behaviour</seeguide> in OTP Design Principles. </p> <p>A supervisor bridge assumes the functions for starting and stopping the subsystem to be located in a callback module exporting a predefined set of functions.</p> - <p>The <seealso marker="sys"><c>sys(3)</c></seealso> module can be used + <p>The <seeerl marker="sys"><c>sys(3)</c></seeerl> module can be used for debugging a supervisor bridge.</p> <p>Unless otherwise stated, all functions in this module fail if @@ -75,8 +75,8 @@ <p>If <c><anno>SupBridgeName</anno>={global,<anno>Name</anno>}</c>, the supervisor bridge is registered globally as <c><anno>Name</anno></c> using - <seealso marker="kernel:global#register_name/2"> - <c>global:register_name/2</c></seealso>.</p> + <seemfa marker="kernel:global#register_name/2"> + <c>global:register_name/2</c></seemfa>.</p> </item> <item> <p>If @@ -86,7 +86,7 @@ <c>Module</c> callback is to export functions <c>register_name/2</c>, <c>unregister_name/1</c>, and <c>send/2</c>, which are to behave like the corresponding functions in - <seealso marker="kernel:global"><c>global</c></seealso>. + <seeerl marker="kernel:global"><c>global</c></seeerl>. Thus, <c>{via,global,GlobalName}</c> is a valid reference.</p> </item> </list> @@ -125,13 +125,14 @@ </func> </funcs> - <section> - <title>Callback Functions</title> - <p>The following functions must be exported from a - <c>supervisor_bridge</c> callback module.</p> - </section> + <funcs> + <fsdescription> + <title>Callback Functions</title> + <p>The following functions must be exported from a + <c>supervisor_bridge</c> callback module.</p> + </fsdescription> <func> <name since="">Module:init(Args) -> Result</name> <fsummary>Initialize process and start subsystem.</fsummary> @@ -144,7 +145,7 @@ </type> <desc> <p>Whenever a supervisor bridge is started using - <seealso marker="#start_link/2"><c>start_link/2,3</c></seealso>, + <seemfa marker="#start_link/2"><c>start_link/2,3</c></seemfa>, this function is called by the new process to start the subsystem and initialize.</p> <p><c>Args</c> is the <c>Args</c> argument provided to the start @@ -188,8 +189,8 @@ <section> <title>See Also</title> - <p><seealso marker="supervisor"><c>supervisor(3)</c></seealso>, - <seealso marker="sys"><c>sys(3)</c></seealso></p> + <p><seeerl marker="supervisor"><c>supervisor(3)</c></seeerl>, + <seeerl marker="sys"><c>sys(3)</c></seeerl></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index ebea054fff..8227be6824 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -41,7 +41,7 @@ understand system messages, such as debug messages and code change. These functions must be used to implement the use of system messages for a process; either directly, or through standard behaviors, such as - <seealso marker="gen_server"><c>gen_server</c></seealso>.</p> + <seeerl marker="gen_server"><c>gen_server</c></seeerl>.</p> <p>The default time-out is 5000 ms, unless otherwise specified. <c>timeout</c> defines the time to wait for the process to respond to a request. If the process does not respond, the @@ -50,8 +50,8 @@ <marker id="dbg_opt"/> <p>The functions make references to a debug structure. The debug structure is a list of <c>dbg_opt()</c>, which is an internal - data type used by function <seealso marker="#handle_system_msg/6"> - <c>handle_system_msg/6</c></seealso>. No debugging is performed if it is + data type used by function <seemfa marker="#handle_system_msg/6"> + <c>handle_system_msg/6</c></seemfa>. No debugging is performed if it is an empty list.</p> </description> @@ -66,8 +66,8 @@ <c>{system, From, Msg}</c>. The content and meaning of this message are not interpreted by the receiving process module. When a system message is received, function - <seealso marker="#handle_system_msg/6"> - <c>handle_system_msg/6</c></seealso> + <seemfa marker="#handle_system_msg/6"> + <c>handle_system_msg/6</c></seemfa> is called to handle the request.</p> </item> <item> @@ -82,7 +82,7 @@ <item> <p>If the modules used to implement the process change dynamically during runtime, the process must understand one more message. An - example is the <seealso marker="gen_event"><c>gen_event</c></seealso> + example is the <seeerl marker="gen_event"><c>gen_event</c></seeerl> processes. The message is <c>{_Label, {From, Ref}, get_modules}</c>. The reply to this message is <c>From ! {Ref, Modules}</c>, where <c>Modules</c> is a list of the currently active modules in the @@ -332,8 +332,8 @@ provided for convenience, allowing developers to avoid having to create their own state extraction functions and also avoid having to interactively extract the state from the return values of - <seealso marker="#get_status-1"><c>get_status/1</c></seealso> or - <seealso marker="#get_status-2"><c>get_status/2</c></seealso> + <seemfa marker="#get_status/1"><c>get_status/1</c></seemfa> or + <seemfa marker="#get_status/2"><c>get_status/2</c></seemfa> while debugging.</p> </note> <p>The value of <c><anno>State</anno></c> varies for different types of @@ -341,19 +341,19 @@ <list type="bulleted"> <item> <p>For a - <seealso marker="gen_server"><c>gen_server</c></seealso> + <seeerl marker="gen_server"><c>gen_server</c></seeerl> process, the returned <c><anno>State</anno></c> is the state of the callback module.</p> </item> <item> <p>For a - <seealso marker="gen_statem"><c>gen_statem</c></seealso> + <seeerl marker="gen_statem"><c>gen_statem</c></seeerl> process, <c><anno>State</anno></c> is the tuple <c>{CurrentState,CurrentData}</c>.</p> </item> <item> <p>For a - <seealso marker="gen_event"><c>gen_event</c></seealso> + <seeerl marker="gen_event"><c>gen_event</c></seeerl> process, <c><anno>State</anno></c> is a list of tuples, where each tuple corresponds to an event handler registered in the process and contains <c>{Module, Id, HandlerState}</c>, @@ -378,9 +378,9 @@ <p>If the callback module exports a function <c>system_get_state/1</c>, it is 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"><c>get_status/1,2</c></seealso>, and - function <seealso marker="#Module:system_get_state/1"> - <c>Module:system_get_state/1</c></seealso> is expected to extract the + <seemfa marker="#get_status/1"><c>get_status/1,2</c></seemfa>, and + function <seemfa marker="#Module:system_get_state/1"> + <c>Module:system_get_state/1</c></seemfa> is expected to extract the state of the callback module from it. Function <c>system_get_state/1</c> must return <c>{ok, State}</c>, where <c>State</c> is the state of the callback module.</p> @@ -394,14 +394,14 @@ <c>Class</c> and <c>Reason</c> indicate details of the exception.</p> <p>Function <c>system_get_state/1</c> is primarily useful for user-defined behaviors and modules that implement OTP - <seealso marker="#special_process">special processes</seealso>. + <seeerl marker="#special_process">special processes</seeerl>. The <c>gen_server</c>, <c>gen_statem</c>, and <c>gen_event</c> OTP behavior modules export this function, so callback modules for those behaviors need not to supply their own.</p> <p>For more information about a process, including its state, see - <seealso marker="#get_status-1"><c>get_status/1</c></seealso> and - <seealso marker="#get_status-2"><c>get_status/2</c></seealso>.</p> + <seemfa marker="#get_status/1"><c>get_status/1</c></seemfa> and + <seemfa marker="#get_status/2"><c>get_status/2</c></seemfa>.</p> </desc> </func> @@ -415,16 +415,16 @@ processes, for example:</p> <list type="bulleted"> <item> - <p>A <seealso marker="gen_server"><c>gen_server</c></seealso> + <p>A <seeerl marker="gen_server"><c>gen_server</c></seeerl> process returns the state of the callback module.</p> </item> <item> - <p>A <seealso marker="gen_statem"><c>gen_statem</c></seealso> + <p>A <seeerl marker="gen_statem"><c>gen_statem</c></seeerl> process returns information, such as its current state name and state data.</p> </item> <item> - <p>A <seealso marker="gen_event"><c>gen_event</c></seealso> + <p>A <seeerl marker="gen_event"><c>gen_event</c></seeerl> process returns information about each of its registered handlers.</p> </item> @@ -434,12 +434,12 @@ can also change the value of <c><anno>Misc</anno></c> by exporting a function <c>format_status/2</c>, which contributes module-specific information. For details, see - <seealso marker="gen_server#Module:format_status/2"> - <c>gen_server:format_status/2</c></seealso>, - <seealso marker="gen_statem#Module:format_status/2"> - <c>gen_statem:format_status/2</c></seealso>, and - <seealso marker="gen_event#Module:format_status/2"> - <c>gen_event:format_status/2</c></seealso>.</p> + <seemfa marker="gen_server#Module:format_status/2"> + <c>gen_server:format_status/2</c></seemfa>, + <seemfa marker="gen_statem#Module:format_status/2"> + <c>gen_statem:format_status/2</c></seemfa>, and + <seemfa marker="gen_event#Module:format_status/2"> + <c>gen_event:format_status/2</c></seemfa>.</p> </desc> </func> @@ -475,8 +475,8 @@ are printed to <c>standard_io</c>.</p> <p>The events are formatted with a function that is defined by the process that generated the event (with a call to - <seealso marker="#handle_debug/4"> - <c>handle_debug/4</c>)</seealso>.</p> + <seemfa marker="#handle_debug/4"> + <c>handle_debug/4</c>)</seemfa>.</p> </desc> </func> @@ -488,7 +488,7 @@ <p>Enables or disables the logging of all system events in text format to the file. The events are formatted with a function that is defined by the process that generated the event (with a call to - <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>). + <seemfa marker="#handle_debug/4"><c>handle_debug/4</c></seemfa>). The file is opened with encoding UTF-8.</p> </desc> </func> @@ -500,7 +500,7 @@ <desc> <p>Turns off all debugging for the process. This includes functions that are installed explicitly with function - <seealso marker="#install/2"><c>install/2,3</c></seealso>, + <seemfa marker="#install/2"><c>install/2,3</c></seemfa>, for example, triggers.</p> </desc> </func> @@ -535,13 +535,13 @@ processes as follows:</p> <list type="bulleted"> <item> - <p>For a <seealso marker="gen_server"><c>gen_server</c></seealso> + <p>For a <seeerl marker="gen_server"><c>gen_server</c></seeerl> process, <c><anno>State</anno></c> is the state of the callback module and <c><anno>NewState</anno></c> is a new instance of that state.</p> </item> <item> - <p>For a <seealso marker="gen_statem"><c>gen_statem</c></seealso> + <p>For a <seeerl marker="gen_statem"><c>gen_statem</c></seeerl> process, <c><anno>State</anno></c> is the tuple <c>{CurrentState,CurrentData}</c>, and <c><anno>NewState</anno></c> is a @@ -549,7 +549,7 @@ a new current state, new state data, or both.</p> </item> <item> - <p>For a <seealso marker="gen_event"><c>gen_event</c></seealso> + <p>For a <seeerl marker="gen_event"><c>gen_event</c></seeerl> process, <c><anno>State</anno></c> is the tuple <c>{Module, Id, HandlerState}</c> as follows:</p> <taglist> @@ -591,12 +591,12 @@ 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 - <seealso marker="#Module:system_replace_state/2"> - <c>system_replace_state/2</c></seealso> function, it is called in the + <seemfa marker="#Module:system_replace_state/2"> + <c>system_replace_state/2</c></seemfa> function, it is 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"><c>get_status/1,2</c></seealso>. + <seemfa marker="#get_status/1"><c>get_status/1,2</c></seemfa>. A <c>system_replace_state/2</c> function is expected to return <c>{ok, NewState, NewMisc}</c>, where <c>NewState</c> is the new state of the callback module, obtained by calling <c>StateFun</c>, and @@ -606,7 +606,7 @@ module within it).</p> <p>If the callback module does not export a <c>system_replace_state/2</c> function, - <seealso marker="#replace_state/2"><c>replace_state/2,3</c></seealso> + <seemfa marker="#replace_state/2"><c>replace_state/2,3</c></seemfa> assumes that <c>Misc</c> is the state of the callback module, 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> @@ -621,7 +621,7 @@ <c>{callback_failed, StateFun, {Class, Reason}}</c>.</p> <p>Function <c>system_replace_state/2</c> is primarily useful for user-defined behaviors and modules that implement OTP - <seealso marker="#special_process">special processes</seealso>. The + <seeerl marker="#special_process">special processes</seeerl>. The OTP behavior modules <c>gen_server</c>, <c>gen_statem</c>, and <c>gen_event</c> export this function, so callback modules for those @@ -680,22 +680,23 @@ <p>Prints all system events on <c>standard_io</c>. The events are formatted with a function that is defined by the process that generated the event (with a call to - <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>). + <seemfa marker="#handle_debug/4"><c>handle_debug/4</c></seemfa>). </p> </desc> </func> </funcs> - <section> - <title>Process Implementation Functions</title> - <marker id="special_process"/> - <p>The following functions are used when implementing a - special process. This is an ordinary process, which does not use a - standard behavior, but a process that understands the standard system - messages.</p> - </section> + <funcs> + <fsdescription> + <title>Process Implementation Functions</title> + <marker id="special_process"/> + <p>The following functions are used when implementing a + special process. This is an ordinary process, which does not use a + standard behavior, but a process that understands the standard system + messages.</p> + </fsdescription> <func> <name name="debug_options" arity="1" since=""/> <fsummary>Convert a list of options to a debug structure.</fsummary> @@ -785,7 +786,7 @@ <p>Prints the logged system events in the debug structure, using <c>FormFunc</c> as defined when the event was generated by a call to - <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>.</p> + <seemfa marker="#handle_debug/4"><c>handle_debug/4</c></seemfa>.</p> </desc> </func> @@ -796,7 +797,7 @@ <p> Returns the logged system events in the debug structure, that is the last argument to - <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>. + <seemfa marker="#handle_debug/4"><c>handle_debug/4</c></seemfa>. </p> </desc> </func> @@ -813,8 +814,8 @@ <v>NMisc = term()</v> </type> <desc> - <p>Called from <seealso marker="#handle_system_msg/6"> - <c>handle_system_msg/6</c></seealso> when the process is to perform a + <p>Called from <seemfa marker="#handle_system_msg/6"> + <c>handle_system_msg/6</c></seemfa> when the process is to perform a code change. The code change is used when the internal data structure has changed. This function converts argument <c>Misc</c> to the new data @@ -829,12 +830,12 @@ <fsummary>Called when the process is to continue its execution.</fsummary> <type> <v>Parent = pid()</v> - <v>Debug = [<seealso marker="#type-dbg_opt">dbg_opt()</seealso>]</v> + <v>Debug = [<seetype marker="#dbg_opt">dbg_opt()</seetype>]</v> <v>Misc = term()</v> </type> <desc> - <p>Called from <seealso marker="#handle_system_msg/6"> - <c>handle_system_msg/6</c></seealso> when the process is to continue + <p>Called from <seemfa marker="#handle_system_msg/6"> + <c>handle_system_msg/6</c></seemfa> when the process is to continue its execution (for example, after it has been suspended). This function never returns.</p> </desc> @@ -849,11 +850,11 @@ <v>State = term()</v> </type> <desc> - <p>Called from <seealso marker="#handle_system_msg/6"> - <c>handle_system_msg/6</c></seealso> + <p>Called from <seemfa marker="#handle_system_msg/6"> + <c>handle_system_msg/6</c></seemfa> when the process is to return a term that reflects its current state. <c>State</c> is the value returned by - <seealso marker="#get_state/2"><c>get_state/2</c></seealso>.</p> + <seemfa marker="#get_state/2"><c>get_state/2</c></seemfa>.</p> </desc> </func> @@ -869,10 +870,10 @@ <v>NMisc = term()</v> </type> <desc> - <p>Called from <seealso marker="#handle_system_msg/6"> - <c>handle_system_msg/6</c></seealso> when the process is to replace + <p>Called from <seemfa marker="#handle_system_msg/6"> + <c>handle_system_msg/6</c></seemfa> when the process is to replace its current state. <c>NState</c> is the value returned by - <seealso marker="#replace_state/3"><c>replace_state/3</c></seealso>. + <seemfa marker="#replace_state/3"><c>replace_state/3</c></seemfa>. </p> </desc> </func> @@ -883,12 +884,12 @@ <type> <v>Reason = term()</v> <v>Parent = pid()</v> - <v>Debug = [<seealso marker="#type-dbg_opt">dbg_opt()</seealso>]</v> + <v>Debug = [<seetype marker="#dbg_opt">dbg_opt()</seetype>]</v> <v>Misc = term()</v> </type> <desc> - <p>Called from <seealso marker="#handle_system_msg/6"> - <c>handle_system_msg/6</c></seealso> when the process is to terminate. + <p>Called from <seemfa marker="#handle_system_msg/6"> + <c>handle_system_msg/6</c></seemfa> when the process is to terminate. For example, this function is called when the process is suspended and its parent orders shutdown. It gives the process a chance to do a cleanup. This function never diff --git a/lib/stdlib/doc/src/timer.xml b/lib/stdlib/doc/src/timer.xml index 165eecfbb0..56342b94be 100644 --- a/lib/stdlib/doc/src/timer.xml +++ b/lib/stdlib/doc/src/timer.xml @@ -41,12 +41,18 @@ process.</p> <p>Successful evaluations of the timer functions give return values containing a timer reference, denoted <c>TRef</c>. By using - <seealso marker="#cancel/1"><c>cancel/1</c></seealso>, + <seemfa marker="#cancel/1"><c>cancel/1</c></seemfa>, the returned reference can be used to cancel any requested action. A <c>TRef</c> is an Erlang term, which contents must not be changed.</p> <p>The time-outs are not exact, but are <em>at least</em> as long as requested.</p> + <p>Creating timers using + <seemfa marker="erts:erlang#send_after/3">erlang:send_after/3</seemfa> and + <seemfa marker="erts:erlang#start_timer/3">erlang:start_timer/3</seemfa> + is much more efficient than using the timers provided by this module. See + <seeguide marker="system/efficiency_guide:commoncaveats#timer-module">the + Timer Module section in the Efficiency Guide</seeguide>.</p> </description> <datatypes> @@ -165,10 +171,10 @@ <anno>T2</anno> - <anno>T1</anno></c> in <em>microseconds</em>, where <c><anno>T1</anno></c> and <c><anno>T2</anno></c> are time-stamp tuples on the same format as returned from - <seealso marker="erts:erlang#timestamp/0"> - <c>erlang:timestamp/0</c></seealso> or - <seealso marker="kernel:os#timestamp/0"> - <c>os:timestamp/0</c></seealso>.</p> + <seemfa marker="erts:erlang#timestamp/0"> + <c>erlang:timestamp/0</c></seemfa> or + <seemfa marker="kernel:os#timestamp/0"> + <c>os:timestamp/0</c></seemfa>.</p> </desc> </func> @@ -195,6 +201,9 @@ can also be an atom of a registered name.)</p> <p>Returns <c>{ok, <anno>TRef</anno>}</c> or <c>{error, <anno>Reason</anno>}</c>.</p> + <p>See also + <seeguide marker="system/efficiency_guide:commoncaveats#timer-module"> + the Timer Module section in the Efficiency Guide</seeguide>.</p> </item> <tag><c>send_after/2</c></tag> <item> @@ -253,7 +262,7 @@ is needed. This is useful during development, but in a target system the server is to be started explicitly. Use configuration parameters for - <seealso marker="kernel:index">Kernel</seealso> for this.</p> + <seeapp marker="kernel:index">Kernel</seeapp> for this.</p> </desc> </func> @@ -270,8 +279,8 @@ <item> <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>, <anno>Arguments</anno>)</c> and measures the elapsed real time as - reported by <seealso marker="erts:erlang#monotonic_time/0"> - <c>erlang:monotonic_time/0</c></seealso>.</p> + reported by <seemfa marker="erts:erlang#monotonic_time/0"> + <c>erlang:monotonic_time/0</c></seemfa>.</p> <p>Returns <c>{<anno>Time</anno>, <anno>Value</anno>}</c>, where <c><anno>Time</anno></c> is the elapsed real time in <em>microseconds</em>, and <c><anno>Value</anno></c> is what is @@ -318,27 +327,27 @@ timer:cancel(R), <section> <title>Notes</title> <p>A timer can always be removed by calling - <seealso marker="#cancel/1"><c>cancel/1</c></seealso>.</p> + <seemfa marker="#cancel/1"><c>cancel/1</c></seemfa>.</p> <p>An interval timer, that is, a timer created by evaluating any of the functions - <seealso marker="#apply_interval/4"><c>apply_interval/4</c></seealso>, - <seealso marker="#send_interval/3"><c>send_interval/3</c></seealso>, and - <seealso marker="#send_interval/2"><c>send_interval/2</c></seealso> + <seemfa marker="#apply_interval/4"><c>apply_interval/4</c></seemfa>, + <seemfa marker="#send_interval/3"><c>send_interval/3</c></seemfa>, and + <seemfa marker="#send_interval/2"><c>send_interval/2</c></seemfa> is linked to the process to which the timer performs its task.</p> <p>A one-shot timer, that is, a timer created by evaluating any of the functions - <seealso marker="#apply_after/4"><c>apply_after/4</c></seealso>, - <seealso marker="#send_after/3"><c>send_after/3</c></seealso>, - <seealso marker="#send_after/2"><c>send_after/2</c></seealso>, - <seealso marker="#exit_after/3"><c>exit_after/3</c></seealso>, - <seealso marker="#exit_after/2"><c>exit_after/2</c></seealso>, - <seealso marker="#kill_after/2"><c>kill_after/2</c></seealso>, and - <seealso marker="#kill_after/1"><c>kill_after/1</c></seealso> + <seemfa marker="#apply_after/4"><c>apply_after/4</c></seemfa>, + <seemfa marker="#send_after/3"><c>send_after/3</c></seemfa>, + <seemfa marker="#send_after/2"><c>send_after/2</c></seemfa>, + <seemfa marker="#exit_after/3"><c>exit_after/3</c></seemfa>, + <seemfa marker="#exit_after/2"><c>exit_after/2</c></seemfa>, + <seemfa marker="#kill_after/2"><c>kill_after/2</c></seemfa>, and + <seemfa marker="#kill_after/1"><c>kill_after/1</c></seemfa> is not linked to any process. Hence, such a timer is removed only when it reaches its time-out, or if it is explicitly removed by a call to - <seealso marker="#cancel/1"><c>cancel/1</c></seealso>.</p> + <seemfa marker="#cancel/1"><c>cancel/1</c></seemfa>.</p> </section> </erlref> diff --git a/lib/stdlib/doc/src/unicode.xml b/lib/stdlib/doc/src/unicode.xml index d626f7473d..1f0133de67 100644 --- a/lib/stdlib/doc/src/unicode.xml +++ b/lib/stdlib/doc/src/unicode.xml @@ -56,23 +56,23 @@ canonical-equivalent Unicode characters as equal. All characters should thus be normalized to one form once on the system borders. One of the following functions can convert characters to their - normalized forms <seealso marker="#characters_to_nfc_list/1"> - <c>characters_to_nfc_list/1</c></seealso>, - <seealso marker="#characters_to_nfc_binary/1"> - <c>characters_to_nfc_binary/1</c></seealso>, - <seealso marker="#characters_to_nfd_list/1"> - <c>characters_to_nfd_list/1</c></seealso> or - <seealso marker="#characters_to_nfd_binary/1"> - <c>characters_to_nfd_binary/1</c></seealso>. + normalized forms <seemfa marker="#characters_to_nfc_list/1"> + <c>characters_to_nfc_list/1</c></seemfa>, + <seemfa marker="#characters_to_nfc_binary/1"> + <c>characters_to_nfc_binary/1</c></seemfa>, + <seemfa marker="#characters_to_nfd_list/1"> + <c>characters_to_nfd_list/1</c></seemfa> or + <seemfa marker="#characters_to_nfd_binary/1"> + <c>characters_to_nfd_binary/1</c></seemfa>. For general text - <seealso marker="#characters_to_nfc_list/1"> - <c>characters_to_nfc_list/1</c></seealso> or - <seealso marker="#characters_to_nfc_binary/1"> - <c>characters_to_nfc_binary/1</c></seealso> is preferred, and + <seemfa marker="#characters_to_nfc_list/1"> + <c>characters_to_nfc_list/1</c></seemfa> or + <seemfa marker="#characters_to_nfc_binary/1"> + <c>characters_to_nfc_binary/1</c></seemfa> is preferred, and for identifiers one of the compatibility normalization functions, such as - <seealso marker="#characters_to_nfkc_list/1"> - <c>characters_to_nfkc_list/1</c></seealso>, + <seemfa marker="#characters_to_nfkc_list/1"> + <c>characters_to_nfkc_list/1</c></seemfa>, is preferred for security reasons. The normalization functions where introduced in OTP 20. Additional information on normalization can be found in the @@ -177,8 +177,8 @@ <name name="characters_to_binary" arity="3" since=""/> <fsummary>Convert a collection of characters to a UTF-8 binary.</fsummary> <desc> - <p>Behaves as <seealso marker="#characters_to_list/2"> - <c>characters_to_list/2</c></seealso>, but produces a binary + <p>Behaves as <seemfa marker="#characters_to_list/2"> + <c>characters_to_list/2</c></seemfa>, but produces a binary instead of a Unicode list.</p> <p><c><anno>InEncoding</anno></c> defines how input is to be interpreted if binaries are present in <c>Data</c></p> @@ -203,8 +203,8 @@ <p>The atoms <c>big</c> and <c>little</c> denote big- or little-endian encoding.</p> <p>Errors and exceptions occur as in - <seealso marker="#characters_to_list/2"> - <c>characters_to_list/2</c></seealso>, but the second element + <seemfa marker="#characters_to_list/2"> + <c>characters_to_list/2</c></seemfa>, but the second element in tuple <c>error</c> or <c>incomplete</c> is a <c>binary()</c> and not a <c>list()</c>.</p> </desc> @@ -256,8 +256,8 @@ 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"> - <c>characters_to_binary/3</c></seealso> + <seemfa marker="#characters_to_binary/3"> + <c>characters_to_binary/3</c></seemfa> comes in handy.</p> <p>Option <c>unicode</c> is an alias for <c>utf8</c>, as this is the preferred encoding for Unicode characters in diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index 789e063c12..cc90f0dafb 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1999</year> - <year>2017</year> + <year>2020</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -55,8 +55,8 @@ source code, with enhancements to many of the applications to support both Unicode encoded filenames and support for UTF-8 encoded files in many circumstances. Most notable is the - support for UTF-8 in files read by <seealso - marker="kernel:file#consult/1"><c>file:consult/1</c></seealso>, + support for UTF-8 in files read by <seemfa + marker="kernel:file#consult/1"><c>file:consult/1</c></seemfa>, release handler support for UTF-8, and more support for Unicode character sets in the I/O system.</p></item> @@ -221,7 +221,7 @@ issues occur, which is why UTF-16 exists in both a big-endian and a little-endian variant.</p> <p>In Erlang, the full UTF-16 range is supported when applicable, like - in the <seealso marker="stdlib:unicode"><c>unicode</c></seealso> + in the <seeerl marker="stdlib:unicode"><c>unicode</c></seeerl> module and in the bit syntax.</p> </item> <tag>UTF-32</tag> @@ -278,13 +278,13 @@ <p>The Unicode characters need to be processed by the Erlang program, which is why library functions must be able to handle them. In some cases functionality has been added to already - existing interfaces (as the <seealso - marker="stdlib:string"><c>string</c></seealso> module now can + existing interfaces (as the <seeerl + marker="stdlib:string"><c>string</c></seeerl> module now can handle strings with any code points). In some cases new - functionality or options have been added (as in the <seealso - marker="stdlib:io"><c>io</c></seealso> module, the file - handling, the <seealso - marker="stdlib:unicode"><c>unicode</c></seealso> module, and + functionality or options have been added (as in the <seeerl + marker="stdlib:io"><c>io</c></seeerl> module, the file + handling, the <seeerl + marker="stdlib:unicode"><c>unicode</c></seeerl> module, and the bit syntax). Today most modules in Kernel and STDLIB, as well as the VM are Unicode-aware.</p> </item> @@ -343,7 +343,7 @@ %% -*- coding: utf-8 -*-</code> <p>This of course requires your editor to support UTF-8 as well. The same comment is also interpreted by functions like - <seealso marker="kernel:file#consult/1"><c>file:consult/1</c></seealso>, + <seemfa marker="kernel:file#consult/1"><c>file:consult/1</c></seemfa>, the release handler, and so on, so that you can have all text files in your source directories in UTF-8 encoding.</p> </item> @@ -382,11 +382,11 @@ <p>Only if a string contains code points < 256, can it be directly converted to a binary by using, for example, - <seealso marker="erts:erlang#iolist_to_binary/1"><c>erlang:iolist_to_binary/1</c></seealso> + <seemfa marker="erts:erlang#iolist_to_binary/1"><c>erlang:iolist_to_binary/1</c></seemfa> or can be sent directly to a port. If the string contains Unicode characters > 255, an encoding must be decided upon and the string is to be converted to a binary in the preferred encoding using - <seealso marker="stdlib:unicode#characters_to_binary/1"><c>unicode:characters_to_binary/1,2,3</c></seealso>. + <seemfa marker="stdlib:unicode#characters_to_binary/1"><c>unicode:characters_to_binary/1,2,3</c></seemfa>. 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> @@ -395,7 +395,7 @@ 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 - <seealso marker="erts:erlang#list_to_binary/1"><c>erlang:list_to_binary/1</c></seealso>, + <seemfa marker="erts:erlang#list_to_binary/1"><c>erlang:list_to_binary/1</c></seemfa>, an ISO Latin-1 Erlang string can be converted into a binary, effectively using bytewise encoding: one byte per character. This was convenient for those limited Erlang strings, but cannot be done for arbitrary Unicode @@ -428,7 +428,7 @@ chardata() = charlist() | unicode_binary() charlist() = maybe_improper_list(char() | unicode_binary() | charlist(), unicode_binary() | nil())</code> - <p>The module <seealso marker="stdlib:unicode"><c>unicode</c></seealso> + <p>The module <seeerl marker="stdlib:unicode"><c>unicode</c></seeerl> 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> @@ -448,8 +448,8 @@ external_charlist() = maybe_improper_list(char() | external_unicode_binary() | <p><marker id="unicode_in_erlang"/>As from Erlang/OTP R16, Erlang source files can be written in UTF-8 or bytewise (<c>latin1</c>) encoding. For information about how to state the encoding of an - Erlang source file, see the <seealso - marker="stdlib:epp#encoding"><c>epp(3)</c></seealso> module. As + Erlang source file, see the <seeerl + marker="stdlib:epp#encoding"><c>epp(3)</c></seeerl> module. As from Erlang/OTP R16, strings and comments can be written using Unicode. As from Erlang/OTP 20, also atoms and functions can be written using Unicode. Modules, applications, and nodes must still be @@ -578,8 +578,8 @@ Eshell V5.10.1 (abort with ^G) bytewise encoded) as string data.</p> <p>These heuristics are also used by - <seealso marker="stdlib:io#format/2"><c>io:format/2</c></seealso>, - <seealso marker="stdlib:io_lib#format/2"><c>io_lib:format/2</c></seealso>, + <seemfa marker="stdlib:io#format/2"><c>io:format/2</c></seemfa>, + <seemfa marker="stdlib:io_lib#format/2"><c>io_lib:format/2</c></seemfa>, and friends when modifier <c>t</c> is used with <c>~p</c> or <c>~P</c>:</p> @@ -644,7 +644,7 @@ en_US.UTF-8</pre> language and character type settings.</p> <p>To investigate what Erlang thinks about the terminal, the call - <seealso marker="stdlib:io#getopts/1"><c>io:getopts()</c></seealso> + <seemfa marker="stdlib:io#getopts/1"><c>io:getopts()</c></seemfa> can be used when the shell is started:</p> <pre> @@ -728,9 +728,9 @@ Eshell V5.10.1 (abort with ^G) <taglist> <tag>Mandatory Unicode file naming</tag> <item> - <p>Windows and, for most common uses, MacOS X enforce Unicode support - for filenames. All files created in the file system have names that - can consistently be interpreted. In MacOS X, all filenames are + <p>Windows, Android and, for most cases, MacOS X enforce Unicode support + for filenames. All files created in the file system have names that can + consistently be interpreted. In MacOS X and Android, all filenames are retrieved in UTF-8 encoding. In Windows, each system call handling filenames has a special Unicode-aware variant, giving much the same effect. There are no filenames on these systems that are not Unicode @@ -740,7 +740,7 @@ Eshell V5.10.1 (abort with ^G) translated to the proper name encoding for the underlying operating system and file system.</p> <p>Doing, for example, a - <seealso marker="kernel:file#list_dir/1"><c>file:list_dir/1</c></seealso> + <seemfa marker="kernel:file#list_dir/1"><c>file:list_dir/1</c></seemfa> on one of these systems can return Unicode lists with code points > 255, depending on the content of the file system.</p> </item> @@ -759,7 +759,7 @@ Eshell V5.10.1 (abort with ^G) <p>In <c>latin1</c> mode, filenames are bytewise encoded. This allows for list representation of all filenames in the system. However, a a file named "Östersund.txt", appears in - <seealso marker="kernel:file#list_dir/1"><c>file:list_dir/1</c></seealso> + <seemfa marker="kernel:file#list_dir/1"><c>file:list_dir/1</c></seemfa> either as "Östersund.txt" (if the filename 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 @@ -767,7 +767,7 @@ Eshell V5.10.1 (abort with ^G) filename translation on such a system, non-UTF-8 filenames are ignored by functions like <c>file:list_dir/1</c>. They can be retrieved with function - <seealso marker="kernel:file#list_dir_all/1"><c>file:list_dir_all/1</c></seealso>, + <seemfa marker="kernel:file#list_dir_all/1"><c>file:list_dir_all/1</c></seemfa>, but wrongly encoded filenames appear as "raw filenames". </p> </item> @@ -802,14 +802,14 @@ Eshell V5.10.1 (abort with ^G) <p>Unicode filename translation is turned on with switch <c>+fnu</c>. On Linux, a VM started without explicitly stating the filename translation mode defaults to <c>latin1</c> as the native filename encoding. On - Windows and MacOS X, the default behavior is that of Unicode filename - translation. Therefore - <seealso marker="kernel:file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seealso> + Windows, MacOS X and Android, the default behavior is that of Unicode + filename translation. Therefore + <seemfa marker="kernel:file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seemfa> by default returns <c>utf8</c> on those systems (Windows does not use UTF-8 on the file system level, but this can safely be ignored by the Erlang programmer). The default behavior can, as stated earlier, be changed using option <c>+fnu</c> or <c>+fnl</c> to the VM, see the - <seealso marker="erts:erl"><c>erl</c></seealso> program. If the VM is + <seecom marker="erts:erl"><c>erl</c></seecom> program. If the VM is started in Unicode filename translation mode, <c>file:native_name_encoding/0</c> returns atom <c>utf8</c>. Switch <c>+fnu</c> can be followed by <c>w</c>, <c>i</c>, or <c>e</c> to control @@ -832,7 +832,7 @@ Eshell V5.10.1 (abort with ^G) </list> <p>Notice that - <seealso marker="kernel:file#read_link/1"><c>file:read_link/1</c></seealso> + <seemfa marker="kernel:file#read_link/1"><c>file:read_link/1</c></seemfa> always returns an error if the link points to an invalid filename.</p> <p>In Unicode filename mode, filenames given to BIF <c>open_port/2</c> with @@ -840,7 +840,7 @@ Eshell V5.10.1 (abort with ^G) is the parameter list specified in option <c>args</c> available when using <c>spawn_executable</c>. The UTF-8 translation of arguments can be avoided using binaries, see section - <seealso marker="#notes-about-raw-filenames">Notes About Raw Filenames</seealso>. + <seeguide marker="#notes-about-raw-filenames">Notes About Raw Filenames</seeguide>. </p> <p>Notice that the file encoding options specified when opening a file has @@ -876,7 +876,7 @@ Eshell V5.10.1 (abort with ^G) therefore expects UTF-8 file naming). The ISO Latin-1 name is not valid UTF-8 and one can be tempted to think that automatic conversion in, for example, - <seealso marker="kernel:file#list_dir/1"><c>file:list_dir/1</c></seealso> + <seemfa marker="kernel:file#list_dir/1"><c>file:list_dir/1</c></seemfa> 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 filename)? The VM converts the filename to UTF-8, as this is @@ -892,7 +892,7 @@ Eshell V5.10.1 (abort with ^G) are invalid under the encoding. By the common function <c>file:list_dir/1</c>, the wrongly encoded filenames are ignored in Unicode filename translation mode, but by function - <seealso marker="kernel:file#list_dir_all/1"><c>file:list_dir_all/1</c></seealso> + <seemfa marker="kernel:file#list_dir_all/1"><c>file:list_dir_all/1</c></seemfa> the filenames with invalid encoding are returned as "raw" filenames, that is, as binaries.</p> @@ -964,9 +964,9 @@ Eshell V5.10.1 (abort with ^G) Unicode.</p> <p>If Unicode filenames are enabled, the calls to - <seealso marker="kernel:os#getenv/0"><c>os:getenv/0,1</c></seealso>, - <seealso marker="kernel:os#putenv/2"><c>os:putenv/2</c></seealso>, and - <seealso marker="kernel:os#unsetenv/1"><c>os:unsetenv/1</c></seealso> + <seemfa marker="kernel:os#getenv/0"><c>os:getenv/0,1</c></seemfa>, + <seemfa marker="kernel:os#putenv/2"><c>os:putenv/2</c></seemfa>, and + <seemfa marker="kernel:os#unsetenv/1"><c>os:unsetenv/1</c></seemfa> handle Unicode strings. On Unix-like platforms, the built-in functions translate environment variables in UTF-8 to/from Unicode strings, possibly with code points > 255. On Windows, the Unicode versions of the @@ -982,8 +982,8 @@ Eshell V5.10.1 (abort with ^G) non-textual or byte-oriented data (such as <c>gen_tcp</c>).</p> <p>Modules handling textual data (such as - <seealso marker="stdlib:io_lib"><c>io_lib</c></seealso> and - <seealso marker="stdlib:string"><c>string</c></seealso> are sometimes + <seeerl marker="stdlib:io_lib"><c>io_lib</c></seeerl> and + <seeerl marker="stdlib:string"><c>string</c></seeerl> are sometimes subject to conversion or extension to be able to handle Unicode characters.</p> @@ -997,7 +997,7 @@ Eshell V5.10.1 (abort with ^G) <taglist> <tag><c>unicode</c></tag> <item> - <p>The <seealso marker="stdlib:unicode"><c>unicode</c></seealso> + <p>The <seeerl marker="stdlib:unicode"><c>unicode</c></seeerl> module is clearly Unicode-aware. It contains functions for conversion between different Unicode formats and some utilities for identifying byte order marks. Few programs handling Unicode data survive without @@ -1005,7 +1005,7 @@ Eshell V5.10.1 (abort with ^G) </item> <tag><c>io</c></tag> <item> - <p>The <seealso marker="stdlib:io"><c>io</c></seealso> module has been + <p>The <seeerl marker="stdlib:io"><c>io</c></seeerl> module has been extended along with the actual I/O protocol to handle Unicode data. This means that many functions require binaries to be in UTF-8, and there are modifiers to format control sequences to allow for output @@ -1016,36 +1016,36 @@ Eshell V5.10.1 (abort with ^G) <p>I/O-servers throughout the system can handle Unicode data and have options for converting data upon output or input to/from the device. As shown earlier, the - <seealso marker="stdlib:shell"><c>shell</c></seealso> module has + <seeerl marker="stdlib:shell"><c>shell</c></seeerl> module has support for Unicode terminals and the - <seealso marker="kernel:file"><c>file</c></seealso> module + <seeerl marker="kernel:file"><c>file</c></seeerl> module allows for translation to and from various Unicode formats on disk.</p> <p>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 best read or written using the - <seealso marker="stdlib:io"><c>io</c></seealso> module.</p> + <seeerl marker="stdlib:io"><c>io</c></seeerl> module.</p> </item> <tag><c>re</c></tag> <item> - <p>The <seealso marker="stdlib:re"><c>re</c></seealso> module allows + <p>The <seeerl marker="stdlib:re"><c>re</c></seeerl> module allows for matching Unicode strings as a special option. As the library is centered on matching in binaries, the Unicode support is UTF-8-centered.</p> </item> <tag><c>wx</c></tag> <item> - <p>The graphical library <seealso marker="wx:wx"><c>wx</c></seealso> + <p>The graphical library <seeerl marker="wx:wx"><c>wx</c></seeerl> has extensive support for Unicode text.</p></item> </taglist> - <p>The <seealso marker="stdlib:string"><c>string</c></seealso> + <p>The <seeerl marker="stdlib:string"><c>string</c></seeerl> module works perfectly for Unicode strings and ISO Latin-1 - strings, except the language-dependent functions <seealso - marker="stdlib:string#uppercase/1"><c>string:uppercase/1</c></seealso> - and <seealso - marker="stdlib:string#lowercase/1"><c>string:lowercase/1</c></seealso>. + strings, except the language-dependent functions <seemfa + marker="stdlib:string#uppercase/1"><c>string:uppercase/1</c></seemfa> + and <seemfa + marker="stdlib:string#lowercase/1"><c>string:lowercase/1</c></seemfa>. These two functions can never function correctly for Unicode characters in their current form, as there are language and locale issues to consider when converting text between cases. Converting @@ -1074,9 +1074,9 @@ Eshell V5.10.1 (abort with ^G) terminal or pipe.</p> <p>A file can have an encoding option that makes it generally usable by the - <seealso marker="stdlib:io"><c>io</c></seealso> module (for example + <seeerl marker="stdlib:io"><c>io</c></seeerl> module (for example <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 + The <seeerl marker="kernel:file"><c>file</c></seeerl> module is byte-oriented, so only ISO Latin-1 characters can be written using that module. Use the <c>io</c> module if Unicode data is to be output to a file with other <c>encoding</c> than <c>latin1</c> (bytewise encoding). @@ -1088,7 +1088,7 @@ Eshell V5.10.1 (abort with ^G) as that is the way to access files other than text files, byte by byte. As with ports, you can 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 + <seeerl marker="stdlib:unicode"><c>unicode</c></seeerl> module or the bit syntax) and then output it on a bytewise (<c>latin1</c>) encoded file.</p> @@ -1096,10 +1096,10 @@ Eshell V5.10.1 (abort with ^G) <list type="bulleted"> <item><p>Use the - <seealso marker="kernel:file"><c>file</c></seealso> module for + <seeerl marker="kernel:file"><c>file</c></seeerl> module for files opened for bytewise access (<c>{encoding,latin1}</c>).</p> </item> - <item><p>Use the <seealso marker="stdlib:io"><c>io</c></seealso> module + <item><p>Use the <seeerl marker="stdlib:io"><c>io</c></seeerl> module when accessing files with any other encoding (for example <c>{encoding,uf8}</c>).</p> </item> @@ -1147,31 +1147,31 @@ ok is started with flag <c>+fna</c> (which is default from Erlang/OTP 17.0).</p> <p>You can check the setting of this by calling - <seealso marker="stdlib:io#getopts/1"><c>io:getopts()</c></seealso>, + <seemfa marker="stdlib:io#getopts/1"><c>io:getopts()</c></seemfa>, which gives 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> + <seecom marker="erts:erl"><c>erl(1)</c></seecom></tag> <item> <p>This flag affects what is interpreted as string data when doing heuristic string detection in the shell and in - <seealso marker="stdlib:io"><c>io</c></seealso>/ - <seealso marker="stdlib:io_lib#format/2"><c>io_lib:format</c></seealso> + <seeerl marker="stdlib:io"><c>io</c></seeerl>/ + <seemfa marker="stdlib:io_lib#format/2"><c>io_lib:format</c></seemfa> with the <c>"~tp"</c> and <c>~tP</c> formatting instructions, as described earlier.</p> <p>You can check this option by calling - <seealso marker="stdlib:io#printable_range/0"><c>io:printable_range/0</c></seealso>, + <seemfa marker="stdlib:io#printable_range/0"><c>io:printable_range/0</c></seemfa>, which returns <c>unicode</c> or <c>latin1</c>. To be compatible with future (expected) extensions to the settings, rather use - <seealso marker="stdlib:io_lib#printable_list/1"><c>io_lib:printable_list/1</c></seealso> + <seemfa marker="stdlib:io_lib#printable_list/1"><c>io_lib:printable_list/1</c></seemfa> to check if a list is printable according to the setting. That function takes into account new possible settings returned from <c>io:printable_range/0</c>.</p> </item> <tag>The <c>+fn</c>{<c>l</c>|<c>u</c>|<c>a</c>} [{<c>w</c>|<c>i</c>|<c>e</c>}] flag to - <seealso marker="erts:erl"><c>erl(1)</c></seealso></tag> + <seecom marker="erts:erl"><c>erl(1)</c></seecom></tag> <item> <p>This flag affects how the filenames are to be interpreted. On operating systems with transparent file naming, this must be @@ -1199,10 +1199,10 @@ ok </item> </list> <p>The filename translation mode can be read with function - <seealso marker="kernel:file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seealso>, + <seemfa marker="kernel:file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seemfa>, which returns <c>latin1</c> (bytewise encoding) or <c>utf8</c>.</p> </item> - <tag><seealso marker="stdlib:epp#default_encoding/0"><c>epp:default_encoding/0</c></seealso></tag> + <tag><seemfa marker="stdlib:epp#default_encoding/0"><c>epp:default_encoding/0</c></seemfa></tag> <item> <p>This function returns the default encoding for Erlang source files (if no encoding comment is present) in the currently running release. @@ -1210,10 +1210,10 @@ ok As from Erlang/OTP 17.0, <c>utf8</c> is returned.</p> <p>The encoding of each file can be specified using comments as described in the - <seealso marker="stdlib:epp#encoding"><c>epp(3)</c></seealso> module. + <seeerl marker="stdlib:epp#encoding"><c>epp(3)</c></seeerl> module. </p> </item> - <tag><seealso marker="stdlib:io#setopts/1"><c>io:setopts/1,2</c></seealso> + <tag><seemfa marker="stdlib:io#setopts/1"><c>io:setopts/1,2</c></seemfa> and flags <c>-oldshell</c>/<c>-noshell</c></tag> <item> <p>When Erlang is started with <c>-oldshell</c> or <c>-noshell</c>, the @@ -1221,7 +1221,7 @@ ok encoding, while an interactive shell defaults to what the environment variables says.</p> <p>You can set the encoding of a file or other I/O server with function - <seealso marker="stdlib:io#setopts/1"><c>io:setopts/2</c></seealso>. + <seemfa marker="stdlib:io#setopts/1"><c>io:setopts/2</c></seemfa>. This can also be set when opening a file. Setting the terminal (or other <c>standard_io</c> server) unconditionally to option <c>{encoding,utf8}</c> implies that UTF-8 encoded characters are @@ -1231,7 +1231,7 @@ ok writing or reading text files in a known encoding.</p> <p>You can retrieve the <c>encoding</c> setting for an I/O server with function - <seealso marker="stdlib:io#getopts/1"><c>io:getopts()</c></seealso>. + <seemfa marker="stdlib:io#getopts/1"><c>io:getopts()</c></seemfa>. </p> </item> </taglist> @@ -1251,7 +1251,7 @@ ok text. This code outlines how to open a file that is believed to have a BOM, and sets the files encoding and position for further sequential reading (preferably using the - <seealso marker="stdlib:io"><c>io</c></seealso> module).</p> + <seeerl marker="stdlib:io"><c>io</c></seeerl> module).</p> <p>Notice that error handling is omitted from the code:</p> @@ -1265,12 +1265,12 @@ open_bom_file_for_reading(File) -> {ok,F}.</code> <p>Function - <seealso marker="stdlib:unicode#bom_to_encoding/1"><c>unicode:bom_to_encoding/1</c></seealso> + <seemfa marker="stdlib:unicode#bom_to_encoding/1"><c>unicode:bom_to_encoding/1</c></seemfa> identifies the encoding from a binary of at least four bytes. It returns, along with a term suitable for setting the encoding of the file, the byte length of the BOM, so that the file position can be set accordingly. Notice that function - <seealso marker="kernel:file#position/2"><c>file:position/2</c></seealso> + <seemfa marker="kernel:file#position/2"><c>file:position/2</c></seemfa> always works on byte-offsets, so that the byte length of the BOM is needed.</p> @@ -1284,7 +1284,7 @@ open_bom_file_for_writing(File,Encoding) -> {ok,F}.</code> <p>The file is in both these cases then best processed using the - <seealso marker="stdlib:io"><c>io</c></seealso> module, as the functions + <seeerl marker="stdlib:io"><c>io</c></seeerl> module, as the functions in that module can handle code points beyond the ISO Latin-1 range.</p> </section> @@ -1293,8 +1293,8 @@ open_bom_file_for_writing(File,Encoding) -> <p>When reading and writing to Unicode-aware entities, like a file opened for Unicode translation, you probably want to format text strings using the functions in the - <seealso marker="stdlib:io"><c>io</c></seealso> module or the - <seealso marker="stdlib:io_lib"><c>io_lib</c></seealso> module. For + <seeerl marker="stdlib:io"><c>io</c></seeerl> module or the + <seeerl marker="stdlib:io_lib"><c>io_lib</c></seeerl> module. For backward compatibility reasons, these functions do not accept 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 @@ -1324,11 +1324,11 @@ ok</pre> bytewise-encoded characters and not UTF-8.</p> <p>Function - <seealso marker="stdlib:io_lib#format/2"><c>io_lib:format/2</c></seealso> + <seemfa marker="stdlib:io_lib#format/2"><c>io_lib:format/2</c></seemfa> behaves similarly. It is defined to return a deep list of characters and the output can easily be converted to binary data for outputting on any device by a simple - <seealso marker="erts:erlang#list_to_binary/1"><c>erlang:list_to_binary/1</c></seealso>. + <seemfa marker="erts:erlang#list_to_binary/1"><c>erlang:list_to_binary/1</c></seemfa>. 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> then fails. However, if the I/O server @@ -1350,7 +1350,7 @@ ok</pre> as such, as the Erlang shell uses the Unicode encoding (and is started with all Unicode characters considered printable). The Unicode list is valid input to function - <seealso marker="stdlib:io#put_chars/2"><c>io:put_chars/2</c></seealso>, + <seemfa marker="stdlib:io#put_chars/2"><c>io:put_chars/2</c></seemfa>, so data can be output on any Unicode-capable device. If the device is a terminal, characters are output in format <c>\x{</c>H...<c>}</c> if encoding is <c>latin1</c>. Otherwise in UTF-8 (for the non-interactive @@ -1373,7 +1373,7 @@ ok</pre> 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). - The <seealso marker="stdlib:unicode"><c>unicode</c></seealso> + The <seeerl marker="stdlib:unicode"><c>unicode</c></seeerl> module can be used to determine if data can be interpreted as UTF-8:</p> <code> @@ -1388,7 +1388,7 @@ heuristic_encoding_bin(Bin) when is_binary(Bin) -> <p>If you do not have a complete binary of the file content, you can instead chunk through the file and check part by part. The return-tuple <c>{incomplete,Decoded,Rest}</c> from function - <seealso marker="stdlib:unicode#characters_to_binary/1"><c>unicode:characters_to_binary/1,2,3</c></seealso> + <seemfa marker="stdlib:unicode#characters_to_binary/1"><c>unicode:characters_to_binary/1,2,3</c></seemfa> comes in handy. The incomplete rest from one chunk of data read from the file is prepended to the next chunk and we therefore avoid the problem of character boundaries when reading chunks of bytes in UTF-8 @@ -1415,7 +1415,7 @@ loop_through_file(F,Acc,{ok,Bin}) when is_binary(Bin) -> <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 function - <seealso marker="stdlib:io#get_chars/3"><c>io:get_chars/3</c></seealso>, + <seemfa marker="stdlib:io#get_chars/3"><c>io:get_chars/3</c></seemfa>, as we have to read characters with a code point > 255:</p> <code> @@ -1454,7 +1454,7 @@ utf8_list_to_string(StrangeList) -> second time is encoded as UTF-8. A common situation is where you read a file, byte by byte, but the content is already UTF-8. If you then convert the bytes to UTF-8, using, for example, the - <seealso marker="stdlib:unicode"><c>unicode</c></seealso> module, or by + <seeerl marker="stdlib:unicode"><c>unicode</c></seeerl> module, or by writing to a file opened with option <c>{encoding,utf8}</c>, you have each <em>byte</em> in the input file encoded as UTF-8, not each character of the original text (one character can have been encoded in diff --git a/lib/stdlib/doc/src/uri_string.xml b/lib/stdlib/doc/src/uri_string.xml index 148accf107..dea8e60979 100644 --- a/lib/stdlib/doc/src/uri_string.xml +++ b/lib/stdlib/doc/src/uri_string.xml @@ -65,24 +65,27 @@ <p>The functions implemented by this module cover the following use cases:</p> <list type="bulleted"> <item>Parsing URIs into its components and returing a map<br></br> - <seealso marker="#parse/1"><c>parse/1</c></seealso> + <seemfa marker="#parse/1"><c>parse/1</c></seemfa> </item> <item>Recomposing a map of URI components into a URI string<br></br> - <seealso marker="#recompose/1"><c>recompose/1</c></seealso> + <seemfa marker="#recompose/1"><c>recompose/1</c></seemfa> </item> <item>Changing inbound binary and percent-encoding of URIs<br></br> - <seealso marker="#transcode/2"><c>transcode/2</c></seealso> + <seemfa marker="#transcode/2"><c>transcode/2</c></seemfa> </item> <item>Transforming URIs into a normalized form<br></br> - <seealso marker="#normalize/1"><c>normalize/1</c></seealso><br></br> - <seealso marker="#normalize/2"><c>normalize/2</c></seealso> + <seemfa marker="#normalize/1"><c>normalize/1</c></seemfa><br></br> + <seemfa marker="#normalize/2"><c>normalize/2</c></seemfa> </item> <item>Composing form-urlencoded query strings from a list of key-value pairs<br></br> - <seealso marker="#compose_query/1"><c>compose_query/1</c></seealso><br></br> - <seealso marker="#compose_query/2"><c>compose_query/2</c></seealso> + <seemfa marker="#compose_query/1"><c>compose_query/1</c></seemfa><br></br> + <seemfa marker="#compose_query/2"><c>compose_query/2</c></seemfa> </item> <item>Dissecting form-urlencoded query strings into a list of key-value pairs<br></br> - <seealso marker="#dissect_query/1"><c>dissect_query/1</c></seealso> + <seemfa marker="#dissect_query/1"><c>dissect_query/1</c></seemfa> + </item> + <item>Decoding percent-encoded triplets<br></br> + <seemfa marker="#percent_decode/1"><c>percent_decode/1</c></seemfa> </item> </list> <p>There are four different encodings present during the handling of URIs:</p> @@ -150,6 +153,21 @@ <funcs> <func> + <name name="allowed_characters" arity="0" since="OTP 23.2"/> + <fsummary>Print allowed characters in URI components.</fsummary> + <desc> + <p>This is a utility function meant to be used in the shell for printing + the allowed characters in each + major URI component, and also in the most important characters sets. + Please note that this function does not replace the ABNF rules defined by + the standards, these character sets are derived directly from those + aformentioned rules. For more information see the + <seeguide marker="uri_string_usage#percent_encoding">Uniform Resource + Identifiers</seeguide> chapter in stdlib's Users Guide.</p> + </desc> + </func> + + <func> <name name="compose_query" arity="1" since="OTP 21.0"/> <fsummary>Compose urlencoded query string.</fsummary> <desc> @@ -161,8 +179,8 @@ <url href="https://www.w3.org/TR/html50/">HTML 5.0</url> specification for non-UTF-8 encodings. </p> - <p>See also the opposite operation <seealso marker="#dissect_query/1"> - <c>dissect_query/1</c></seealso>. + <p>See also the opposite operation <seemfa marker="#dissect_query/1"> + <c>dissect_query/1</c></seemfa>. </p> <p><em>Example:</em></p> <pre> @@ -194,8 +212,8 @@ 0x61 to 0x7A, are percent-encoded (U+0025 PERCENT SIGN character (%) followed by uppercase ASCII hex digits representing the hexadecimal value of the byte). </p> - <p>See also the opposite operation <seealso marker="#dissect_query/1"> - <c>dissect_query/1</c></seealso>. + <p>See also the opposite operation <seemfa marker="#dissect_query/1"> + <c>dissect_query/1</c></seemfa>. </p> <p><em>Example:</em></p> <pre> @@ -221,8 +239,8 @@ <url href="https://www.w3.org/TR/html50/">HTML 5.0</url> specification for non-UTF-8 encodings. </p> - <p>See also the opposite operation <seealso marker="#compose_query/1"> - <c>compose_query/1</c></seealso>. + <p>See also the opposite operation <seemfa marker="#compose_query/1"> + <c>compose_query/1</c></seemfa>. </p> <p><em>Example:</em></p> <pre> @@ -292,8 +310,8 @@ compliant <c>uri_string()</c> into a <c>uri_map()</c>, that holds the parsed components of the <c>URI</c>. If parsing fails, an error tuple is returned.</p> - <p>See also the opposite operation <seealso marker="#recompose/1"> - <c>recompose/1</c></seealso>.</p> + <p>See also the opposite operation <seemfa marker="#recompose/1"> + <c>recompose/1</c></seemfa>.</p> <p><em>Example:</em></p> <pre> 1> <input>uri_string:parse("foo://user@example.com:8042/over/there?name=ferret#nose").</input> @@ -309,6 +327,37 @@ </func> <func> + <name name="percent_decode" arity="1" since="OTP 23.2"/> + <fsummary>Decode percent-decode triplets in the input.</fsummary> + <desc> + <p>Decodes all percent-encoded triplets in the input that can be both a + <c>uri_string()</c> and a <c>uri_map()</c>. Note, that this function performs + raw decoding and it shall be used on already parsed URI components. Applying + this function directly on a standard URI can effectively change it.</p> + <p>If the input encoding is not UTF-8, an error tuple is returned.</p> + <p><em>Example:</em></p> + <pre> +1> <input>uri_string:percent_decode(#{host => "localhost-%C3%B6rebro",path => [],</input> +1> <input>scheme => "http"}).</input> +#{host => "localhost-örebro",path => [],scheme => "http"} +2> <![CDATA[uri_string:percent_decode(<<"%C3%B6rebro">>).]]> +<![CDATA[<<"örebro"/utf8>>]]> + </pre> + <warning><p> + Using <c>uri_string:percent_decode/1</c> directly on a URI is not safe. This + example shows, that after each consecutive application of the function + the resulting URI will be changed. None of these URIs refer to the same + resource.</p> + <pre> +<![CDATA[3> uri_string:percent_decode(<<"http://local%252Fhost/path">>). +<<"http://local%2Fhost/path">> +4> uri_string:percent_decode(<<"http://local%2Fhost/path">>). +<<"http://local/host/path">>]]> + </pre></warning> + </desc> + </func> + + <func> <name name="recompose" arity="1" since="OTP 21.0"/> <fsummary>Recompose URI.</fsummary> <desc> @@ -316,15 +365,15 @@ <c><anno>URIString</anno></c> (percent-encoded), based on the components of <c><anno>URIMap</anno></c>. If the <c><anno>URIMap</anno></c> is invalid, an error tuple is returned.</p> - <p>See also the opposite operation <seealso marker="#parse/1"> - <c>parse/1</c></seealso>.</p> + <p>See also the opposite operation <seemfa marker="#parse/1"> + <c>parse/1</c></seemfa>.</p> <p><em>Example:</em></p> <pre> 1> <input>URIMap = #{fragment => "nose", host => "example.com", path => "/over/there",</input> 1> port => 8042, query => "name=ferret", scheme => "foo", userinfo => "user"}. -#{fragment => "top",host => "example.com", - path => "/over/there",port => 8042,query => "?name=ferret", - scheme => foo,userinfo => "user"} +#{fragment => "nose",host => "example.com", + path => "/over/there",port => 8042,query => "name=ferret", + scheme => "foo",userinfo => "user"} 2> <input>uri_string:recompose(URIMap).</input> "foo://example.com:8042/over/there?name=ferret#nose"</pre> diff --git a/lib/stdlib/doc/src/uri_string_usage.xml b/lib/stdlib/doc/src/uri_string_usage.xml new file mode 100644 index 0000000000..72851096b7 --- /dev/null +++ b/lib/stdlib/doc/src/uri_string_usage.xml @@ -0,0 +1,370 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2020</year> + <year>2020</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </legalnotice> + + <title>Uniform Resource Identifiers</title> + <prepared>Péter Dimitrov</prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>2020-09-30</date> + <rev>PA1</rev> + <file>uri_string_usage.xml</file> + </header> + <section> + <title>Basics</title> + <p>At the time of writing this document, in October 2020, there are + two major standards concerning Universal Resource Identifiers and + Universal Resource Locators:</p> + <list type="bulleted"> + <item><p> + <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986 - Uniform Resource + Identifier (URI): Generic Syntax</url></p></item> + <item><p> + <url href="https://url.spec.whatwg.org/">WHAT WG URL - Living standard</url> + </p></item> + </list> + <p> + The former is a classical standard with a proper formal syntax, using the so + called <url href="https://www.ietf.org/rfc/rfc2234.txt">Augmented Backus-Naur Form + (ABNF)</url> for describing + the grammar, while the latter is a living document describing the current pratice, + that is, how a majority of Web browsers work with URIs. WHAT WG URL is Web focused + and it has no formal grammar but a plain english description of the algorithms + that should be followed.</p> + <p>What is the difference between them, if any? They provide an overlapping + definition for resource identifiers and they are not compatible. + The <seeerl marker="stdlib:uri_string"><c>uri_string</c></seeerl> module implements + <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url> and the term URI will + be used throughout this document. A URI is an identifier, a string of characters + that identifies a particular resource.</p> + <p> + For a more complete problem + statement regarding the URIs check the + <url href="https://tools.ietf.org/html/draft-ruby-url-problem-01">URL Problem + Statement and Directions</url>.</p> + </section> + + <section> + <title>What is a URI?</title> + <p>Let's start with what it is not. It is not the text that you type in the address + bar in your Web browser. Web browsers do all possible heuristics to convert the + input into a valid URI that could be sent over the network.</p> + <p>A URI is an identifier consisting of a sequence of characters matching the syntax + rule named <c>URI</c> in + <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>. + </p> + <p>It is crucial to clarify that a <i>character</i> is a symbol that is displayed on + a terminal or written to paper and should not be confused with its internal + representation.</p> + <p>A URI more specifically, is a sequence of characters from a + subset of the US ASCII character set. The generic URI syntax consists of a + hierarchical sequence of components referred to as the scheme, authority, + path, query, and fragment. There is a formal description for + each of these components in + <url href="https://www.ietf.org/rfc/rfc2234.txt">ABNF</url> notation in + <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>:</p> + <pre> + URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] + hier-part = "//" authority path-abempty + / path-absolute + / path-rootless + / path-empty + scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) + authority = [ userinfo "@" ] host [ ":" port ] + userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) + + reserved = gen-delims / sub-delims + gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" + sub-delims = "!" / "$" / "&" / "'" / "(" / ")" + / "*" / "+" / "," / ";" / "=" + + unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" + </pre> + </section> + + <section> + <title>The uri_string module</title> + <p>As producing and consuming standard URIs can get quite complex, Erlang/OTP + provides + a module, <seeerl marker="stdlib:uri_string"><c>uri_string</c></seeerl>, to handle all the most difficult operations such as parsing, + recomposing, normalizing and resolving URIs against a base URI. + </p> + <p>The API functions in <seeerl marker="stdlib:uri_string"><c>uri_string</c></seeerl> + work on two basic data types + <seetype marker="uri_string#uri_string"><c>uri_string()</c></seetype> and + <seetype marker="uri_string#uri_map"><c>uri_map()</c></seetype>. + <seetype marker="uri_string#uri_string"><c>uri_string()</c></seetype> represents a + standard URI, while + <seetype marker="uri_string#uri_map"><c>uri_map()</c></seetype> is a wider datatype, + that can represent URI components using + <seeguide marker="unicode_usage#what-unicode-is">Unicode</seeguide> characters. + <seetype marker="uri_string#uri_map"><c>uri_map()</c></seetype> + is a convenient choice for enabling + operations such as producing standard compliant URIs out of components that have + special or <seeguide marker="unicode_usage#what-unicode-is">Unicode</seeguide> + characters. It is easier to explain this by an example. + </p> + <p>Let's say that we would like to create the following URI and send it over the + network: <c>http://cities/örebro?foo bar</c>. This is not a valid URI as it contains + characters that are not allowed in a URI such as "ö" and the space. We can verify + this by parsing the URI: + </p> + <pre> + 1> uri_string:parse("http://cities/örebro?foo bar"). + {error,invalid_uri,":"} + </pre> + <p>The URI parser tries all possible combinations to interpret the input and fails + at the last attempt when it encounters the colon character <c>":"</c>. Note, that + the inital fault occurs when the parser attempts to interpret the character + <c>"ö"</c> and after a failure back-tracks to the point where it has another + possible parsing alternative.</p> + <p>The proper way to solve this problem is to use + <seemfa marker="uri_string#recompose/1"><c>uri_string:recompose/1</c></seemfa> + with a <seetype marker="uri_string#uri_map"><c>uri_map()</c></seetype> as input:</p> + <pre> + 2> uri_string:recompose(#{scheme => "http", host => "cities", path => "/örebro", + query => "foo bar"}). + "http://cities/%C3%B6rebro?foo%20bar" + </pre> + <p>The result is a valid URI where all the special characters are encoded as defined + by the standard. Applying + <seemfa marker="uri_string#parse/1"><c>uri_string:parse/1</c></seemfa> and + <seemfa marker="uri_string#percent_decode/1"><c>uri_string:percent_decode/1</c></seemfa> + on the URI returns the original input: + </p> + <pre> + 3> uri_string:percent_decode(uri_string:parse("http://cities/%C3%B6rebro?foo%20bar")). + #{host => "cities",path => "/örebro",query => "foo bar", + scheme => "http"} + </pre> + <p>This symmetric property is heavily used in our property test suite. + </p> + </section> + + <section> + <title>Percent-encoding</title> + <p>As you have seen in the previous chapter, a standard URI can only contain a strict + subset of the US ASCII character set, moreover the allowed set of characters is not + the same in the different URI components. Percent-encoding is a mechanism to + represent a data octet in a component when that octet's corresponding character + is outside of + the allowed set or is being used as a delimiter. This is what you see when <c>"ö"</c> + is encoded as <c>%C3%B6</c> and <c>space</c> as <c>%20</c>. + Most of the API functions are + expecting UTF-8 encoding when handling percent-encoded triplets. The UTF-8 encoding + of the <seeguide marker="unicode_usage#what-unicode-is">Unicode</seeguide> + character <c>"ö"</c> is two octets: <c>OxC3 0xB6</c>. + The character <c>space</c> is in the first 128 characters of + <seeguide marker="unicode_usage#what-unicode-is">Unicode</seeguide> and it is encoded + using a single octet <c>0x20</c>.</p> + <note><p><seeguide marker="unicode_usage#what-unicode-is">Unicode</seeguide> + is backward compatible with ASCII, the encoding of the first 128 + characters is the same binary value as in ASCII. + </p></note> + <p><marker id="percent_encoding"></marker> + It is a major source of confusion exactly which characters will be + percent-encoded. In order to make it easier to answer this question the library + provides a utility function, + <seemfa marker="uri_string#allowed_characters/0"><c>uri_string:allowed_characters/0 + </c></seemfa>, + that lists the allowed set of characters in each major + URI component, and also in the most important standard character sets. + </p> + <pre> + 1> uri_string:allowed_characters(). + <![CDATA[{scheme, + "+-.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"}, + {userinfo, + "!$%&'()*+,-.0123456789:;=ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~"}, + {host, + "!$&'()*+,-.0123456789:;=ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~"}, + {ipv4,".0123456789"}, + {ipv6,".0123456789:ABCDEFabcdef"}, + {regname, + "!$%&'()*+,-.0123456789;=ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~"}, + {path, + "!$%&'()*+,-./0123456789:;=@ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~"}, + {query, + "!$%&'()*+,-./0123456789:;=?@ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~"}, + {fragment, + "!$%&'()*+,-./0123456789:;=?@ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~"}, + {reserved,"!#$&'()*+,/:;=?@[]"}, + {unreserved, + "-.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~"}] ]]> + </pre> + <p>If a URI component has a character that is not allowed, it will be + percent-encoded when the URI is produced: + </p> + <pre> + 2> uri_string:recompose(#{scheme => "https", host => "local#host", path => ""}). + "https://local%23host" + </pre> + <p>Consuming a URI containing percent-encoded triplets can take many steps. The + following example shows how to handle an input URI that is not normalized and + contains multiple percent-encoded triplets. + First, the input <seetype marker="uri_string#uri_string"><c>uri_string()</c></seetype> + is to be parsed into a <seetype marker="uri_string#uri_map"><c>uri_map()</c></seetype>. + The parsing only splits the URI into its components without doing any decoding: + </p> + <pre> + 3> uri_string:parse("http://%6C%6Fcal%23host/%F6re%26bro%20"). + #{host => "%6C%6Fcal%23host",path => "/%F6re%26bro%20", + scheme => "http"}} + </pre> + <p>The input is a valid URI but how can you decode those + percent-encoded octets? You can try to normalize the input with + <seemfa marker="uri_string#normalize/1"><c>uri_string:normalize/1</c></seemfa>. The + normalize operation decodes those + percent-encoded triplets that correspond to a character in the unreserved set. + Normalization is a safe, idempotent operation that converts a URI into its + canonical form:</p> + <pre> + 4> uri_string:normalize("http://%6C%6Fcal%23host/%F6re%26bro%20"). + "http://local%23host/%F6re%26bro%20" + 5> uri_string:normalize("http://%6C%6Fcal%23host/%F6re%26bro%20", [return_map]). + #{host => "local%23host",path => "/%F6re%26bro%20", + scheme => "http"} + </pre> + <p>There are still a few percent-encoded triplets left in the output. At this point, + when the URI is already parsed, it is safe to apply application specific decoding on + the remaining character triplets. Erlang/OTP provides a function, + <seemfa marker="uri_string#percent_decode/1"><c>uri_string:percent_decode/1</c></seemfa> + for raw percent decoding + that you can use on the host and path components, or on the whole map: + </p> + <pre> + 6> uri_string:percent_decode("local%23host"). + "local#host" + 7> uri_string:percent_decode("/%F6re%26bro%20"). + <![CDATA[{error,invalid_utf8,<<"/öre&bro ">>}]]> + 8> uri_string:percent_decode(#{host => "local%23host",path => "/%F6re%26bro%20", + scheme => "http"}). + <![CDATA[{error,{invalid,{path,{invalid_utf8,<<"/öre&bro ">>}}}}]]> + </pre> + <p>The <c>host</c> was successfully decoded but the path contains at least one + character with + non-UTF-8 encoding. In order to be able to decode this, you have to make assumptions + about the encoding used in these triplets. The most obvious choice is + <i>latin-1</i>, so you can try + <seemfa marker="uri_string#transcode/2"><c>uri_string:transcode/2</c></seemfa>, to + transcode the path to UTF-8 and run the percent-decode operation on the + transcoded string: + </p> + <pre> + 9> uri_string:transcode("/%F6re%26bro%20", [{in_encoding, latin1}]). + "/%C3%B6re%26bro%20" + 10> uri_string:percent_decode("/%C3%B6re%26bro%20"). + <![CDATA["/öre&bro "]]> + </pre> + <p>It is important to emphasize that it is not safe to apply + <seemfa marker="uri_string#percent_decode/1"><c>uri_string:percent_decode/1</c></seemfa> + directly on an input URI: + </p> + <pre> + 11> uri_string:percent_decode("http://%6C%6Fcal%23host/%C3%B6re%26bro%20"). + <![CDATA["http://local#host/öre&bro " + 12> uri_string:parse("http://local#host/öre&bro ").]]> + {error,invalid_uri,":"} + </pre> + <note><p>Percent-encoding is implemented in + <seemfa marker="uri_string#recompose/1"><c>uri_string:recompose/1</c></seemfa> + and it happens when converting a + <seetype marker="uri_string#uri_map"><c>uri_map()</c></seetype> + into a <seetype marker="uri_string#uri_string"><c>uri_string()</c></seetype>. + There is no equivalent to a raw percent-encoding function as percent-encoding + shall be applied on the component level using different sets of allowed characters. + Applying percent-encoding directly on an input URI would not be safe just as in + the case of + <seemfa marker="uri_string#percent_decode/1"><c>uri_string:percent_decode/1</c></seemfa>, + the output could be an invalid URI. + </p> + </note> + </section> + + <section> + <title>Normalization</title> + <p>Normalization is the operation of converting the input URI into a <i>canonical</i> + form and keeping the reference to the same underlying resource. The most common + application of normalization is determining whether two URIs are equivalent + without accessing their referenced resources.</p> + <p>Normalization has 6 distinct steps. First the input URI is parsed into an + intermediate form that can handle + <seeguide marker="unicode_usage#what-unicode-is">Unicode</seeguide> characters. + This datatype is the + <seetype marker="uri_string#uri_map"><c>uri_map()</c></seetype>, that can hold the + components of the URI in map elements of type + <seetype marker="unicode#chardata"><c>unicode:chardata()</c></seetype>. + After having the intermediate form, a sequence of + normalization algorithms are applied to the individual URI components:</p> + <taglist> + <tag>Case normalization</tag> + <item> + <p>Converts the <c>scheme</c> and <c>host</c> components + to lower case as they are not case sensitive.</p> + </item> + <tag>Percent-encoding normalization</tag> + <item> + <p>Decodes percent-encoded triplets that + correspond to characters in the unreserved set.</p> + </item> + <tag>Scheme-based normalization</tag> + <item> + <p>Applying rules for the schemes http, https, + ftp, ssh, sftp and tftp.</p> + </item> + <tag>Path segment normalization</tag> + <item> + <p>Converts the path into a canonical form.</p> + </item> + </taglist> + <p>After these steps, the intermediate data structure, an + <seetype marker="uri_string#uri_map"><c>uri_map()</c></seetype>, + is fully normalized. The last step is applying + <seemfa marker="uri_string#recompose/1"><c>uri_string:recompose/1</c></seemfa> + that converts the intermediate structure into a valid canonical URI string.</p> + <p>Notice the order, the + <seemfa marker="uri_string#normalize/2"><c>uri_string:normalize(URIMap, [return_map])</c></seemfa> that we + used many times in this user guide is a shortcut in the normalization process + returning the intermediate datastructure, and allowing us to inspect and apply + further decoding on the remaining percent-encoded triplets.</p> + <pre> + 13> uri_string:normalize("hTTp://LocalHost:80/%c3%B6rebro/a/../b"). + "http://localhost/%C3%B6rebro/b" + 14> uri_string:normalize("hTTp://LocalHost:80/%c3%B6rebro/a/../b", [return_map]). + #{host => "localhost",path => "/%C3%B6rebro/b", + scheme => "http"} + </pre> + </section> + + <section> + <title>Special considerations</title> + <p>The current URI implementation provides support for producing and consuming + standard URIs. The API is not meant to be directly exposed in a Web + browser's address bar where users can basically enter free text. Application + designers shall implement proper heuristics to map the input into a parsable URI.</p> + </section> + +</chapter> diff --git a/lib/stdlib/doc/src/win32reg.xml b/lib/stdlib/doc/src/win32reg.xml index 76d6bfdea3..3c34f66e38 100644 --- a/lib/stdlib/doc/src/win32reg.xml +++ b/lib/stdlib/doc/src/win32reg.xml @@ -87,7 +87,7 @@ hkdd HKEY_DYN_DATA</pre> <p>Some registry values are stored as strings with references to environment variables, for example, <c>%SystemRoot%Windows</c>. <c>SystemRoot</c> is an environment variable, and is to be replaced with its value. Function - <seealso marker="#expand/1"><c>expand/1</c></seealso> is provided so that + <seemfa marker="#expand/1"><c>expand/1</c></seemfa> is provided so that environment variables surrounded by <c>%</c> can be expanded to their values.</p> <p>For more information on the Windows registry, see consult the Win32 @@ -99,7 +99,7 @@ hkdd HKEY_DYN_DATA</pre> <name name="reg_handle"/> <desc> <p>As returned by - <seealso marker="#open/1"><c>open/1</c></seealso>.</p> + <seemfa marker="#open/1"><c>open/1</c></seemfa>.</p> </desc> </datatype> <datatype> @@ -159,8 +159,8 @@ hkdd HKEY_DYN_DATA</pre> <p>Deletes the current key, if it is valid. Calls the Win32 API function <c>RegDeleteKey()</c>. Notice that this call does not change the current key (unlike - <seealso marker="#change_key_create/2"> - <c>change_key_create/2</c></seealso>). + <seemfa marker="#change_key_create/2"> + <c>change_key_create/2</c></seemfa>). This means that after the call, the current key is invalid.</p> </desc> </func> @@ -204,9 +204,9 @@ hkdd HKEY_DYN_DATA</pre> <p>Opens the registry for reading or writing. The current key is the root (<c>HKEY_CLASSES_ROOT</c>). Flag <c>read</c> in the mode list can be omitted.</p> - <p>Use <seealso marker="#change_key/2"><c>change_key/2</c></seealso> + <p>Use <seemfa marker="#change_key/2"><c>change_key/2</c></seemfa> with an absolute path after - <seealso marker="#open/1"><c>open</c></seealso>.</p> + <seemfa marker="#open/1"><c>open</c></seemfa>.</p> </desc> </func> @@ -256,7 +256,7 @@ hkdd HKEY_DYN_DATA</pre> <desc> <p>Retrieves a list of all values on the current key. The values have types corresponding to the registry types, see - <seealso marker="#value/2"><c>value/2</c></seealso>. + <seemfa marker="#value/2"><c>value/2</c></seemfa>. Calls the Win32 API function <c>EnumRegValuesEx()</c>.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/zip.xml b/lib/stdlib/doc/src/zip.xml index 306ad27997..a056621ca1 100644 --- a/lib/stdlib/doc/src/zip.xml +++ b/lib/stdlib/doc/src/zip.xml @@ -47,42 +47,42 @@ <list type="bulleted"> <item> <p>To create zip archives, use function - <seealso marker="#zip/2"><c>zip/2</c></seealso> or - <seealso marker="#zip/2"><c>zip/3</c></seealso>. They are + <seemfa marker="#zip/2"><c>zip/2</c></seemfa> or + <seemfa marker="#zip/2"><c>zip/3</c></seemfa>. They are also available as <c>create/2,3</c>, to resemble the - <seealso marker="erl_tar"><c>erl_tar</c></seealso> module.</p> + <seeerl marker="erl_tar"><c>erl_tar</c></seeerl> module.</p> </item> <item> <p>To extract files from a zip archive, use function - <seealso marker="#unzip/1"><c>unzip/1</c></seealso> or - <seealso marker="#unzip/2"><c>unzip/2</c></seealso>. They are + <seemfa marker="#unzip/1"><c>unzip/1</c></seemfa> or + <seemfa marker="#unzip/2"><c>unzip/2</c></seemfa>. They are also available as <c>extract/1,2</c>, to resemble the - <seealso marker="erl_tar"><c>erl_tar</c></seealso> module.</p> + <seeerl marker="erl_tar"><c>erl_tar</c></seeerl> module.</p> </item> <item> <p>To fold a function over all files in a zip archive, use function - <seealso marker="#foldl/3"><c>foldl/3</c></seealso>.</p> + <seemfa marker="#foldl/3"><c>foldl/3</c></seemfa>.</p> </item> <item> <p>To return a list of the files in a zip archive, use function - <seealso marker="#list_dir/1"><c>list_dir/1</c></seealso> or - <seealso marker="#list_dir/2"><c>list_dir/2</c></seealso>. They are + <seemfa marker="#list_dir/1"><c>list_dir/1</c></seemfa> or + <seemfa marker="#list_dir/2"><c>list_dir/2</c></seemfa>. They are also available as <c>table/1,2</c>, to resemble the - <seealso marker="erl_tar"><c>erl_tar</c></seealso> module.</p> + <seeerl marker="erl_tar"><c>erl_tar</c></seeerl> module.</p> </item> <item> <p>To print a list of files to the Erlang shell, use function - <seealso marker="#t/1"><c>t/1</c></seealso> or - <seealso marker="#tt/1"><c>tt/1</c></seealso>.</p> + <seemfa marker="#t/1"><c>t/1</c></seemfa> or + <seemfa marker="#tt/1"><c>tt/1</c></seemfa>.</p> </item> <item> <p>Sometimes it is desirable to open a zip archive, and to unzip files from it file by file, without having to reopen the archive. This can be done by functions - <seealso marker="#zip_open/1"><c>zip_open/1,2</c></seealso>, - <seealso marker="#zip_get/1"><c>zip_get/1,2</c></seealso>, - <seealso marker="#zip_list_dir/1"><c>zip_list_dir/1</c></seealso>, and - <seealso marker="#zip_close/1"><c>zip_close/1</c></seealso>.</p> + <seemfa marker="#zip_open/1"><c>zip_open/1,2</c></seemfa>, + <seemfa marker="#zip_get/1"><c>zip_get/1,2</c></seemfa>, + <seemfa marker="#zip_list_dir/1"><c>zip_list_dir/1</c></seemfa>, and + <seemfa marker="#zip_close/1"><c>zip_close/1</c></seemfa>.</p> </item> </list> </description> @@ -136,8 +136,8 @@ <tag><c>info</c></tag> <item> <p>File information as in - <seealso marker="kernel:file#read_file_info/1"> - <c>file:read_file_info/1</c></seealso> + <seemfa marker="kernel:file#read_file_info/1"> + <c>file:read_file_info/1</c></seemfa> in Kernel</p> </item> <tag><c>comment</c></tag> @@ -165,15 +165,15 @@ <datatype> <name name="create_option"/> <desc> - <p>These options are described in <seealso marker="#zip_options"> - <c>create/3</c></seealso>.</p> + <p>These options are described in <seeerl marker="#zip_options"> + <c>create/3</c></seeerl>.</p> </desc> </datatype> <datatype> <name name="handle"/> <desc> <p>As returned by - <seealso marker="#zip_open/2"><c>zip_open/2</c></seealso>.</p> + <seemfa marker="#zip_open/2"><c>zip_open/2</c></seemfa>.</p> </desc> </datatype> </datatypes> @@ -245,7 +245,7 @@ <p><c>list_dir/2</c> provides options.</p> <p><c>table/1</c> and <c>table/2</c> are provided as synonyms to resemble the - <seealso marker="erl_tar"><c>erl_tar</c></seealso> module.</p> + <seeerl marker="erl_tar"><c>erl_tar</c></seeerl> module.</p> <p>The result value is the tuple <c>{ok, List}</c>, where <c>List</c> contains the zip archive comment as the first element.</p> <p>One option is available:</p> @@ -293,7 +293,7 @@ <p><c>unzip/2</c> provides options to extract some files, and more.</p> <p><c>extract/1</c> and <c>extract/2</c> are provided as synonyms to resemble module - <seealso marker="erl_tar"><c>erl_tar</c></seealso>.</p> + <seeerl marker="erl_tar"><c>erl_tar</c></seeerl>.</p> <p>If argument <c><anno>Archive</anno></c> is specified as a binary, the contents of the binary is assumed to be a zip archive, otherwise a filename.</p> @@ -344,8 +344,8 @@ <p>Uses the specified directory as current directory. It is prepended to filenames when extracting them from the zip archive. (Acting like - <seealso marker="kernel:file#set_cwd/1"> - <c>file:set_cwd/1</c></seealso> in Kernel, + <seemfa marker="kernel:file#set_cwd/1"> + <c>file:set_cwd/1</c></seemfa> in Kernel, but without changing the global <c>cwd</c> property.)</p> </item> </taglist> @@ -358,12 +358,14 @@ <name name="create" arity="2" since=""/> <name name="create" arity="3" since=""/> <fsummary>Create a zip archive with options.</fsummary> + <type name="create_option"/> + <type name="extension_spec"/> <desc> <p>Creates a zip archive containing the files specified in <c><anno>FileList</anno></c>.</p> <p><c>create/2</c> and <c>create/3</c> are provided as synonyms to resemble module - <seealso marker="erl_tar"><c>erl_tar</c></seealso>.</p> + <seeerl marker="erl_tar"><c>erl_tar</c></seeerl>.</p> <p><c><anno>FileList</anno></c> is a list of files, with paths relative to the current directory, which are stored with this path in the archive. Files can also be specified with data in binaries @@ -408,7 +410,7 @@ <p>The output is not to a file, but instead as a tuple <c>{<anno>FileName</anno>, binary()}</c>. The binary is a full zip archive with header and can be extracted with, for example, - <seealso marker="#unzip/2"><c>unzip/2</c></seealso>.</p> + <seemfa marker="#unzip/2"><c>unzip/2</c></seemfa>.</p> </item> <tag><c>{comment, <anno>Comment</anno>}</c></tag> <item> @@ -419,8 +421,8 @@ <p>Uses the specified directory as current work directory (<c>cwd</c>). This is prepended to filenames when adding them, although not in the zip archive (acting like - <seealso marker="kernel:file#set_cwd/1"> - <c>file:set_cwd/1</c></seealso> in Kernel, but without + <seemfa marker="kernel:file#set_cwd/1"> + <c>file:set_cwd/1</c></seemfa> in Kernel, but without changing the global <c>cwd</c> property.).</p> </item> <tag><c>{compress, <anno>What</anno>}</c></tag> @@ -485,7 +487,7 @@ <fsummary>Close an open archive.</fsummary> <desc> <p>Closes a zip archive, previously opened with - <seealso marker="#zip_open/1"><c>zip_open/1,2</c></seealso>. + <seemfa marker="#zip_open/1"><c>zip_open/1,2</c></seemfa>. All resources are closed, and the handle is not to be used after closing.</p> </desc> @@ -499,7 +501,7 @@ <p>Extracts one or all files from an open archive.</p> <p>The files are unzipped to memory or to file, depending on the options specified to function - <seealso marker="#zip_open/1"><c>zip_open/1,2</c></seealso> + <seemfa marker="#zip_open/1"><c>zip_open/1,2</c></seemfa> when opening the archive.</p> </desc> </func> @@ -521,9 +523,9 @@ <p>Opens a zip archive, and reads and saves its directory. This means that later reading files from the archive is faster than unzipping files one at a time with - <seealso marker="#unzip/1"><c>unzip/1,2</c></seealso>.</p> + <seemfa marker="#unzip/1"><c>unzip/1,2</c></seemfa>.</p> <p>The archive must be closed with - <seealso marker="#zip_close/1"><c>zip_close/1</c></seealso>.</p> + <seemfa marker="#zip_close/1"><c>zip_close/1</c></seemfa>.</p> <p>The <c><anno>ZipHandle</anno></c> is closed if the process that originally opened the archive dies.</p> </desc> |