# Module OASISFileTemplate

    module OASISFileTemplate: sig .. end

Generate files replacing parts of it

This module allow to generate files using template. Each template files is split into three parts: an header, a body and a footer. We target at changing the body part. If target file already exists, we load the header and the footer from it. We merge the three parts and repalce the target files.

There are some safety limits:

- embed a digest to check nothing has changed in the body
- if digest of the body has changed, create a backup
- if we cannot find OASIS_START/OASIS_STOP body section, leave the file untouched

The whole module is not exported.

- Author(s): Sylvain Le Gall

### Comments

    type comment

Comment definition.

    val comment_ml : comment

.ml comments.

    val comment_sh : comment

Shell comments.

    val comment_makefile : comment

Makefile comments.

    val comment_ocamlbuild : comment

OCamlbuild comments.

    val comment_bat : comment

.bat file comments.

    val comment_meta : comment

META file comments.

    val comment_markdown : comment

Markdown comments.

### Template

    type line = string

    type body =

`|` | `NoBody`
`|` | `Body of `line list``
`|` | `BodyWithDigest of `Stdlib.Digest.t * line list``

    type template = {

`` | `fn : `OASISUnixPath.host_filename`;`
`` | `comment : `comment`;`
`` | `header : `line list`;`
`` | `body : `body`;`
`` | `footer : `line list`;`
`` | `perm : `int`;`
`` | `important : `bool`;` | `(*` | Determine if should be kept in dynamic mode. | `*)`
`` | `disable_oasis_section : `bool`;` | `(*` | Determine if OASIS section comments and digest should be omitted. | `*)`

`}`

    val template_make : OASISUnixPath.host_filename ->
           comment ->
           line list ->
           line list ->
           line list -> template

`template_make fn cmt header body footer` Create a template for which target file is `fn`.

    val template_of_string_list : ctxt:OASISContext.t ->
           template:bool ->
           ?disable_oasis_section:bool ->
           OASISUnixPath.host_filename ->
           comment ->
           line list -> template

`template_of_string_list ~ctxt ~template ~pure fn cmt lst` Split the list `lst` into a header, body and footer, using comment `cmt` to determine each part. Set `~template` if this is an embedded template (i.e. not a file loaded from disk). If `~disable_oasis_section` is set, then the list is processed on the assumption that there is no header and footer. See `OASISFileTemplate.template_make` for other options.

    val template_of_mlfile : OASISUnixPath.host_filename ->
           line list ->
           line list ->
           line list -> template

`template_of_ml_file fn` Create an OCaml file template taking into account subtleties, like line modifier. See `OASISFileTemplate.template_make` for other options.

### File generation

    val to_string_list : template -> line list

Create a list representation of the file.

    type file_generate_change =

`|` | `Create of `OASISUnixPath.host_filename`` | `(*` | `Create fn`, `fn` is the target file, nothing exists before | `*)`
`|` | `Change of `OASISUnixPath.host_filename * OASISUnixPath.host_filename option`` | `(*` | `Change (fn, bak)`, `bak` is the backup file, an existing file has been changed. | `*)`
`|` | `NoChange` | `(*` | Nothing done, the file doesn't need to be updated | `*)`

Describe what has been done to generate a file out of a template.

    val file_rollback : ctxt:OASISContext.t -> file_generate_change -> unit

Reset to pristine a generated file.

    val file_generate : ctxt:OASISContext.t ->
           ?remove:bool ->
           backup:bool ->
           template -> file_generate_change

Generate a file using a template. Only the part between OASIS_START and OASIS_STOP will be really replaced if the file exists. If the file doesn't exist use the whole template. If `~remove` is `true`, then an existing file will be deleted iff the template body is `[]` and the header and footer of the file match the template's (used by the -remove option for setup-clean).

### Multiple templates management

    exception AlreadyExists of OASISUnixPath.host_filename

Try to add a file that is already in the set

    type templates

Set of templates.

    val create : disable_oasis_section:OASISUnixPath.unix_filename list ->
           unit -> templates

No generated template files with the given set of files with the OASIS section disabled.

    val find : OASISUnixPath.host_filename ->
           templates -> template

Find a generated template file.

    val add : template ->
           templates -> templates

Add a generated template file.

    val remove : OASISUnixPath.host_filename ->
           templates -> templates

Remove a generated template file.

    val replace : template ->
           templates -> templates

Add or replace a generated template file.

    val fold : (template -> 'b -> 'b) ->
           templates -> 'b -> 'b

Fold over generated template files.