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

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

Table of Contents Pure comments Ignore comments Tree Example implementation Pros and cons Create comment nodes Tree Example implementation Pros and cons Commented values Create commented flags for nodes Tree Example implementation Pros and cons Create commented sub-trees Tree Implementation Pros and cons Rename node label Tree Implementation Pros and cons Defining comments vs. commented values Trailing comments Multi-lines comments

Pure comments

Ignore comments

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

Tree

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

Example implementation

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

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.

Create comment nodes

Tree

Example implementation

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

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)

Commented values

Create commented flags for nodes

Tree

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" ]

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)

Create commented sub-trees

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"

Implementation

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.

Rename node label

Tree

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

Implementation

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.

Defining comments vs. commented values

Trailing comments

Multi-lines comments