Merge branch 'pan/otp_8579_autoimport_override' into dev

* origin/pan/otp_8579_autoimport_override:
  Update preloaded modules
  Update primary bootstrap
  Remove outcommented code from erl_lint
  Make port_command/3 auto-imported
  Remove (harmless) warnings about min/max in core applications
  Autoimport min/2 and max/2
  Improve coverage of erl_int in testcases
  Change warning to error for nowarn_bif_clash compiler directive
  Add -compile({no_auto_import,[F/A]}) doc to compiler.xml
  Add some testcases to compiler to verify that overriding really happens
  Return nowarn_bif_clash functionality but with warning
  Teach erl_lint to better override BIFs with local functions and imports
  Teach compiler to override autoimport with import
  First prototype for local functions overriding autoimported

OTP-8579  Local functions should override auto-imported

Local and imported functions now override the autoimported
BIFs when the names clash. The pre R14 behaviour was that
autoimported BIFs would override local functions. To avoid
that old programs change behaviour, the following will
generate an error:

Doing a call without explicit module name to a local function
having a name clashing with the name of an autoimported BIF
that was present (and autoimported) before OTP R14A
Explicitly importing a function having a name clashing with
the name of an autoimported BIF that was present (and
autoimported) before OTP R14A Using any form of the old
compiler directive nowarn_bif_clash

If the BIF was added or autoimported in OTP R14A or later,
overriding it with an import or a local function will only
result in a warning,

To resolve clashes, you can either use the explicit module
name erlang to call the BIF, or you can remove the autoimport
of that specific BIF by using the new compiler directive
-compile({no_auto_import,[F/A]})., which makes all calls to
the local or imported function without explicit module name
pass without warnings or errors.

The change makes it possible to add autoimported BIFs without
breaking or silently changing old code in the future. However
some current code ingeniously utilizing the old behaviour or
the nowarn_bif_clash compiler directive, might need changing
to be accepted by the compiler.

1 files changed, 85 insertions, 12 deletions

diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml
index b56b8acbf0..714ecccaf6 100644
--- a/system/doc/reference_manual/expressions.xml
+++ b/system/doc/reference_manual/expressions.xml
@@ -217,12 +217,16 @@ lists:keysearch(Name, 1, List)</code>
     <p>In the second form of function calls,
       <c>ExprF(Expr1,...,ExprN)</c>, <c>ExprF</c> must be an atom or
       evaluate to a fun.</p>
+
     <p>If <c>ExprF</c> is an atom the function is said to be called by
-      using the <em>implicitly qualified function name</em>. If
-      <c>ExprF/N</c> is the name of a function explicitly or
-      automatically imported from module <c>M</c>, then the call is
-      short for <c>M:ExprF(Expr1,...,ExprN)</c>. Otherwise,
-      <c>ExprF/N</c> must be a locally defined function. Examples:</p>
+      using the <em>implicitly qualified function name</em>.  If the
+      function <c>ExprF</c> is locally defined, it is called.
+      Alternatively if <c>ExprF</c> is explicitly imported from module
+      <c>M</c>, <c>M:ExprF(Expr1,...,ExprN)</c> is called. If
+      <c>ExprF</c> is neither declared locally nor explicitly
+      imported, <c>ExprF</c> must be the name of an automatically
+      imported BIF. Examples:</p>
+
     <code type="none">
 handle(Msg, State)
 spawn(m, init, [])</code>
@@ -238,16 +242,85 @@ Fun2([1,2], [3,4])
 
 fun lists:append/2([1,2], [3,4])
 => [1,2,3,4]</code>
-    <p>To avoid possible ambiguities, the fully qualified function
-      name must be used when calling a function with the same name as
-      a BIF, and the compiler does not allow defining a function with
-      the same name as an explicitly imported function.</p>
+
     <p>Note that when calling a local function, there is a difference
-      between using the implicitly or fully qualified function name, as
-      the latter always refers to the latest version of the module. See
-      <seealso marker="code_loading">Compilation and Code Loading</seealso>.</p>
+    between using the implicitly or fully qualified function name, as
+    the latter always refers to the latest version of the module. See
+    <seealso marker="code_loading">Compilation and Code Loading</seealso>.</p>
+
     <p>See also the chapter about
       <seealso marker="functions#eval">Function Evaluation</seealso>.</p>
+
+    <section>
+      <title>Local Function Names Clashing With  Auto-imported BIFs</title>
+    <p>If a local function has the same name as an auto-imported BIF,
+    the semantics is that implicitly qualified function calls are
+    directed to the locally defined function, not to the BIF. To avoid
+    confusion, there is a compiler directive available,
+    <c>-compile({no_auto_import,[F/A]})</c>, that makes a BIF not
+    being auto-imported. In certain situations, such a compile-directive
+    is mandatory.</p>
+
+    <warning><p>Before OTP R14A (ERTS version 5.8), an implicitly
+    qualified function call to a function having the same name as an
+    auto-imported BIF always resulted in the BIF being called. In
+    newer versions of the compiler the local function is instead
+    called. The change is there to avoid that future additions to the
+    set of auto-imported BIFs does not silently change the behavior
+    of old code.</p>
+
+    <p>However, to avoid that old (pre R14) code changed it's
+    behavior when compiled with OTP version R14A or later, the
+    following restriction applies: If you override the name of a BIF
+    that was auto-imported in OTP versions prior to R14A (ERTS version
+    5.8) and have an implicitly qualified call to that function in
+    your code, you either need to explicitly remove the auto-import
+    using a compiler directive, or replace the call with a fully
+    qualified function call, otherwise you will get a compilation
+    error. See example below:</p> </warning>
+
+    <code type="none">
+-export([length/1,f/1]).
+
+-compile({no_auto_import,[length/1]}). % erlang:length/1 no longer autoimported
+
+length([]) ->
+    0;
+length([H|T]) ->
+    1 + length(T). %% Calls the local funtion length/1
+
+f(X) when erlang:length(X) > 3 -> %% Calls erlang:length/1,
+                                  %% which is allowed in guards
+    long.</code>
+
+    <p>The same logic applies to explicitly imported functions from
+    other modules as to locally defined functions. To both import a
+    function from another module and have the function declared in the
+    module at the same time is not allowed.</p>
+
+    <code type="none">
+-export([f/1]).
+
+-compile({no_auto_import,[length/1]}). % erlang:length/1 no longer autoimported
+
+-import(mod,[length/1]).
+
+f(X) when erlang:length(X) > 33 -> %% Calls erlang:lenght/1,
+                                   %% which is allowed in guards
+
+    erlang:length(X);              %% Explicit call to erlang:length in body
+
+f(X) ->
+    length(X).                     %% mod:length/1 is called</code>
+
+
+    <p>For auto-imported BIFs added to Erlang in release R14A and thereafter,
+    overriding the name with a local function or explicit import is always
+    allowed. However, if the <c>-compile({no_auto_import,[F/A])</c>
+    directive is not used, the compiler will issue a warning whenever
+    the function is called in the module using the implicitly qualified
+    function name.</p>
+    </section>
   </section>
 
   <section>