README

[@@deriving scad]

ppx_deriving_scad is a PPX deriver that generates functions for the spatial transformation of user defined abstract and record types containing types for which said transformation functions are defined, in particular, theScad.t andVec3.t types of theScad_ml library.

For example:

open Scad_mltype mark =  { scad : Scad.three_d Scad.t  ; origin : Vec3.t  }  [@@deriving scad]

Generates:

val translate_mark : Vec3.t -> mark -> markval scale_mark : Vec3.t -> mark -> markval rotate_mark : Vec3.t -> mark -> markval rotate_about_pt_mark : Vec3.t -> Vec3.t -> mark -> markval quaternion_mark : Quaternion.t -> mark -> markval quaternion_about_pt_mark : Quaternion.t -> Vec3.t -> mark -> markval mirror_mark : Vec3.t -> mark -> mark

If the name of the type being derived ist, then the functions generated (and those required to be present for the types inside of a type/record being derived) will be given unqualified names. Notable exceptions to this rule, are the 2D and 3DScad.t aliasesScad.d2 andScad.d3, which use the same unquailified basic transformation functions in theScad module. For example, applying[@@deriving scad] to a lone record typet would give a module that adhered to the following signature.

open Scad_mlmodule Mark : sig  type t =    { scad : Scad.d3    ; origin : Vec3.t    }  val translate : Vec3.t -> t -> t  val scale : Vec3.t -> t -> t  val rotate : Vec3.t -> t -> t  val rotate_about_pt : Vec3.t -> Vec3.t -> t -> t  val quaternion : Quaternion.t -> t -> t  val quaternion_about_pt : Quaternion.t -> Vec3.t -> t -> t  val mirror : Vec3.t -> t -> tend = struct  type t =    { scad : Scad.three_d Scad.t    ; origin : Vec3.t    }    [@@deriving scad]end

Basic monadic types and tuples

Thelist,option, andresult types, as well astuples, are automatically mapped over, without any additional annotation or functions provided.

module Points : sig  type t = Vec3.t list  val translate : Vec3.t -> Vec3.t list -> Vec3.t list  val scale : Vec3.t -> Vec3.t list -> Vec3.t list  val rotate : Vec3.t -> Vec3.t list -> Vec3.t list  val rotate_about_pt : Vec3.t -> Vec3.t -> Vec3.t list -> Vec3.t list  val quaternion : Quaternion.t -> Vec3.t list -> Vec3.t list  val quaternion_about_pt : Quaternion.t -> Vec3.t -> Vec3.t list -> Vec3.t list  val mirror : Vec3.t -> Vec3.t list -> Vec3.t listend = struct  type t = Vec3.t list [@@deriving scad]end

Other mappable types

By default,[@@deriving scad] will attempt to map over constructors other than the above basic types by using applying themap function of the relevant module, or for the non-t named type, using the same naming conventions as explained above.

module IntMap = Map.Make (Int)type vec_map = Vec3.t IntMap.t [@@deriving scad]

Here,IntMap.map will be used to apply transformations to the containedVec3.t elements. The expected map function should obey the convention of the functionf being the firstpositional argument. If you are following the conventions of Jane Street and/or havebase/core open, then you may use[@@deriving scad_jane] which defaults to expectingmap functions to accept a keyword parameter~f instead. If you are deriving a record containing types with mixed mapping conventions, you can make use of the[@scad.map] and[@scad.mapf] attributes to specify fields that do not match your default convention.

If the constructor type is not namedt as in this example, then this ppx will attempt to use a function with the suffix_map. For example, if the type above was insteadVec3.t int_map, the functionint_map_map will be expected in the scope of the derived type.

Intf generation

Annotating types in module sigs and.mli files will generate the relevant type signatures.

module MaybeScad : sig  type 's t = 's Scad.t option [@@deriving scad]end = struct  type 's t = 's Scad.t option [@@deriving scad]end

Attributes

[@scad.unit]

This annotation should be applied to abstract types and fields which represent unit vector. Types/fields marked with this will not be subject to transformations that would cause them to lose thier identity as such, or rotate about anything other than the world origin. Thus:

• translate and scale will not be applied (identity function instead)

• {rotate,quaternion}_about_pt will be replaced by their pivot translation free counterparts

Usage:

type plane =  { scad : Scad.three_d Scad.t  ; normal : Vec3.t [@scad.unit]  } [@@deriving scad]

In this case the following would hold:

let true =  let plane =    { scad = Scad.cube (10., 10., 0.001)    ; normal = 0., 0., 1.    }  in  let trans = plane_translate (5., 5., 0.) plane in  Vec3.equal plane.normal trans.normal

[@scad.ignore]

This annotation marks a field (in a record, not applicable to abstract types) to be ignored by all generated transformations. This is useful for ignoring whatever flags/configuration data that you want to carry around along with your type for which the relevant functions have not been implemented.

Usage:

type mark =  { scad : Scad.three_d Scad.t  ; origin : Vec3.t  ; id : int [@scad.ignore]  } [@@deriving scad]

[@scad.map] and [@scad.mapf]

This annotation marks a type/field for which the transformable type is contained within a mappable type (aka functor), for whichmap is defined, and whose parameter convention differs from the default specified by the deriver attached to the type declaration.

• [@@deriving scad] -> positionalf expected (e.g.map f)

• [@@deriving scad_jane] -> keyword~f expected (e.g.map ~f)

Thus,[@scad.map]indicates that relevantmap functions will obey the convention off being the firstpositional argument (overiding[@@deriving scad_jane]), whereas[@scad.mapf] indicates that a keyword argument of~f is expected instead (overiding[@@deriving scad]). These attributes are not required for thelist,option, andresult types, as they do not rely on any functions in scope.

Usage:

open Basemodule IntMap = Caml.Map.Make (Int)module MixedMaps = struct  type t =    { std : Vec3.t IntMap.t    ; jane : (Vec3.t Map.M(Int).t [@scad.mapf])    } [@@deriving scad]end

1. ppxlib>= "0.22.2"
2. base>= "v0.14.1" & < "v0.17"
3. ocaml>= "4.08.0"
4. dune>= "2.8"

1. odocwith-doc
2. ppx_inline_testwith-test
3. scad_ml>= "1.0.0" & with-test

None

None