NAME

Graph::Easy::Introspect - Introspection and AST for Graph::Easy layouts

SYNOPSIS

use Graph::Easy;
use Graph::Easy::Parser::Graphviz;
use Graph::Easy::Introspect;

my $parser = Graph::Easy::Parser::Graphviz->new;
my $g      = $parser->from_text('digraph { A -> B -> C }');

my $ast       = $g->ast;
my $grid      = $g->ast_grid;       # 2D char array, undef if ast not called
my $cell_grid = $g->ast_cell_grid;  # cell-key => info hash

for my $node (@{ $ast->{nodes} }) {
    printf "%s at char (%d,%d) size %dx%d\n",
        $node->{id},
        $node->{char_x},  $node->{char_y},
        $node->{char_width}, $node->{char_height};
}

DESCRIPTION

This module extends Graph::Easy with three entry points: ast, ast_grid, and ast_cell_grid. ast renders the graph and returns a complete, self-contained data structure describing nodes, edges, groups, and positions. The rendered character grid and cell-grid lookup table are stored separately and retrieved via ast_grid and ast_cell_grid.

The module monkey-patches three packages:

• Graph::Easy::Introspect — helper functions (not methods)

• Graph::Easy::Edge — path, from_port, to_port, arrow_dir

• Graph::Easy — ast, ast_grid, ast_cell_grid

as_ascii is called exactly once per ast invocation. Character-space coordinates and rendered dimensions are captured by wrapping Graph::Easy::_prepare_layout at module load time.

COORDINATE SYSTEMS

Two coordinate systems coexist in the AST.

Cell-grid space: each node occupies one or more layout cells. node.x and node.y are cell-grid coordinates. node.bbox is expressed in cell-grid units. Edge path points carry x and y in cell-grid units.

Character space: the actual rendered positions. node.char_x and node.char_y are the character-space top-left corner of the node box. node.char_width and node.char_height are the rendered dimensions.

Port char_x and char_y are on the node face (the border character row or column), not the top-left of the adjacent edge cell. This gives correct, distinct coordinates for both ends of short single-cell edges.

AST STRUCTURE

Top level

{
  meta    => { introspect_version, graph_easy_version, generated_at, layout_algorithm },
  graph   => { is_directed, label, total_width, total_height, attrs },
  nodes   => [ ... ],
  edges   => [ ... ],
  groups  => [ ... ],
}

The character grid and cell-grid are not part of the AST. Retrieve them with ast_grid and ast_cell_grid after calling ast.

On error, returns { error => $message, meta => { introspect_version => $v } }.

Node entry

{
  id          => 'A',
  label       => 'A',
  is_anon     => 0,
  is_isolated => 0,
  x           => 0,          # cell-grid
  y           => 0,          # cell-grid
  char_x      => 2,          # character space, top-left of box
  char_y      => 3,          # character space
  char_width  => 9,          # character space, rendered
  char_height => 3,          # character space, rendered
  width       => 5,          # intrinsic (pre-expansion) char width
  height      => 3,
  bbox        => { x1, y1, x2, y2 },   # cell-grid
  component   => 0,
  groups      => ['g1'],
  edges_in    => [0],
  edges_out   => [1],
  ports       => {
    left    => [ { edge_id, role, x, y, char_x, char_y, seq } ],
    right   => [...],
    top     => [...],
    bottom  => [...],
    unknown => [...],   # catch-all; empty in normal layouts
  },
  attrs       => { shape => 'rounded', ... },
}

Edge entry

{
  id               => 0,
  from             => 'A',
  to               => 'B',
  is_self_loop     => 0,
  is_bidirectional => 0,
  multiplicity     => 1,
  arrow_dir        => 'right',
  from_port        => { x, y, char_x, char_y },  # char coords on from-node face
  to_port          => { x, y, char_x, char_y },  # char coords on to-node face
  from_side        => 'right',
  to_side          => 'left',
  label            => undef,
  label_x          => undef,   # cell-grid
  label_y          => undef,
  label_char_x     => undef,   # character space
  label_char_y     => undef,
  path             => [ { x, y, char_x, char_y, char_x2, char_y2,
                           line_x1, line_y1, line_x2, line_y2,
                           type, type_code, is_label } ],
  attrs            => { style => 'dashed', ... },
}

Group entry

{
  id          => 'mygroup',
  label       => 'mygroup',
  nodes       => ['A', 'B'],
  bbox        => { x1, y1, x2, y2 },    # cell-grid
  char_x      => 0,                      # character space, top-left of border
  char_y      => 0,
  char_width  => 13,
  char_height => 8,
  attrs       => { ... },
}

AUTHOR

Nadim Khemir <nadim.khemir@gmail.com>

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.