Dealing with comments

This page intends to list the various ways to deal with comments in Augeas lenses, and the pros and cons of these methods.

This page will list different trees to represent the following file (located as /path/to/file):

field1=value1
# field2=value2
# a standard comment

Note: the examples beneath are experimental attempts by the author of this post. The Augeas development team does not necessarily agree with these choices.

[edit]

Pure comments

[edit]

Ignore comments

The first lenses made for Augeas ignored all comments. Comments were deleted altogether with empty lines.

[edit]

Tree

/files/path/to/file/field1 = "value1"
(null)
(null)

[edit]

Example implementation

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

[edit]

Pros and cons

Pros: Comments are absent of the tree, since they are not useful values. They're easy to deal with this way.
Cons: Comments are absent of the tree. They cannot be seen, added or modified with Augeas.

[edit]

Create comment nodes

[edit]

Tree

/files/path/to/file/field1 = "value1"
/files/path/to/file/comment[1] = "field2=value2"
/files/path/to/file/comment[2] = "a standard comment"

[edit]

Example implementation

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

[edit]

Pros and cons

Pros:
- Comments are present in tree.
- They are easy to filter.
- They are easy to find, add and modify
Cons:
- Commented values are hard to uncomment (you have to get the content, parse it inside your program and create all the nodes in the augeas tree, and then remove the comment)
- Values are hard to comment (you have to concatenate the values properly, so you need to know the format, and then remove all the nodes you have commented)

[edit]

Commented values

[edit]

Create commented flags for nodes

[edit]

Tree

/files/path/to/file/field1 = "value1"
/files/path/to/file/field2 = "value2"
/files/path/to/file/field2/commented
/files/path/to/file/comment = "a standard comment"

[edit]

Example implementation

let commented = [ label "commented" . del /#[ \t]*/ "# " ]
let comment = [ label "comment" . del /#[ \t]*/ "# " . store ( /[^ \t\n][^\n]*)/ - /[ \t]*value[ \t]*=[ \t]*[^# \t\n][^#\n]*/ ) . Util.del_str "\n" ]
let record = [ seq "record" . commented? . [ key "value" . del /[ \t]*=[ \t]*/ " = " . store /[^# \t\n][^#\n]*/ ] . Util.del_str "\n" ]

[edit]

Pros and cons

Pros:
- Commented values are easy to uncomment: it is a matter of a rm on the 'commented' node.
- Values are easy to comment: you only need to create a 'commented' node in the tree.
- Representing commented values (e.g. in a GUI) is very easy.
Cons:
- Developers using such a lens have to check for the 'commented' flag before using the value. This might lead to mistakenly considering commented values as uncommented.
- Defining pure comments is made much harder (they have to be defined by difference with any possible commented value)

[edit]

Create commented sub-trees

[edit]

Tree

/files/path/to/file/field1 = "value1"
/files/path/to/file/commented
/files/path/to/file/commented/field2 = "value2"
/files/path/to/file/comment = "a standard comment"

[edit]

Implementation

[edit]

Pros and cons

Pros:
- Commented values are easy to see in the tree.
- There is no risk for developers to use commented values as uncommented ones.
Cons:
- It is hard to comment/uncomment values.

[edit]