NAME
Spreadsheet::Reader::ExcelXML::Cell - ExcelXML Cell data class
SYNOPSIS
#!/usr/bin/env perl
use Spreadsheet::Reader::ExcelXML::Cell;
use Spreadsheet::Reader::ExcelXML::Error;
my $cell_inputs = {
'cell_hidden' => 0,
'r' => 'A2',
'cell_row' => 1,
'cell_unformatted' => 'Hello',
'cell_col' => 0,
'cell_xml_value' => 'Hello',
'cell_type' => 'Text',
'error_inst' => Spreadsheet::Reader::ExcelXML::Error->new,
};
my $cell_instance = Spreadsheet::Reader::ExcelXML::Cell->new( $cell_inputs );
print "Cell value is: " . $cell_instance->value . "\n";
###########################
# SYNOPSIS Output
# Cell value is: Hello
###########################DESCRIPTION
This is the class that contains cell data. There are no XML parsing actions taken in the background of this class. All data has been pre-coalated/built from the Worksheet class. In general the Worksheet class will populate the attributes of this class when it is generated. If you want to use it as a standalone class just fill in the Attributes below. It should be noted that the Formatter class also pre-converts the unformatted value. Not much goes on here but access or excesize of code provided from other places.
Primary Methods
This is the method used to transform data stored in the Attributes (not just return it directly). The method is an object method and should be implemented on the instance.
Example:
my $value = $cell_intance->value;value
Definition: Returns the formatted value of the cell transformed from the base xml string if it is available. In the weird case where the cell_xml_value is not available but the unformatted value is then this method will use the unformatted value. This method then applies any conversion stored in the cell_coercion attribute. If there is no format/conversion set then this will return the selected value. Any failures to process this value can be retrieved with $self->error.
Accepts:Nothing
Returns: the cell 'value' processed by the set conversion
Attributes
This class is just a storage of coallated information about the requested cell stored in the following attributes. For more information on attributes see Moose::Manual::Attributes. Data about the cell can be retrieved from each attribute using the 'attribute methods'. 'Delegated methods' are methods available at the class or instance level directly delegated from that specific attribute.
error_inst
Definition: This attribute holds an 'error' object instance. In general the package will share a reference for this instance accross the workbook with all worksheets and all cells so any 'set' or 'get' action should be available at all touch points for this error object. If you wish to have a unique error instance you can set it here.
Default: a Spreadsheet::Reader::ExcelXML::Error instance with the attributes set as;
( should_warn => 0 )Range: a 'Spreadsheet::Reader::ExcelXML::Error' instance. To roll this on your own, the minimum list of methods to implement for your own instance is;
error set_error clear_error set_warnings if_warnDelegated methods Links to default implementation and method name conversions (if any) delegated from this attribute to the package.
"error" in Spreadsheet::Reader::ExcelXML::Error
"set_error" in Spreadsheet::Reader::ExcelXML::Error
"clear_error" in Spreadsheet::Reader::ExcelXML::Error
cell_xml_value
Definition: This contains the raw value stored in xml for this cell. This can be different than the 'cell_unformatted' value based on archane rules set by Microsoft.
Range:Any string or nothing
attribute methods Methods provided to adjust this attribute
xml_value
Definition: returns the attribute value
has_xml_value
Definition: predicate for this attribute
cell_unformatted
Definition: This holds the unformatted value of the cell. The unformatted value of the cell as defined by this package is the value displayed in the formula bar when selecting the cell. This can be a bit squidgy where the cell is actually populated with a formula. In that case this should contain the implied value based on my (or your) visibility to the excel value that would normally be there.
Range: a string
attribute methods Methods provided to adjust this attribute
unformatted
Definition: returns the attribute value
has_unformatted
Definition: a predicate method for the attribute
rich_text
Definition: This attribute holds a rich text data structure like "get_rich_text()" in Spreadsheet::ParseExcel::Cell with the exception that it doesn't bless each hashref into an object. The hashref's are also organized per the Excel xlsx information in the the sharedStrings.xml file. In general this is an arrayref of arrayrefs where the second level contains two positions. The first position is the place (from zero) where the formatting is implemented. The second position is a hashref of the formatting values. The format is in force until the next start place is identified.
note: It is important to understand that Excel can store two formats for the same cell and often they don't agree. For example using the attribute cell_font will not always contain the same value as specific fonts (or any font) listed in the rich text array.
Default: undef = no rich text defined for this cell
Range: an array ref of rich_text positions and definitions
attribute methods Methods provided to adjust this attribute
get_rich_text
Definition: returns the attribute value
has_rich_text
Definition: Indicates if the attribute has anything stored
cell_font
Definition: This holds the font assigned to the cell
Range: a hashref of definitions for the font
attribute methods Methods provided to adjust this attribute
get_font
Definition: returns the attribute contents
has_font
Definition: Predicate for the attribute contentss
cell_border
Definition: This holds the border settings assigned to the cell
Range: a hashref of border definitions
attribute methods Methods provided to adjust this attribute
get_border
Definition: returns the attribute contents
has_border
Definition: Indicates if the attribute has any contents
cell_style
Definition: This holds the style settings assigned to the cell
Range: a hashref of style definitions
attribute methods Methods provided to adjust this attribute
get_style
Definition: returns the attribute contents
has_style
Definition: Indicates if the attribute has anything stored
cell_fill
Definition: This holds the fill settings assigned to the cell
Range: a hashref of style definitions
attribute methods Methods provided to adjust this attribute
get_fill
Definition: returns the attribute value
has_fill
Definition: Indicates if the attribute has anything stored
cell_alignment
Definition: This holds the alignment settings assigned to the cell
Range: The alignment definition
attribute methods Methods provided to adjust this attribute
get_alignment
Definition: returns the attribute value
has_alignment
Definition: Indicates if the attribute has anything stored
cell_type
Definition: This holds the type of data stored in the cell. In general it follows the convention of ParseExcel (Date, Numeric, or Text) however, since custom coercions will change data to some possible non excel standard state this also allows a 'Custom' type representing any cell with a custom conversion assigned to it (by you either at the worksheet level or here).
Range: Text = Strings, Numeric = Real Numbers, Date = Real Numbers with an assigned Date conversion or ISO dates, Custom = any stored value with a custom conversion
attribute methods Methods provided to adjust this attribute
type
Definition: returns the attribute value
has_type
Definition: Indicates if the attribute has anything stored
cell_encoding
Definition: This holds the byte encodeing of the data stored in the cell
Default: Unicode
Range: Traditional encoding options
attribute methods Methods provided to adjust this attribute
encoding
Definition: returns the attribute value
has_encoding
Definition: Indicates if the attribute has anything stored
cell_merge
Definition: if the cell is part of a group of merged cells this will store the upper left and lower right cell ID's in a string concatenated with a ':'
Default: undef
Range: two cell ID's
attribute methods Methods provided to adjust this attribute
merge_range
Definition: returns the attribute value
is_merged
Definition: Indicates if the attribute has anything stored
cell_formula
Definition: if the cell value (raw xml) is calculated based on a formula the Excel formula string is stored in this attribute.
Default: undef
Range: Excel formula string
attribute methods Methods provided to adjust this attribute
formula
Definition: returns the attribute value
has_formula
Definition: Indicates if the attribute has anything stored
cell_row
Definition: This is the sheet row that the cell was read from. The value is stored in the user context ( either count from zero or count from one).
Range: the minimum row to the maximum row
attribute methods Methods provided to adjust this attribute
row
Definition: returns the attribute value
has_row
Definition: Indicates if the attribute has anything stored
cell_col
Definition: This is the sheet column that the cell was read from. The value is stored in the user context ( either count from zero or count from one).
Range: the minimum column to the maximum column
attribute methods Methods provided to adjust this attribute
col
Definition: returns the attribute value
has_col
Definition: Indicates if the attribute has anything stored
r
Definition: This is the cell ID of the cell
attribute methods Methods provided to adjust this attribute
cell_id
Definition: returns the attribute value
has_cell_id
Definition: Indicates if the attribute has anything stored
cell_hyperlink
Definition: This stores an arraryref of hyperlinks from the cell
attribute methods Methods provided to adjust this attribute
get_hyperlink
Definition: returns the attribute value
has_hyperlink
Definition: Indicates if the attribute has anything stored
cell_hidden
Definition: This stores the hidden state of the cell. The stored value indicates which entity is controlling hiddeness.
Range: (sheet|column|row|0)
attribute methods Methods provided to adjust this attribute
is_hidden
Definition: returns the attribute value
has cell_coercion =>( isa => HasMethods[ 'assert_coerce', 'display_name' ], reader => 'get_coercion', writer => 'set_coercion', predicate => 'has_coercion', clearer => 'clear_coercion', handles =>{ coercion_name => 'display_name',# }, );
cell_coercion
Definition: This attribute holds the tranformation code to turn an unformatted value into a formatted value.
Default: a Type::Tiny instance with sub types set to assign different inbound data types to different coercions for the target outcome of formatted data.
Range: If you wish to set this with your own code it must have two methods. First, 'assert_coerce' which will be applied when transforming the unformatted value. Second, 'display_name' which will be used to self identify. For an example of how to build a custom format see "custom_formats" in Spreadsheet::Reader::ExcelXML::Worksheet.
attribute methods Methods provided to adjust this attribute
get_coercion
Definition: returns the contents of the attribute
clear_coercion
Definition: used to clear this attribute
set_coercion
Definition: used to set a new coercion instance. Implementation of this method will also switch the cell type to 'Custom'.
has_coercion
Definition: Indicate if any coecion code is applied
Delegated method: Methods delegated from the instance for conversion type checking. The name delegated to is listed next to a link for the default method delegated from.
coercion_name => "display_name" in Type::Tiny
SUPPORT
TODO
1. Return the merge range in array and hash formats
2. Add calc chain values
AUTHOR
Jed Lund
jandrew@cpan.org
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) 2016 by Jed
DEPENDENCIES
Spreadsheet::Reader::ExcelXML - the package
SEE ALSO
Spreadsheet::Read - generic Spreadsheet reader
Spreadsheet::ParseExcel - Excel binary version 2003 and earlier (.xls files)
Spreadsheet::XLSX - Excel version 2007 and later
Spreadsheet::ParseXLSX - Excel version 2007 and later
All lines in this package that use Log::Shiras are commented out