| 1 | package StateML ; | ||
| 2 | |||
| 3 | $VERSION = 0.22 ; | ||
| 4 | |||
| 5 | =head1 NAME | ||
| 6 | |||
| 7 | StateML - State Machine Markup Language, with GraphViz and template-driven code generation | ||
| 8 | |||
| 9 | =head1 SYNOPSIS | ||
| 10 | |||
| 11 | ## See the stml command for command line use (recommended) | ||
| 12 | |||
| 13 | ## Here's what a .stml file might look like: | ||
| 14 | |||
| 15 | <machine | ||
| 16 | id="main" | ||
| 17 | xmlns="http://slaysys.com/StateML/1.0" | ||
| 18 | xmlns:C="http://your.com/path/to/ns/for/C/code" | ||
| 19 | xmlns:Perl="http://your.com/path/to/ns/for/perl/code" | ||
| 20 | xmlns:Java="http://your.com/path/to/ns/for/Java/code" | ||
| 21 | ... | ||
| 22 | > | ||
| 23 | <event id="init"> | ||
| 24 | <C:api>void init_event_handler()</C:api> | ||
| 25 | </event> | ||
| 26 | <state id="#ALL" graphviz:style="dashed"> | ||
| 27 | <arc event_id="init" goto="running"> | ||
| 28 | <C:handler>init_device()</C:handler> | ||
| 29 | </arc> | ||
| 30 | </state> | ||
| 31 | <state id="running"/> | ||
| 32 | </machine> | ||
| 33 | |||
| 34 | use StateML; | ||
| 35 | |||
| 36 | my $machine = StateML->parse( $source ); ## filename, GLOB, etc. | ||
| 37 | |||
| 38 | StateML->parse( $source, $machine ); ## Add to existing machine | ||
| 39 | |||
| 40 | ... process $machine as needed, see stml source for ideas... | ||
| 41 | |||
| 42 | =head1 DESCRIPTION | ||
| 43 | |||
| 44 | WARNING: Alpha code. I use it in production, but you may want to limit | ||
| 45 | your use to development only. | ||
| 46 | |||
| 47 | StateML is an XML dialect and a tool (L<stml|stml>) that reads this | ||
| 48 | dialect (by default from files with a ".stml" extension) and converts | ||
| 49 | it to source code using source code to a data structure. | ||
| 50 | |||
| 51 | It can then emit the data structure as a graphviz-generated image | ||
| 52 | or graph specification or you may take the data structure and do | ||
| 53 | what you want with it (bin/stml can pass it to template toolkit, for | ||
| 54 | instance). | ||
| 55 | |||
| 56 | =cut | ||
| 57 | |||
| 58 | use strict ; | ||
| 59 | #use SelfTest ; | ||
| 60 | |||
| 61 | =for testing | ||
| 62 | use Test ; | ||
| 63 | use StateML ; | ||
| 64 | plan tests => 0 ; | ||
| 65 | |||
| 66 | =cut | ||
| 67 | |||
| 68 | use XML::SAX::ParserFactory; | ||
| 69 | use StateML::SAXHandler ; | ||
| 70 | |||
| 71 | =for testing | ||
| 72 | my $m = StateML->parse( \'<machine><state id="1" /></machine>' ) ; | ||
| 73 | ok( scalar $m->states, 1 ) ; | ||
| 74 | |||
| 75 | =cut | ||
| 76 | |||
| 77 | =over | ||
| 78 | |||
| 79 | =item parse | ||
| 80 | |||
| 81 | my $m = StateML->parse( \$StateML_string ) ; | ||
| 82 | my $m = StateML->parse( \*F ) ; | ||
| 83 | |||
| 84 | =cut | ||
| 85 | |||
| 86 | sub parse { | ||
| 87 | my $self = shift ; | ||
| 88 | |||
| 89 | my ( $source, $machine ) = @_; | ||
| 90 | |||
| 91 | require StateML::SAXHandler; | ||
| 92 | require XML::Filter::Mode; | ||
| 93 | my $handler = StateML::SAXHandler->new( $machine ) ; | ||
| 94 | |||
| 95 | my $mode_filter = XML::Filter::Mode->new( | ||
| 96 | Handler => $handler, | ||
| 97 | Modes => [$machine->modes], | ||
| 98 | ); | ||
| 99 | |||
| 100 | ## Require PurePerl for now to get the bugs out | ||
| 101 | local $XML::ParserPackage = "XML::SAX::PurePerl"; | ||
| 102 | my $p = XML::SAX::ParserFactory->parser( | ||
| 103 | Handler => $mode_filter, | ||
| 104 | UseAttributeOrder => 1, | ||
| 105 | Source => $source, | ||
| 106 | ) ; | ||
| 107 | return $p->parse ; | ||
| 108 | } | ||
| 109 | |||
| 110 | =back | ||
| 111 | |||
| 112 | =cut | ||
| 113 | |||
| 114 | package StateML::Machine ; | ||
| 115 | |||
| 116 | use StateML::Constants qw( stateml_1_0_graphviz_ns ); | ||
| 117 | |||
| 118 | =head1 graphviz Support | ||
| 119 | |||
| 120 | Any XML attributes in the namespace | ||
| 121 | |||
| 122 | http://slaysys.com/StateML/1.0/GraphViz | ||
| 123 | |||
| 124 | (generally mapped to the "graphviz:" prefix), like | ||
| 125 | |||
| 126 | <machine | ||
| 127 | id="foo" | ||
| 128 | xmlns="http://slaysys.com/StateML/1.0" | ||
| 129 | xmlns:graphviz="http://slaysys.com/StateML/1.0/GraphViz" | ||
| 130 | > | ||
| 131 | |||
| 132 | <event graphviz:style="bold"> | ||
| 133 | |||
| 134 | <state id="foo" | ||
| 135 | graphviz:style="dashed" | ||
| 136 | graphviz:peripheries="2" | ||
| 137 | > | ||
| 138 | </machine> | ||
| 139 | |||
| 140 | are passed to the L<dot> program. See the dot program for details. | ||
| 141 | StateML does not police these. | ||
| 142 | |||
| 143 | =cut | ||
| 144 | |||
| 145 | ### HACKHACKHACK: There is no clean way to build a non-template back end, | ||
| 146 | ### yet I want to generate any image format Graphviz can, so I hack it | ||
| 147 | ### in this way. This is called by the stml program, and as such should | ||
| 148 | ### be somewhere other than here. Will clean up some day... | ||
| 149 | sub as_GraphViz { | ||
| 150 | my $self = shift ; | ||
| 151 | |||
| 152 | my ( $options ) = @_ ; | ||
| 153 | |||
| 154 | $options->{page_size} ||= "8x10"; | ||
| 155 | |||
| 156 | require GraphViz ; | ||
| 157 | my $g = GraphViz->new( | ||
| 158 | width => 8, # defaults | ||
| 159 | height => 10, | ||
| 160 | $self->attributes( stateml_1_0_graphviz_ns ), | ||
| 161 | exists $options->{page_size} | ||
| 162 | ? do { | ||
| 163 | my ( $w, $h ) = | ||
| 164 | $options->{page_size} =~ /^([\d.]+)[x,]([\d.]+)\z/ | ||
| 165 | or die "Invalid page size specification\n"; | ||
| 166 | ( | ||
| 167 | width => $w, | ||
| 168 | height => $h, | ||
| 169 | ); | ||
| 170 | } | ||
| 171 | : (), | ||
| 172 | ) ; | ||
| 173 | |||
| 174 | my $show_all = 0 ; | ||
| 175 | |||
| 176 | for ( $self->arcs ) { | ||
| 177 | my $from = $_->{FROM} ; | ||
| 178 | die "undefined state $_->{FROM}." unless defined $from ; | ||
| 179 | $show_all ||= uc $from eq "#ALL"; | ||
| 180 | } | ||
| 181 | |||
| 182 | for ( $show_all ? ( $self->all_state ) : (), $self->states ) { | ||
| 183 | my $label = $_->name; | ||
| 184 | $label .= "\n(" . $_->id . ")" if $options->{show_ids}; | ||
| 185 | $label .= | ||
| 186 | join( "", | ||
| 187 | $options->{show_handlers} | ||
| 188 | ? ( | ||
| 189 | map( "\nentry: $_", @{$_->{ENTRY_HANDLERS}} ), | ||
| 190 | map( "\nexit: $_", @{$_->{EXIT_HANDLERS}} ), | ||
| 191 | ) | ||
| 192 | : (), | ||
| 193 | ( $options->{show_description} | ||
| 194 | && defined $_->{DESCRIPTION} | ||
| 195 | && length $_->{DESCRIPTION} | ||
| 196 | ) | ||
| 197 | ? "\n$_->{DESCRIPTION}" | ||
| 198 | : (), | ||
| 199 | ) ; | ||
| 200 | |||
| 201 | $_->attribute( stateml_1_0_graphviz_ns, "style", "dashed" ) | ||
| 202 | if uc $_->id eq "#ALL" | ||
| 203 | && ! defined $_->attribute( stateml_1_0_graphviz_ns, "style" ) ; | ||
| 204 | |||
| 205 | $_->{NODE_ID} = $g->add_node( | ||
| 206 | $_->id, | ||
| 207 | shape => "record", | ||
| 208 | label => $label, | ||
| 209 | height => 0, | ||
| 210 | width => 0, | ||
| 211 | fontsize => $options->{font_size} || 10, | ||
| 212 | length $_->{PARENT_ID} && $_->{PARENT_ID} ne $self->id | ||
| 213 | ? ( cluster => $_->{PARENT_ID} ) | ||
| 214 | : (), | ||
| 215 | $_->attributes( stateml_1_0_graphviz_ns ), | ||
| 216 | ) ; | ||
| 217 | } | ||
| 218 | |||
| 219 | my @arcs = $self->arcs; | ||
| 220 | my $fold_arcs = 0; | ||
| 221 | |||
| 222 | if ( $fold_arcs ) { | ||
| 223 | my %arcs; | ||
| 224 | for ( @arcs ) { | ||
| 225 | my $name = $_->name; | ||
| 226 | $name .= "[" . $_->guard . "]" if defined $_->guard; | ||
| 227 | |||
| 228 | my $key = join "", | ||
| 229 | $_->from, | ||
| 230 | "->", | ||
| 231 | $_->to, | ||
| 232 | map { ( "/", $_ ) } $_->handler_descriptions; | ||
| 233 | if ( my $arc = $arcs{$key} ) { | ||
| 234 | $arc->name( $arc->name . ",\n" . $name ); | ||
| 235 | $arc->{IsCompositeArc} = 1; | ||
| 236 | } | ||
| 237 | else { | ||
| 238 | $arcs{$key} = StateML::Arc->new( %$_ ); | ||
| 239 | } | ||
| 240 | } | ||
| 241 | @arcs = values %arcs; | ||
| 242 | } | ||
| 243 | |||
| 244 | for ( @arcs ) { | ||
| 245 | my $from = $self->state_by_id( $_->{FROM} )->{NODE_ID} ; | ||
| 246 | die "undefined state $_->{FROM}." unless defined $from ; | ||
| 247 | my $to = $self->state_by_id( $_->{TO} )->{NODE_ID} ; | ||
| 248 | die "undefined state $_->{TO}." unless defined $to; | ||
| 249 | my $label = $_->name; | ||
| 250 | $label .= | ||
| 251 | "\n[" . $_->guard . "]" if defined $_->guard && length $_->guard; | ||
| 252 | |||
| 253 | if ( $options->{show_handlers} ) { | ||
| 254 | # my @descs = $_->handler_descriptions; | ||
| 255 | # my $s = join "", $label, @descs; | ||
| 256 | # my $prefix = "\n"; | ||
| 257 | # $_->{IsCompositeArc} | ||
| 258 | # || @descs > 1 | ||
| 259 | # || $s =~ tr/\n// | ||
| 260 | # || length $s > 20 | ||
| 261 | # ? "\n" | ||
| 262 | # : ""; | ||
| 263 | |||
| 264 | $label .= join "", map "\n / $_", map { | ||
| 265 | local $_ = $_; | ||
| 266 | s/\n/\n /g; | ||
| 267 | $_; | ||
| 268 | } $_->handler_descriptions; | ||
| 269 | } | ||
| 270 | |||
| 271 | if ( defined $_->{DESCRIPTION} && length $_->{DESCRIPTION} ) { | ||
| 272 | my $s = "\n$_->{DESCRIPTION}"; | ||
| 273 | $s =~ s/\n/\n /; | ||
| 274 | $label .= $s; | ||
| 275 | } | ||
| 276 | |||
| 277 | $label .= "\n"; | ||
| 278 | $label =~ s/\\/\\\\/g; | ||
| 279 | $label =~ s/"/\\"/g; | ||
| 280 | $label =~ s/\n/\\l/g; | ||
| 281 | |||
| 282 | $_->attribute( stateml_1_0_graphviz_ns, "style", "dashed" ) | ||
| 283 | if uc $from eq "#ALL" | ||
| 284 | && ! defined $_->attribute( stateml_1_0_graphviz_ns, "style" ) ; | ||
| 285 | |||
| 286 | $g->add_edge( | ||
| 287 | $from => $to, | ||
| 288 | fontsize => $options->{font_size} || 10, | ||
| 289 | label => "$label", | ||
| 290 | $_->attributes( stateml_1_0_graphviz_ns ), | ||
| 291 | ) ; | ||
| 292 | } | ||
| 293 | |||
| 294 | return $g ; | ||
| 295 | } | ||
| 296 | |||
| 297 | =head1 LIMITATIONS | ||
| 298 | |||
| 299 | Alpha code. Ok test suite, but we may need to change things in | ||
| 300 | non-backward compatible ways. | ||
| 301 | |||
| 302 | =head1 COPYRIGHT | ||
| 303 | |||
| 304 | Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved | ||
| 305 | |||
| 306 | =head1 LICENSE | ||
| 307 | |||
| 308 | You may use this module under the terms of the BSD, Artistic, or GPL licenses, | ||
| 309 | any version. | ||
| 310 | |||
| 311 | =head1 AUTHOR | ||
| 312 | |||
| 313 | Barrie Slaymaker <barries@slaysys.com> | ||
| 314 | |||
| 315 | =cut | ||
| 316 | |||
| 317 | |||
| 318 | 1 ; |