File 4191-Document-epp-scan_erl_form-1-and-add-epp-s... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 4191-Document-epp-scan_erl_form-1-and-add-epp-scan_file-2.patch of Package erlang (Revision 38489c07175b7fbd451db8f53462a958)

Currently displaying revision 38489c07175b7fbd451db8f53462a958 , Show latest

From 81bce85477dea8ab3eb219130370458c9cae6a1d Mon Sep 17 00:00:00 2001
From: Richard Carlsson <carlsson.richard@gmail.com>
Date: Fri, 12 Jun 2020 12:47:42 +0200
Subject: [PATCH] Document epp:scan_erl_form/1 and add epp:scan_file/2

---
 lib/stdlib/doc/src/epp.xml    | 30 ++++++++++++++++++++++-
 lib/stdlib/src/epp.erl        | 46 ++++++++++++++++++++++++++++++++++-
 lib/stdlib/src/erl_scan.erl   |  2 +-
 lib/stdlib/test/epp_SUITE.erl | 19 +++++++++++++--
 4 files changed, 92 insertions(+), 5 deletions(-)

diff --git a/lib/stdlib/doc/src/epp.xml b/lib/stdlib/doc/src/epp.xml
index 1c5fefe559..6cd715c55c 100644
--- a/lib/stdlib/doc/src/epp.xml
+++ b/lib/stdlib/doc/src/epp.xml
@@ -72,6 +72,9 @@
 <datatype>
 <name name="source_encoding"></name>
 </datatype>
+ <datatype>
+ <name name="warning_info"></name>
+ </datatype>
 </datatypes>
 
 <funcs>
@@ -160,7 +163,6 @@
 <name name="parse_erl_form" arity="1" since=""/>
 <fsummary>Return the next Erlang form from the opened Erlang source file.
 </fsummary>
- <type name="warning_info"/>
 <desc>
 Returns the next Erlang form from the opened Erlang source file.
 Tuple <c>{eof, <anno>Line</anno>}</c> is returned at the end of the
@@ -229,6 +231,32 @@
 </desc>
 </func>
 
+ <func>
+ <name name="scan_erl_form" arity="1" since="OTP R13B03"/>
+ <fsummary>Return the raw tokens of the next Erlang form from the opened
+ Erlang source file.</fsummary>
+ <desc>
+ Returns the raw tokens of the next Erlang form from the opened
+ Erlang source file. A tuple <c>{eof, Line}</c> is
+ returned at the end of the file. The first form corresponds to an
+ implicit attribute <c>-file(File,1).</c>, where <c>File</c> is the
+ file name.
+ </desc>
+ </func>
+
+ <func>
+ <name name="scan_file" arity="2" since="OTP 24.0"/>
+ <fsummary>Preprocess an Erlang source file, returning raw tokens.</fsummary>
+ <desc>
+ Preprocesses an Erlang source file returning a list of the lists
+ of raw tokens of each form.
+ Notice that the tuple <c>{eof, Line}</c> returned at the
+ end of the file is included as a "form", and any failures to scan a
+ form are included in the list as tuples <c>{error,
+ <anno>ErrorInfo</anno>}</c>.
+ </desc>
+ </func>
+
 <func>
 <name name="set_encoding" arity="1" since="OTP R16B"/>
 <fsummary>Read and set the encoding of an I/O device.</fsummary>
diff --git a/lib/stdlib/src/epp.erl b/lib/stdlib/src/epp.erl
index b390697a56..1ec3307dbd 100644
--- a/lib/stdlib/src/epp.erl
+++ b/lib/stdlib/src/epp.erl
@@ -23,7 +23,7 @@
 
 -export([open/1, open/2,open/3,open/5,close/1,format_error/1]).
 -export([scan_erl_form/1,parse_erl_form/1,macro_defs/1]).
--export([parse_file/1, parse_file/2, parse_file/3]).
+-export([scan_file/1, scan_file/2, parse_file/1, parse_file/2, parse_file/3]).
 -export([default_encoding/0, encoding_to_string/1,
 read_encoding_from_binary/1, read_encoding_from_binary/2,
 set_encoding/1, set_encoding/2, read_encoding/1, read_encoding/2]).
@@ -82,6 +82,8 @@
 %% close(Epp)
 %% scan_erl_form(Epp)
 %% parse_erl_form(Epp)
+%% scan_file(Epp)
+%% scan_file(FileName, Options)
 %% parse_file(Epp)
 %% parse_file(FileName, Options)
 %% parse_file(FileName, IncludePath, PreDefMacros)
@@ -151,6 +153,15 @@ close(Epp) ->
 receive {'DOWN',Ref,_,_,_} -> ok end,
 R.
 
+-spec scan_erl_form(Epp) ->
+ {'ok', Tokens} | {error, ErrorInfo} |
+ {'warning',WarningInfo} | {'eof',Line} when
+ Epp :: epp_handle(),
+ Tokens :: erl_scan:tokens(),
+ Line :: erl_anno:line(),
+ ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
+ WarningInfo :: warning_info().
+
 scan_erl_form(Epp) ->
 epp_request(Epp, scan_erl_form).
 
@@ -230,6 +241,39 @@ format_error({warning,Term}) ->
 io_lib:format("-warning(~tp).", [Term]);
 format_error(E) -> file:format_error(E).
 
+-spec scan_file(FileName, Options) ->
+ {'ok', [Form], Extra} | {error, OpenError} when
+ FileName :: file:name(),
+ Options :: [{'includes', IncludePath :: [DirectoryName :: file:name()]} |
+		 {'source_name', SourceName :: file:name()} |
+		 {'macros', PredefMacros :: macros()} |
+		 {'default_encoding', DefEncoding :: source_encoding()}],
+ Form :: erl_scan:tokens() | {'error', ErrorInfo} | {'eof', Loc},
+ Loc :: erl_anno:location(),
+ ErrorInfo :: erl_scan:error_info(),
+ Extra :: [{'encoding', source_encoding() | 'none'}],
+ OpenError :: file:posix() | badarg | system_limit.
+
+scan_file(Ifile, Options) ->
+ case open([{name, Ifile}, extra | Options]) of
+	{ok,Epp,Extra} ->
+	 Forms = scan_file(Epp),
+	 close(Epp),
+	 {ok,Forms,Extra};
+	{error,E} ->
+	 {error,E}
+ end.
+
+scan_file(Epp) ->
+ case scan_erl_form(Epp) of
+	{ok,Toks} ->
+ [Toks|scan_file(Epp)];
+	{error,E} ->
+	 [{error,E}|scan_file(Epp)];
+	{eof,Location} ->
+	 [{eof,Location}]
+ end.
+
 -spec parse_file(FileName, IncludePath, PredefMacros) ->
 {'ok', [Form]} | {error, OpenError} when
 FileName :: file:name(),
diff --git a/lib/stdlib/src/erl_scan.erl b/lib/stdlib/src/erl_scan.erl
index 312b040002..0fe242220f 100644
--- a/lib/stdlib/src/erl_scan.erl
+++ b/lib/stdlib/src/erl_scan.erl
@@ -63,7 +63,7 @@
 -export_type([error_info/0,
 options/0,
 return_cont/0,
- token/0,
+ token/0, tokens/0,
 tokens_result/0]).
 
 %% Removed functions and types
diff --git a/lib/stdlib/test/epp_SUITE.erl b/lib/stdlib/test/epp_SUITE.erl
index 81457863ab..572c719417 100644
--- a/lib/stdlib/test/epp_SUITE.erl
+++ b/lib/stdlib/test/epp_SUITE.erl
@@ -29,7 +29,7 @@
 otp_8562/1, otp_8665/1, otp_8911/1, otp_10302/1, otp_10820/1,
 otp_11728/1, encoding/1, extends/1, function_macro/1,
 	 test_error/1, test_warning/1, otp_14285/1,
-	 test_if/1,source_name/1,otp_16978/1,file_macro/1]).
+	 test_if/1,source_name/1,otp_16978/1,scan_file/1,file_macro/1]).
 
 -export([epp_parse_erl_form/2]).
 
@@ -70,7 +70,7 @@ all() ->
 overload_mac, otp_8388, otp_8470, otp_8562,
 otp_8665, otp_8911, otp_10302, otp_10820, otp_11728,
 encoding, extends, function_macro, test_error, test_warning,
- otp_14285, test_if, source_name, otp_16978, file_macro].
+ otp_14285, test_if, source_name, otp_16978, scan_file, file_macro].
 
 groups() ->
 [{upcase_mac, [], [upcase_mac_1, upcase_mac_2]},
@@ -842,6 +842,21 @@ otp_8130(Config) when is_list(Config) ->
 
 ok.
 
+scan_file(Config) when is_list(Config) ->
+ DataDir = proplists:get_value(data_dir, Config),
+ File = filename:join(DataDir, "source_name.erl"),
+
+ {ok, Toks, [{encoding, _}]} = epp:scan_file(File, []),
+ [FileForm1, ModuleForm, ExportForm,
+ FileForm2, FileForm3, FunctionForm,
+ {eof,_}] = Toks,
+ [{'-',_}, {atom,_,file}, {'(',_} | _ ] = FileForm1,
+ [{'-',_}, {atom,_,module}, {'(',_} | _ ] = ModuleForm,
+ [{'-',_}, {atom,_,export}, {'(',_} | _ ] = ExportForm,
+ [{'-',_}, {atom,_,file}, {'(',_} | _ ] = FileForm2,
+ [{'-',_}, {atom,_,file}, {'(',_} | _ ] = FileForm3,
+ ok.
+
 macs(Epp) ->
 Macros = epp:macro_defs(Epp), % not documented
 lists:sort([MName || {{atom,MName},_} <- Macros]).
-- 
2.26.2

Places

File 4191-Document-epp-scan_erl_form-1-and-add-epp-scan_file-2.patch of Package erlang (Revision 38489c07175b7fbd451db8f53462a958)

Places