Current section
Files
Jump to
Current section
Files
src/wooper_info.hrl
% Copyright (C) 2003-2019 Olivier Boudeville
%
% This file is part of the Ceylan-WOOPER library.
%
% This library is free software: you can redistribute it and/or modify
% it under the terms of the GNU Lesser General Public License or
% the GNU General Public License, as they are published by the Free Software
% Foundation, either version 3 of these Licenses, or (at your option)
% any later version.
% You can also redistribute it and/or modify it under the terms of the
% Mozilla Public License, version 1.1 or later.
%
% 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 and the GNU General Public License
% for more details.
%
% You should have received a copy of the GNU Lesser General Public
% License, of the GNU General Public License and of the Mozilla Public License
% along with this library.
% If not, see <http://www.gnu.org/licenses/> and
% <http://www.mozilla.org/MPL/>.
%
% Author: Olivier Boudeville [olivier (dot) boudeville (at) esperide (dot) com]
% Describes a member attribute of the state of a given class: stores all
% class-level information (i.e. metadata) regarding this attribute.
%
-record( attribute_info, {
% The name of this attribute (ex: 'total_surface'):
name :: wooper:attribute_name(),
% The type of this attribute, currently as an atom (later: as
% type_utils:type()).
%
% Ex: '{ atom(), [ float() ] }'.
%
type = undefined :: maybe( type_utils:type_description() ),
% The qualifiers (if any) that apply to this attribute:
qualifiers = [] :: maybe( [ wooper:attribute_qualifier() ] ),
% Textual description (if any) of that attribute (free text):
description = undefined :: maybe( text_utils:bin_string() )
} ).
% Note: method information do not have an 'exported' field like functions, as
% they must be exported in all cases anyway (ex: to be callable for child
% classes).
% Stores and centralises WOOPER-level information gathered about a given
% request.
%
% This record is to strictly supersede the Myriad-level function_info one.
%
% See also: this counterpart function_info Myriad record, defined in
% ast_info.hrl.
%
-record( request_info, {
% The name of that request:
name = undefined :: wooper:request_name(),
% The arity of that request:
arity = undefined :: wooper:method_arity(),
% Qualifiers applying to this request:
qualifiers = [] :: wooper:method_qualifiers(),
% Corresponds to (our view of) the location of the full form for the
% definition (first clause) of this request (not of the spec):
%
location = undefined :: maybe( ast_info:location() ),
% Corresponds to the line of the first defined clause (in its source
% file):
%
% (this information is not redundant with the previous field, as they
% are different types of locations)
%
line = undefined :: maybe( ast_base:line() ),
% Request actual definition, a (non-located) list of the abstract
% forms of its clauses:
%
clauses = [] :: [ meta_utils:clause_def() ],
% The type specification (if any) of that request, as an abstract
% form:
spec = undefined :: maybe( wooper_info:located_method_spec() )
} ).
% Stores and centralises WOOPER-level information gathered about a given oneway
% method.
%
% This record is to strictly supersede the Myriad-level function_info one.
%
% See also: the function_info counterpart Myriad record, defined in
% ast_info.hrl.
%
-record( oneway_info, {
% The name of that oneway:
name = undefined :: wooper:oneway_name(),
% The arity of that oneway:
arity = undefined :: wooper:method_arity(),
% Qualifiers applying to this oneway:
qualifiers = [] :: wooper:method_qualifiers(),
% Corresponds to (our view of) the location of the full form for the
% definition (first clause) of this oneway (not of the spec):
%
location = undefined :: maybe( ast_info:location() ),
% Corresponds to the line of the first defined clause (in its source
% file):
%
% (this information is not redundant with the previous field, as they
% are different types of locations)
%
line = undefined :: maybe( ast_base:line() ),
% Oneway actual definition, a (non-located) list of the abstract
% forms of its clauses:
%
clauses = [] :: [ meta_utils:clause_def() ],
% The type specification (if any) of that oneway, as an abstract
% form:
spec = undefined :: maybe( wooper_info:located_method_spec() )
} ).
% Stores and centralises WOOPER-level information gathered about a given static
% method.
%
% This record is to strictly supersede the Myriad-level function_info one.
%
% See also: the function_info counterpart Myriad record, defined in
% ast_info.hrl.
%
-record( static_info, {
% The name of that static method:
name = undefined :: wooper:static_name(),
% The arity of that static method:
arity = undefined :: wooper:method_arity(),
% Qualifiers applying to this static method:
qualifiers = [] :: wooper:method_qualifiers(),
% Corresponds to (our view of) the location of the full form for the
% definition (first clause) of this static (not of the spec):
%
location = undefined :: maybe( ast_info:location() ),
% Corresponds to the line of the first defined clause (in its source
% file):
%
% (this information is not redundant with the previous field, as they
% are different types of locations)
%
line = undefined :: maybe( ast_base:line() ),
% Static actual definition, a (non-located) list of the abstract
% forms of its clauses:
%
clauses = [] :: [ meta_utils:clause_def() ],
% The type specification (if any) of that static, as an abstract
% form:
%
spec = undefined :: maybe( wooper_info:located_method_spec() )
} ).
% Description of the class name:
-type class_entry() :: maybe( { wooper:classname(), ast_info:located_form() } ).
% Stores and centralises WOOPER-level information gathered about a given class.
%
% This record is to strictly supersede the Myriad-level module_info one.
%
% See also: the (superseded here) {module,function}_info counterpart Myriad
% records, defined in ast_info.hrl.
%
-record( class_info, {
% Name of that class:
class :: class_entry(),
% Ordered list of the superclasses of this class:
superclasses :: [ wooper:classname() ],
% All the class-specific attributes of the instances (hence not
% comprising inherited ones):
%
attributes :: wooper_info:attribute_table(),
% All inherited attribute definitions for this class:
inherited_attributes :: wooper_info:attribute_table(),
% A table, whose keys are compilation options (ex: no_auto_import,
% inline, etc.) and whose values are aggregated lists of their
% associated values (ex: [{size,1}] and [{get_bucket_index,2},{f/1}]).
%
% Note: for the 'inline' key, if full inlining is enabled ( '-compile(
% inline ).'), then its associated key is not a list of function
% identifiers, but 'all'.
%
compilation_options :: ast_info:compile_option_table(),
% We merely touch compilation options (ex: '{compile, { inline, [ {
% FunName, Arity } ] } }'):
%
compilation_option_defs = [] :: [ ast_info:located_form() ],
% Other (unrecognised, not corresponding to other fields of interest)
% parse-level attributes (ex: '-my_attribute( my_value ).'), as a table
% associating, to an attribute name (an atom key), a list of pairs
% comprising each a value and an AST form.
%
% Such attributes, also named "wild attributes", mostly correspond to
% user-defined ones.
%
parse_attributes :: ast_info:attribute_table(),
% As remote function specifications can be defined, like:
% -spec Mod:Name(...) -> ...
%
remote_spec_defs = [] :: [ ast_info:located_form() ],
% Include files (typically *.hrl files, but also includes the .erl
% source module):
%
% (expected to remain empty, as the preprocessor is supposed to have
% already been run)
%
includes = [] :: [ file_utils:file_name() ],
% Include definitions:
include_defs = [] :: [ ast_info:located_form() ],
% Whether a type (possibly any kind of it; ex: opaque or not) is
% exported is recorded primarily in its own type_info record through a
% list of locations, while the information sufficient to reconstruct the
% actual forms for the exports of all types are recorded here.
%
% Note: it is better that way, as a type export attribute may define any
% number of exports, and we need to record its definition line.
%
% (this field must be kept synchronised with the table in the
% 'types' field)
%
type_exports :: ast_info:type_export_table(),
% All information, indexed by type identifiers, about all the types
% defined in that module:
%
types :: ast_info:type_table(),
% All information (notably: field descriptions), indexed by record
% names, about all the records known of that module:
%
records :: ast_info:record_table(),
% Lists the functions imported by that module, per-module.
function_imports :: ast_info:function_import_table(),
% The definitions of the function imports:
function_imports_defs = [] :: [ ast_info:located_form() ],
% Whether a plain function (i.e. not a method) is exported is recorded
% primarily in its own record through a list of locations, while the
% information sufficient to reconstruct the actual forms for the exports
% of all functions are recorded here.
%
% Note: it is better that way, as a function export attribute may define
% any number of exports, and we need to record its definition line.
%
% (this field must be kept synchronised with the table in the
% corresponding 'functions' field)
%
function_exports :: ast_info:function_export_table(),
% All information about the other, plain functions defined for that
% class:
%
% (this field must be kept synchronised with the table in the
% 'function_exports' field)
%
functions :: ast_info:function_table(),
% All information about the constructor(s) of that class:
constructors :: wooper_info:constructor_table(),
% All information about the new operators (ex: remote_new_link/N) of
% that class:
%
new_operators :: ast_info:function_table(),
% All information about the destructor (if any) of that class:
destructor = undefined :: maybe( ast_info:function_info() ),
% Whether a request is exported is recorded primarily in its own
% request_info record through a list of locations, while the information
% sufficient to reconstruct the actual forms for the exports of all are
% recorded here.
%
% Note: it is better that way, as a request export attribute may define
% any number of exports, and we need to record its definition line.
%
% (this field must be kept synchronised with the table in the
% corresponding 'requests' field)
%
request_exports :: wooper_info:request_export_table(),
% All information about the class-specific (member) request methods
% defined for that class:
%
% (this field must be kept synchronised with the table in the
% 'request_exports' field)
%
requests :: wooper_info:request_table(),
% Whether a oneway is exported is recorded primarily in its own
% oneway_info record through a list of locations, while the information
% sufficient to reconstruct the actual forms for the exports of all are
% recorded here.
%
% Note: it is better that way, as a oneway export attribute may define
% any number of exports, and we need to record its definition line.
%
% (this field must be kept synchronised with the table in the
% corresponding 'oneways' field)
%
oneway_exports :: wooper_info:oneway_export_table(),
% All information about the class-specific (member) oneway methods
% defined for that class:
%
% (this field must be kept synchronised with the table in the
% 'oneway_exports' field)
%
oneways :: wooper_info:oneway_table(),
% Whether a static method is exported is recorded primarily in its own
% static_info record through a list of locations, while the information
% sufficient to reconstruct the actual forms for the exports of all are
% recorded here.
%
% Note: it is better that way, as a static method export attribute may
% define any number of exports, and we need to record its definition
% line.
%
% (this field must be kept synchronised with the table in the
% corresponding 'statics' field)
%
static_exports :: wooper_info:static_export_table(),
% All information about the class-specific (member) static methods
% defined for that class:
%
% (this field must be kept synchronised with the table in the
% 'static_exports' field)
%
statics :: wooper_info:static_table(),
% The definitions of the list of optional callbacks:
optional_callbacks_defs = [] :: [ ast_info:located_form() ],
% Tells whether this class shall be compiled and run in debug mode,
% hence with extended checks for example (slower, safer, easier to
% debug).
%
debug_mode = true :: boolean(),
% The number of the last line in the original source file:
%
% (any added code will be put afterwards)
%
last_line :: ast_base:line(),
% Section markers, offering reference locations to AST transformations.
markers :: ast_info:section_marker_table(),
% Error information collected when traversing the AST.
errors = [] :: [ ast_info:error() ],
% List of all the located forms that are unhandled, which might be
% typically errors, like:
%
% '{error,{LineNumber,erl_parse, ["syntax error before: ","')'"]}}''.
%
unhandled_forms = [] :: [ ast_info:located_form() ]
} ).