NAME

Spreadsheet::Reader::Format - Formatting for various spreadsheet readers

SYNOPSYS

#!/usr/bin/env perl
use MooseX::ShortCut::BuildInstance 'build_instance';
use Spreadsheet::Reader::Format;
use Spreadsheet::Reader::Format::FmtDefault;
use Spreadsheet::Reader::Format::ParseExcelFormatStrings;
use Spreadsheet::Reader::ExcelXML;
my $formatter = build_instance(
	package => 'FormatInstance',
	# The base United State localization settings - Inject your customized format class here
	superclasses => [ 'Spreadsheet::Reader::Format::FmtDefault' ],
	# ParseExcelFormatStrings => The Excel string parser generation engine
	# Format => The top level interface defining minimum compatability requirements
	add_roles_in_sequence =>[qw(
		Spreadsheet::Reader::Format::ParseExcelFormatStrings
		Spreadsheet::Reader::Format
	)],
	target_encoding => 'latin1',# Adjust the string output encoding here
	datetime_dates	=> 1,
);

# Use in a standalone manner
my	$date_string = 'yyyy-mm-dd';
my	$time		= 55.0000102311;
# Build a coercion with excel format string: $date_string
my	$coercion	= $formatter->parse_excel_format_string( $date_string );
# Checking that a DateTime object was returned
print ref( $coercion->assert_coerce( $time ) ) . "\n";
# Checking that the date and time are presented correctly: 1904-02-25T00:00:01
print $coercion->assert_coerce( $time ) . "\n";

# Set specific default custom formats here (for use in an excel parser)
$formatter->set_defined_excel_formats( 0x2C => 'MyCoolFormatHere' );

# Use the formatter like Spreadsheet::ParseExcel
my $parser	= Spreadsheet::Reader::ExcelXML->new;
my $workbook = $parser->parse( '../t/test_files/TestBook.xlsx', $formatter );

DESCRIPTION

In general a completly built formatter class as shown in the SYNOPSYS is already used by the package Spreadsheet::Reader::ExcelXML to turn unformatted data into formatted data. The purpose is to allow the Excel equivalent of localization of the output. The general localization options are mostly found at the workbook level. Individual cells also contain information about how that cell data should be formatted.

It is possible to insert alternate roles in the Formatter build or use methods to customize the defaults used by the formatter for use in the Spreadsheet reader. It is also possible to use the formatter to output custom format code for post processing output..

Module Description

This module is written to be an Interface for the Formatter class used in Spreadsheet::Reader::ExcelXML so that the core parsing engine and the regional formatting settings for the parser can easily be swapped. This interface really only defines method requirements for the undlerlying instance since the engine it uses was custom-built for Spreadsheet::Reader::ExcelXML. However, adding a shim to this package so it can be used by Spreadsheet::ParseExcel (for example) should be easier because of the abstraction.

This module does not provide unique methods. It just requires methods and provides a uniform interface for the workbook package. Additional attributes and methods provided by the sub modules may be available to the instance but are not in the strictest sence required.

Methods

These are the methods required by this interface. Links to the default implementation of each method are provided but any customization of the formatter instance for Spreadsheet parsing will as a minimum require these methods.

parse_excel_format_string( $string, $name )

Definition: This is the method to convert Excel format strings to code that will translate raw data from the file to formatted output in the form defined by the string. It is possible to pass a format name that will be incorperated so that the method $coercion->display_name returns $name.

Default source: "parse_excel_format_string( $string, $name )" in Spreadsheet::Reader::Format::ParseExcelFormatStrings

get_defined_conversion( $position )

Definition: This method returns the code for string conversion for a pre-defined conversion by position.

Default source: "get_defined_conversion( $position )" in Spreadsheet::Reader::Format::ParseExcelFormatStrings

set_target_encoding( $encoding )

Definition: This sets the output $encoding for strings.

Default source: "set_target_encoding( $encoding )" in Spreadsheet::Reader::Format::FmtDefault

get_target_encoding

Definition: This returns the output encoding definition for strings.

Default source: "get_target_encoding" in Spreadsheet::Reader::Format::FmtDefault

has_target_encoding

Definition: It is possible to not set a target encoding in which case any call to decode data acts like a pass through. This returns true if the target encoding is set.

Default source: "has_target_encoding" in Spreadsheet::Reader::Format::FmtDefault

change_output_encoding( $string )

Definition: This is the method call that implements the output encoding change for $string.

Default source: "change_output_encoding( $string )" in Spreadsheet::Reader::Format::FmtDefault

get_excel_region

Definition: It may be useful for this instance to self identify it's target output. This method returns that value

Default source: "get_excel_region" in Spreadsheet::Reader::Format::FmtDefault

set_defined_excel_formats( %args )

Definition: This allows for adjustment and or addition to the output format lookup table. The default implementation allows for multiple ways to do this so please review that documentation for details.

Default source: "set_defined_excel_formats( %args )" in Spreadsheet::Reader::Format::FmtDefault

set_cache_behavior( $bool )

Definition: This sets the flag that turns on caching of built format conversion code sets

Default source: "set_cache_behavior( $bool )" in Spreadsheet::Reader::Format::ParseExcelFormatStrings

set_date_behavior( $bool )

Definition: This sets the flag that interrupts the date formatting to return a datetime object rather than a date string

Default source: "set_date_behavior( $bool )" in Spreadsheet::Reader::Format::ParseExcelFormatStrings

set_european_first( $bool )

Definition: This also sets a flag dealing with dates. The date behavior that is affected here involves parsing date strings (not excel date numbers) and checks the DD-MM-YY form before it checkes the MM-DD-YY form when attempting to parse date strings.

Default source: "set_european_first( $bool )" in Spreadsheet::Reader::Format::ParseExcelFormatStrings

set_workbook_inst( $instance )

Definition: This sets the workbook instance in the Formatter instance. Spreadsheet::Reader::ExcelXML should do this automatically and will overwrite this attribute if the end-user sets it. The purpose of this instance is for the formatter to see some of the workbook level methods;

Delegates:

"set_error" in Spreadsheet::Reader::ExcelXML

"get_epoch_year" in Spreadsheet::Reader::ExcelXML

Default source: "set_workbook_inst( $instance )" in Spreadsheet::Reader::Format::ParseExcelFormatStrings