The R13B03 release.OTP_R13B03

1 files changed, 423 insertions, 0 deletions

diff --git a/lib/edoc/src/edoc_parser.yrl b/lib/edoc/src/edoc_parser.yrl
new file mode 100644
index 0000000000..0eea8ae66f
--- /dev/null
+++ b/lib/edoc/src/edoc_parser.yrl
@@ -0,0 +1,423 @@
+%% ========================== -*-Erlang-*- =============================
+%% EDoc type specification grammar for the Yecc parser generator,
+%% adapted from Sven-Olof Nystr�m's type specification parser.
+%%
+%% Also contains entry points for parsing things like typedefs,
+%% references, and throws-declarations.
+%%
+%% Copyright (C) 2002-2005 Richard Carlsson
+%%
+%% This library is free software; you can redistribute it and/or modify
+%% it under the terms of the GNU Lesser General Public License as
+%% published by the Free Software Foundation; either version 2 of the
+%% License, or (at your option) any later version.
+%%
+%% This library is distributed in the hope that it will be useful, but
+%% WITHOUT ANY WARRANTY; without even the implied warranty of
+%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+%% Lesser General Public License for more details.
+%%
+%% You should have received a copy of the GNU Lesser General Public
+%% License along with this library; if not, write to the Free Software
+%% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+%% USA
+%%
+%% Author contact: [email protected]
+%%
+%% $Id$
+%%
+%% =====================================================================
+
+Nonterminals
+start spec func_type utype_list utype_tuple utypes utype ptypes ptype
+nutype function_name where_defs defs def typedef etype throws qname ref
+aref mref lref pref var_list vars fields field.
+
+Terminals
+atom float integer var string start_spec start_typedef start_throws
+start_ref
+
+'(' ')' ',' '.' '->' '{' '}' '[' ']' '|' '+' ':' '::' '=' '/' '//' '*'
+'#' 'where'.
+
+Rootsymbol start.
+
+start -> start_spec spec: '$2'.
+start -> start_throws throws: '$2'.
+start -> start_typedef typedef: '$2'.
+start -> start_ref ref: '$2'.
+
+%% Produced in reverse order.
+qname -> atom: [tok_val('$1')].
+qname -> qname '.' atom: [tok_val('$3') | '$1'].
+
+spec -> func_type where_defs:
+    #t_spec{type = '$1', defs = lists:reverse('$2')}.
+spec -> function_name func_type where_defs:
+    #t_spec{name = '$1', type = '$2', defs = lists:reverse('$3')}.
+
+where_defs -> 'where' defs: '$2'.
+where_defs -> defs: '$1'.
+
+function_name -> atom: #t_name{name = tok_val('$1')}.
+
+func_type -> utype_list '->' utype:
+    #t_fun{args = element(1, '$1'), range = '$3'}.
+
+
+%% Paired with line number, for later error reporting
+utype_list -> '(' ')' : {[], tok_line('$1')}.
+utype_list -> '(' utypes ')' : {lists:reverse('$2'), tok_line('$1')}.
+
+utype_tuple -> '{' '}' : [].
+utype_tuple -> '{' utypes '}' : lists:reverse('$2').
+
+%% Produced in reverse order.
+utypes -> utype : ['$1'].
+utypes -> utypes ',' utype : ['$3' | '$1'].
+
+utype -> nutype string: annotate('$1', tok_val('$2')).
+utype -> nutype: '$1'.
+
+nutype -> var '::' ptypes: annotate(union('$3'), tok_val('$1')).
+nutype -> ptypes: union('$1').
+
+%% Produced in reverse order.
+ptypes -> ptype : ['$1'].
+ptypes -> ptypes '+' ptype : ['$3' | '$1'].
+ptypes -> ptypes '|' ptype : ['$3' | '$1'].
+
+ptype -> var : #t_var{name = tok_val('$1')}.
+ptype -> atom : #t_atom{val = tok_val('$1')}.
+ptype -> integer: #t_integer{val = tok_val('$1')}.
+ptype -> float: #t_float{val = tok_val('$1')}.
+ptype -> utype_tuple : #t_tuple{types = '$1'}.
+ptype -> '[' ']' : #t_nil{}.
+ptype -> '[' utype ']' : #t_list{type = '$2'}.
+ptype -> utype_list:
+	if length(element(1, '$1')) == 1 -> 
+		%% there must be exactly one utype in the list
+		hd(element(1, '$1'));
+	   length(element(1, '$1')) == 0 ->
+		return_error(element(2, '$1'), "syntax error before: ')'");
+	   true ->
+		return_error(element(2, '$1'), "syntax error before: ','")
+	end.
+ptype -> utype_list '->' ptype:
+	#t_fun{args = element(1, '$1'), range = '$3'}.
+ptype -> '#' atom '{' '}' :
+        #t_record{name = #t_atom{val = tok_val('$2')}}.
+ptype -> '#' atom '{' fields '}' :
+	#t_record{name = #t_atom{val = tok_val('$2')},
+		  fields = lists:reverse('$4')}.
+ptype -> atom utype_list:
+	#t_type{name = #t_name{name = tok_val('$1')},
+		args = element(1, '$2')}.
+ptype -> qname ':' atom utype_list : 
+	#t_type{name = #t_name{module = qname('$1'),
+			       name = tok_val('$3')},
+		args = element(1, '$4')}.
+ptype -> '//' atom '/' qname ':' atom utype_list : 
+	#t_type{name = #t_name{app = tok_val('$2'),
+			       module = qname('$4'),
+			       name = tok_val('$6')},
+		args = element(1, '$7')}.
+
+%% Produced in reverse order.
+fields -> field : ['$1'].
+fields -> fields ',' field : ['$3' | '$1'].
+
+field -> atom '=' utype :
+	#t_field{name = #t_atom{val = tok_val('$1')}, type = '$3'}.
+
+%% Produced in reverse order.
+defs -> '$empty' : [].
+defs -> defs def : ['$2' | '$1'].
+defs -> defs ',' def : ['$3' | '$1'].
+
+def -> var '=' utype:
+       #t_def{name =  #t_var{name = tok_val('$1')},
+	      type = '$3'}.
+def -> atom var_list '=' utype:
+       #t_def{name = #t_type{name = #t_name{name = tok_val('$1')},
+			     args = '$2'},
+	      type = '$4'}.
+
+var_list -> '(' ')' : [].
+var_list -> '(' vars ')' : lists:reverse('$2').
+
+%% Produced in reverse order.
+vars -> var : [#t_var{name = tok_val('$1')}].
+vars -> vars ',' var : [#t_var{name = tok_val('$3')} | '$1'].
+
+typedef -> atom var_list where_defs:
+       #t_typedef{name = #t_name{name = tok_val('$1')},
+		  args = '$2',
+		  defs = lists:reverse('$3')}.
+typedef -> atom var_list '=' utype where_defs:
+       #t_typedef{name = #t_name{name = tok_val('$1')},
+		  args = '$2',
+		  type = '$4',
+		  defs = lists:reverse('$5')}.
+
+%% References
+
+ref -> aref: '$1'.
+ref -> mref: '$1'.
+ref -> lref: '$1'.
+ref -> pref: '$1'.
+
+aref -> '//' atom:
+    edoc_refs:app(tok_val('$2')).
+aref -> '//' atom '/' mref:
+    edoc_refs:app(tok_val('$2'), '$4').
+aref -> '//' atom '/' pref:
+    edoc_refs:app(tok_val('$2'), '$4').
+
+mref -> qname ':' atom '/' integer:
+    edoc_refs:function(qname('$1'), tok_val('$3'), tok_val('$5')).
+mref -> qname ':' atom '(' ')':
+    edoc_refs:type(qname('$1'), tok_val('$3')).
+mref -> qname:
+    edoc_refs:module(qname('$1')).
+
+pref -> qname '.' '*':
+    edoc_refs:package(qname('$1')).
+
+lref -> atom '/' integer:
+    edoc_refs:function(tok_val('$1'), tok_val('$3')).
+lref -> atom '(' ')':
+    edoc_refs:type(tok_val('$1')).
+
+%% Exception declarations
+
+etype -> utype: '$1'.
+
+throws -> etype where_defs:
+	#t_throws{type = '$1',
+		  defs = lists:reverse('$2')}.
+
+%% (commented out for now)
+%% Header
+%% "%% ========================== -*-Erlang-*- ============================="
+%% "%% EDoc function specification parser, generated from the file"
+%% "%% \"edoc_parser.yrl\" by the Yecc parser generator."
+%% "%%"
+%% "%% Copyright (C) 2002-2005 Richard Carlsson"
+%% "%%"
+%% "%% This library is free software; you can redistribute it and/or modify"
+%% "%% it under the terms of the GNU Lesser General Public License as"
+%% "%% published by the Free Software Foundation; either version 2 of the"
+%% "%% License, or (at your option) any later version."
+%% "%%"
+%% "%% This library is distributed in the hope that it will be useful, but"
+%% "%% WITHOUT ANY WARRANTY; without even the implied warranty of"
+%% "%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU"
+%% "%% Lesser General Public License for more details."
+%% "%%"
+%% "%% You should have received a copy of the GNU Lesser General Public"
+%% "%% License along with this library; if not, write to the Free Software"
+%% "%% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307"
+%% "%% USA"
+%% "%%"
+%% "%% @private"
+%% "%% @author Richard Carlsson <[email protected]>"
+%% "%% ===================================================================="
+%% .
+
+Erlang code.
+
+%% ========================== -*-Erlang-*- =============================
+%% EDoc function specification parser, generated from the file
+%% "edoc_parser.yrl" by the Yecc parser generator.
+%%
+%% Copyright (C) 2002-2005 Richard Carlsson
+%%
+%% This library is free software; you can redistribute it and/or modify
+%% it under the terms of the GNU Lesser General Public License as
+%% published by the Free Software Foundation; either version 2 of the
+%% License, or (at your option) any later version.
+%%
+%% This library is distributed in the hope that it will be useful, but
+%% WITHOUT ANY WARRANTY; without even the implied warranty of
+%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+%% Lesser General Public License for more details.
+%%
+%% You should have received a copy of the GNU Lesser General Public
+%% License along with this library; if not, write to the Free Software
+%% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+%% USA
+%% ====================================================================
+
+-export([parse_spec/2, parse_typedef/2, parse_throws/2, parse_ref/2,
+	 parse_see/2, parse_param/2]).
+
+-include("edoc_types.hrl").
+
+%% Multiple entry point hack:
+
+start_spec(Ts, L) -> run_parser(Ts, L, start_spec).
+
+start_typedef(Ts, L) -> run_parser(Ts, L, start_typedef).
+
+start_throws(Ts, L) -> run_parser(Ts, L, start_throws).
+
+start_ref(Ts, L) -> run_parser(Ts, L, start_ref).
+
+%% Error reporting fix
+
+run_parser(Ts, L, Start) ->
+    case parse([{Start,L} | Ts]) of
+	{error, {999999,?MODULE,_}} ->
+	    What = case Start of
+		       start_spec -> "specification";
+		       start_typedef -> "type definition";
+		       start_throws -> "exception declaration";
+		       start_ref -> "reference"
+		   end,
+	    {error, {L,?MODULE,["unexpected end of ", What]}};
+	Other -> Other
+    end.
+
+%% Utility functions:
+
+tok_val(T) -> element(3, T).
+
+tok_line(T) -> element(2, T).
+
+qname([A]) ->
+    A;    % avoid unnecessary call to packages:concat/1.
+qname(List) ->
+    list_to_atom(packages:concat(lists:reverse(List))).
+
+union(Ts) ->
+    case Ts of
+	[T] -> T;
+	_ -> #t_union{types = lists:reverse(Ts)}
+    end.
+
+annotate(T, A) -> ?add_t_ann(T, A).
+    
+%% ---------------------------------------------------------------------
+
+%% @doc EDoc type specification parsing. Parses the content of
+%% <a href="overview-summary.html#ftag-spec">`@spec'</a> declarations.
+
+parse_spec(S, L) ->
+    case edoc_scanner:string(S, L) of
+	{ok, Ts, _} ->
+	    case start_spec(Ts, L) of
+		{ok, Spec} ->
+		    Spec;
+		{error, E} ->
+		    throw_error(E, L)
+	    end;
+	{error, E, _} ->
+	    throw_error(E, L)
+    end.
+
+%% ---------------------------------------------------------------------
+
+%% @doc EDoc type definition parsing. Parses the content of
+%% <a href="overview-summary.html#gtag-type">`@type'</a> declarations.
+
+parse_typedef(S, L) ->
+    {S1, S2} = edoc_lib:split_at_stop(S),
+    N = edoc_lib:count($\n, S1),
+    L1 = L + N,
+    Text = edoc_lib:strip_space(S2),
+    {parse_typedef_1(S1, L), edoc_wiki:parse_xml(Text, L1)}.
+
+parse_typedef_1(S, L) ->
+    case edoc_scanner:string(S, L) of
+	{ok, Ts, _} ->
+	    case start_typedef(Ts, L) of
+		{ok, T} ->
+		    T;
+		{error, E} ->
+		    throw_error({parse_typedef, E}, L)
+	    end;
+	{error, E, _} ->
+	    throw_error({parse_typedef, E}, L)
+    end.
+
+%% ---------------------------------------------------------------------
+
+%% @doc Parses a <a
+%% href="overview-summary.html#References">reference</a> to a module,
+%% package, function, type, or application
+
+parse_ref(S, L) ->
+    case edoc_scanner:string(S, L) of
+	{ok, Ts, _} ->
+	    case start_ref(Ts, L) of
+		{ok, T} ->
+		    T;
+		{error, E} ->
+		    throw_error({parse_ref, E}, L)
+	    end;
+	{error, E, _} ->
+	    throw_error({parse_ref, E}, L)
+    end.
+
+%% ---------------------------------------------------------------------
+
+%% @doc Parses the content of
+%% <a href="overview-summary.html#ftag-see">`@see'</a> references.
+parse_see(S, L) ->
+    {S1, S2} = edoc_lib:split_at_stop(S),
+    N = edoc_lib:count($\n, S1),
+    L1 = L + N,
+    Text = edoc_lib:strip_space(S2),
+    {parse_ref(S1, L), edoc_wiki:parse_xml(Text, L1)}.
+
+%% ---------------------------------------------------------------------
+
+%% @doc Parses the content of
+%% <a href="overview-summary.html#ftag-param">`@param'</a> tags.
+parse_param(S, L) ->
+    {S1, S2} = edoc_lib:split_at_space(edoc_lib:strip_space(S)),
+    case edoc_lib:strip_space(S1) of
+	"" -> throw_error(parse_param, L);
+	Name -> 
+	    Text = edoc_lib:strip_space(S2),
+	    {list_to_atom(Name), edoc_wiki:parse_xml(Text, L)}
+    end.
+
+%% ---------------------------------------------------------------------
+
+%% @doc EDoc exception specification parsing. Parses the content of
+%% <a href="overview-summary.html#ftag-throws">`@throws'</a> declarations.
+
+parse_throws(S, L) ->
+    case edoc_scanner:string(S, L) of
+	{ok, Ts, _} ->
+	    case start_throws(Ts, L) of
+		{ok, Spec} ->
+		    Spec;
+		{error, E} ->
+		    throw_error({parse_throws, E}, L)
+	    end;
+	{error, E, _} ->
+	    throw_error({parse_throws, E}, L)
+    end.
+
+%% ---------------------------------------------------------------------
+
+throw_error({L, M, D}, _L0) ->
+    throw({error,L,{format_error,M,D}});
+throw_error({parse_spec, E}, L) ->
+    throw_error({"specification", E}, L);
+throw_error({parse_typedef, E}, L) ->
+    throw_error({"type definition", E}, L);
+throw_error({parse_ref, E}, L) ->
+    throw_error({"reference", E}, L);
+throw_error({parse_throws, E}, L) ->
+    throw_error({"throws-declaration", E}, L);
+throw_error(parse_param, L) ->
+    throw({error, L, "missing parameter name"});
+throw_error({Where, E}, L) when is_list(Where) ->
+    throw({error,L,{"unknown error parsing ~s: ~P.",[Where,E,15]}});
+throw_error(E, L) ->
+    %% Just in case.
+    throw({error,L,{"unknown parse error: ~P.",[E,15]}}).