=pod

=encoding utf-8

=head1 NAME

Spreadsheet::XLSX::Reader::LibXML::CalcChain - Read xlsx calcChain files with LibXML

=head1 SYNOPSIS

The following uses the 'calcChain.xml' file found in the t/test_files/xl/ folder.  
It also uses the XMLReader version of the CalcChain class.  (Any version will do.)
	
    #!/usr/bin/env perl
    $|=1;
    use Data::Dumper;
    use Spreadsheet::XLSX::Reader::LibXML::Error;
    use Spreadsheet::XLSX::Reader::LibXML::XMLReader::CalcChain;

    my $file_instance = Spreadsheet::XLSX::Reader::LibXML::XMLReader::CalcChain->new(
		file_name => 'calcChain.xml',
		error_inst => Spreadsheet::XLSX::Reader::LibXML::Error->new,
	);
    print Dumper( $file_instance->get_calc_chain_position( 2 ) );

	###########################
	# SYNOPSIS Screen Output
	# 01: $VAR1 = {
	# 02:           'r' => 'D14',
	# 03:           's' => '1'
 	# 04:         };
	###########################

=head1 DESCRIPTION

B<This documentation is written to explain ways to extend this package.  To use the data 
extraction of Excel workbooks, worksheets, and cells please review the documentation for  
L<Spreadsheet::XLSX::Reader::LibXML>,
L<Spreadsheet::XLSX::Reader::LibXML::Worksheet>, and 
L<Spreadsheet::XLSX::Reader::LibXML::Cell>>

This general class is written to access the sub file calcChain.xml from an unzipped 
.xlsx file.  The file to be read is generally found in the xl/ sub folder after the 
master file is unzipped.  The calcChain.xml file contains the calculation sequence 
and data source(s) used when building the value for cells with formulas.  (The 
formula presented in the L<Cell|Spreadsheet::XlSX::Reader::LibXML::Cell> instance is 
collected from somewhere else.  This documentation is for a general explanation but 
the example uses an XMLReader version for this file.  Documentation specific to that 
reader can be found in L<~XMLReader::CalcChain
|Spreadsheet::XLSX::Reader::LibXML::XMLReader::CalcChain>.  To replace or augment 
this class you would need to fork the L<github
|https://github.com/jandrew/Spreadsheet-XLSX-Reader-LibXML> package and insert a call 
for your new class in the $parser_modules variable maintained in the 
L<Spreadsheet::XLSX::Reader::LibXML> class.  (about line 34).
	
=head2 Required Methods

These are the primary way(s) to use this class.  For additional CalcChain options see the 
L<Attributes|/Attributes> section.  I<All replacement classes must provide these methods.>  
Methods used to manipulate the attributes are listed in each attribute.

=head3 get_calc_chain_position( $integer )

=over

B<Definition:> This will return the calcChain information from the identified $integer position.  
(Counting from zero).  The information is returned as a perl hash ref.

B<Accepts:> an $integer for the calcChain position

B<Returns:> a hash ref of data

=back

=head2 Attributes

Data passed to new when creating an instance.   For modification of 
these attributes see the listed 'attribute methods'. For more information on 
attributes see L<Moose::Manual::Attributes>.

=head3 file_name

=over

B<Definition:> This needs to be the full file path to the calcChain file to 
be parsed.  When set it will open and read the primary settings in the calcChain 
and then maintain an open file handle for accessing data within the file.

B<Required:> Yes

B<Default:> none

B<Range> an actual Excel 2007+ calcChain file

B<attribute methods> Methods provided to adjust this attribute
		
=over

B<get_file_name>

=over

B<Definition:> Returns the value stored in the instance

=back

=back

=back

=head3 error_inst

=over

B<Definition:> Currently all CalcChain readers require an 
L<Error|Spreadsheet::XLSX::Reader::LibXML::Error> instance.

B<Required:> Yes

B<Default:> none

B<Range:> The minimum list of methods to implement for your own instance is;

	error set_error clear_error set_warnings if_warn

B<attribute methods> Methods provided to adjust this attribute
		
=over

B<get_error_inst>

=over

B<Definition:> returns this instance

=back

B<error>

=over

B<Definition:> Used to get the most recently logged error

=back

B<set_error>

=over

B<Definition:> used to set a new error string

=back

B<clear_error>

=over

B<Definition:> used to clear the current error string in this attribute

=back

B<set_warnings>

=over

B<Definition:> used to turn on or off real time warnings when errors are set

=back

B<if_warn>

=over

B<Definition:> a method mostly used to extend this package and see if warnings 
should be emitted.

=back

=back

=back

=head1 SUPPORT

=over

L<github Spreadsheet::XLSX::Reader::LibXML/issues
|https://github.com/jandrew/Spreadsheet-XLSX-Reader-LibXML/issues>

=back

=head1 TODO

=over

B<1.> Write a DOM version of the parser

=back

=head1 AUTHOR

=over

=item Jed Lund

=item jandrew@cpan.org

=back

=head1 COPYRIGHT

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

The full text of the license can be found in the
LICENSE file included with this module.

This software is copyrighted (c) 2014 by Jed Lund

=head1 DEPENDENCIES

=over

L<Spreadsheet::XLSX::Reader::LibXML>

=back

=head1 SEE ALSO

=over

L<Spreadsheet::ParseExcel> - Excel 2003 and earlier

L<Spreadsheet::XLSX> - 2007+

L<Spreadsheet::ParseXLSX> - 2007+

L<Log::Shiras|https://github.com/jandrew/Log-Shiras>

=over

All lines in this package that use Log::Shiras are commented out

=back

=back

=cut

#########1#########2 main pod documentation end  5#########6#########7#########8#########9