| 1 | package StateML::SAXHandler ; | ||
| 2 | |||
| 3 | $VERSION = 0.001 ; | ||
| 4 | |||
| 5 | =head1 NAME | ||
| 6 | |||
| 7 | StateML::SAXHandler - convert a SAX stream to a StateML::Machine | ||
| 8 | |||
| 9 | =head1 SYNOPSIS | ||
| 10 | |||
| 11 | ## From StateML::parse() | ||
| 12 | require StateML::SAXHandler; | ||
| 13 | require XML::Filter::Mode; | ||
| 14 | my $handler = StateML::SAXHandler->new( $machine ) ; | ||
| 15 | |||
| 16 | my $mode_filter = XML::Filter::Mode->new( | ||
| 17 | Handler => $handler, | ||
| 18 | Modes => [$machine->modes], | ||
| 19 | ); | ||
| 20 | |||
| 21 | ## Require PurePerl for now to get the bugs out | ||
| 22 | local $XML::ParserPackage = "XML::SAX::PurePerl"; | ||
| 23 | my $p = XML::SAX::ParserFactory->parser( | ||
| 24 | Handler => $mode_filter, | ||
| 25 | UseAttributeOrder => 1, | ||
| 26 | Source => $source, | ||
| 27 | ) ; | ||
| 28 | |||
| 29 | return $p->parse ; | ||
| 30 | |||
| 31 | =head1 DESCRIPTION | ||
| 32 | |||
| 33 | Use like a normal SAX handler, then collect the machine from the | ||
| 34 | SAX pipline's end_document() event. | ||
| 35 | |||
| 36 | See L<XML::Filter::Modes|XML::Filter::Modes> for an oft-used | ||
| 37 | prefilter to "shape" your machines by giving elements to nodes. | ||
| 38 | |||
| 39 | See L<StateML|StateML>::parse() for source examples. | ||
| 40 | |||
| 41 | =cut | ||
| 42 | |||
| 43 | use strict ; | ||
| 44 | |||
| 45 | use Carp ; | ||
| 46 | use StateML::Machine; | ||
| 47 | use StateML::Constants qw( stateml_1_0_ns ); | ||
| 48 | |||
| 49 | sub new { | ||
| 50 | my $proto = shift ; | ||
| 51 | my $class = ref $proto || $proto ; | ||
| 52 | my $self = bless { | ||
| 53 | }, $class ; | ||
| 54 | $self->machine( @_ ) if @_ ; | ||
| 55 | return $self ; | ||
| 56 | } | ||
| 57 | |||
| 58 | |||
| 59 | sub machine { | ||
| 60 | my $self = shift ; | ||
| 61 | $self->{MACHINE} = shift if @_ ; | ||
| 62 | return $self->{MACHINE} ; | ||
| 63 | } | ||
| 64 | |||
| 65 | |||
| 66 | sub parser { | ||
| 67 | my $self = shift ; | ||
| 68 | $self->{PARSER} = shift if @_ ; | ||
| 69 | return $self->{PARSER} ; | ||
| 70 | } | ||
| 71 | |||
| 72 | |||
| 73 | sub _location { | ||
| 74 | my $self = shift ; | ||
| 75 | return '';# unless $self->{DOC_LOCATOR}; | ||
| 76 | my $pl = $self->{DOC_LOCATOR}; | ||
| 77 | return join( | ||
| 78 | " ", | ||
| 79 | "", | ||
| 80 | "at", | ||
| 81 | defined $pl->{SystemId} | ||
| 82 | ? "$pl->{SystemId}," | ||
| 83 | : (), | ||
| 84 | "line", | ||
| 85 | $pl->{LineNumber}, | ||
| 86 | "column", | ||
| 87 | $pl->{ColumnNumber} | ||
| 88 | ) ; | ||
| 89 | } | ||
| 90 | |||
| 91 | |||
| 92 | sub _X { | ||
| 93 | my $self = shift ; | ||
| 94 | die @_, $self->_location, "\n" ; | ||
| 95 | } | ||
| 96 | |||
| 97 | |||
| 98 | sub _top { | ||
| 99 | return shift->{ELT_STACK}->[-1] ; | ||
| 100 | } | ||
| 101 | |||
| 102 | |||
| 103 | sub set_document_locator { | ||
| 104 | my $self = shift; | ||
| 105 | |||
| 106 | $self->{DOC_LOCATOR} = shift; | ||
| 107 | } | ||
| 108 | |||
| 109 | |||
| 110 | sub start_document { | ||
| 111 | my $self = shift ; | ||
| 112 | $self->{ELT_STACK} = [ | ||
| 113 | { ELT => {Name => "#root"}}, ## Fake elt, so stack never empty | ||
| 114 | ] ; | ||
| 115 | $self->{InStateMLElt} = [ 0 ]; | ||
| 116 | } | ||
| 117 | |||
| 118 | sub end_document { shift->machine } | ||
| 119 | |||
| 120 | ## Poor excuse for a DTD :) | ||
| 121 | my %can_be_in = ( | ||
| 122 | "machine" => [ "#root" ], | ||
| 123 | "class" => [ qw( machine state ) ], | ||
| 124 | "state" => [ qw( machine state ) ], | ||
| 125 | "event" => [ qw( machine arc ) ], | ||
| 126 | "action" => [ qw( machine ) ], | ||
| 127 | |||
| 128 | "name" => [ qw( state event action ) ], | ||
| 129 | "description" => [ qw( machine event state arc action ) ], | ||
| 130 | |||
| 131 | "version" => [ qw( machine ) ], | ||
| 132 | "preamble" => [ qw( machine ) ], | ||
| 133 | "postamble" => [ qw( machine ) ], | ||
| 134 | |||
| 135 | "api" => [ qw( event ) ], | ||
| 136 | "pre-handler" => [ qw( event ) ], | ||
| 137 | "post-handler" => [ qw( event ) ], | ||
| 138 | |||
| 139 | "entry-handler" => [ qw( state ) ], | ||
| 140 | "exit-handler" => [ qw( state ) ], | ||
| 141 | "arc" => [ qw( state ) ], | ||
| 142 | |||
| 143 | "handler" => [ qw( event arc action ) ], | ||
| 144 | ) ; | ||
| 145 | |||
| 146 | |||
| 147 | sub _stateml_attrs { | ||
| 148 | my ( $elt ) = @_; | ||
| 149 | |||
| 150 | ## Return a list of ( Name => $value ) pairs of all attrs in | ||
| 151 | ## the empty namespace or in the StateML namespace | ||
| 152 | ( | ||
| 153 | map { | ||
| 154 | ( my $key = uc $_->{LocalName} ) =~ s/-/_/g; | ||
| 155 | my $value = $_->{Value}; | ||
| 156 | $value = [ grep length, split /,/, $value ] | ||
| 157 | if $key eq "CLASS_IDS"; | ||
| 158 | ( $key => $value ); | ||
| 159 | } grep $_->{NamespaceURI} eq "" | ||
| 160 | || $_->{NamespaceURI} eq stateml_1_0_ns, | ||
| 161 | values %{ $elt->{Attributes} } | ||
| 162 | ); | ||
| 163 | } | ||
| 164 | |||
| 165 | |||
| 166 | sub start_element { | ||
| 167 | my $self = shift ; | ||
| 168 | |||
| 169 | my ( $elt ) = @_ ; | ||
| 170 | |||
| 171 | push @{$self->{InStateMLElt}}, $elt->{NamespaceURI} eq stateml_1_0_ns; | ||
| 172 | if ( $self->{InStateMLElt}->[-1] ) { | ||
| 173 | push @{$self->{InStateMLElt}}, 1; | ||
| 174 | my $parent = $self->_top ; | ||
| 175 | my $parent_type = $parent->{ELT}->{Name} ; | ||
| 176 | |||
| 177 | my $elt_type = $elt->{Name} ; | ||
| 178 | |||
| 179 | croak "<$elt> may not have a missing prefix\n" | ||
| 180 | if substr( $elt, 0, 1 ) eq ":" ; | ||
| 181 | croak "<$elt> may not have multiple prefixes\n" | ||
| 182 | if substr( $elt, 0, 1 ) eq ":" ; | ||
| 183 | |||
| 184 | my $h = { | ||
| 185 | ELT => $elt, | ||
| 186 | LOCATION => $self->_location, | ||
| 187 | _stateml_attrs $elt, | ||
| 188 | } ; | ||
| 189 | |||
| 190 | $elt_type =~ s/.*:// ; | ||
| 191 | $elt->{Name} =~ s/.*:// ; | ||
| 192 | |||
| 193 | $self->_X( "<$elt_type> not allowed in <$parent_type>" ) | ||
| 194 | unless grep $parent_type eq $_, @{$can_be_in{$elt_type}} ; | ||
| 195 | |||
| 196 | if ( $elt_type eq "api" ) { | ||
| 197 | push @{$parent->{APIS}}, $h ; | ||
| 198 | } | ||
| 199 | elsif ( $elt_type =~ /amble$/ ) { | ||
| 200 | $h->{CODE} = "" ; | ||
| 201 | } | ||
| 202 | elsif ( $elt_type =~ /handler$/ ) { | ||
| 203 | $h->{CODE} = "" ; | ||
| 204 | } | ||
| 205 | elsif ( $elt_type eq "action" ) { | ||
| 206 | $h = StateML::Action->new( %$h ) ; | ||
| 207 | $self->machine->add( $h ) ; | ||
| 208 | } | ||
| 209 | elsif ( $elt_type eq "class" ) { | ||
| 210 | $h = StateML::Class->new( %$h ) ; | ||
| 211 | $self->machine->add( $h ) ; | ||
| 212 | } | ||
| 213 | elsif ( $elt_type eq "event" ) { | ||
| 214 | $h = StateML::Event->new( %$h ) ; | ||
| 215 | $self->machine->add( $h ) ; | ||
| 216 | if ( UNIVERSAL::isa( $parent, "StateML::Arc" ) ) { | ||
| 217 | ## Bypass event_id() to prevent defaulting | ||
| 218 | my $old_event_id = $parent->{EVENT_ID}; | ||
| 219 | my $id = $h->id; | ||
| 220 | die | ||
| 221 | "<arc event_id='$old_event_id'> conflicts with <event id='$id'>\n" | ||
| 222 | if defined $old_event_id && $old_event_id ne $id; | ||
| 223 | $parent->event_id( $id ); | ||
| 224 | } | ||
| 225 | } | ||
| 226 | elsif ( $elt_type eq "machine" ) { | ||
| 227 | $self->{MACHINE_ID} = $h->{ID}; | ||
| 228 | my $m = $self->machine ; | ||
| 229 | $m->{$_} = $h->{$_} for grep !defined $m->{$_}, keys %$h; | ||
| 230 | $h = $m ; | ||
| 231 | $h->{ID} = "#MACHINE 1" unless defined $h->{ID}; | ||
| 232 | } | ||
| 233 | elsif ( $elt_type eq "state" ) { | ||
| 234 | my $id = $h->{ID}; | ||
| 235 | $self->_X( "<state> missing an id=" ) unless defined $id ; | ||
| 236 | |||
| 237 | my $old_h = $self->machine->state_by_id( $id ) ; | ||
| 238 | |||
| 239 | if ( $old_h ) { | ||
| 240 | $old_h->{LOCATION} .= " and $h->{LOCATION}" ; | ||
| 241 | $h = $old_h ; | ||
| 242 | $h->{ELT} = $elt ; | ||
| 243 | } | ||
| 244 | else { | ||
| 245 | $h = StateML::State->new( | ||
| 246 | %$h, | ||
| 247 | ELT => $elt, | ||
| 248 | ID => $id, | ||
| 249 | PARENT_ID => $self->{MACHINE_ID}, | ||
| 250 | ORDER => scalar $self->machine->states, | ||
| 251 | ) ; | ||
| 252 | $self->machine->add( $h ) ; | ||
| 253 | } | ||
| 254 | } | ||
| 255 | elsif ( $elt_type eq "arc" ) { | ||
| 256 | $h->{TO} = delete $h->{GOTO} if exists $h->{GOTO}; | ||
| 257 | $h = StateML::Arc->new( %$h ) ; | ||
| 258 | $h->from( $parent->id ) unless defined $h->from; | ||
| 259 | $h->to( $parent->id ) unless defined $h->to; | ||
| 260 | $self->machine->add( $h ) ; | ||
| 261 | } | ||
| 262 | |||
| 263 | $h->{LOCATION} = $self->_location ; | ||
| 264 | |||
| 265 | $h->{ATTRS} = { | ||
| 266 | map | ||
| 267 | { ( $_ => $elt->{Attributes}->{Value} ); } | ||
| 268 | keys %{$elt->{Attributes}} | ||
| 269 | }; | ||
| 270 | |||
| 271 | push @{$self->{ELT_STACK}}, $h ; | ||
| 272 | } | ||
| 273 | } | ||
| 274 | |||
| 275 | |||
| 276 | sub characters { | ||
| 277 | my $self = shift ; | ||
| 278 | my ( $h ) = @_ ; | ||
| 279 | return unless $self->{InStateMLElt}->[-1]; | ||
| 280 | |||
| 281 | my $parent = $self->_top ; | ||
| 282 | my $elt_type = $parent->{ELT}->{Name} ; | ||
| 283 | if ( $elt_type =~ /handler$/ && ! $parent->{ACTION_ID} ) { | ||
| 284 | $parent->{CODE} .= $h->{Data} ; | ||
| 285 | } | ||
| 286 | elsif ( $elt_type =~ /amble$/ ) { | ||
| 287 | $parent->{CODE} .= $h->{Data} ; | ||
| 288 | } | ||
| 289 | elsif ( $elt_type eq "api" ) { | ||
| 290 | $self->_X( "stack underflow" ) unless @{$self->{ELT_STACK}} >= 2 ; | ||
| 291 | $self->{ELT_STACK}->[-2]->{API} .= $h->{Data} ; | ||
| 292 | } | ||
| 293 | elsif ( $elt_type eq "name" ) { | ||
| 294 | $self->_X( "stack underflow" ) unless @{$self->{ELT_STACK}} >= 2 ; | ||
| 295 | $self->{ELT_STACK}->[-2]->{NAME} .= $h->{Data} ; | ||
| 296 | } | ||
| 297 | elsif ( $elt_type eq "description" ) { | ||
| 298 | $self->_X( "stack underflow" ) unless @{$self->{ELT_STACK}} >= 2 ; | ||
| 299 | $self->{ELT_STACK}->[-2]->{DESCRIPTION} .= $h->{Data} ; | ||
| 300 | } | ||
| 301 | elsif ( $h->{Data} =~ /\S/ ) { | ||
| 302 | my $location = $self->_location || '' ; | ||
| 303 | warn "Ignoring '$h->{Data}' in <$elt_type>$location.\n" ; | ||
| 304 | } | ||
| 305 | } | ||
| 306 | |||
| 307 | |||
| 308 | sub _deindent { | ||
| 309 | my $ltrim; | ||
| 310 | |||
| 311 | for ( $_[0] =~ /\n( *)\S/mg ) { | ||
| 312 | $ltrim = length if ! defined $ltrim || length $_ < $ltrim; | ||
| 313 | } | ||
| 314 | |||
| 315 | $_[0] =~ s/[ \t]+$//; ## Remove trailing spaces. | ||
| 316 | $_[0] =~ s/^([ \t]*\n)+//; ## Remove leading blank lines | ||
| 317 | |||
| 318 | return unless defined $ltrim; | ||
| 319 | |||
| 320 | $_[0] =~ s/^ {$ltrim}//mg; | ||
| 321 | } | ||
| 322 | |||
| 323 | |||
| 324 | sub end_element { | ||
| 325 | my $self = shift ; | ||
| 326 | |||
| 327 | my ( $elt ) = @_ ; | ||
| 328 | |||
| 329 | if ( $self->{InStateMLElt}->[-1] ) { | ||
| 330 | |||
| 331 | my $popped = pop @{$self->{ELT_STACK}} ; | ||
| 332 | my $elt_type = $popped->{ELT}->{Name} ; | ||
| 333 | |||
| 334 | $elt->{Name} =~ s/.*:// ; | ||
| 335 | $self->_X( "</$elt->{Name}> found, expected </$elt_type>" ) | ||
| 336 | unless $elt->{Name} eq $elt_type ; | ||
| 337 | |||
| 338 | my $parent = $self->_top ; | ||
| 339 | |||
| 340 | if ( $elt_type =~ /handler$/ ) { | ||
| 341 | my $htype = uc $elt->{Name} ; | ||
| 342 | $htype =~ tr/-/_/ ; | ||
| 343 | my $code = defined $popped->{ACTION_ID} | ||
| 344 | ? \$popped->{ACTION_ID} | ||
| 345 | : do { | ||
| 346 | _deindent $popped->{CODE} | ||
| 347 | unless defined $parent->{DEINDENT} && ! $parent->{DEINDENT}; | ||
| 348 | $popped->{CODE}; | ||
| 349 | }; | ||
| 350 | push @{$parent->{"${htype}S"}}, $code; | ||
| 351 | } | ||
| 352 | |||
| 353 | if ( $elt_type =~ /amble$/ ) { | ||
| 354 | my $htype = uc $elt->{Name} ; | ||
| 355 | _deindent $popped->{CODE} | ||
| 356 | unless defined $parent->{DEINDENT} && ! $parent->{DEINDENT}; | ||
| 357 | push @{$parent->{$htype}}, $popped->{CODE} ; | ||
| 358 | } | ||
| 359 | } | ||
| 360 | |||
| 361 | pop @{$self->{InStateMLElt}}; | ||
| 362 | } | ||
| 363 | |||
| 364 | =head1 LIMITATIONS | ||
| 365 | |||
| 366 | Alpha code. Ok test suite, but we may need to change things in | ||
| 367 | non-backward compatible ways. | ||
| 368 | |||
| 369 | =head1 COPYRIGHT | ||
| 370 | |||
| 371 | Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved | ||
| 372 | |||
| 373 | =head1 LICENSE | ||
| 374 | |||
| 375 | You may use this module under the terms of the BSD, Artistic, or GPL licenses, | ||
| 376 | any version. | ||
| 377 | |||
| 378 | =head1 AUTHOR | ||
| 379 | |||
| 380 | Barrie Slaymaker <barries@slaysys.com> | ||
| 381 | |||
| 382 | =cut | ||
| 383 | |||
| 384 | 1 ; |