Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
home:Ledest:erlang:23
erlang
0189-parsetools-Use-types-and-specs-for-documen...
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
File 0189-parsetools-Use-types-and-specs-for-documentation.patch of Package erlang
From f673f30f37627eefc5367cba1baa0a037c43dfb6 Mon Sep 17 00:00:00 2001 From: Hans Bolinder <hasse@erlang.org> Date: Mon, 2 Nov 2020 11:52:22 +0100 Subject: [PATCH 1/2] parsetools: Use types and specs for documentation --- lib/parsetools/doc/specs/.gitignore | 1 + lib/parsetools/doc/src/Makefile | 2 + lib/parsetools/doc/src/leex.xml | 102 +++++++++++----------- lib/parsetools/doc/src/specs.xml | 5 ++ lib/parsetools/doc/src/yecc.xml | 126 ++++++++++++++-------------- lib/parsetools/src/leex.erl | 36 +++++++- lib/parsetools/src/yecc.erl | 37 +++++++- 7 files changed, 190 insertions(+), 119 deletions(-) create mode 100644 lib/parsetools/doc/specs/.gitignore create mode 100644 lib/parsetools/doc/src/specs.xml diff --git a/lib/parsetools/doc/specs/.gitignore b/lib/parsetools/doc/specs/.gitignore new file mode 100644 index 0000000000..322eebcb06 --- /dev/null +++ b/lib/parsetools/doc/specs/.gitignore @@ -0,0 +1 @@ +specs_*.xml diff --git a/lib/parsetools/doc/src/Makefile b/lib/parsetools/doc/src/Makefile index a4d7d4381b..bbf84c9c06 100644 --- a/lib/parsetools/doc/src/Makefile +++ b/lib/parsetools/doc/src/Makefile @@ -43,6 +43,8 @@ XML_FILES = \ $(BOOK_FILES) $(XML_CHAPTER_FILES) \ $(XML_PART_FILES) $(XML_REF3_FILES) $(XML_APPLICATION_FILES) +TOP_SPECS_FILE = specs.xml + IMAGE_FILES = XML_HTML_FILES = \ diff --git a/lib/parsetools/doc/src/leex.xml b/lib/parsetools/doc/src/leex.xml index 9bfc5cf0af..1de5b94eea 100644 --- a/lib/parsetools/doc/src/leex.xml +++ b/lib/parsetools/doc/src/leex.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2009</year><year>2019</year> + <year>2009</year><year>2020</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -29,32 +29,27 @@ <note><p>The Leex module should be considered experimental as it will be subject to changes in future releases.</p></note> </description> - <section> - <title>DATA TYPES</title> - <code type="none"> -ErrorInfo = {ErrorLine,module(),error_descriptor()} -ErrorLine = integer() -Token = tuple()</code> - </section> + + <datatypes> + <datatype> + <name name="error_info"></name> + <desc><p>The standard <c>error_info()</c> structure that is returned + from all I/O modules. <c><anno>ErrorDescriptor</anno></c> is formatable + by <seemfa marker="#format_error/1"><c>format_error/1</c></seemfa>.</p> + </desc> + </datatype> + </datatypes> + <funcs> <func> - <name since="">file(FileName) -> LeexRet</name> - <name since="OTP R16B02">file(FileName, Options) -> LeexRet</name> + <name name="file" arity="1" since=""/> + <name name="file" arity="2" since="OTP R16B02"/> <fsummary>Generate a lexical analyzer</fsummary> - <type> - <v>FileName = filename()</v> - <v>Options = Option | [Option]</v> - <v>Option = - see below -</v> - <v>LeexRet = {ok, Scannerfile} - | {ok, Scannerfile, Warnings} - | error - | {error, Errors, Warnings}</v> - <v>Scannerfile = filename()</v> - <v>Warnings = Errors = [{filename(), [ErrorInfo]}]</v> - <v>ErrorInfo = {ErrorLine, module(), Reason}</v> - <v>ErrorLine = integer()</v> - <v>Reason = - formatable by format_error/1 -</v> - </type> + <type name="leex_ret"/> + <type name="ok_ret"/> + <type name="error_ret"/> + <type name="errors"/> + <type name="warnings"/> <desc> <p>Generates a lexical analyzer from the definition in the input file. The input file has the extension <c>.xrl</c>. This is @@ -68,72 +63,71 @@ Token = tuple()</code> description of the DFA in a format which can be viewed with Graphviz, <c>www.graphviz.com</c>.</p> </item> - <tag><c>{includefile,Includefile}</c></tag> + <tag><c>{includefile,<anno>Includefile</anno>}</c></tag> <item><p>Uses a specific or customised prologue file instead of default <c>lib/parsetools/include/leexinc.hrl</c> which is otherwise included.</p> </item> - <tag><c>{report_errors, bool()}</c></tag> + <tag><c>{report_errors, boolean()}</c></tag> <item><p>Causes errors to be printed as they occur. Default is <c>true</c>.</p> </item> - <tag><c>{report_warnings, bool()}</c></tag> + <tag><c>{report_warnings, boolean()}</c></tag> <item><p>Causes warnings to be printed as they occur. Default is <c>true</c>.</p> </item> - <tag><c>warnings_as_errors</c></tag> - <item> - <p>Causes warnings to be treated as errors.</p> - </item> - <tag><c>{report, bool()}</c></tag> + <tag><c>{report, boolean()}</c></tag> <item><p>This is a short form for both <c>report_errors</c> and <c>report_warnings</c>.</p> </item> - <tag><c>{return_errors, bool()}</c></tag> - <item><p>If this flag is set, <c>{error, Errors, Warnings}</c> + <tag><c>{return_errors, boolean()}</c></tag> + <item><p>If this flag is set, + <c>{error, <anno>Errors</anno>, <anno>Warnings</anno>}</c> is returned when there are errors. Default is <c>false</c>.</p> </item> - <tag><c>{return_warnings, bool()}</c></tag> + <tag><c>{return_warnings, boolean()}</c></tag> <item><p>If this flag is set, an extra field containing - <c>Warnings</c> is added to the tuple returned upon + <c><anno>Warnings</anno></c> is added to the tuple returned upon success. Default is <c>false</c>.</p> </item> - <tag><c>{return, bool()}</c></tag> + <tag><c>{return, boolean()}</c></tag> <item><p>This is a short form for both <c>return_errors</c> and <c>return_warnings</c>.</p> </item> - <tag><c>{scannerfile, Scannerfile}</c></tag> - <item><p><c>Scannerfile</c> is the name of the file that + <tag><c>{scannerfile, <anno>Scannerfile</anno>}</c></tag> + <item><p><c><anno>Scannerfile</anno></c> is the name of the file that will contain the Erlang scanner code that is generated. The default (<c>""</c>) is to add the extension - <c>.erl</c> to <c>FileName</c> stripped of the + <c>.erl</c> to <c><anno>FileName</anno></c> stripped of the <c>.xrl</c> extension.</p> </item> - <tag><c>{verbose, bool()}</c></tag> + <tag><c>{verbose, boolean()}</c></tag> <item><p>Outputs information from parsing the input file and generating the internal tables.</p> </item> + <tag><c>{warnings_as_errors, boolean()}</c></tag> + <item> + <p>Causes warnings to be treated as errors.</p> + </item> </taglist> <p>Any of the Boolean options can be set to <c>true</c> by stating the name of the option. For example, <c>verbose</c> is equivalent to <c>{verbose, true}</c>.</p> <p>Leex will add the extension <c>.hrl</c> to the - <c>Includefile</c> name and the extension <c>.erl</c> to the - <c>Scannerfile</c> name, unless the extension is already + <c><anno>Includefile</anno></c> name and the extension <c>.erl</c> to the + <c><anno>Scannerfile</anno></c> name, unless the extension is already there.</p> </desc> </func> <func> - <name since="">format_error(ErrorInfo) -> Chars</name> - <fsummary>Return an English description of a an error tuple.</fsummary> - <type> - <v>Chars = [char() | Chars]</v> - </type> + <name name="format_error" arity="1" since=""/> + <fsummary>Return an English description of a an error reason.</fsummary> <desc> - <p>Returns a string which describes the error - <c>ErrorInfo</c> returned when there is an error in a - regular expression.</p> + <p>Returns a descriptive string in English of an error reason + <c><anno>ErrorDescriptor</anno></c> returned by + <seemfa marker="#file/1"><c>leex:file/1,2</c></seemfa> + when there is an error in a regular expression.</p> </desc> </func> </funcs> @@ -154,7 +148,7 @@ Token = tuple()</code> <v>String = string()</v> <v>StringRet = {ok,Tokens,EndLine} | ErrorInfo</v> <v>Tokens = [Token]</v> - <v>EndLine = StartLine = integer()</v> + <v>EndLine = StartLine = erl_anno:line()</v> </type> <desc> <p>Scans <c>String</c> and returns all the tokens in it, or an @@ -178,7 +172,7 @@ Token = tuple()</code> <v>TokenRet = {ok, Token, EndLine} | {eof, EndLine} | ErrorInfo</v> - <v>StartLine = EndLine = integer()</v> + <v>StartLine = EndLine = erl_anno:line()</v> </type> <desc> <p>This is a re-entrant call to try and scan one token from @@ -214,7 +208,7 @@ io:request(InFile, {get_until,unicode,Prompt,Module,token,[Line]}) | {eof, EndLine} | ErrorInfo</v> <v>Tokens = [Token]</v> - <v>StartLine = EndLine = integer()</v> + <v>StartLine = EndLine = erl_anno:line()</v> </type> <desc> <p>This is a re-entrant call to try and scan tokens from diff --git a/lib/parsetools/doc/src/specs.xml b/lib/parsetools/doc/src/specs.xml new file mode 100644 index 0000000000..21f8b1b25b --- /dev/null +++ b/lib/parsetools/doc/src/specs.xml @@ -0,0 +1,5 @@ +<?xml version="1.0" encoding="utf-8" ?> +<specs xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include href="../specs/specs_leex.xml"/> + <xi:include href="../specs/specs_yecc.xml"/> +</specs> diff --git a/lib/parsetools/doc/src/yecc.xml b/lib/parsetools/doc/src/yecc.xml index 67a2c95c25..a956cff872 100644 --- a/lib/parsetools/doc/src/yecc.xml +++ b/lib/parsetools/doc/src/yecc.xml @@ -44,108 +44,112 @@ parser generator, and the principle and problems of LALR parsing with finite look-ahead.</p> </description> + + <datatypes> + <datatype> + <name name="error_info"></name> + <desc><p>The standard <c>error_info()</c> structure that is returned + from all I/O modules. <c><anno>ErrorDescriptor</anno></c> is formatable + by <seemfa marker="#format_error/1"><c>format_error/1</c></seemfa>.</p> + </desc> + </datatype> + </datatypes> + <funcs> <func> - <name since="">file(Grammarfile [, Options]) -> YeccRet</name> + <name name="file" arity="1" since=""/> + <name name="file" arity="2" since=""/> <fsummary>Give information about resolved and unresolved parse action conflicts.</fsummary> - <type> - <v>Grammarfile = filename()</v> - <v>Options = Option | [Option]</v> - <v>Option = - see below -</v> - <v>YeccRet = {ok, Parserfile} | {ok, Parserfile, Warnings} | error | {error, Errors, Warnings}</v> - <v>Parserfile = filename()</v> - <v>Warnings = Errors = [{filename(), [ErrorInfo]}]</v> - <v>ErrorInfo = {ErrorLine, module(), Reason}</v> - <v>ErrorLine = integer()</v> - <v>Reason = - formatable by format_error/1 -</v> - </type> + <type name="yecc_ret"/> + <type name="ok_ret"/> + <type name="error_ret"/> + <type name="errors"/> + <type name="warnings"/> <desc> - <p><c>Grammarfile</c> is the file of declarations and grammar + <p><c><anno>Grammarfile</anno></c> is the file of declarations and grammar rules. Returns <c>ok</c> upon success, or <c>error</c> if there are errors. An Erlang file containing the parser is created if there are no errors. The options are: </p> <taglist> - <tag><c>{parserfile, Parserfile}</c>.</tag> - <item><c>Parserfile</c> is the name of the file that will - contain the Erlang parser code that is generated. The - default (<c>""</c>) is to add the extension <c>.erl</c> - to <c>Grammarfile</c> stripped of the <c>.yrl</c> - extension. - </item> - <tag><c>{includefile, Includefile}</c>.</tag> - <item>Indicates a customized prologue file which the user + <tag><c>{includefile, <anno>Includefile</anno>}</c>.</tag> + <item><p>Indicates a customized prologue file which the user may want to use instead of the default file <c>lib/parsetools/include/yeccpre.hrl</c> which is otherwise included at the beginning of the resulting - parser file. <em>N.B.</em> The <c>Includefile</c> is + parser file. <em>N.B.</em> The <c><anno>Includefile</anno></c> is included 'as is' in the parser file, so it must not have a module declaration of its own, and it should not be compiled. It must, however, contain the necessary export - declarations. The default is indicated by <c>""</c>. + declarations. The default is indicated by <c>""</c>.</p> </item> - <tag><c>{report_errors, bool()}</c>.</tag> - <item>Causes errors to be printed as they occur. Default is - <c>true</c>. + <tag><c>{parserfile, <anno>Parserfile</anno>}</c>.</tag> + <item><p><c><anno>Parserfile</anno></c> is the name of the file that will + contain the Erlang parser code that is generated. The + default (<c>""</c>) is to add the extension <c>.erl</c> + to <c><anno>Grammarfile</anno></c> stripped of the <c>.yrl</c> + extension.</p> </item> - <tag><c>{report_warnings, bool()}</c>.</tag> - <item>Causes warnings to be printed as they occur. Default is - <c>true</c>. + <tag><c>{report_errors, boolean()}</c>.</tag> + <item><p>Causes errors to be printed as they occur. Default is + <c>true</c>.</p> </item> - <tag><c>{report, bool()}</c>.</tag> - <item>This is a short form for both <c>report_errors</c> and - <c>report_warnings</c>. + <tag><c>{report_warnings, boolean()}</c>.</tag> + <item><p>Causes warnings to be printed as they occur. Default is + <c>true</c>.</p> </item> - <tag><c>warnings_as_errors</c></tag> - <item> - <p>Causes warnings to be treated as errors.</p> + <tag><c>{report, boolean()}</c>.</tag> + <item><p>This is a short form for both <c>report_errors</c> and + <c>report_warnings</c>.</p> </item> - <tag><c>{return_errors, bool()}</c>.</tag> - <item>If this flag is set, <c>{error, Errors, Warnings}</c> + <tag><c>{return_errors, boolean()}</c>.</tag> + <item><p>If this flag is set, + <c>{error, <anno>Errors</anno>, <anno>Warnings</anno>}</c> is returned when there are errors. Default is - <c>false</c>. + <c>false</c>.</p> </item> - <tag><c>{return_warnings, bool()}</c>.</tag> - <item>If this flag is set, an extra field containing - <c>Warnings</c> is added to the tuple returned upon - success. Default is <c>false</c>. + <tag><c>{return_warnings, boolean()}</c>.</tag> + <item><p>If this flag is set, an extra field containing + <c><anno>Warnings</anno></c> is added to the tuple returned upon + success. Default is <c>false</c>.</p> </item> - <tag><c>{return, bool()}</c>.</tag> - <item>This is a short form for both <c>return_errors</c> and - <c>return_warnings</c>. + <tag><c>{return, boolean()}</c>.</tag> + <item><p>This is a short form for both <c>return_errors</c> and + <c>return_warnings</c>.</p> </item> - <tag><c>{verbose, bool()}</c>. </tag> - <item>Determines whether the parser generator should give + <tag><c>{verbose, boolean()}</c>. </tag> + <item><p>Determines whether the parser generator should give full information about resolved and unresolved parse action conflicts (<c>true</c>), or only about those conflicts that prevent a parser from being generated from - the input grammar (<c>false</c>, the default). + the input grammar (<c>false</c>, the default).</p> + </item> + <tag><c>{warnings_as_errors, boolean()}</c></tag> + <item> + <p>Causes warnings to be treated as errors.</p> </item> </taglist> <p>Any of the Boolean options can be set to <c>true</c> by stating the name of the option. For example, <c>verbose</c> is equivalent to <c>{verbose, true}</c>. </p> - <p>The value of the <c>Parserfile</c> option stripped of the + <p>The value of the <c><anno>Parserfile</anno></c> option stripped of the <c>.erl</c> extension is used by Yecc as the module name of the generated parser file.</p> <p>Yecc will add the extension <c>.yrl</c> to the - <c>Grammarfile</c> name, the extension <c>.hrl</c> to the - <c>Includefile</c> name, and the extension <c>.erl</c> to - the <c>Parserfile</c> name, unless the extension is already + <c><anno>Grammarfile</anno></c> name, the extension <c>.hrl</c> to the + <c><anno>Includefile</anno></c> name, and the extension <c>.erl</c> to + the <c><anno>Parserfile</anno></c> name, unless the extension is already there.</p> </desc> </func> <func> - <name since="">format_error(Reason) -> Chars</name> - <fsummary>Return an English description of a an error tuple.</fsummary> - <type> - <v>Reason = - as returned by yecc:file/1,2 -</v> - <v>Chars = [char() | Chars]</v> - </type> + <name name="format_error" arity="1" since=""/> + <fsummary>Return an English description of a an error reason.</fsummary> <desc> - <p>Returns a descriptive string in English of an error tuple - returned by <c>yecc:file/1,2</c>. This function is mainly + <p>Returns a descriptive string in English of an error reason + <c><anno>ErrorDescriptor</anno></c> returned by + <c>yecc:file/1,2</c>. This function is mainly used by the compiler invoking Yecc.</p> </desc> </func> diff --git a/lib/parsetools/src/leex.erl b/lib/parsetools/src/leex.erl index 8a4a5e8d86..f60ad76175 100644 --- a/lib/parsetools/src/leex.erl +++ b/lib/parsetools/src/leex.erl @@ -89,11 +89,40 @@ compile(Input0, Output0, error end. -%% file(File) -> ok | error. -%% file(File, Options) -> ok | error. +-type error_info() :: {erl_anno:line() | 'none', + module(), ErrorDescriptor :: term()}. +-type errors() :: [{file:filename(), [error_info()]}]. +-type warnings() :: [{file:filename(), [error_info()]}]. +-type ok_ret() :: {'ok', Scannerfile :: file:filename()} + | {'ok', Scannerfile :: file:filename(), warnings()}. +-type error_ret() :: 'error' + | {'error', Errors :: errors(), Warnings :: warnings()}. +-type leex_ret() :: ok_ret() | error_ret(). + +-spec file(FileName) -> leex_ret() when + FileName :: file:filename(). file(File) -> file(File, []). +-spec file(FileName, Options) -> leex_ret() when + FileName :: file:filename(), + Options :: Option | [Option], + Option :: {'dfa_graph', boolean()} + | {'includefile', Includefile :: file:filename()} + | {'report_errors', boolean()} + | {'report_warnings', boolean()} + | {'report', boolean()} + | {'return_errors', boolean()} + | {'return_warnings', boolean()} + | {'return', boolean()} + | {'scannerfile', Scannerfile :: file:filename()} + | {'verbose', boolean()} + | {'warnings_as_errors', boolean()} + | 'dfa_graph' + | 'report_errors' | 'report_warnings' | 'report' + | 'return_errors' | 'return_warnings' | 'return' + | 'verbose' | 'warnings_as_errors'. + file(File, Opts0) -> case is_filename(File) of no -> erlang:error(badarg, [File,Opts0]); @@ -125,6 +154,9 @@ file(File, Opts0) -> end, leex_ret(St). +-spec format_error(ErrorDescriptor) -> io_lib:chars() when + ErrorDescriptor :: term(). + format_error({file_error, Reason}) -> io_lib:fwrite("~ts",[file:format_error(Reason)]); format_error(missing_defs) -> "missing Definitions"; diff --git a/lib/parsetools/src/yecc.erl b/lib/parsetools/src/yecc.erl index f44b1da861..6e132c7660 100644 --- a/lib/parsetools/src/yecc.erl +++ b/lib/parsetools/src/yecc.erl @@ -151,6 +151,9 @@ compile(Input0, Output0, error end. +-spec format_error(ErrorDescriptor) -> io_lib:chars() when + ErrorDescriptor :: term(). + format_error(bad_declaration) -> io_lib:fwrite("unknown or bad declaration, ignored", []); format_error({bad_expect, SymName}) -> @@ -232,8 +235,38 @@ format_error({bad_symbol, String}) -> format_error(cannot_parse) -> io_lib:fwrite("cannot parse; possibly encoding mismatch", []). -file(File) -> - file(File, [report_errors, report_warnings]). +-type error_info() :: {erl_anno:line() | 'none', + module(), ErrorDescriptor :: term()}. +-type errors() :: [{file:filename(), [error_info()]}]. +-type warnings() :: [{file:filename(), [error_info()]}]. +-type ok_ret() :: {'ok', Parserfile :: file:filename()} + | {'ok', Parserfile :: file:filename(), warnings()}. +-type error_ret() :: 'error' + | {'error', Errors :: errors(), Warnings :: warnings()}. +-type yecc_ret() :: ok_ret() | error_ret(). + +-spec file(FileName) -> yecc_ret() when + FileName :: file:filename(). + +file(GrammarFile) -> + file(GrammarFile, [report_errors, report_warnings]). + +-spec file(Grammarfile, Options) -> yecc_ret() when + Grammarfile :: file:filename(), + Options :: Option | [Option], + Option :: {'includefile', Includefile :: file:filename()} + | {'report_errors', boolean()} + | {'report_warnings', boolean()} + | {'report', boolean()} + | {'return_errors', boolean()} + | {'return_warnings', boolean()} + | {'return', boolean()} + | {'parserfile', Parserfile :: file:filename()} + | {'verbose', boolean()} + | {'warnings_as_errors', boolean()} + | 'report_errors' | 'report_warnings' | 'report' + | 'return_errors' | 'return_warnings' | 'return' + | 'verbose' | 'warnings_as_errors'. file(File, Options) -> case is_filename(File) of -- 2.26.2
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
Terms
openSUSE Build Service is sponsored by
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor
