Frama-C:
Plug-ins:
Libraries:

Frama-C API - Filepos

This module handle positions in a source file. Filepos.t is a Frama-C datatype, and comes with usual compare, equal, hash and pretty functions.

  • compare orders location first by file path, then by offset in the file. This means the position order will be compatible with the apparition order in each file. If no offset information is available in both compared positions, the line then column will be used.
  • hash only hashes the path and the line of the position.
type t
val pp : Ppx_deriving_runtime.Format.formatter -> t -> Ppx_deriving_runtime.unit
val show : t -> Ppx_deriving_runtime.string
type origin =
  1. | Unknown
    (*

    Unknown position. This constructor should be avoided.

    *)
  2. | Original
    (*

    The position is in one of the user input files.

    *)
  3. | Generated of string
    (*

    The position is in generated input. The string is a name identifying the generator.

    *)
  4. | Preprocessed of t
    (*

    The position is in file that have been produced from a preprocessing at the given position.

    *)
  5. | Included of t
    (*

    The position is in a file included from the given position

    *)
val pp_origin : Ppx_deriving_runtime.Format.formatter -> origin -> Ppx_deriving_runtime.unit
val show_origin : origin -> Ppx_deriving_runtime.string
include Datatype.S_with_collections with type t := t
include Datatype.S with type t := t
include Datatype.S_no_copy with type t := t
include Datatype.Ty with type t := t
val ty : t Type.t
val datatype_name : string

Unique name of the datatype.

val datatype_descr : t Descr.t

Datatype descriptor.

val packed_descr : Structural_descr.pack

Packed version of the descriptor.

val reprs : t list

List of representants of the descriptor.

val equal : t -> t -> bool

Equality: same spec than Stdlib.(=).

val compare : t -> t -> int

Comparison: same spec than Stdlib.compare.

val hash : t -> int

Hash function: same spec than Hashtbl.hash.

val mem_project : (Project_skeleton.t -> bool) -> t -> bool

mem_project f x must return true iff there is a value p of type Project.t in x such that f p returns true.

val copy : t -> t

Deep copy: no possible sharing between x and copy x.

module Set : Datatype.Set with type elt = t
module Map : Datatype.Map with type key = t
module Hashtbl : Datatype.Hashtbl with type key = t

Pretty printing

val pretty : Stdlib.Format.formatter -> t -> unit

Pretty prints a position in the format <file>:<line>, with variants for unknown files or generated positions.

val pretty_long : Stdlib.Format.formatter -> t -> unit

Pretty prints a position in the format "<file>", line <line> or, if the column number is available, in the format "<file>", line <line>, character <char>, with variants for unknown files or generated positions.

val pretty_debug : Stdlib.Format.formatter -> t -> unit

Debug printer. Prints the internal representation of locations.

Construction

val make : ?path:Filepath.t -> ?offset:int -> ?line:int -> ?column:int -> ?origin:origin -> unit -> t

Make a new position. The default for origin is Original.

Special positions

val generated : ?pos:t -> string -> t

Make a new position for a generated input. The generator name is given as a string. If the position is provided, it is copied (except for its origin), else it is unknown.

val unknown : t

Special representation of an unknown position.

Conversion from/to Lexing.position

val of_lexing_pos : ?origin:origin -> Stdlib.Lexing.position -> t

Convert a Lexing.position to a Filepos.t.

val to_lexing_pos : t -> Stdlib.Lexing.position

Convert a Filepos.t to a Lexing.position

Position tracking

val update_line : ?path:Filepath.t -> line:int -> t -> t

Update the current line of the position. Tries to keep track the file inclusions; recursive inclusion is unsupported.

val incr_line : t -> t

Increment the line number in the position.

val update_column : column:int -> t -> t

Update the column of the position.

Accessors

val original : t -> t

Get the original position. If the position is in a preprocessed code, returns the source of the preprocessing otherwise this function is the identity.

val path : t -> Filepath.t

Get the path of a position. If the position is in a preprocessed code, returns the original file.

val line : t -> int

Get the line of a position, starting at 1. If the position is in a preprocessed code, returns the line in the original file.

val column : t -> int

Get the column of the position, starting at 1. If the position is in a preprocessed code and as Frama-C cannot track the column in the original file, this function will likely return 0.

val origin : t -> origin

Get the origin of a position.

val input_path : t -> Filepath.t

Get the path of the input file. Unlike path, if the position is in a preprocessed code, it returns the preprocessed output path.

val input_line : t -> int

Get the line in the input file, starting at 1. Unlike line, if the position is in a preprocessed code, it returns the line in the preprocessed output.

val input_column : t -> int

Get the column in the input file, starting at 1. Unlike column, if the position is in a preprocessed code, it returns the column in the preprocessed output.

val input_offset : t -> int

Get the offset in the input file, starting at 0. Unlike offset, if the position is in a preprocessed code, it returns the offset in the preprocessed output.

val generated_by : t -> string option

If the origine of the position is Generated name, return Some name else return None.

val is_empty : t -> bool

Return true if all values of the given position are the default values of make.

val is_preprocessed : t -> bool

Returns whether the location is a preprocessed file. If true is returned then original will likely not be the identity path and line will likely to return different results than input_path and input_line.

val inclusions : t -> t list

Returns the list of inclusion positions when the position is in preprocessed code; returns nothing if the position is not in an included file.

Datatype with comparison/hash on original source positions

This module provides an alternative datatype where only original positions are considered for compare, equal and hash. This is intended for preprocessed code where the same file can be included several times leading to tokens having different position in the preprocessing output but the same original position.