Documenting the Language

[Gunilla Arendt]

As a coincidence, I'm right now in the process of putting together
an 'Erlang Reference Manual'. When your message arrived, I was making
a list of BIFs allowed in guards...

The reference manual will be included in OTP as soon as possible,
which means in the commercial R9C release planned for August and
possibly in an Open Source snapshot before that.

/ Gunilla Arendt, Erlang/OTP team

Vance Shipley wrote:
> 
> <grump>
> There really does need to be a document which definetivly
> decribes the core langauge.  Now I know there is the
> "Reference Manual" but it is dated February 9, 1999 and is
> "DRAFT (0.7)".  It's the Erlang 4.7.3 reference manual and
> we're currently on 5.2.  It's also only available as a
> postscript file and I haven't had any luck text searching it.
> 
> A case in point is the collection of boolean BIFs:
> 
>         is_atom/1, is_constant/1, is_float/1,
>         is_integer/1, is_list/1, is_number/1,
>         is_pid/1, is_port/1, is_reference/1,
>         is_tuple/1, is_binary/1, is_function/1,
>         is_record/1
> 
> The closest these come to being documented is in the ERTS
> User's Guide under Match Specifications in Erlang.  Other than
> this they were mentioned in the release notes of the compiler
> and there is a passing mention in Erlang Extensions Since 4.4
> under Boolean expressions in guards.
> 
> Another issue is in what is allowed in a guard.  I found through
> trial and error that is_process_alive/1 is not allowed in a guard
> despite it's encouraging name.  There is a function exported from
> erl_internal, and documented, which tests if a function is valid
> in a guard:
> 
>      guard_bif(Name, Arity) -> bool()
> 
>      Types:
>      Name = atom()
>      Arity = integer()
> 
>      Returns true if Name/Arity is an Erlang BIF which is allowed
>      in guards, otherwise false.
> 
> That was a little hard to find though and it still doesn't give
> me a list, it only allows me to test what the compiler will
> complain about later.
> 
> When try & cond show up will they only be mentioned in the release
> notes?  There has been a lot of talk about promoting Erlang here.
> I think having a definitive list of BIFS would be a good start.
> 
> I would do it myself but I don't appear to be qualified as I tried
> but quickly got lost in categorizing bifs,operators,guards,tests,etc.
> </grump>
> 
>         -Vance