[nfc] Add ability to test code snippets

[seldridge]

This demonstrates a flow that can be used to validate that all code snippets used in the FIRRTL specification correctly parse. This is implemented using a simple pandoc filter to extract the bodies of all code blocks with known languages (FIRRTL and Verilog), write them to the build directory, and then run them all through an appropriate tool based on file extension (firtool or verilator).

This may be a little cumbersome as every code example has to be completely legal. To alleviate this, this PR includes the ability to add special delimiters, indicated by lines with the text snippetbegin/snippetend which will cause the filter to extract only the lines between the delimiters.

CC: @dtzSiFive

[seldridge]

This now includes basic delimited support. The magic delimiters snippetbegin/snippetend can be used to extract out any number of code regions. E.g., this allows you to do things like:

FIRRTL version 4.0.0
circuit Foo:
  module Foo:
    input a: UInt<1>
    output b: UInt<1>

    ;; snippetbegin
    connect b, a
    ;; snippetend

This will extract the entire code block to a file. It will replace the original code block with:

    connect b, a

[mmaloney-sf]

Just to be sure, the line comment syntax is ; ... in FIRRTL and not // ... right? (Your example in the PR looks like it will error out. I don't know if that's material to the logic, though).

[seldridge]

Just to be sure, the line comment syntax is ; ... in FIRRTL and not // ... right? (Your example in the PR looks like it will error out. I don't know if that's material to the logic, though).

Yes! That's a mistake. The filter will still handle that, but that is illegal FIRRTL. The intent is that the code should put the snippetbegin/snippetend delimiters inside a comment.

[seldridge]

@mwachs5 wrote:

could we add a few sentences to CONTRIBUTING.md that explains this a little bit?

Added in the force push!