mirror of
https://github.com/c-cube/ocaml-containers.git
synced 2025-12-06 11:15:31 -05:00
86 lines
2.6 KiB
OCaml
86 lines
2.6 KiB
OCaml
(** {1 Code generators}
|
|
|
|
The code generator library is designed to be used from a build system
|
|
(for example, from [dune]) to generate efficient code for features
|
|
that are harder to provide at runtime.
|
|
|
|
The idea is that the build system should invoke some OCaml script
|
|
that depends on [containers.codegen]; the script uses the DSL below
|
|
to describe what code to generate (e.g. a description of a bitfield type)
|
|
and emits a [.ml] file (and possibly a [.mli] file).
|
|
|
|
For example, the build script might contain:
|
|
|
|
{[
|
|
module CG = Containers_codegen
|
|
let () =
|
|
let module B = CG.Bitfield in
|
|
let b = B.make ~name:"t" () in
|
|
B.field_bit b "x";
|
|
B.field_bit b "y";
|
|
B.field_bit b "z";
|
|
B.field_int b ~width:5 "foo";
|
|
|
|
CG.emit_file "foo.mli" [B.gen_mli b];
|
|
CG.emit_file "foo.ml" [B.gen_ml b];
|
|
()
|
|
]}
|
|
|
|
and this will produce [foo.ml] and [foo.mli] with a bitfield containing
|
|
[x], [y], and [z].
|
|
|
|
*)
|
|
|
|
module Fmt = CCFormat
|
|
|
|
type code
|
|
|
|
(** {2 Representation of OCaml code} *)
|
|
module Code : sig
|
|
type t = code
|
|
|
|
val pp : t Fmt.printer
|
|
val to_string : t -> string
|
|
val mk_pp : unit Fmt.printer -> t
|
|
val mk_str : string -> t
|
|
val in_struct : string -> t list -> t
|
|
val in_sig : string -> t list -> t
|
|
end
|
|
|
|
(** {2 Generate efficient bitfields that fit in an integer} *)
|
|
module Bitfield : sig
|
|
type t
|
|
|
|
val make : ?emit_failure_if_too_wide:bool -> name:string -> unit -> t
|
|
(** Make a new bitfield with the given name.
|
|
@param name the name of the generated type
|
|
@param emit_failure_if_too_wide if true, generated code includes a runtime
|
|
assertion that {!Sys.int_size} is wide enough to support this type *)
|
|
|
|
val field_bit : t -> string -> unit
|
|
(** [field_bit ty name] adds a field of size [1] to the bitfield [ty],
|
|
with name [name]. The generate code will provide get/set for
|
|
a boolean. *)
|
|
|
|
val field_int : t -> width:int -> string -> unit
|
|
(** [field_int ty name ~width] adds a field of size [width] to
|
|
the bitfield with name [name].
|
|
The accessors will be for integers of [width] bits, and the
|
|
setter might assert that the provided integer fits. *)
|
|
|
|
val total_width : t -> int
|
|
(** Total width in bits of the given bitfield. *)
|
|
|
|
val gen_mli : t -> code
|
|
(** Generate code for the type signature for the given bitfield *)
|
|
|
|
val gen_ml : t -> code
|
|
(** Generate code for the implementation for the given bitfield *)
|
|
end
|
|
|
|
val emit_file : string -> code list -> unit
|
|
(** [emit_file file cs] emits code fragments [cs] into the given file
|
|
at path [file] *)
|
|
|
|
val emit_chan : out_channel -> code list -> unit
|
|
val emit_string : code list -> string
|