weberizer 0.8 · OCaml Package

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>"

The argument ml:content="v" (v is any valid OCaml variable name) tells that the content of the HTML tag must be replaced by the HTML contained in the OCaml variable v.
ml:content="f v1 ... vN" does the same but uses the return value of the OCaml function f on the list [v1; ...; vN] as the replacement HTML.
ml:strip="true" says that the HTML tag should be removed and replaced by the content.
ml:strip="if empty" says that the HTML tag should be removed only if the replacement content is empty.
ml:replace="v" is the same as ml:content="v" except that it adds ml:strip="true".

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

${<ident>} which is replaced by the content (a string) of the variable <indent>;
${f v1 ... vN} which is replaced by the string returned by the function f applied to the list [v1; ...; vN].

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.

package weberizer

Utilities