[erlang-questions] idea: function meta data

[Andreas Hillqvist]

So the shortest step from the syntax in todays Erlang, would be to
separate by convention instead of syntax. I.e. doc() and fun_doc() or
doc_fun().
Is a proposed in my answer.

I tried to address this problem was in my first answer by proposing an
new prefix.
With another prefix we get clear distinction between module- and
function-level meta data.

But this raised the question:
Should the meta data syntax be consistent, independent of level?


An alternativ would be to use the module meta declaration:
         -doc("Math module with some fancy math functions.").
         -keywords([math, fancy, factorial]).
         -export([fac/1].
         -module(test).

         -fun(doc, "The factorial function.").
         -fun(keywords, [math]).
         fac(0) -> 1;
         fac(N) -> N*fac(N-1)

But with this behaviour, I do not consider the module meta declaration
to be meta anymore. Module is now part of the syntax.

Should we introduce a module declaration to the Erlang syntax?


So the "real" question is: how do we separate module-level meta data
from function-level meta data?
 * By convention:
   % Module-level:
   -doc("text").

   %Function-level:
   -fun_doc("text").
   %or
      -doc_fun("text").

 * By prefix:
   % Module-level:
      -doc("text").
   % Function-level:
      --fun_doc("text").
   % or
      +doc_fun("text").
    % or something else

 * By module declaration:
   % Module-level:
      -doc("text").

      -module(my_module).
   % or
      module{my_module}.
    % or something else


   % Function-level:
   -doc("text").

To illustrate some of the possibilities to separate.

I believe the most likely to be implemented is "By convention".
Because it dose not affect old code and dose not introduce anything
new to the syntax.
A new module declaration is the least likely to be implemented.
New prefix simplifies the implementation of function-level meta, my
guess to why Joe choose the +prefix to illustrate an implementation.

Pleas feel free to suggest other ways to address this issue.


Regards
Andreas Hillqvist

2007/11/16, Lev Walkin <vlm@REDACTED>:
>
>
> I think there's is a problem with attributing metadata to
> module or to function. In your example, consider the
> first -doc() to be absent. What makes the second -doc()
> be bound to function? The extra line directly above it
> certainly makes it so for humans, but it shouldn't be
> relied upon formally.
>
> Perhaps (I live motivation outside this email), something like this?
>
>         -module(test).
>         -doc("Math module with some fancy math functions.").
>         -keywords([math, fancy, factorial]).
>         -export([fac/1].
>
>         -fun(doc, "The factorial function.").
>         -fun(keywords, [math]).
>         fac(0) -> 1;
>         fac(N) -> N*fac(N-1)
>
>
> Andreas Hillqvist wrote:
> > You make a good point.
> >
> > So would this look like:
> >      -module(test).
> >      -doc("Math module with some fancy math functions.").
> >      -keywords([math, fancy, factorial]).
> >      -export([fac/1].
> >
> >      -doc("The factorial function, for they day you will need it.").
> >      -keywords([math]).
> >      fac(0) -> 1;
> >      fac(N) -> N*fac(N-1)
> >
> > I believe Erlang supports multiple occurrences, example a hlr is
> > expanded by the pre-parser to:
> >      -file("/xxx/yyy/zzz.hrl", 1).
> >      -hrl_id(aaa).
> >      -hrl_vsn(bbb).
> >      -hrl_date(ccc).
> >      -hrl_author(ddd).
> >
> >      foo() -> bar.
> >
> > Where hlr headers seems to be prefixed with hlr. So to differentiate
> > module level headers from function level we may use the "fun_" prefix
> > on atoms:
> >      -module(test).
> >      -doc("Math module with some fancy math functions.").
> >      -keywords([math, fancy, factorial]).
> >      -export([fac/1].
> >
> >      -fun_doc("The factorial function, for they day you will need it.").
> >      -fun_keywords([math]).
> >      fac(0) -> 1;
> >      fac(N) -> N*fac(N-1)
> >
> >
> > Just my ideas/suggestions, pleas feel free to criticize.
> >    ;-)
> >
> >
> > Regards
> > Andreas Hillqvist
> >
> > 2007/11/15, Lev Walkin <vlm@REDACTED>:
> >> One of the most peculiar problems people have with certain languages
> >> (Objective-C) is that punctuation and non-alphabetical characters
> >> are overloaded beyond all reason. +module, -interface, @end, etc.
> >>
> >> We risk ending up with something like
> >>
> >> -module(test).
> >> +module(test).
> >> @module(test).
> >>
> >> where module is a keyword in one place and atom in another. Having
> >> more or less uniform "-<keyword>(<value>)." is arguably more
> >> self-consistent and removes unnecessary learning curve.
> >>
> >> Just 2c.
> >>
> >> Andreas Hillqvist wrote:
> >>> I like the Idea of function meta data.
> >>>
> >>> But it might be better/simpler/easier/harder to use an alternativ
> >>> prefix, like double -- (Similar to %, %% and %%%).
> >>>
> >>> Why not use the name atom instead of meta?
> >>> To me meta dose not contribute with value to the syntax.
> >>>
> >>> Would look like:
> >>>
> >>>     -module(test).
> >>>     -export([fac/1].
> >>>
> >>>     --doc("the factorial function").
> >>>     --type("int -> int").
> >>>     --keywords([math]).
> >>>     fac(0) -> 1;
> >>>     fac(N) -> N*fac(N-1)
> >>>
> >>> Or some other prefix like "+"(Just an example, Do not like + myself.
> >>> To much alike the udiff format. ;-)?
> >>>     -module(test).
> >>>     -export([fac/1].
> >>>
> >>>     +doc("the factorial function").
> >>>     +type("int -> int").
> >>>     +keywords([math]).
> >>>
> >>>     fac(0) -> 1;
> >>>     fac(N) -> N*fac(N-1)
> >>>
> >>>
> >>> Regards
> >>> Andreas Hillqvist
> >>>
> >>> 2007/11/15, Joe Armstrong <erlang@REDACTED>:
> >>>> Module have metadata  Mod:module_info(export) etc.
> >>>>
> >>>> But functions do not.
> >>>>
> >>>> idea - attach function meta data with a new attribute.
> >>>>
> >>>>      -meta(doc, "the factorial function").
> >>>>      -meta(type, "int -> int").
> >>>>      -meta(keywords, [math]).
> >>>>
> >>>>      fac(0) -> 1;
> >>>>      fac(N) -> N*fac(N-1)
> >>>>
> >>>> The meta data gets *attached* to the Next function in the module
> >>>>
> >>>>     -meta(process, true).
> >>>>     foo() -> spawn(fun() -> ... end)
> >>>>
> >>>> After compilation meta data can be access as follows:
> >>>>
> >>>>    Mod:meta_data(fac, 1, doc) => "the factorial function"
> >>>>    ...
> >>>>    Mod:meta_data(fac, 1, glurk) => '$nothing'
> >>>>
> >>>> if we then *standardise* the meta data it will be easy to make loads
> >>>> of nice tools for type checking, documentation etc.
> >>>>
> >>>> I'm off on a trip today - so can somebody hack the preprocess and
> >>>> parser to do this? (( this needs a small change
> >>>> attributes have a different syntax and must be at *before* all functions))
> >>>>
> >>>> This adds introspection to the language !
> >>>>
> >>>> /Joe Armstrong
> >>>> _______________________________________________
> >>>> erlang-questions mailing list
> >>>> erlang-questions@REDACTED
> >>>> http://www.erlang.org/mailman/listinfo/erlang-questions
> >>>>
> >>> _______________________________________________
> >>> erlang-questions mailing list
> >>> erlang-questions@REDACTED
> >>> http://www.erlang.org/mailman/listinfo/erlang-questions
> >>
>
>