Module Ocaml_parsing.Builtin_attributes

Support for the builtin attributes:

Warning: this module is unstable and part of compiler-libs.

Attribute tracking for warning 53

type current_phase =
  1. | Parser
  2. | Invariant_check

register_attr must be called on the locations of all attributes that should be tracked for the purpose of misplaced attribute warnings. In particular, it should be called on all attributes that are present in the source program except those that are contained in the payload of another attribute (because these may be left behind by a ppx and intentionally ignored by the compiler).

The current_phase argument indicates when this function is being called

  • either when an attribute is created in the parser or when we see an attribute while running the check in the Ast_invariants module. This is used to ensure that we track only attributes from the final version of the parse tree: we skip adding attributes seen at parse time if we can see that a ppx will be run later, because the Ast_invariants check is always run on the result of a ppx.

Note that the Ast_invariants check is also run on parse trees created from marshalled ast files if no ppx is being used, ensuring we don't miss attributes in that case.

val register_attr : current_phase -> string Location.loc -> unit
val mark_payload_attrs_used : Parsetree.payload -> unit

Marks the attributes hiding in the payload of another attribute used, for the purposes of misplaced attribute warnings (see comment on current_phase above). In the parser, it's simplest to add these to the table and remove them later, rather than threading through state tracking whether we're in an attribute payload.

val warn_unused : unit -> unit

Issue misplaced attribute warnings for all attributes created with mk_internal but not yet marked used. Does nothing if compilation is stopped before lambda due to command-line flags.

Warning 53 helpers for environment attributes

Some attributes, like deprecation markers, do not affect the compilation of the definition on which they appear, but rather result in warnings on future uses of that definition. This is implemented by moving the raw attributes into the environment, where they will be noticed on future accesses.

To make misplaced attribute warnings work appropriately for these attributes, we mark them "used" when they are moved into the environment. This is done with the helper functions in this section.

val mark_alert_used : Parsetree.attribute -> unit

Marks the attribute used for the purposes of misplaced attribute warnings if it is an alert. Call this when moving things allowed to have alert attributes into the environment.

val mark_alerts_used : Parsetree.attributes -> unit

The same as List.iter mark_alert_used.

val mark_warn_on_literal_pattern_used : Parsetree.attributes -> unit

Marks "warn_on_literal_pattern" attributes used for the purposes of misplaced attribute warnings. Call this when moving constructors into the environment.

val mark_deprecated_mutable_used : Parsetree.attributes -> unit

Marks "deprecated_mutable" attributes used for the purposes of misplaced attribute warnings. Call this when moving labels of mutable fields into the environment.

val mark_zero_alloc_attribute_checked : string -> Location.t -> unit

Warning 53 helpers for zero alloc

Zero_alloc attributes are checked in late stages of compilation in the backend. Registering them helps detect code that is not checked, because it is optimized away by the middle-end.

val warn_unchecked_zero_alloc_attribute : unit -> unit

Helpers for alert and warning attributes

val check_alerts : Location.t -> Parsetree.attributes -> string -> unit
val check_alerts_inclusion : def:Location.t -> use:Location.t -> Location.t -> Parsetree.attributes -> Parsetree.attributes -> string -> unit

Find alerts (and mark them used, wrt misplaced attribute warnings)

val alerts_of_sig : mark:bool -> Parsetree.signature -> Merlin_utils.Misc.alerts
val alerts_of_str : mark:bool -> Parsetree.structure -> Merlin_utils.Misc.alerts
val check_deprecated_mutable : Location.t -> Parsetree.attributes -> string -> unit
val check_deprecated_mutable_inclusion : def:Location.t -> use:Location.t -> Location.t -> Parsetree.attributes -> Parsetree.attributes -> string -> unit
val error_of_extension : Parsetree.extension -> Location.error
val warning_attribute : ?ppwarning:bool -> Parsetree.attribute -> unit

Apply warning settings from the specified attribute. "ocaml.warning"/"ocaml.warnerror" (and variants without the prefix) are processed and marked used for warning 53. Other attributes are ignored.

Also implement ocaml.ppwarning (unless ~ppwarning:false is passed).

val warning_scope : ?ppwarning:bool -> Parsetree.attributes -> (unit -> 'a) -> 'a

Execute a function in a new scope for warning settings. This means that the effect of any call to warning_attribute during the execution of this function will be discarded after execution.

The function also takes a list of attributes which are processed with warning_attribute in the fresh scope before the function is executed.

Helpers for searching for particular attributes

val has_attribute : string -> Parsetree.attributes -> bool

has_attribute name attrs is true if an attribute with name name or "ocaml." ^ name is present in attrs. It marks that attribute used for the purposes of misplaced attribute warnings.

type attr_action =
  1. | Mark_used_only
  2. | Return

select_attributes actions attrs finds the elements of attrs that appear in actions and either returns them or just marks them used, according to the corresponding attr_action.

Each element (nm, action) of the actions list is an attribute along with an attr_action specifying what to do with that attribute. The action is used to accommodate different compiler configurations. If an attribute is used only in some compiler configurations, it's important that we still look for it and mark it used when compiling with other configurations. Otherwise, we would issue spurious misplaced attribute warnings.

val select_attributes : (string * attr_action) list -> Parsetree.attributes -> Parsetree.attributes
val attr_equals_builtin : Parsetree.attribute -> string -> bool

attr_equals_builtin attr s is true if the name of the attribute is s or "ocaml." ^ s. This is useful for manually inspecting attribute names, but note that doing so will not result in marking the attribute used for the purpose of warning 53, so it is usually preferrable to use has_attribute or select_attributes.

val warn_on_literal_pattern : Parsetree.attributes -> bool
val explicit_arity : Parsetree.attributes -> bool
val has_unboxed : Parsetree.attributes -> bool
val has_boxed : Parsetree.attributes -> bool
val has_unsafe_allow_any_mode_crossing : Parsetree.attributes -> bool
val parse_standard_interface_attributes : Parsetree.attribute -> unit
val parse_standard_implementation_attributes : Parsetree.attribute -> unit
val curry_attr_name : string

The attribute placed on the inner Ptyp_arrow node in x -> (y -> z) (meaning the y -> z node) to indicate parenthesization. This is relevant for locals, as local_ x -> (y -> z) is different than local_ x -> y -> z.

val curry_attr : Location.t -> Parsetree.attribute
val has_local_opt : Parsetree.attributes -> bool
val has_layout_poly : Parsetree.attributes -> bool
val has_curry : Parsetree.attributes -> bool
val has_or_null_reexport : Parsetree.attributes -> bool
val tailcall : Parsetree.attributes -> ([ `Tail | `Nontail | `Tail_if_possible ] option, [ `Conflict ]) result
type jkind_attribute =
  1. | Immediate64
  2. | Immediate
val jkind_attribute_to_string : jkind_attribute -> string
val jkind_attribute_of_string : string -> jkind_attribute option
val error_message_attr : Parsetree.attributes -> string option

Finds the first "error_message" attribute, marks it as used, and returns its string payload. Returns None if no such attribute is present.

There should be at most one "error_message" attribute, additional ones are sliently ignored. *

val get_int_payload : Parsetree.payload -> (int, unit) Result.t

get_int_payload is a helper for working with attribute payloads. Given a payload that consist of a structure containing exactly

  PStr [
    {pstr_desc =
       Pstr_eval (Pexp_constant (Pconst_integer(i, None)), [])
    }
  ]

it returns i.

val get_optional_bool_payload : Parsetree.payload -> (bool option, unit) Result.t

get_optional_bool_payload is a helper for working with attribute payloads. It behaves like get_int_payload, except that it looks for a boolean constant rather than an int constant, and returns None rather than Error if the payload is empty.

val parse_optional_id_payload : string -> Location.t -> empty:'a -> (string * 'a) list -> Parsetree.payload -> ('a, unit) Result.t

parse_id_payload is a helper for parsing information from an attribute whose payload is an identifier. If the given payload consists of a single identifier, that identifier is looked up in the association list. The result is returned, if it exists. The empty value is returned if the payload is empty. Otherwise, Error () is returned and a warning is issued.

type zero_alloc_check = {
  1. strict : bool;
  2. opt : bool;
  3. arity : int;
  4. loc : Location.t;
  5. custom_error_msg : string option;
}
type zero_alloc_assume = {
  1. strict : bool;
  2. never_returns_normally : bool;
  3. never_raises : bool;
  4. arity : int;
  5. loc : Location.t;
}
type zero_alloc_attribute =
  1. | Default_zero_alloc
  2. | Ignore_assert_all
  3. | Check of zero_alloc_check
  4. | Assume of zero_alloc_assume
val is_zero_alloc_check_enabled : opt:bool -> bool
val get_zero_alloc_attribute : in_signature:bool -> on_application:bool -> default_arity:int -> Parsetree.attributes -> zero_alloc_attribute
val zero_alloc_attribute_only_assume_allowed : zero_alloc_attribute -> zero_alloc_assume option
val assume_zero_alloc : inferred:bool -> zero_alloc_assume -> Ocaml_utils.Zero_alloc_utils.Assume_info.t
type tracing_probe = {
  1. name : string;
  2. name_loc : Location.t;
  3. enabled_at_init : bool;
  4. arg : Parsetree.expression;
}
val get_tracing_probe_payload : Parsetree.payload -> (tracing_probe, unit) result
val get_eval_payload : Parsetree.payload -> (Parsetree.core_type, unit) result

Gets the payload of a eval extension node which evaluates quotes, for example: %eval: int

val has_atomic : Parsetree.attributes -> bool
val merlin_let_punned : string

The name of the attribute used to identify punned let expressions. When a let expression is punned, an attribute with this name is added to the pattern and expression nodes by the parser.