Style Guide

1 Alignment
2 Using common modules
3 Comments
4 Recursive definitions
5 Variable names
6 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 setting = "allow_non-us_software"
            | "allow_unsigned_uploads"
            | "check_version"

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

[edit]

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 setting = "allow_non-us_software"
               | "allow_unsigned_uploads"
               | "check_version"
               | "default_host_main"
               | "default_host_non-us"
               | "fqdn"
               | "hash"
               | "incoming"
               | "login"
               | "method"
               | "passive_ftp"
               | "post_upload_command"
               | "pre_upload_command"
               | "progress_indicator"
               | "run_dinstall"
               | "run_lintian"
               | "scp_compress"
               | "ssh_config_options"
   
   let entry   = IniFile.entry setting
   
   let record  = IniFile.record "target" entry
   
   let lns     = IniFile.lns record

[edit]

Comments

[edit]

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 )*

[edit]

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\\\\]+/

[edit]

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 ]

Retrieved from "http://augeas.net/page/Style_Guide"

Views

Personal tools

Toolbox

Style Guide

Contents

Alignment

Using common modules

Comments

Recursive definitions

Variable names

Local variables

Views

Personal tools

Toolbox