VCP/ui_machines README
 
Overview
========
 
This directory contains a set of .stml files defining a single,
monolithic UI state machine that is used to prompt the user if
they run VCP in interactive mode.
 
The reason it's a monolithic state machine is that it's easier to build
it that way; at some point we may want to split it in to multiple state
machines.
 
Each .stml file is the UI for a single module in the lib/VCP hierarchy,
with VCP.stml, VCP-Dest-p4.stml, etc.  These are all compiled in to a
single state machine in lib/VCP/UIMachines.pm.
 
 
Detailed UI Documentation
=========================
 
make ui (and thus just plain "make") creates an image in ui.png and
also writes plenty of POD in to lib/VCP/UIMachines.pm, so this should
work well enough for now:
 
    make ui && { ee ui.png & perldoc lib/VCP/UIMachines.pm }
 
 
Build Configuration
===================
 
Makefile.PL detects the presece of the ui_machines/ directory and, if
present, adds a "ui" rule to build lib/VCP/UIMachines.pm if ui_machines/
is present.  So "make ui" rebuilds the .pm, though this is also
a part of the normal make process and you should not need to do "make
ui" much.
 
If you add or remove a .stml file from ui_machines/, rerun
 
    perl Makefile.PL
    make
 
to update the modules.
 
 
Why do we put lib/VCP/UIMachines.pm in the main repository?
===========================================================
 
lib/VCP/UIMachines.pm is in the main repository, so you need to p4 edit
it in order to remake it.  This is for two reasons: so we capture the
actual as-shipped version (regenerating it could be impossible if
StateML package changes) and so that users can p4 sync revml/... and get
it.
 
 
STML Conventions
================
 
Some notes on the .stml documents:
 
- .stml files are named for the VCP modules they correspond to, changing
  the '::' to a '-'.  So VCP::Source::p4's .stml file is named
  VCP-Source-p4.stml.  These may be moved in to the modules as POD
  sections in the future.
 
- Each .stml file should have the name of the module it corresponds to
  in it's <machine> id attribute. This causes stml to draw a box around each
  with a label.
 
- The inital state in VCP.stml must have id="init" so VCP::UI knows
  where to begin.
 
- The id="..." value for each state is taken literally as the subroutine
  name, so make sure it's a valid Perl sub name.
 
- The classes determine what kind of method is used to implement
  each state, class names are "prompt_class", "entry_class",
  "exit_class".
 
- prompt_class <state>s should have ids ending in _prompt to make
  the generated code a bit more readable/debuggable.
 
- Actions take place on arcs or state entry/exit handlers.
 
- We may now use ' or " in <name> or <description> elements
 
- For prompt_class <state>s:
  - <name> contains the prompt
  - <description> contains the explanatory text.
    - This must be preformatted plain text wrapped at 72 columns or
      less.
    - The UI may rewrap this along the lines of Perl POD (ie indent to
      indicate literal spaces), but this is not to be assumed.
    - Leading and trailing whitespace is trimmed (which may make
      wrapping in your favorite editor easier).
 
  - For <arc>s from prompt_class <state>s:
 
    - The guard="..." is code that will be called to validate the input.
 
    - The guard= snippet must be a valid perl snippet, either a regular
      expression ( "qr/.../" ) or a CODE reference ("sub { ... }").
 
    - The <description> is the response text presented to the user.
 
    - If the response needs to be validated more subtly than by matching
      the exact description string, the <arc> should contain a guard
      attribute
 
        <arc to="source_p4_p4d_dir" guard="qr/y(es)?/i">
          <description>yes</description>
        </arc>
 
 
  - All <state>s in a given stml file other than vcp.stml should
    be prefixed with a string related to the source module like so:
    VCP-Source-p4.pm's states' ids are prefixed with "source_p4".