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 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 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 or elements - For prompt_class s: - contains the prompt - 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 s from prompt_class 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 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 should contain a guard attribute yes - All 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".