POD AN::Tools::String

From Alteeve Wiki
Revision as of 02:32, 20 September 2009 by Digimer (talk | contribs)
Jump to navigation Jump to search

 AN!Tools :: AN::Tools :: POD AN::Tools::String

NAME

AN::Tools::String

This module handles all of the "string" functions. In other words, all processing of data to be written to log files or show to user's gets fed through here. This also handles loading one or more language's "words" from XML files into the '$an->data' hash reference.

SYNOPSIS

 use AN::Tools;

 # Get a common object handle on all AN::Tools::* modules.
 my $an=AN::Tools->new();
 
 # Access this module's methods using '$an->String->read_words()' syntax. For
 # example, this is how you would read in an XML words file.
 $an->String->read_words({file=>"/path/to/program/words.xml"});

DESCRIPTION

This module provides access to the various "words" processing methods. These include reading in XML words files, inserting variables into strings, processing template files and so forth.

NOTES

All AN::Tools::* modules expects the data they receive to be in UTF-8 encoded format. Likewise, they return UTF-8 encoded strings. If you are getting weird output or are seeing a "wide character in print" error, check that you are not getting double-encoded UTF-8 strings by casting your data as UTF-8 in the first place.

METHODS

Below are the detailed usage instructions for the methods provided by this module.

force_utf8

Example

 # Force 'utf8' mode for an XML words file to be read then turn it back off.
 $an->String->force_utf8(1);
 $an->String->read_words({file=>"/path/to/program/words.xml"});
 $an->String->force_utf8(0);

Details

This returns or sets whether the filehandle used to read files is forced into UTF8 mode. In practice, this should never be needed because all files should already be saved as UTF-8 encoded files. However, if this is not the case, setting this to '1' will tell AN::Tools::String methods to call 'binmode FH, encoding(utf8);'.

If you use this and then see "wide-character in print" warnings, try setting this back to 0,

read_words

Example

 # Read in your program's XML words file into the '$an->data' hash reference.
 $an->String->read_words({file=>"/path/to/program/words.xml"});
 
 # Same, but this time read the XML words file into your own dedicated hash
 # reference.
 my $hash={};
 $an->String->read_words({
       file    =>      "/path/to/program/words.xml",
       hash    =>      $hash
 });

Details

This reads in an XML words file with your program's words. By default, the data is fed into the '$an->data' hash reference under the 'words' key. This data is meant to be accessed and manipulated by the get_word method, but if you have a need to directly access it, it is in the following format:

  1. Get the 'an_0000' keyed word under the Canadian English (en_CA) language. my $word=$an->data()->{words}{lang}{en_CA}{key}{an_0000}{content}; print "Word: [$word].\n"; # prints "Word: [AN::Tools rapid development suite.]."

If you pass your own hash reference, AN::Tools will not have access to the words you read by default. To let get_word access your words you will need to pass the hash param when calling it (and other) methods in the future. Using the example above, you would access data fed into your hash file this way:

  1. Get the 'an_0000' keyed word under the Canadian English (en_CA) language. my $word=$hash->{words}{lang}{en_CA}{key}{an_0000}{content}; print "Word: [$word].\n"; # prints "Word: [AN::Tools rapid development suite.]."

Parameters

file

This is the relative or fully defined path to your XML word file to read.

hash

Default: $an->data

This is an optional, alternative hash reference to read your word file into.

XML Words Format Details

This describes the format of the XML word files used by AN::Tools. Please see the build-in tools.xml file in the root of the AN::Tools module directory for a better feel for these file's layout.

The "word" file is structured like this:

<?xml version="1.0" encoding="UTF-8"?>
<words>
       <langs>en_CA,jp</langs>
       <lang name="en_CA" long_name="Canadian English">
               <key name="comment">Created by Madison Kelly (mkelly@alteeve.com) for the AN::Tools suite of perl modules.</key>
               <key name="an_0000">AN::Tools rapid development suite.</key>
       </lang>
       
       <langs>jp</langs>
       <lang name="jp" long_name="日本語">
               <key name="comment">Created by Madison Kelly (mkelly@alteeve.com) for the AN::Tools suite of perl modules.</key>
               <key name="an_0000">テスト単語</key>
       </lang>
</words>

All languages are within the 'words' block. The first argument, langs, is a comma-seperated list of enabled languages. This allows you to have a work-in-progress language without making it available to users of the program by simply leaving out of this list.

Each actual language is contained in a lang block. The most important entry is the name value. This must be set to the language's ISO language code and must be in the langs CSV value above in order to be used. The long_name is the name of the language. This is generally written in the language itself and this is the value shown to users when they choose which language they wish to use.

Within each lang block is a collection of key blocks; One for each word string available to the program. These key entries have one variable called name which is the key used in your program to call the string. It is critical that each keys in all languages have the same meaning!

Using the key block.

To embed HTML into a string, simply wrap the contents in a <![CDATA[...]]> block. Anything within a CDATA is uninterpreted by AN::Tools.

Both CDATA blocks and normal word strings can span muliple lines. When this is the case, AN::Tools automatically removes the first and last line wrap. This allows you to make your XML words file a little cleaner by letting you start you multi-line string on a new line and also put your closing </key> key on an indented new line.

By convention only, key names are generally in the format "<prefix>_<4-digit-padded_sequence>". If you expect your project will used more that 10,000 entries you may want to use a five-digit padded sequence number. However, you may just as well wish to use a totally different naming convention, it is up to you. It only matters that no two strings have the same associated key name.

The only exception is error_####. AN::Tools will try to parse these keys when exiting in an error state to set an exit code. The idea is that this allows a way to easily keep a language-independant, up to date exit code library. This is not strictly required though, and without it AN::Tools will exit with a generic 65536 (unknown error) code.

You can also embed variables into strings in any order you wish. This allows for different languages to construct sentances in any order irregardless of where the English strings inserts variables and values. Recognized replacement keys are:

- #!data!...!# - Substitute in any value found in the '$an->data' hash. This
                 uses the format: #!data!foo::bar!# which corresponds to the
                 hash value: $an->data->{foo}{bar}.
- #!var!...!#  - Substitute in variables passed in from the program. These can
                 be inserted in any order you wish. This uses the format:
                 #!var!0!# which corresponds to the first value in the
                 "variable" array reference passed to the
                 $an->String->get_string() method. #!var!1!# would be the
                 second and so on.
- #!word!...!# - Substitute in another word key. This uses the format:
                 #!word!an_0000!# which would substitute the same language's
                 value found in the given key (an_0000 in this case).
                 NOTE: You CAN NOT substitute in a string that has #!var!x!#
                       values of it's own. This would cause AN::Tools to now
                       know where put the values in it's 'var' array
                       reference. If you need this, pre-process your string
                       and pass it in as another variable.

When adding word strings specific to your project, and if you wish to make use of future releases of AN::Tools, it is *strongly* advised that you create a new 'X_####' section (or sections) specifically for your program. In this way, it is unlikely future additions or removal or core keys will ever conflict with your program. A list of keys used by the AN::Tools suite is below.

Translating

To add a new langage, copy a completed language between '<lang ...>' and '</lang>' and change the 'name' to the ISO code for the language you are adding. Once your translation is ready (or to test), add your languages' ISO code to the '<langs>...</langs>' CSV entry. It should then show up in the user's profile right away, assuming 'system::display::enable_user_language' is not set to '0'.

Some words may appear to be duplicates when in fact each is used depending on the user's display mode. For example, 'title_0001' is used when writing out to a console where 'title_0002' is used when writing out to a browser and in turn uses the 'CDATA' pragma to embed a link. Please be very sure before merging or deleting keys!

Reserved Keys

AN::Tools uses an internal words file that uses the following keys. Please do not use the same name space in your program to avoid conflicts.

an_####
These are the word strings used internally by the various AN::Tools modules.
t_####
These are word strings used by 't/String.t' to test the AN::Tools::String module's methods.
ta_####
These are word strings used in 't/test.xml' by 't/String.t' to test the AN::Tools::String module's methods that offer alternate hash support.

SEE ALSO

Other modules in the AN::Tools suite:

AN::Tools
AN::Tools::Alert
AN::Tools::Readable
AN::Tools::Math

LICENSE

Copyright (c) 2009 Alteeve's Niche!. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

 

Any questions, feedback, advice, complaints or meanderings are welcome.
Alteeve's Niche! Enterprise Support:
Alteeve Support
Community Support
© Alteeve's Niche! Inc. 1997-2024   Anvil! "Intelligent Availability®" Platform
legal stuff: All info is provided "As-Is". Do not use anything here unless you are willing and able to take responsibility for your own actions.