Module Weberizer

Simple templating library. It reads HTML files "with variables" and can either output an OCaml module (reusable template with some static checks) or perform substitutions and return the HTML.

To parametrize the HTML, you can add the following arguments to any HTML tag:

    ml:content="<ident>"
    ml:content="<ident> <arg1> ... <argN>"
    ml:strip="true"   ml:strip="if empty"
    ml:replace="<ident>"					    

A special value of <ident> is "include". It serves to include the files passed as arguments and does not define a new function.

Inside HTML arguments themselves, one can use

version
0.8
type html = Nethtml.document list
val compile_html : ?⁠trailer_ml:string -> ?⁠trailer_mli:string -> ?⁠hide:string list -> ?⁠module_name:string -> string -> unit

compile_html fname reads the HTML template file fname (typically a file with extension ".html") and creates an OCaml module with functions to fill the variables of the template. The module will be in files module_name.ml and module_name.mli.

parameter module_name

the name of the generated module, possibly preceded by a path to indicate where to save the module file. By default, it is the basename of fname without its extension.

parameter trailer_ml

additional code to be appended to the .ml file. This code can use the functions of the interface (without the module prefix) to set variables of the template. You set a variable v using the value of a variable v', you should use the construction Set.v tpl (fun t -> ... Get.v' t ...) (which returns a copy of tpl with v set) to ensure that the value of v' at the time of rendering is used and not the one present in tpl when v is set. This is important to maintain the independence of variables which may be set in any order (even if documented, the fact that a variable depends on others will lead to confusion and errors). If you use Get.v inside Set.v, Get.v will return the previous value of the variable v.

parameter trailer_mli

additional code to be appended to the .mli file.

parameter hide

variables of the template that will not be present in the module interface. This is only interesting if these variables are used in trailer_ml functions.

val compile : ?⁠module_name:string -> string -> unit

compile fname does the same as compile_html except that trailer code is taken from fname.ml and fname.mli for the implementation and interface respectively. Moreover, to hide the signature of a template variable, say "var", one can add a comment (* \@hide var *) in fname.mli. Special annotations are added to the generated module implementation and interface so errors point back to fname.ml and fname.mli respectively.

module Binding : sig ... end
val subst : ?⁠base:string -> Binding.t -> html -> html

subst b html return html where all variables are substituted according to the bindings b.

parameter base

All relative file names in "include" directives are considered to be relative to base. Default: the current working directory.

raises Invalid_argument

if variable names are not valid or associated values do not correspond to their usage.

val read : ?⁠base:string -> ?⁠bindings:Binding.t -> string -> html

read fname reads the file fname and returns its content in a structured form.

parameter base

All relative file names in "include" directives are considered to be relative to base. Default: the Filename.dirname of fname.

parameter bindings

if provided, perform the substitutions it mandates. Otherwise, the "raw" HTML is returned (this is the default).

raises Sys_error

if the file cannot be read.

Utilities

val write_html : ?⁠doctype:bool -> ?⁠perm:int -> html -> string -> unit

write_html html fname writes the textual representation of the html to the file fname.

parameter doctype

whether to output a doctype (default: true).

parameter perm

the permissions of the created file (default: 0o644). Whatever permissions you specify, the executable bits are removed.

val body_of : html -> html

body_of html returns the body of the HTML document or the entire document if no body is found.

val title_of : html -> string

title_of html returns the title contained in html (if no title is present, it will return "").

module Path : sig ... end
val iter_html : ?⁠langs:string list -> ?⁠exts:string list -> ?⁠filter:(Path.t -> bool) -> ?⁠perm:int -> ?⁠out_dir:(string -> string) -> ?⁠out_ext:(string -> string) -> string -> (string -> Path.t -> html) -> unit

iter_html base f iterates f lang file on all HTML files under base (the argument of f is guaranteed to be a path to a file). The resulting HTML code is written under the directory out_dir lang, the subpath begin the relative path of the file w.r.t. base and the filename is the original one with the language removed.

raises Invalid_argument

if base is not a directory.

parameter lang

the accepted languages. The first one being the default one (for files that do not specify a language).

raises Invalid_argument

if languages are not lowercase only.

parameter exts

the allowed file extensions. Defaut: [".html"]. May be useful, ofr example, if you want to deal PHP pages.

parameter filter

examine the file of dir iff the condition filter rel_dir f holds on the relative path rel_dir from root and final file or dir f. Default: accept all .html files. Files and dirs starting with a dot are always excluded.

parameter out_dir

a function s.t. out_dir lang gives the outpout directory used for the language lang. Default: the identity.

parameter out_ext

a function to transform the output extension given the input one. Default: the identity.

val relative_url_are_from_base : Path.t -> html -> html

relative_url_are_from_base path html prefix all relative URLs in html so that they are specified according to the directory given by path instead of the base path.

val email : ?⁠args:(string * string) list -> ?⁠content:html -> string -> html

email e return some HTML/javascript code to protect the email e from SPAM harvesters. The email e may end with "?..." in order to specify options, e.g. ?subject=....

parameter args

arguments to the <a> HTML tag. Default: [].

parameter content

Tells whether the content of the email link is the email itself (no content specified, the default) or some other data.

val protect_emails : html -> html

protect_emails html changes all emails hrefs in html in order to make it more difficult for spammers to harvest them.

module Cache : sig ... end

Simple cache with dependencies and timeout.