1
%% =====================================================================
2
%% This library is free software; you can redistribute it and/or modify
3
%% it under the terms of the GNU Lesser General Public License as
4
%% published by the Free Software Foundation; either version 2 of the
5
%% License, or (at your option) any later version.
7
%% This library is distributed in the hope that it will be useful, but
8
%% WITHOUT ANY WARRANTY; without even the implied warranty of
9
%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10
%% Lesser General Public License for more details.
12
%% You should have received a copy of the GNU Lesser General Public
13
%% License along with this library; if not, write to the Free Software
14
%% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
19
%% @copyright 2003 Richard Carlsson
20
%% @author Richard Carlsson <richardc@csd.uu.se>
23
%% =====================================================================
25
%% @doc Interface for calling EDoc from Erlang startup options.
27
%% The following is an example of typical usage in a Makefile:
29
%% erl -noshell -run edoc_run application "'$(APP_NAME)'" \
30
%% '"."' '[{def,{vsn,"$(VSN)"}}]'
32
%% (note the single-quotes to avoid shell expansion, and the
33
%% double-quotes enclosing the strings).
35
%% <strong>New feature in version 0.6.9</strong>: It is no longer
36
%% necessary to write `-s init stop' last on the command line in order
37
%% to make the execution terminate. The termination (signalling success
38
%% or failure to the operating system) is now built into these
43
-export([file/1, application/1, packages/1, files/1, toc/1]).
45
-import(edoc_report, [report/2, error/1]).
48
%% @spec application([string()]) -> none()
50
%% @doc Calls {@link edoc:application/3} with the corresponding
51
%% arguments. The strings in the list are parsed as Erlang constant
52
%% terms. The list can be either `[App]', `[App, Options]' or `[App,
53
%% Dir, Options]'. In the first case {@link edoc:application/1} is
54
%% called instead; in the second case, {@link edoc:application/2} is
57
%% The function call never returns; instead, the emulator is
58
%% automatically terminated when the call has completed, signalling
59
%% success or failure to the operating system.
63
case parse_args(Args) of
64
[App] -> edoc:application(App);
65
[App, Opts] -> edoc:application(App, Opts);
66
[App, Dir, Opts] -> edoc:application(App, Dir, Opts);
68
invalid_args("edoc_run:application/1", Args)
73
%% @spec files([string()]) -> none()
75
%% @doc Calls {@link edoc:files/2} with the corresponding arguments. The
76
%% strings in the list are parsed as Erlang constant terms. The list can
77
%% be either `[Files]' or `[Files, Options]'. In the first case, {@link
78
%% edoc:files/1} is called instead.
80
%% The function call never returns; instead, the emulator is
81
%% automatically terminated when the call has completed, signalling
82
%% success or failure to the operating system.
86
case parse_args(Args) of
87
[Files] -> edoc:files(Files);
88
[Files, Opts] -> edoc:files(Files, Opts);
90
invalid_args("edoc_run:files/1", Args)
95
%% @spec packages([string()]) -> none()
97
%% @doc Calls {@link edoc:application/2} with the corresponding
98
%% arguments. The strings in the list are parsed as Erlang constant
99
%% terms. The list can be either `[Packages]' or `[Packages, Options]'.
100
%% In the first case {@link edoc:application/1} is called instead.
102
%% The function call never returns; instead, the emulator is
103
%% automatically terminated when the call has completed, signalling
104
%% success or failure to the operating system.
108
case parse_args(Args) of
109
[Packages] -> edoc:packages(Packages);
110
[Packages, Opts] -> edoc:packages(Packages, Opts);
112
invalid_args("edoc_run:packages/1", Args)
117
%% @hidden Not official yet
120
case parse_args(Args) of
121
[Dir, Paths] -> edoc:toc(Dir,Paths);
122
[Dir, Paths, Opts] -> edoc:toc(Dir,Paths,Opts);
124
invalid_args("edoc_run:toc/1", Args)
130
%% @spec file([string()]) -> none()
132
%% @deprecated This is part of the old interface to EDoc and is mainly
133
%% kept for backwards compatibility. The preferred way of generating
134
%% documentation is through one of the functions {@link application/1},
135
%% {@link packages/1} and {@link files/1}.
137
%% @doc Calls {@link edoc:file/2} with the corresponding arguments. The
138
%% strings in the list are parsed as Erlang constant terms. The list can
139
%% be either `[File]' or `[File, Options]'. In the first case, an empty
140
%% list of options is passed to {@link edoc:file/2}.
142
%% The following is an example of typical usage in a Makefile:
143
%% ```$(DOCDIR)/%.html:%.erl
144
%% erl -noshell -run edoc_run file '"$<"' '[{dir,"$(DOCDIR)"}]' \
147
%% The function call never returns; instead, the emulator is
148
%% automatically terminated when the call has completed, signalling
149
%% success or failure to the operating system.
153
case parse_args(Args) of
154
[File] -> edoc:file(File, []);
155
[File, Opts] -> edoc:file(File, Opts);
157
invalid_args("edoc_run:file/1", Args)
162
invalid_args(Where, Args) ->
163
report("invalid arguments to ~s: ~w.", [Where, Args]),
168
case catch {ok, F()} of
172
report("edoc terminated abnormally: ~P.", [E, 10]),
175
report("internal error: throw without catch in edoc: ~P.",
181
case erlang:whereis(code_server) of
189
%% When and if a function init:stop/1 becomes generally available, we
190
%% can use that instead of delay-and-pray when there is an error.
193
%% shut down emulator nicely, signalling "normal termination"
196
%% delay 1 second to allow I/O to finish
197
receive after 1000 -> ok end,
198
%% stop emulator the hard way with a nonzero exit value
201
parse_args([A | As]) when atom(A) ->
202
[parse_arg(atom_to_list(A)) | parse_args(As)];
203
parse_args([A | As]) ->
204
[parse_arg(A) | parse_args(As)];
209
case catch {ok, edoc_lib:parse_expr(A, 1)} of
211
case catch erl_parse:normalise(Expr) of
213
report("bad argument: '~s':", [A]),
219
report("error parsing argument '~s'", [A]),