Implement ?FUNCTION_NAME and ?FUNCTION_ARITY macros

For a long time, users have asked for one or more macros that would
return the name and arity of the current function.

We could define a single ?FUNCTION macro that would return
a {Name,Arity} tuple.  However, to access just the name or
just the arity for the function, element/2 must be used.
That would limit its usefulness, because element/2 is not
allowed in all contexts.

Therefore, it seems that we will need two macros.
?FUNCTION_NAME that expands to the name of the current function
and ?FUNCTION_ARITY that expands to arity of the current
function.

Converting the function name to a string can be done like this:

  f() ->
    atom_to_list(?FUNCTION_NAME) ++ "/" ++
	integer_to_list(?FUNCTION_ARITY).

f/0 will return "f/0". The BEAM compiler will evaluate the
entire expression at compile-time, so there will not be
any run-time penalty for the function calls.

The implementation is non-trivial because the preprocessor is
run before the parser.

One way to implement the macros would be to replace them with some
placeholder and then let the parser or possibly a later pass replace
the placeholder with correct value. That could potentially slow
down the compiler and cause incompatibilities for parse transforms.

Another way is to let the preprocessor do the whole job. That means
that the preprocessor will have to scan the function head to find
out the name and arity. The scanning of the function head can be
delayed until the first occurrence of a ?FUNCTION_NAME or
?FUNCTION_ARITY.

I have chosen the second way because it seems less likely to cause
weird compatibility problems.

1 files changed, 4 insertions, 0 deletions

diff --git a/system/doc/reference_manual/macros.xml b/system/doc/reference_manual/macros.xml
index 3b1f72e5d6..42ea639b54 100644
--- a/system/doc/reference_manual/macros.xml
+++ b/system/doc/reference_manual/macros.xml
@@ -146,6 +146,10 @@ bar(X) ->
       <item>The current line number.</item>
       <tag><c>?MACHINE</c>.</tag>
       <item>The machine name, <c>'BEAM'</c>.</item>
+      <tag><c>?FUNCTION_NAME</c></tag>
+      <item>The name of the current function.</item>
+      <tag><c>?FUNCTION_ARITY</c></tag>
+      <item>The arity (number of arguments) for the current function.</item>
     </taglist>
   </section>