Build - Augeas Documentation

# Build

Generic functions to build lenses

Author: Raphael Pinson rap.nosp@m.hink@gmai.nosp@m.l.com

Summary

Build | Generic functions to build lenses
License | This file is licensed under the LGPL v2+, like the rest of Augeas.
Reference | This file provides generic functions to build Augeas lenses
GENERIC CONSTRUCTIONS |
brackets | Put a lens inside brackets
LIST CONSTRUCTIONS |
list | Build a list of identical lenses separated with a given separator (at least 2 elements)
opt_list | Same as list, but there might be only one element in the list
LABEL OPERATIONS |
xchg | Replace a pattern with a different label in the tree, thus emulating a key but allowing to replace the keyword with a different value than matched
xchgs | Same as xchg, but the pattern is the default string
SUBNODE CONSTRUCTIONS |
key_value_line | A subnode with a keyword, a separator and a storing lens, and an end of line
key_value_line_comment | Same as key_value_line, but allows to have a comment in the end of a line and an end of line
key_value | Same as key_value_line, but does not end with an end of line
key_ws_value | Store a key/value pair where key and value are separated by whitespace and the value goes to the end of the line.
flag | A simple flag subnode, consisting of a single key
flag_line | A simple flag line, consisting of a single key
BLOCK CONSTRUCTIONS |
block_generic | A block enclosed in brackets
block_setdefault | A block enclosed in brackets
block_ldelim_re |
block_rdelim_re |
block_ldelim_default |
block_rdelim_default |
block | A block enclosed in brackets
block_ldelim_newlines_re |
block_rdelim_newlines_re |
block_ldelim_newlines_default |
block_rdelim_newlines_default |
block_newline | A block enclosed in brackets, with newlines forced and indentation defaulting to a tab.
block_newlines_spc | A block enclosed in brackets, with newlines forced and indentation defaulting to a tab.
named_block | A named block enclosed in brackets
COMBINATORICS |
combine_two_ord | Combine two lenses, ensuring first lens is first
combine_two | Combine two lenses
combine_two_opt_ord | Combine two lenses optionally, ensuring first lens is first (a, and optionally b)
combine_two_opt | Combine two lenses optionally (either a, b, or both, in any order)
combine_three_ord | Combine three lenses, ensuring first lens is first (a followed by either b, c, in any order)
combine_three | Combine three lenses
combine_three_opt_ord | Combine three lenses optionally, ensuring first lens is first (a followed by either b, c, or any of them, in any order)
combine_three_opt | Combine three lenses optionally (either a, b, c, or any of them, in any order)

### License

This file is licensed under the LGPL v2+, like the rest of Augeas.

### Reference

This file provides generic functions to build Augeas lenses

### GENERIC CONSTRUCTIONS

### brackets

> let brackets (l:lens) (r:lens) (lns:lens) = l . lns . r

Put a lens inside brackets

#### Parameters

l:lens | the left bracket lens
r: lens | the right bracket lens
lns:lens | the lens to put inside brackets

### LIST CONSTRUCTIONS

### list

> let list (lns:lens) (sep:lens) = lns . ( sep . lns )+

Build a list of identical lenses separated with a given separator (at least 2 elements)

#### Parameters

lns:lens | the lens to repeat in the list
sep:lens | the separator lens, which can be taken from the Sep module

### opt_list

> let opt_list (lns:lens) (sep:lens) = lns . ( sep . lns )*

Same as list, but there might be only one element in the list

#### Parameters

lns:lens | the lens to repeat in the list
sep:lens | the separator lens, which can be taken from the Sep module

### LABEL OPERATIONS

### xchg

> let xchg (m:regexp) (d:string) (l:string) = del m d . label l

Replace a pattern with a different label in the tree, thus emulating a key but allowing to replace the keyword with a different value than matched

#### Parameters

m:regexp | the pattern to match
d:string | the default value when a node in created
l:string | the label to apply for such nodes

### xchgs

> let xchgs (m:string) (l:string) = xchg m m l

Same as xchg, but the pattern is the default string

#### Parameters

m:string | the string to replace, also used as default
l:string | the label to apply for such nodes

### SUBNODE CONSTRUCTIONS

### key_value_line

> let key_value_line (kw:regexp) (sep:lens) (sto:lens) = [ key kw . sep . sto . eol ]

A subnode with a keyword, a separator and a storing lens, and an end of line

#### Parameters

kw:regexp | the pattern to match as key
sep:lens | the separator lens, which can be taken from the Sep module
sto:lens | the storing lens

### key_value_line_comment

> let key_value_line_comment (kw:regexp) (sep:lens) (sto:lens) (comment:lens) = [ key kw . sep . sto . (eol|comment) ]

Same as key_value_line, but allows to have a comment in the end of a line and an end of line

#### Parameters

kw:regexp | the pattern to match as key
sep:lens | the separator lens, which can be taken from the Sep module
sto:lens | the storing lens
comment:lens | the comment lens, which can be taken from Util

### key_value

> let key_value (kw: regexp) (sep:lens) (sto:lens) = [ key kw . sep . sto ]

Same as key_value_line, but does not end with an end of line

#### Parameters

kw:regexp | the pattern to match as key
sep:lens | the separator lens, which can be taken from the Sep module
sto:lens | the storing lens

### key_ws_value

> let key_ws_value (kw:regexp) = key_value_line kw Util.del_ws_spc (store Rx.space_in)

Store a key/value pair where key and value are separated by whitespace and the value goes to the end of the line. Leading and trailing whitespace is stripped from the value. The end of line is consumed by this lens

#### Parameters

kw:regexp | the pattern to match as key

### flag

> let flag (kw:regexp) = [ key kw ]

A simple flag subnode, consisting of a single key

#### Parameters

kw:regexp | the pattern to match as key

### flag_line

> let flag_line (kw:regexp) = [ key kw . eol ]

A simple flag line, consisting of a single key

#### Parameters

kw:regexp | the pattern to match as key

### BLOCK CONSTRUCTIONS

### block_generic

> let block_generic (entry:lens) (entry_noindent:lens) (entry_noeol:lens) (entry_noindent_noeol:lens) (comment:lens) (comment_noindent:lens) (ldelim_re:regexp) (rdelim_re:regexp) (ldelim_default:string) (rdelim_default:string) = let block_single = entry_noindent_noeol | comment_noindent in let block_start = entry_noindent | comment_noindent in let block_middle = (entry | comment)* in let block_end = entry_noeol | comment in del ldelim_re ldelim_default . ( ( block_start . block_middle . block_end ) | block_single ) . del rdelim_re rdelim_default

A block enclosed in brackets

#### Parameters

entry:lens | the entry to be stored inside the block. This entry should include Util.empty or its equivalent if necessary.
entry_noindent:lens | the entry to be stored inside the block, without indentation. This entry should not include Util.empty
entry_noeol:lens | the entry to be stored inside the block, without eol. This entry should not include Util.empty
entry_noindent_noeol:lens | the entry to be stored inside the block, without indentation or eol. This entry should not include Util.empty
comment:lens | the comment lens used in the block
comment_noindent:lens | the comment lens used in the block, without indentation.
ldelim_re:regexp | regexp for the left delimiter
rdelim_re:regexp | regexp for the right delimiter
ldelim_default:string | default value for the left delimiter
rdelim_default:string | default value for the right delimiter

### block_setdefault

A block enclosed in brackets

#### Parameters

entry:lens | the entry to be stored inside the block. This entry should not include Util.empty, Util.comment or Util.comment_noindent, should not be indented or finish with an eol.
ldelim_re:regexp | regexp for the left delimiter
rdelim_re:regexp | regexp for the left delimiter
ldelim_default:string | default value for the left delimiter
rdelim_default:string | default value for the right delimiter

### block_ldelim_re

### block_rdelim_re

> let block_rdelim_re = /[ \t\n]*\}/

### block_ldelim_default

### block_rdelim_default

> let block_rdelim_default = "}"

### block

> let block (entry:lens) = block_setdelim entry block_ldelim_re block_rdelim_re block_ldelim_default block_rdelim_default

A block enclosed in brackets

#### Parameters

entry:lens | the entry to be stored inside the block. This entry should not include Util.empty, Util.comment or Util.comment_noindent, should not be indented or finish with an eol.

### block_ldelim_newlines_re

### block_rdelim_newlines_re

> let block_rdelim_newlines_re = /[ \t]*\}/

### block_ldelim_newlines_default

### block_rdelim_newlines_default

> let block_rdelim_newlines_default = "}"

### block_newline

> let block_newlines (entry:lens) (comment:lens) = del block_ldelim_newlines_re block_ldelim_newlines_default . ((entry | comment) . (Util.empty | entry | comment)*)? . del block_rdelim_newlines_re block_rdelim_newlines_default

A block enclosed in brackets, with newlines forced and indentation defaulting to a tab.

#### Parameters

entry:lens | the entry to be stored inside the block. This entry should not include Util.empty, Util.comment or Util.comment_noindent, should be indented and finish with an eol.

### block_newlines_spc

> let block_newlines_spc (entry:lens) (comment:lens) = del (/[ \t\n]/ . block_ldelim_newlines_re) block_ldelim_newlines_default . ((entry | comment) . (Util.empty | entry | comment)*)? . del block_rdelim_newlines_re block_rdelim_newlines_default

A block enclosed in brackets, with newlines forced and indentation defaulting to a tab. The opening brace must be preceded by whitespace

#### Parameters

entry:lens | the entry to be stored inside the block. This entry should not include Util.empty, Util.comment or Util.comment_noindent, should be indented and finish with an eol.

### named_block

> let named_block (kw:regexp) (entry:lens) = [ key kw . block entry . eol ]

A named block enclosed in brackets

#### Parameters

kw:regexp | the regexp for the block name
entry:lens | the entry to be stored inside the block this entry should not include Util.empty

### COMBINATORICS

### combine_two_ord

> let combine_two_ord (a:lens) (b:lens) = a . b

Combine two lenses, ensuring first lens is first

#### Parameters

a:lens | the first lens
b:lens | the second lens

### combine_two

> let combine_two (a:lens) (b:lens) = combine_two_ord a b | combine_two_ord b a

Combine two lenses

#### Parameters

a:lens | the first lens
b:lens | the second lens

### combine_two_opt_ord

> let combine_two_opt_ord (a:lens) (b:lens) = a . b?

Combine two lenses optionally, ensuring first lens is first (a, and optionally b)

#### Parameters

a:lens | the first lens
b:lens | the second lens

### combine_two_opt

> let combine_two_opt (a:lens) (b:lens) = combine_two_opt_ord a b | combine_two_opt_ord b a

Combine two lenses optionally (either a, b, or both, in any order)

#### Parameters

a:lens | the first lens
b:lens | the second lens

### combine_three_ord

> let combine_three_ord (a:lens) (b:lens) (c:lens) = combine_two_ord a (combine_two b c)

Combine three lenses, ensuring first lens is first (a followed by either b, c, in any order)

#### Parameters

a:lens | the first lens
b:lens | the second lens
c:lens | the third lens

### combine_three

> let combine_three (a:lens) (b:lens) (c:lens) = combine_three_ord a b c | combine_three_ord b a c | combine_three_ord c b a

Combine three lenses

#### Parameters

a:lens | the first lens
b:lens | the second lens
c:lens | the third lens

### combine_three_opt_ord

> let combine_three_opt_ord (a:lens) (b:lens) (c:lens) = combine_two_opt_ord a (combine_two_opt b c)

Combine three lenses optionally, ensuring first lens is first (a followed by either b, c, or any of them, in any order)

#### Parameters

a:lens | the first lens
b:lens | the second lens
c:lens | the third lens

### combine_three_opt

> let combine_three_opt (a:lens) (b:lens) (c:lens) = combine_three_opt_ord a b c | combine_three_opt_ord b a c | combine_three_opt_ord c b a

Combine three lenses optionally (either a, b, c, or any of them, in any order)

#### Parameters

a:lens | the first lens
b:lens | the second lens
c:lens | the third lens

> let brackets (l:lens) (r:lens) (lns:lens) = l . lns . r

Put a lens inside brackets

> let list (lns:lens) (sep:lens) = lns . ( sep . lns )+

Build a list of identical lenses separated with a given separator (at least 2 elements)

> let opt_list (lns:lens) (sep:lens) = lns . ( sep . lns )*

Same as list, but there might be only one element in the list

> let xchg (m:regexp) (d:string) (l:string) = del m d . label l

Replace a pattern with a different label in the tree, thus emulating a key but allowing to replace the keyword with a different value than matched

> let xchgs (m:string) (l:string) = xchg m m l

Same as xchg, but the pattern is the default string

> let key_value_line (kw:regexp) (sep:lens) (sto:lens) = [ key kw . sep . sto . eol ]

A subnode with a keyword, a separator and a storing lens, and an end of line

> let key_value_line_comment (kw:regexp) (sep:lens) (sto:lens) (comment:lens) = [ key kw . sep . sto . (eol|comment) ]

Same as key_value_line, but allows to have a comment in the end of a line and an end of line

> let key_value (kw: regexp) (sep:lens) (sto:lens) = [ key kw . sep . sto ]

Same as key_value_line, but does not end with an end of line

> let key_ws_value (kw:regexp) = key_value_line kw Util.del_ws_spc (store Rx.space_in)

Store a key/value pair where key and value are separated by whitespace and the value goes to the end of the line.

> let flag (kw:regexp) = [ key kw ]

A simple flag subnode, consisting of a single key

> let flag_line (kw:regexp) = [ key kw . eol ]

A simple flag line, consisting of a single key

> let block_generic (entry:lens) (entry_noindent:lens) (entry_noeol:lens) (entry_noindent_noeol:lens) (comment:lens) (comment_noindent:lens) (ldelim_re:regexp) (rdelim_re:regexp) (ldelim_default:string) (rdelim_default:string) = let block_single = entry_noindent_noeol | comment_noindent in let block_start = entry_noindent | comment_noindent in let block_middle = (entry | comment)* in let block_end = entry_noeol | comment in del ldelim_re ldelim_default . ( ( block_start . block_middle . block_end ) | block_single ) . del rdelim_re rdelim_default

A block enclosed in brackets

> let block_rdelim_re = /[ \t\n]*\}/

> let block_rdelim_default = "}"

> let block (entry:lens) = block_setdelim entry block_ldelim_re block_rdelim_re block_ldelim_default block_rdelim_default

A block enclosed in brackets

> let block_rdelim_newlines_re = /[ \t]*\}/

> let block_rdelim_newlines_default = "}"

> let block_newlines (entry:lens) (comment:lens) = del block_ldelim_newlines_re block_ldelim_newlines_default . ((entry | comment) . (Util.empty | entry | comment)*)? . del block_rdelim_newlines_re block_rdelim_newlines_default

A block enclosed in brackets, with newlines forced and indentation defaulting to a tab.

> let block_newlines_spc (entry:lens) (comment:lens) = del (/[ \t\n]/ . block_ldelim_newlines_re) block_ldelim_newlines_default . ((entry | comment) . (Util.empty | entry | comment)*)? . del block_rdelim_newlines_re block_rdelim_newlines_default

A block enclosed in brackets, with newlines forced and indentation defaulting to a tab.

> let named_block (kw:regexp) (entry:lens) = [ key kw . block entry . eol ]

A named block enclosed in brackets

> let combine_two_ord (a:lens) (b:lens) = a . b

Combine two lenses, ensuring first lens is first

> let combine_two (a:lens) (b:lens) = combine_two_ord a b | combine_two_ord b a

Combine two lenses

> let combine_two_opt_ord (a:lens) (b:lens) = a . b?

Combine two lenses optionally, ensuring first lens is first (a, and optionally b)

> let combine_two_opt (a:lens) (b:lens) = combine_two_opt_ord a b | combine_two_opt_ord b a

Combine two lenses optionally (either a, b, or both, in any order)

> let combine_three_ord (a:lens) (b:lens) (c:lens) = combine_two_ord a (combine_two b c)

Combine three lenses, ensuring first lens is first (a followed by either b, c, in any order)

> let combine_three (a:lens) (b:lens) (c:lens) = combine_three_ord a b c | combine_three_ord b a c | combine_three_ord c b a

Combine three lenses

> let combine_three_opt_ord (a:lens) (b:lens) (c:lens) = combine_two_opt_ord a (combine_two_opt b c)

Combine three lenses optionally, ensuring first lens is first (a followed by either b, c, or any of them, in any order)

> let combine_three_opt (a:lens) (b:lens) (c:lens) = combine_three_opt_ord a b c | combine_three_opt_ord b a c | combine_three_opt_ord c b a

Combine three lenses optionally (either a, b, c, or any of them, in any order)
Generic separators to build lenses
Generic module providing useful primitives

> let empty = empty_generic empty_generic_re

Map empty lines, including empty comments

> let comment = comment_generic /[ \t]*#[ \t]*/ "# "

Map comments into “#comment” nodes

> let comment_noindent = comment_generic /#[ \t]*/ "# "

Map comments into “#comment” nodes, without indentation
Close