- 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".
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#8 | 5400 | Barrie Slaymaker |
- Misc. doc tweaks |
19 years ago | |
#7 | 3254 | Barrie Slaymaker | Redo machine naminf convention. | 22 years ago | |
#6 | 3242 | Barrie Slaymaker | Allow ' and " in prompt, but { and } must be balanced. | 22 years ago | |
#5 | 3237 | Barrie Slaymaker | More work on the UI StateML conventions | 22 years ago | |
#4 | 3234 | Barrie Slaymaker | More updates, passes make ui now. | 22 years ago | |
#3 | 3231 | Barrie Slaymaker | work on STML->source code conventions | 22 years ago | |
#2 | 3230 | John Fetkovich | spelling | 22 years ago | |
#1 | 3228 | Barrie Slaymaker | Add ui_machines/README | 22 years ago |