File 1044-erlang_fun_to_list-1-Improvements-due-to-comments-fr.patch of Package erlang
From 69986f99ad0840f9a15e811ba202db4efa3e99c3 Mon Sep 17 00:00:00 2001
From: Kjell Winblad <kjellwinblad@gmail.com>
Date: Tue, 29 Sep 2020 11:24:25 +0200
Subject: [PATCH 34/39] erlang_fun_to_list/1: Improvements due to comments from
@bjorng
* Change structure
* Warnings to notes
* Add example
---
erts/doc/src/erlang.xml | 103 +++++++++++++++++++++++++++++-----------
1 file changed, 74 insertions(+), 29 deletions(-)
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 7bce904b69..d46df36345 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -2123,43 +2123,88 @@ true</pre>
<name name="fun_to_list" arity="1"/>
<fsummary>Text representation of a fun.</fsummary>
<desc>
- <warning>
- <p>This function is <em>not</em> guaranteed to work as described here
- when <c><anno>Fun</anno></c> was created while executing
- uncompiled code (uncompiled escripts, the Erlang shell, and
- other code executed by the <seealso
- marker="stdlib:erl_eval"><c>erl_eval</c> module</seealso>).</p>
- </warning>
- <p>Returns <c><anno>String</anno></c> that represents the code
+ <p>Returns <c><anno>String</anno></c> that represents the code
that created <c><anno>Fun</anno></c>.</p>
- <warning>
- <p>Generally, one can not use this function to check if two
- funs are equal as this function does not take the fun's
- environment into account. See <seealso
- marker="#fun_info/1"><c>erlang:fun_info/1</c></seealso> for how
- to get the environment of a fun.</p>
- </warning>
- <note>
- <p><c><anno>String</anno></c> has the following form, if
- <c><anno>Fun</anno></c> was created by an expression of the
- form <c>fun ModuleName:FuncName/Arity</c>:</p>
- <p><c>"fun ModuleName:FuncName/Arity"</c>,</p>
- <p>and <c><anno>String</anno></c> has the following form, if
- <c><anno>Fun</anno></c> was created by a <seealso
- marker="system/reference_manual:expressions#fun-expressions">fun
- expression</seealso>:</p>
+ <p><c><anno>String</anno></c> has the following form, if
+ <c><anno>Fun</anno></c> was created by a <seealso
+ marker="system/reference_manual:expressions#fun-expressions">fun
+ expression</seealso> of the form <c>fun
+ ModuleName:FuncName/Arity</c>:</p>
+
+ <p><c>"fun ModuleName:FuncName/Arity"</c></p>
- <p><c>"#Fun<M.I.U>"</c>, where M, I and U correspond to
- the values named <c>module</c>, <c>index</c> and <c>uniq</c>
- in the result of <seealso
- marker="#fun_info/1"><c>erlang:fun_info(Fun)</c></seealso>.</p>
+ <p>The form of <c><anno>String</anno></c> when
+ <c><anno>Fun</anno></c> is created from other types of <seealso
+ marker="system/reference_manual:expressions#fun-expressions">fun
+ expressions</seealso> differs depending on if the fun
+ expression was executed while executing compiled code or if
+ the fun expression was executed while executing uncompiled
+ code (uncompiled escripts, the Erlang shell, and other code
+ executed by the erl_eval module):</p>
+ <taglist>
+ <tag>compiled code</tag>
+ <item><p><c>"#Fun<M.I.U>"</c>, where M, I and U
+ correspond to the values named <c>module</c>, <c>index</c>
+ and <c>uniq</c> in the result of <seealso
+ marker="#fun_info/1"><c>erlang:fun_info(Fun)</c></seealso>.</p></item>
+ <tag>uncompiled code</tag>
+
+ <item>All funs created from fun expressions in uncompiled
+ code with the same arity are mapped to the same list by
+ <c>fun_to_list/1</c>.</item>
+ </taglist>
+
+
+ <note>
+ <p>Generally, one can not use <c>fun_to_list/1</c> to check if
+ two funs are equal as <c>fun_to_list/1</c> does not take the
+ fun's environment into account. See <seealso
+ marker="#fun_info/1"><c>erlang:fun_info/1</c></seealso> for how
+ to get the environment of a fun.</p>
+ </note>
+ <note>
<p>The output of <c>fun_to_list/1</c> can differ between
- Erlang implementations and can change in future
+ Erlang implementations and may change in future
versions.</p>
</note>
+ <p>Examples:</p>
+ <code>
+-module(test).
+-export([add/1, add2/0, fun_tuple/0]).
+add(A) -> fun(B) -> A + B end.
+add2() -> fun add/1.
+fun_tuple() -> {fun() -> 1 end, fun() -> 1 end}.
+ </code>
+<pre>
+> <input>{fun test:add/1, test:add2()}.</input>
+{fun test:add/1,#Fun<test.1.107738983>}
+</pre>
+<p>
+ Explanation: <c>fun test:add/1</c> is upgradable but <c>test:add2()</c> is not upgradable.
+</p>
+<pre>
+> <input>{test:add(1), test:add(42)}.</input>
+{#Fun<test.0.107738983>,#Fun<test.0.107738983>}
+</pre>
+<p>Explanation: <c>test:add(1)</c> and <c>test:add(42)</c> has the
+same string representation as the environment is not taken into
+account.</p>
+<pre>
+><input>test:fun_tuple().</input>
+{#Fun<test.2.107738983>,#Fun<test.3.107738983>}
+</pre>
+<p>Explanation: The string representations differ because the funs
+come from different fun experssions.</p>
+<pre>
+> <input>{fun() -> 1 end, fun() -> 1 end}.</input> > <input></input>
+{#Fun<erl_eval.45.97283095>,#Fun<erl_eval.45.97283095>}
+</pre>
+<p>Explanation: All funs created from fun expressions of this form in
+uncompiled code with the same arity are mapped to the same list by
+<c>fun_to_list/1</c>.</p>
</desc>
</func>
--
2.26.2
