Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • Lately, we've been using code generators to build C (gcc and quircky C compilers for embedded processors) in two areas:
    1. State machines. Using something I call StateML to defined events, actions, states and arcs along with snippets of documentation and snippets of source code for zero, one, or more languages side by side in the same file to generate any and often all of:
      • State diagrams (via GraphViz) in .png or .ps format.
      • HTML text + graphics docs, HTML generated using a TT2 template and graphics from the last bullet, and then,
      • via html2ps and ps2pdf and some creative cat(1)ing, .pdf text+graphics docs (this toolchain was build by a coworker).
      • Working code in various languages simultaneously using TT2 templates.
      The idea is that all the things you need are defined in one .stml file that's an XML formatted literate, declarative definition that can be "tangled" via TT2 C, C++, Perl, Java, etc. templates in to source code or "woven" via graphviz + TT2 HTML template in to copious reference documentation. We don't generate user / tutorial docs in true literate programming style, but I think we could if need be (state machines are so branchy that they're not necessarily conducive to non-reference descriptions that I normally think of when I think of literate programming).
    2. Math transforms. When dealing with a very limited embedded chip, we need to do complex, nonlinear transforms, so I use Perl to
      1. build the tables,
      2. perform analytics to help design appropriate approximation parameters,
      3. emit the C arrays and matched lookup routines via TT2 that implement the transform, and
      4. build test suites using real floating point that are run on the device or a microprocessor simulator to make sure the integer math all comes out within acceptable error limits (we've used a GPLed PIC microprocessor simulator for this, for example).

    The advantages to #1 is that we generate docs and prototype gcc code while in the speccing and analysis stage so that we can get customer feedback and make sure the state machine works, and then generate real code. Then as we go through the implementation and revision / maintenance phases, we update the .stml file and get working code and updated docs all at once. No more stale / misleading docs.

    The advantage to #2 is a reduced compile/edit/debug cycle with easily parameterized transforms without having to recode the C all the time. We hard code in a few sanity tests at corner and one or two typical points on the transform's input range and let the perl script verify that all the other data points match perl's floating point calcs.

    The overall advantage to this approach is that bugs are usually systematic (instead of just being at the corner conditions) and show up far sooner and more pervasively (since they're usually bugs in the TT2 templates), and that we can make minor design changes (add a state, move a transform's endpoint, etc) easily with less chance of introducing bugs (like forgetting to break out of a switch condition) and get new documentation and code that's guaranteed to be in sync.

    phew.

    The disadvantage is that we spend more time on tools development and there's temptation to use a tool like the StateML tool where it doesn't belong.

    I've finally understood why both flowcharts and state charts (even newer incarnations of such) are so damn frustrating: they're all to abstract and limited. They're good for modelling simple things, or homogeneous problem or solution spaces, but large flowcharts and state charts really inspire MEGO (My Eyes Glaze Over) because flowcharts capture state in an awkward fashion, while state diagrams and state machines are too limited to work for many hairy problems.

    I've been looking around at newer modelling techniques with an eye towards being able to generate code and documentation from a single spec and I've found that many of them lack the expressive power of a hand drawn diagram. And tools like dia, which allows you to get pretty expressive (assuming you find the symbols you want or can take the time to do some C++ hacking to make your own), aren't really flexible enough quite yet to serve as diagramming front ends with enough rigor / extensibility to allow code generation. dia's getting close though.

    Note that I have little use for state diagrams and flow charts as pure modelling artifacts; that's trivial. Where the art comes in in all of this is being able to build a model that's expressive enough to communicate with clients (with a lot of technical details not filled in yet or supressed) while being complete and rigorous enough by the time you need to generate code that you don't need to throw the model away.

    I've looked at a UML CASE tool or two, and the failing there I see is that they take UML, which is designed to be usable piecewise and build all-inclusive, prescriptive OO modelling / code generating frameworks in them. Few real world apps I've worked on could be cost effectively modelled that way; often the GUI components are more feasible to use drag-n-drop IDEs for (IOW, proprietary codegens to address the language issues you mention while facilitating graphic layout) while internals are often piecewise add-hoc: a state machine here, an IDL-based RPC thingy there, an XML parser over yonder.

    Ok, ramble done. Suffice it to say that I'm suffused with the itch to build a better diagramming tool that scales between expressivity (so my firm can communicate designs clearly, both internally and externally) and rigourousness / completeness (so we can reap the rewards of literate programming) while not being so exclusive and prescriptive that it's all or nothing. A pipe dream, but a useful one to persue, I hope. All in my copious spare time.

    - Barrie

    • Wow.

      Suffice it to say that I'm suffused with the itch to build a better diagramming tool that scales between expressivity (so my firm can communicate designs clearly, both internally and externally) and rigourousness / completeness (so we can reap the rewards of literate programming) while not being so exclusive and prescriptive that it's all or nothing. A pipe dream, but a useful one to persue, I hope. All in my copious spare time.

      Sounds like you're attacking an interesting, yet different problem tha