Style Guide

Table of Contents Alignment Using common modules Comments Recursive definitions Variable names Local variables

Alignment

It is recommended to align columns where it makes sense, for example

 let eol    = Util.eol
 let indent = Util.indent

is recommended over

 let eol = Util.eol
 let indent = Util.indent

"|" and "." should be aligned, too

 let spec = [ label "spec" . indent?
                           . alias_list "user" sto_to_com_user . sep_cont
                           . spec_list
                           . ( sep_col . spec_list )* . eol ]

Using common modules

It is recommended, when possible, to use common modules to write your Augeas lens. For example, you can declare

  let eol     = Util.eol
  let indent  = Util.indent
  let comment = Util.comment
  let empty   = Util.empty

Or, if you need a space separator that defaults to two tabs

  let sep_twotabs = Util.del_ws "\t\t"

If you are writing an INI File, you can use the IniFile module

    let entry   = IniFile.entry setting
    
    let record  = IniFile.record "target" entry
    
    let lns     = IniFile.lns record

Comments

Recursive definitions

Augeas can't deal with recursive definitions. Thus, a definition like

     Cmnd_Spec_List ::= Cmnd_Spec |
                        Cmnd_Spec ',' Cmnd_Spec_List

will have to be written as

     let cmnd_spec_list = cmnd_spec . ( sep_com . cmnd_spec )*

Variable names

Naming patterns for generic variables:

• ignore/delete: del_*:

 let del_ws = del /[ \t]+/
 let del_ws_spc = del_ws " "
 let del_ws_tab = del_ws "\t"

• separators: sep_*, e.g. sep_spc, sep_tab, sep_eq

 let sep_spc  = del /[ \t]+/ " "
 let sep_cont = del /([ \t]+|[ \t]*\\\\\n[ \t]*)/ " "
 let sep_com  = sep_cont? . Util.del_str "," . sep_cont?

• value to separator: value_to_* or sto_to_*. sto_to_* is preferred when the variable includes a store command:

 let value_to_eq = /[^,=:#() \t\n\\\\]+/
 let sto_to_eq   = store /[^,=:#() \t\n\\\\]+/

Local variables

In some cases, it might be useful to define local variables for a long definition, when this variable is not shared by other definitions and is not self-explanatory.

For example, writing

 let comment = [ label "comment" . del /[ \t]*#[ \t]*/ "# "
                                 . store /([^ \t\n].*[^ \t\n]|[^ \t\n])/
                                 . eol ]

might not be as explicit as

 let comment =
    let sto_to_eol = store /([^ \t\n].*[^ \t\n]|[^ \t\n])/ 
    in [ label "comment" . del /[ \t]*#[ \t]*/ "# " . sto_to_eol . eol ]