package ppxlib
Install
dune-project
Dependency
Authors
Maintainers
Sources
sha256=2e223837e7cecc3bc84a432432c0a72f4e1d5be9165c9c33772f156db85db0b3
sha512=78c62c6de7a641b950de9b4b744841c8823918c545046693e291077adfcd069a812094c11d8d51f792c0b5f340307d38f452ff0a92520df63ed17a3ca9922e2e
doc/ppxlib/Ppxlib/Attribute/index.html
Module Ppxlib.Attribute
Source
This module provides hygiene for attributes. The goal is to report misuses of attributes to the user as soon as possible so that no mistyped attribute get silently ignored.
Type of declared attribute.
The 'context
type parameter describes where the attribute is expected and the 'payload
one what its payload should contain.
val declare :
string ->
'a Context.t ->
(Astlib.Ast_502.Parsetree.payload, 'b, 'c) Ast_pattern.t ->
'b ->
('a, 'c) t
declare fully_qualified_name context payload_pattern k
declares an attribute. k
is used to build the value resulting from parsing the payload.
For instance if a rewriter named "foo" expect the attribute @@default
on record field declaration with an expression as payload:
let default =
Attribute.declare "foo.default" Attribute.Context.label_declaration
Ast_pattern.(pstr (pstr_eval __ nil))
(fun x -> x)
fully_qualified_name
is expected to be a dot-separated list of names. When matching, any full suffix will be accepted. So for instance an attribute declared with name "foo.bar.default" will match exactly these attribute names: "default", "bar.default" and "foo.bar.default".
Additionally it is possible to prevent a suffix to be shortened by prefixing it with '@'. So for instance an attribute declared with name "foo.@bar.default" will match exactly these attribute names: "bar.default" and "foo.bar.default".
When matching against a list of attributes on an item, if several matches are possible, the longest one is used. For instance using the attribute "foo.default" declared in the previous example, on this code it will match the @foo.default 0
attribute:
type t = { x : int [@default 42] [@foo.default 0] }
This is to allow the user to specify a @default
attribute for all re-writers that use it but still put a specific one for one specific re-writer.
It is not allowed to declare an attribute with a name that matches a previously-defined one on the same context. For instance trying to declare the same attribute twice will fail.
val declare_with_name_loc :
string ->
'a Context.t ->
(Astlib.Ast_502.Parsetree.payload, 'b, 'c) Ast_pattern.t ->
(name_loc:Location.t -> 'b) ->
('a, 'c) t
Same as declare
but the callback receives the location of the name of the attribute.
val declare_with_attr_loc :
string ->
'a Context.t ->
(Astlib.Ast_502.Parsetree.payload, 'b, 'c) Ast_pattern.t ->
(attr_loc:Location.t -> 'b) ->
('a, 'c) t
Same as declare
but the callback receives the location of the attribute.
val get_res :
('a, 'b) t ->
?mark_as_seen:bool ->
'a ->
('b option, Location.Error.t Stdppx.NonEmptyList.t) result
Gets the associated attribute value. Marks the attribute as seen unless mark_as_seen=false
. Returns an Error
if the attribute is duplicated
See get_res
. Raises a located error if the attribute is duplicated
val has_flag_res :
'a flag ->
?mark_as_seen:bool ->
'a ->
(bool, Location.Error.t Stdppx.NonEmptyList.t) result
Answers whether the given flag is attached as an attribute. See get_res
for the meaning of mark_as_seen
.
See has_flag_res
. Raises a located error if the attribute is duplicated.
val consume_res :
('a, 'b) t ->
'a ->
(('a * 'b) option, Location.Error.t Stdppx.NonEmptyList.t) result
consume_res t x
returns the value associated to attribute t
on x
if present as well as x
with t
removed.
See consume_res
. Raises a located exception in case of error.
val remove_seen_res :
'a Context.t ->
packed list ->
'a ->
('a, Location.Error.t Stdppx.NonEmptyList.t) result
See remove_seen_res
. Raises in case of error.
Code that is voluntarily dropped by a rewriter needs to be given to this object. All attributes inside will be marked as handled.
Raise if there are unused attributes.
Collect all errors due to unused attributes.
Collect all attribute names. To be used in conjunction with check_all_seen
.
Check that all attributes collected by collect_unseen_errors
have been:
- matched at least once by one of:
get
,consume
orFloating.convert
- seen by
check_unused
(to allow allowlisted attributed to pass through)
This helps with faulty ppx rewriters that silently drop attributes.
Mark an attribute as seen and handled. This is only to make ppx rewriters that don't use ppxlib works well with the ones that do use it.
val dropped_so_far_structure :
Astlib.Ast_502.Parsetree.structure_item list ->
string Loc.t list
Return the list of attributes that have been dropped so far: attributes that haven't been marked and are not present in the given AST. This is used to debug extensions that drop attributes.
val dropped_so_far_signature :
Astlib.Ast_502.Parsetree.signature_item list ->
string Loc.t list
val pattern :
('a, 'b) t ->
('a, 'c, 'd) Ast_pattern.t ->
('a, 'b option -> 'c, 'd) Ast_pattern.t
val pattern_res :
('a, 'b) t ->
('a, 'c, 'd) Ast_pattern.t ->
('a, 'b option -> 'c, ('d, Location.Error.t Stdppx.NonEmptyList.t) result)
Ast_pattern.t