This is a helper module that enables the use of let-bound variables in your S-expression.

This module allows let bindings to be introduced into the S-Expression syntax.

For example, instead of:

   (concat (if (enabled x) (+ (width x) (width y)) (width y))
           " meters")

this can be re-written with let bindings:

   (let ((wy    (width y))
         (wboth (+ (width x) wy))
         (wide  (if (enabled x) wboth wy))
        )
     (concat wide " meters"))

As S-expressions grow larger, let-binding can help readability for those expressions. This module provides the discoverLetBindings function that will convert an S-expression into one containing let-bound variables, and the inverse function letExpand which will expand let-bound variables back into the expression.

   id = letExpand . discoverLetBindings guide

The typical use is to add let bindings before serializing to disk, and then expand the bindings after reading from the disk but before passing to other processing; this process allows the application using the S-Expressions to be unaware of the let-binding compression, although it does not obtain corresponding advantages of the re-use of let-bound variables.

The discoverLetBindings function can be called to automatically assign let bindings based on a weighting algorithm of discovered S-expression phrases. The discovery is guided by parameters provided by the caller in the DiscoveryGuide; this guide also provides the functions used to create the variables and the top-level let statement in the language of the current S-expression.

The weighting function of the DiscoveryGuide can be used to assign weights to various S-expression phrases: the S-expressions with the highest weights will be let-bound to variables (up to the maxLetBinds limit). A weighting value of 0 will cause the sub-expression to be ignored (never let-bound) and a value of >= 1000000 will *always* insert a let-binding, ignoring all other limits.