lib/Text/Tradition/Parser/GraphML.pm

   1 package Text::Tradition::Parser::GraphML;
   2
   3 use strict;
   4 use warnings;
   5 use Exporter 'import';
   6 use vars qw/ @EXPORT_OK $xpc /;
   7
   8 use XML::LibXML;
   9 use XML::LibXML::XPathContext;
  10
  11 @EXPORT_OK = qw/ graphml_parse populate_witness_path /;
  12
  13 =head1 NAME
  14
  15 Text::Tradition::Parser::GraphML
  16
  17 =head1 DESCRIPTION
  18
  19 Parser module for Text::Tradition, given a GraphML file that describes
  20 a collation graph.  Returns the information about the graph that has
  21 been parsed out from the GraphML.  This module is meant to be used
  22 with a module (e.g. CollateX or Self) that interprets the specific
  23 GraphML conventions of the source program.
  24
  25 =head1 METHODS
  26
  27 =head2 B<graphml_parse>( $init_opts )
  28
  29 parse( $init_opts );
  30
  31 Takes a set of Tradition initialization options, among which should be either
  32 'file' or 'string'; parses that file or string and returns a list of nodes, edges,
  33 and their associated data.
  34
  35 =cut
  36
  37 # Return graph -> nodeid -> { key1/val1, key2/val2, key3/val3 ... }
  38 #              -> edgeid -> { source, target, wit1/val1, wit2/val2 ...}
  39
  40 sub graphml_parse {
  41     my( $opts ) = @_;
  42
  43     my $graph_hash = { 'nodes' => [],
  44                        'edges' => [] };
  45
  46     my $parser = XML::LibXML->new();
  47     my $doc;
  48     if( exists $opts->{'string'} ) {
  49         $doc = $parser->parse_string( $opts->{'string'} );
  50     } elsif ( exists $opts->{'file'} ) {
  51         $doc = $parser->parse_file( $opts->{'file'} );
  52     } else {
  53         warn "Could not find string or file option to parse";
  54         return;
  55     }
  56
  57     my( $graphattr, $nodedata, $witnesses ) = ( {}, {}, {} );
  58     my $graphml = $doc->documentElement();
  59     $xpc = XML::LibXML::XPathContext->new( $graphml );
  60     $xpc->registerNs( 'g', 'http://graphml.graphdrawing.org/xmlns' );
  61
  62     # First get the ID keys, for witnesses and for collation data
  63     foreach my $k ( $xpc->findnodes( '//g:key' ) ) {
  64         # Each key has a 'for' attribute; the edge keys are witnesses, and
  65         # the node keys contain an ID and string for each node.
  66         my $keyid = $k->getAttribute( 'id' );
  67         my $keyname = $k->getAttribute( 'attr.name' );
  68
  69                 # Keep track of the XML identifiers for the data carried
  70                 # in each node element.
  71                 my $dtype = $k->getAttribute( 'for' );
  72                 if( $dtype eq 'graph' ) {
  73                         $graphattr->{$keyid} = $keyname;
  74         } elsif( $dtype eq 'node' ) {
  75             $nodedata->{$keyid} = $keyname;
  76         } else {
  77             $witnesses->{$keyid} = $keyname;
  78         }
  79     }
  80
  81     my $graph_el = $xpc->find( '/g:graphml/g:graph' )->[0];
  82
  83     my $node_reg = {};
  84
  85     # Read in graph globals (if any).
  86     print STDERR "Reading graphml global data\n";
  87     foreach my $dkey ( keys %$graphattr ) {
  88         my $keyname = $graphattr->{$dkey};
  89         my $keyvalue = _lookup_node_data( $graph_el, $dkey );
  90         $graph_hash->{'global'}->{$keyname} = $keyvalue;
  91     }
  92
  93     # Add the nodes to the graph hash.
  94     print STDERR "Reading graphml nodes\n";
  95     my @nodes = $xpc->findnodes( '//g:node' );
  96     foreach my $n ( @nodes ) {
  97         # Could use a better way of registering these
  98         my $node_hash = {};
  99         foreach my $dkey ( keys %$nodedata ) {
 100             my $keyname = $nodedata->{$dkey};
 101             my $keyvalue = _lookup_node_data( $n, $dkey );
 102             $node_hash->{$keyname} = $keyvalue if defined $keyvalue;
 103         }
 104         $node_reg->{$n->getAttribute( 'id' )} = $node_hash;
 105         push( @{$graph_hash->{'nodes'}}, $node_hash );
 106     }
 107
 108     # Now add the edges, and cross-ref with the node objects.
 109     print STDERR "Reading graphml edges\n";
 110     my @edges = $xpc->findnodes( '//g:edge' );
 111     foreach my $e ( @edges ) {
 112         my $from = $e->getAttribute('source');
 113         my $to = $e->getAttribute('target');
 114
 115         # We don't know whether the edge data is one per witness
 116         # or one per witness type, or something else.  So we just
 117         # save it and let our calling parser decide.
 118         my $edge_hash = {
 119             'source' => $node_reg->{$from},
 120             'target' => $node_reg->{$to},
 121         };
 122         foreach my $wkey( keys %$witnesses ) {
 123             my $wname = $witnesses->{$wkey};
 124             my $wlabel = _lookup_node_data( $e, $wkey );
 125             $edge_hash->{$wname} = $wlabel if $wlabel;
 126         }
 127         push( @{$graph_hash->{'edges'}}, $edge_hash );
 128     }
 129     return $graph_hash;
 130 }
 131
 132 =head2 B<populate_witness_path>( $tradition )
 133
 134 Given a tradition, populate the 'path' and 'uncorrected_path' attributes
 135 of all of its witnesses.  Useful for all formats based on the graph itself.
 136
 137 =cut
 138
 139 sub populate_witness_path {
 140     my ( $tradition, $ante_corr ) = @_;
 141     my $c = $tradition->collation;
 142     print STDERR "Walking paths for witnesses\n";
 143     foreach my $wit ( $tradition->witnesses ) {
 144         my @path = $c->reading_sequence( $c->start, $c->end, $wit->sigil );
 145         $wit->path( \@path );
 146         if( $ante_corr->{$wit->sigil} ) {
 147                 # Get the uncorrected path too
 148                 my @uc = $c->reading_sequence( $c->start, $c->end,
 149                         $wit->sigil . $c->ac_label, $wit->sigil );
 150                 $wit->uncorrected_path( \@uc );
 151         }
 152     }
 153 }
 154
 155 sub _lookup_node_data {
 156     my( $xmlnode, $key ) = @_;
 157     my $lookup_xpath = './g:data[@key="%s"]/child::text()';
 158     my $data = $xpc->find( sprintf( $lookup_xpath, $key ), $xmlnode );
 159     # If we get back an empty nodelist, we return undef.
 160     if( ref( $data ) ) {
 161         return undef unless $data->size;
 162         return $data->to_literal->value;
 163     }
 164     # Otherwise we got back a value. Return it.
 165     return $data;
 166 }
 167
 168 =back
 169
 170 =head1 LICENSE
 171
 172 This package is free software and is provided "as is" without express
 173 or implied warranty.  You can redistribute it and/or modify it under
 174 the same terms as Perl itself.
 175
 176 =head1 AUTHOR
 177
 178 Tara L Andrews, aurum@cpan.org
 179
 180 =cut
 181
 182 1;