Content::matrix read out values

[PhilterPaper]

Per PDF::API2 ssimms/pdfapi2/issues/66, @cl0ne requested accessor to read matrix list:

Greetings!

Private matrix field is never used (neither written to nor read from) /lib/PDF/API2/Content.pm.52

$self->{' matrix'} = [1, 0, 0, 1, 0, 0]; 

and in matrix property we return $self for graphics objects:

/lib/PDF/API2/Content.pm.316-336

sub matrix { 
my $self = shift(); 
if (scalar(@_)) { 
my ($a, $b, $c, $d, $e, $f) = @_; 
if ($self->_in_text_object()) { 
$self->add(_matrix_text($a, $b, $c, $d, $e, $f)); 
$self->{' textmatrix'} = [$a, $b, $c, $d, $e, $f]; 
$self->{' textlinematrix'} = [0, 0]; 
} 
else { 
$self->add(_matrix_gfx($a, $b, $c, $d, $e, $f)); 
} 
} 

 if ($self->_in_text_object()) { 
     return @{$self->{' textmatrix'}}; 
 } 
 else { 
     return $self; 
 } 

}

> Shouldn't we store changes to the graphics state matrix in the aforementioned private field and return it from matrix accessor?

-------------------

> It's possible, but it could very easily become a bug factory without a clear benefit. The current matrix method is write-only, and 
> suggests that you use transform unless you particularly need to pass a low-level matrix.
>
> Do you have a use case for reading the matrix that can't be accomplished by the existing transformation methods?

[PhilterPaper]

1. Make sure various matrix calls (setters/getters) and direct variable access are all singing from the same page.
2. $content->transform( 'matrix' => [ 6 element list ]) needs to be consistent with individual calls (skew(), etc.).
3. $content->matrix( 6 element list ) needs to be consistent with transform(matrix) method.
4. Object variables matrix, textmatrix, textlinematrix need to be understood and kept consistent, particularly with if and how text and graphics matrices interact.

Once all these are understood and consistently handled, it shouldn't be a problem to return the current matrices through their accessors. As pointed out, currently in graphics mode it just returns $self -- it would be strange if anyone was already calling $self->matrix(), so changing its meaning shouldn't cause compatibility issues. One would think that setting scale(x,y) should be reflected in a matrix() call, but check to be sure!

To answer Steve's question, if someone is choosing to use a matrix call to set all 6 elements at once, it would be reasonable to expect that all 6 elements could be returned from the current matrix, so the list may be updated and resubmitted.