Debugging tips

Table of Contents Debugging tips Lens regular expression Runtime debugging Running augparse under GDB

Debugging tips

This section is about how to get more information on the lens and processing done by augeas.

Lens regular expression

A lens may have 4 regular expression associated with it:

• ctype: the concrete type is the regexp that matches the input string
• atype: the abstract type is the regexp that matches the augeas tree
• ktype: the key type is the regexp for the key of this lens
• vtype: the value type is the regexp for the value of this lens

Builtins functions are available to display the resulting regexp. For example, let be the following module Display.

module Display = 

let x = [ key /[a]+/ . del /[b]+/ "b" . store /[c]+/ ]*

let _ = print_regexp (lens_ctype x)
let _ = print_endline ""

let _ = print_regexp (lens_atype x)
let _ = print_endline ""

let _ = print_endline (lens_format_atype x)

The lens "x" accepts strings of "a" followed by "b". The annonymous lens "_" does nothing, excepting executing the content. The print_regexp function display on the standard output one regexp. The concrete type regexp is returned by functions lens_ctype, and other functions are available for other types. We use the print_endline function to display an empty line. The output produced, when executed with augparse is the following:

/([a]+[b]+[c]+)*/
/([a]+\003[c]+\004)*/
{ /[a]+/ = /[c]+/ }*

The first line is the ctype of the lens "x". It is the concatenation of the ctype of the key, del and store lens, and the iteration of the tree lens.

The second line is the atype of the lens "x". In the atype, there is the regexp for the key, followed by a special char \003, then the regexp of the store lens, followed by another special char \004, and finaly the iteration of the tree lens. This format reflects the key and value pairs of a tree node.

The third line, produced by lens_format_atype shows the atype of "x" in a way that makes it clearer what trees are matched: it uses the same notation as tree literals in tests, except that the label and the value of each node are a regular expression and not a string. In this example, the lens matches a tree that has an arbitrary number of nodes at the top level whose labels match [a]+ and whose values match [c]+

Runtime debugging

Many more debugging information is available at runtime by setting environment variables.

#!/bin/sh

T=/tmp/augeas
mkdir -p $T
export AUGEAS_DEBUG_DIR=$T
export AUGEAS_DEBUG=cf.jmt.build:cf.jmt:cf.jmt.visit:cf.jmt.parse:cf.approx:cf.get

First, for some debugging output, there are graphviz graph output, and we need to set the output directory for them with AUGEAS_DEBUG_DIR.

Second, the AUGEAS_DEBUG variable can hold many flags for different debugging information. In the example, all available variables are set.

In the case of recursive lens, the concrete type regexp can't be computed, because the resulting language is not regular. We can get the corresponding grammar and parsing information by using cf.* flags.

The flags for AUGEAS_DEBUG turn on the following debug output:

cf.approx	output dot drawings of the recursive transition network (RTN) used to approximate the abstract type of a recursive lens; print the resulting regular approximation of the type as a regular expression on stdout
cf.get	print details of the traversal of the parse tree for a recursive lens on stderr; for each node in the parse tree, print when an interior node is entered and exited, and information about leaves (terminals). In particular, print the part of the input string covered by the node of the parse tree, and the lens associated with it
cf.jmt	print the context-free grammar into which a recursive lens is transformed for parsing with a Jim/Mandelbaum transducer, together with how the lenses map to states in the transducer
cf.jmt.build	produce dot drawings of the Jim/Mandelbaum transducer (JMT): the raw transducer after construction, the transducer after eliminating epsilon transitions, and the determinized transducer
cf.jmt.parse	produce a dot drawing of the Earley sets and items constructed during a parse with the JMT, using the same conventions as the pictures in the Jim/Mandelbaum paper
cf.jmt.visit	print details of traversing the parse tree constructed with the JMT; this is similar to the output that cf.get produces, but from the point of view of the transducer
lenses	produce a dot drawing of lenses hierarchy with their corresponding flags and associated regexp. To get the drawing even if the lens has a typecheck error, use --notypecheck option.

Running augparse under GDB

You can't launch directly augparse from the src directory, because it's a wrapper script that exec augparse. Also, LD_LIBRARY_PATH must be set to include libaugeas.so.

To get augparse running under GDB inside the source directory, you need to run it through libtool:

$ cd augeas/src
$ libtool --mode=execute gdb augparse
(gdb) run --nostdinc -I ../lenses/ ../lenses/tests/test_json.aug 
...

Then, GDB will work properly.