NAME

Spreadsheet::XLSX::Reader::LibXML::FmtDefault - Default xlsx number formats and localization

PACKAGE SYNOPSIS

    #!/usr/bin/env perl
        use     Spreadsheet::XLSX::Reader::LibXML::FmtDefault;
        use     Spreadsheet::XLSX::Reader::LibXML;
        my      $formatter =    Spreadsheet::XLSX::Reader::LibXML::FmtDefault->new(
                                                                target_encoding => 'latin1',
                                                                datetime_dates  => 1,
                                                                dont_inherit    => 1,
                                                        );
                $formatter->set_defined_excel_formats( 0x2C => 'MyCoolFormatHere' );
        my      $parser = Spreadsheet::XLSX::Reader::LibXML->new;
        my      $workbook = $parser->parse( $file, $formatter );
                $workbook = Spreadsheet::XLSX::Reader::LibXML->new(# This is an alternate way
                                                file_name               => $file,
                                                formatter_inst  => $formatter,
                                        );

PACKAGE DESCRIPTION

If you wish to set attributes for the formatter class that are fixed and not inherited by the package then you can build the formatter class with the attribute dont_inherit set to 1 and then pass that instance as either the second argument to the "parse( $file_name|$file_handle, $formatter )" in Spreadsheet::XLSX::Reader::LibXML command or to the attribute "formatter_inst" in Spreadsheet::XLSX::Reader::LibXML when calling new. The following formatter attributes are inherited if 'dont_inherit' is not set. It should be noted that datetime_dates can be set via a method inherited by the workbook

        package                 => formatter
        ################           ################
        error_inst              => error_inst
        get_epoch_year (method) => epoch_year
        cache_positions         => cache_formats

If you want to modify the default output formats you can do that here and they won't be overwritten even if 'dont_inherit => 0'.

CLASS SYNOPSIS

        #!/usr/bin/env perl
        use             Spreadsheet::XLSX::Reader::LibXML::FmtDefault;
        my              $formatter = Spreadsheet::XLSX::Reader::LibXML::FmtDefault->new;
        my              $excel_format_string = $formatter->get_defined_excel_format( 0x0E );
        print   $excel_format_string . "\n";
                        $excel_format_string = $formatter->get_defined_excel_format( '0x0E' );
        print   $excel_format_string . "\n";
                        $excel_format_string = $formatter->get_defined_excel_format( 14 );
        print   $excel_format_string . "\n";
                        $formatter->set_defined_excel_formats( '0x17' => 'MySpecialFormat' );#Won't really translate!
                        $excel_format_string = $formatter->get_defined_excel_format( 23 );
        print   $excel_format_string . "\n";
        my              $conversion     = $formatter->parse_excel_format_string( '[$-409]dddd, mmmm dd, yyyy;@' );
        print   'For conversion named: ' . $conversion->name . "\n";
        for my  $unformatted_value ( '7/4/1776 11:00.234 AM', 0.112311 ){
                print "Unformatted value: $unformatted_value\n";
                print "..coerces to: " . $conversion->assert_coerce( $unformatted_value ) . "\n";
        }

        ###########################
        # SYNOPSIS Screen Output
        # 01: yyyy-mm-dd
        # 02: yyyy-mm-dd
        # 03: yyyy-mm-dd
        # 04: MySpecialFormat   
        # 05: For conversion named: DATESTRING_0
        # 06: Unformatted value: 7/4/1776 11:00.234 AM
        # 07: ..coerces to: Thursday, July 04, 1776
        # 08: Unformatted value: 0.112311
        # 09: ..coerces to: Friday, January 01, 1904
        ###########################

CLASS DESCRIPTION

This documentation is written to explain the lesser used options and features of this class. The general use of the main package is explained in the documentation for Workbooks. In general replacement of this class requires replacement of the methods and attributes documented here and in Spreadsheet::XLSX::Reader::LibXML::ParseExcelFormatStrings. The private methods and attributes here (if any) are up to you. It is possible to replace only this class and use the role ~::ParseExcelFormatStrings with it. Additionally while this class has been changed from a role to better match the flow of Spreadsheet::ParseExcel The actual implementation is very different since the underlying architecture is different as well. (The ~::ParseExcel equivalent is therefore not interchangeable)

This class is the tool for number and string localization. It stores the number conversion format strings and the code of the defined region. In this particular case this module is set for the base english conversion set. It does rely on Spreadsheet::XLSX::Reader::LibXML::ParseExcelFormatStrings to build the actual coercions used to transform numbers for each format string. However, the ParseExcelFormatStrings transformation should work for all region specific strings. When changing the number formats (output) for this class you could just set a different hash ref when calling a new or update the values with the method set_defined_excel_formats. This package also uses Encode to provide for encoding changes for strings. In general the package XML::LibXML pulls the defined encoding for the Excel file from the underlying XML encoding and auto parses it to perl coding for storage. This package does provide a way to export the data out to your target_encoding.

Primary Methods

These are the primary ways to use this class. For additional FmtDefault options see the Attributes section.

get_defined_excel_format( $position )

Definition: This will return the preset excel format string for the stored position. The positions are actually stored in a hash where the keys are integers representing a position in an order list.

Accepts: an integer or an octal number or octal string for the for the format string $position

Returns: an excel format string

Delegated to the workbook class: yes

set_defined_excel_formats( %args )

Definition: This will set the excel format strings for the stored positions. The positions are actually stored in a hash where the keys are integers representing a position in an order list.

Accepts: a Hash list, a hash ref (both with keys representing positions), or an array of strings with the update strings in the equivalent position. All empty positions are ignored meaning that the defalt value is left in force. To erase the default value send '@' (passthrough) as the format string for that position. This function does not do any string validation. The validation is done when the coercion is generated.

Returns: 1 for success

total_defined_excel_formats

Definition: This returns the current count of excel formats that are defined

Accepts: nothing

Returns: $count (an integer)

Delegated to the workbook class: yes

change_output_encoding( $string )

Definition: This is always called by the Worksheet when a cell value is retreived in order to allow for encoding adjustments on the way out. See "ENCODINGS SUPPORT IN XML::LIBXML" in XML::LibXML for an explanation of how the input encoding is handled. This conversion out is done prior to any number formatting. If you are replacing this role you need to have the function and you can use it to mangle your output string any way you want.

Accepts: a perl coded string

Returns: the converted $string decoded to the defined format

Delegated to the workbook class: yes

get_defined_conversion( $position )

Defined in "get_defined_conversion( $position )" in Spreadsheet::XLSX::Reader::LibXML::ParseExcelFormatStrings

parse_excel_format_string( $format_string, $name )

Defined in "parse_excel_format_string( $string, $name )" in Spreadsheet::XLSX::Reader::LibXML::ParseExcelFormatStrings

Delegated to the workbook class: no

Attributes

Data passed to new when creating an instance of this class. For modification of these attributes see the listed 'attribute methods'. For more information on attributes see Moose::Manual::Attributes. The easiest way to modify these attributes are when a class instance is created and before it is passed to the workbook or parser.

error_inst

Definition: This is mostly a place to store the shared error reporting instance from the workbook. It is not necessary to define this attribute since it will be overwritten by the workbook when the Spreadsheet::XLSX::Reader::LibXML instance is loaded to the parser / workbook.

Required Methods: (of the instance) error, set_error, clear_error

Default: none

Attribute required: no

attribute methods Methods provided to adjust this attribute

set_error_inst

Definition: use to set a new error instance.

excel_region

Definition: This records the target region of this localization role (Not the region of the Excel workbook being parsed). It's mostly a reference value.

Default: en = english

Attribute required: no

attribute methods Methods provided to adjust this attribute

get_excel_region

Definition: returns the value of the attribute (en)

set_excel_region

Definition: sets the value of the attribute.

target_encoding

Definition: This is the target output encoding. If it is not defined the string transformation step becomes a passthrough. When the value is loaded it is used as a 'decode' target by Encode to transform the internally stored perl string to some target 'output' formatting. The testing for the results of entering actual values here is weak.

Attribute required: no

Default: none

Range: Any encoding recognized by Encode

attribute methods Methods provided to adjust this attribute

set_target_encoding( $encoding )

Definition: This should be recognized by "Listing available encodings" in Encode

get_target_encoding

Definition: Returns the currently set attribute value

defined_excel_translations

Definition: In Excel part of localization is the way numbers are displayed. Excel manages that with a default list of format strings that make the numbers appear in a familiar way. This is where you store / change that list for this package. In this case the numbers are stored as hash key => value pairs where the keys are integers representing the format string position and the values are the Excel readable format strings (definitions). Beware that if you change the list your reader may break if you don't supply replacements for all the values in the default list. If you just want to replace some of the values use the method set_defined_excel_formats.

Attribute required: yes

Default: see the code

Range: Any hashref of formats recognized by Spreadsheet::XLSX::Reader::::LibXML::ParseExcelFormatStrings

attribute methods Methods provided to by the attribute to adjust it.

total_defined_excel_formats

Definition: get the count of the current key => value pairs

See get_defined_excel_format and set_defined_excel_formats

dont_inherit

Definition: If for some reason you wish to set the formatter instance with settings that do not inherit from the workbook then this attribute if for you. The package to formtter inheritances are identified in the PACKAGE DESCRIPTION

Attribute required: no

Default: 0 = inherit from the package

Range: 1|0

attribute methods Methods provided to by the attribute to adjust it.

block_inherit

Definition: This is the reader for the attribute value