COCCILIB(3COCCI)

💖 COCCILIB(3COCCI) 💖

okay bestie, sit down, hydrate, because this is the manual page for Coccilib — the library of functions you use with Coccinelle OCaml script code. yes. OCaml. inside your Coccinelle. it's giving ✨spatch but make it functional✨.

---

🎀 MODULE 🎀

Module Coccilib

---

🌸 DOCUMENTATION 🌸

Module Coccilib

 : sig end

---

🦋 Positions 🦋

First up, the little record that tells you where things are. Iconic.

type pos = {
 current_element : string ;
 current_element_line : int ;
 current_element_col : int ;
 current_element_line_end : int ;
 current_element_col_end : int ;
 file : string ;
 line : int ;
 col : int ;
 line_end : int ;
 col_end : int ;
 }

A value of type pos describes a position in a source file, no cap. Let's break it down because there's a lot of fields here:

• current_element — the name of the function containing the matched position.
• current_element_line — the number of the line containing the first character of the function containing the matched position.
• current_element_col — the (0-based) column containing the first character of the function containing the matched position.
• current_element_line_end — the number of the line containing the last character of the function containing the matched position.
• current_element_col_end — the (0-based) column containing the last character of the function containing the matched position.
• file — the name of the file containing the matched position.
• line — the number of the line containing the first character of the matched position.
• col — the (0-based) column containing the first character of the matched position.
• line_end — the number of the line containing the last character of the matched position.
• col_end — the (0-based) column containing the last character of the matched position.

---

🌈 Abstract Syntax Tree 🌈

now the AST type. this is the big one. it's literally a buffet of things you can match on 🍓:

type param_type
 =
 | Pos of pos list
 | Str of string
 | Type of Ast_c.fullType
 | Init of Ast_c.initialiser
 | InitList of Ast_c.initialiser Ast_c.wrap2 list
 | Int of int
 | Param of Ast_c.parameterType
 | ParamList of Ast_c.parameterType Ast_c.wrap2 list
 | Expr of Ast_c.expression
 | ExprList of Ast_c.argument Ast_c.wrap2 list
 | Decl of Ast_c.declaration
 | Field of Ast_c.field
 | FieldList of Ast_c.field list
 | Stmt of Ast_c.statement

val make_ident : string -> Ast_c.metavar_binding_kind

Make an identifier. simple. slay.

val make_expr : string -> Ast_c.metavar_binding_kind

Make an expression.

val make_expr_with_env : string -> string -> Ast_c.metavar_binding_kind

Make an expression in a type environment. The first argument is a string containing any C variable declarations needed to make the environment and the second argument is a string containing the expression.

val make_stmt : string -> Ast_c.metavar_binding_kind

Make a single statement.

val make_stmt_in_env : string -> Ast_c.metavar_binding_kind

Make a single statement in a type environment. The first argument is a string containing any C variable declarations needed to make the environment and the second argument is a string containing the statement.

val make_type : string -> Ast_c.metavar_binding_kind

Make a type.

val make_listlen : int -> Ast_c.metavar_binding_kind

Make a list length — for parameter lists, expression lists, etc. yes bestie, the etc. is doing heavy lifting but we move 💅

val make_full_position : string -> string -> int -> int -> int -> int ->
int -> int -> int -> int -> Ast_c.metavar_binding_kind

Make a position. The arguments are the file name, the function or other toplevel element containing the position, the starting line of the containing element, the starting column of the containing element, the ending line of the containing element, the ending column of the containing element, the starting line of the created position, the starting column of the created position, the ending line of the created position, and the ending column of the created position.

⚠️ okay important details here, don't skip: the ending line is the one that contains the last character of what is to be matched. The ending character is one past the last character of the thing to be matched. The containing element position will be a default value. (Also — the original text says "start at 0" right in here, and honestly? same energy. just keep the column rules in mind, bestie.)

Hmm, let me give you that last bit straight since it's load-bearing: lines start at 1, columns start at 0 (the text in this one just trails off into "start at 0"), and the containing element position will be a default value.

val make_position : string -> string -> int -> int -> int -> int ->
Ast_c.metavar_binding_kind

Make a position. The arguments are the file name, the function or other toplevel element containing the position, the starting line, the starting column, the ending line, and the ending column. Lines start at 1. Columns start at 0. The ending line is the one that contains the last character of what is to be matched. The ending character is one past the last character of the thing to be matched. The containing element position will be a default value.

---

👑 Match management functions 👑

these are the ones that decide whether your match sticks around or gets yeeted 🫶

val include_match : bool -> unit

If the argument is true, retain the environment with respect to which the ocaml script code is being executed for use in subsequent rules. If the argument is false, discard this environment. By default, the environment is retained.

val exit : unit -> unit

If called, aborts the treatment of the current file. All previous changes take effect. (so like, the stuff you already did? still happening. no undo button, bestie.)

val dir : unit -> string

Returns the directory on which spatch was launched.

val files : unit -> string list

Returns the list of files on which spatch is currently working. The result is the empty list if spatch is not currently working on any file (eg, in an initialize or finalize rule).

val cocci_version : unit -> string

Returns a string indicating the current version. Note that if Coccinelle has been modified since a release, the version number will be postfixed with "-dirty". (ngl, -dirty is a whole mood.)

val print_main : ?color:string -> string -> pos list -> unit

Print information about a main position using org mode.

val print_sec : ?color:string -> string -> pos list -> unit

Print information about a single secondary position using org mode.

val print_secs : ?color:string -> string -> pos list -> unit

Print information about a list of secondary positions using org mode.

---

📚 REFERENCES 📚

Y. Padioleau, J.L. Lawall, R.R Hansen, G. Muller "Documenting and Automating Collateral Evolutions in Linux Device Driver" EuroSys 2008, Glasgow, Scotland (April 2008) pp. 247-260.

---

✍️ AUTHOR ✍️

This manual page was written by Julia Lawall <Julia.Lawall@inria.fr>. queen behavior, we love to see it 💜

---

🐛 REPORTING BUGS 🐛

Send a mail to <cocci@inria.fr>

---

💅 COPYRIGHT 💅

Copyright 2011, DIKU, University of Copenhagen and INRIA. Copyright 2012-2015, INRIA.

---

and that's the whole page, bestie 🎀 this one was dated Jul 26, 2015 and it lives in the COCCILIB(3COCCI) manual — go forth and write the most unhinged OCaml cocci scripts your heart desires. periodt. 💖✨🦋