In this tutorial, a few features of f2dot will be presented. All examples will work on the toySDF example presented in the Synchronous Dataflow Tutorial. As suggested in the tool's help document, the output is controlled by the options in the config file. Some command line arguments override these options, for user convenience.

Running the f2dot tool on toySDF's top.xml with the default options, outputs the following graph:

Altering the direction or detail level, we get the following graphs:

f2dot top.xml --dir=TB	f2dot top.xml --dir=TB --level=1

The config file has numerous other options for customizing the output. Since they are all documented, we shall only focus on the most important ones: the information tags. They define what information should appear as labels on the different elements of the output graph.

These tags are XPath1.0 queries wrapped inside a minimal custom grammar for defining label layout. This grammar is defined as:

LABEL = R      LABEL =       # an INFO_TAG may/may not contain row (R) information 
    R = R R        R = {D}   # (any number of) rows (R) consist of data (D) surrounded by curly brackets {}
    D = D && D     D = q     # data (D) on the same row is separated by && and consists of XPath queries (q)

Since an XPath query returns a list of informations, through this grammar f2dot takes care of merging and zipping data in a relevant manner for the user. For example, assuming that queryX returns a list dataX = [dataX[0], dataX[1], ...], the following INFO_TAG

{query1} {query2 && query3 && query4}

will enable f2dot to arrange the lable as:

               data1[0]
               data1[1]
                 ...
    data2[0] : data3[0] : data4[0]
    data2[1] : data3[1] : data4[1]
      ...         ...         ...

A good tutorial for XPath syntax may be found here. Based on that, the following query

./process_constructor/argument[@name='_func']/../argument/@name | ./process_constructor[@name='delay']/@moc

can be translated to

return all the values of the attribute name of the nodes tagged argument which are children of node process_constructor IF the node process_constructor has at least one child node argument having an attribute name with the value _func | ALSO, return all the values of the attribute moc of the nodes tagged process_constructor IF this node has least one attribute name with the value delay.

Putting this new knowledge in practice, we can play around with what information we want extracted from the ForSyDe-XML files and plotted as node labels in the output graph. For example, if we alter the f2dot.config file with the following INFO_TAGS

LEAF_INFO_TAGS={ ./@name } {./process_constructor/argument[@name='_func']/../argument/@name | ./process_constructor[@name='delay']/@moc && ./process_constructor/argument[@name='_func']/../argument/@value}
COMPOSITE_INFO_TAGS={./@name } {  name(./@component_name) && ./@component_name }
LEAF_PORT_INFO_TAGS= {./@name && ./@type }
COMPOSITE_PORT_INFO_TAGS={./@name }{ ./@direction }
SIGNAL_INFO_TAGS={./@moc }

we get the annotated graph:

As of f2dot-0.1.3, XPath queries can include pre-extracted variables for more complex expressions. This extends the previous grammar table with the following rules:

LABEL = V R      LABEL = R      LABEL =      # an INFO_TAG may/may not contain row information (R), prepended by variable expressions (V)
    V = V V          V = <<q>>               # variable expressions (V) consist of complete queries (q) surounded by << and >>
    R = R R          R = {D}                 # (any number of) rows (R) consist of data (D) surrounded by curly brackets {}
    D = D && D       D = v_q                 # data (D) on the same row is separated by && and consists of XPath variable-bound queries (v_q)

Data querries (v_q) are now variable-bound, meaning that they might call variables of form $i (with i in [1..] being the index of the V expression). These variables are extracted by the querries (q) before evaluating (v_q) and replaced in (v_q), rendering them valid XPath expressions.

For example the expression for LEAF_PORT_INFO_TAGS:

LEAF_PORT_INFO_TAGS= << concat(substring-before(./@name, 'port'), substring-after(./@name, 'port')) >> { ./../process_constructor/argument[contains(@name , '$1')]/@value && ./@type }

extracting port information from the following leaf_process node

	<leaf_process name="downSampler1">
		<port name="iport1" type="float" direction="in"/>
		<port name="oport1" type="float" direction="out"/>
		<process_constructor name="comb" moc="sdf">
			<argument name="_func" value="downSampler_func"/>
			<argument name="o1toks" value="2"/>
			<argument name="i1toks" value="3"/>
		</process_constructor>
	</leaf_process>

would print the token values from the process constructor arguments which have matching name as the port name. For this we need to extract the port name as a variable and drop the substring 'port' from it (e.g. iport1 becomes i1). This string is then inserted into the {D} query, matching the values of the token arguments. Using the following configuration file, the previous toy example is plotted as: