PICU - Perl wrappers for ICU Copyright 2000-2002, Brian Stell All rights reserved. This package is free software; you can redistribute it and/or modify it under the terms of the "Artistic License" which comes with this Kit. This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Artistic License for more details. You should have received a copy of the Artistic License with this Kit, in the file named "Artistic". If not, I'll be glad to provide one. For the latest information see the Picu homepage: http://picu.sourceforge.net/ James Briggs (mrperl) hereby assigns all copyright for his past and future Picu contributions to Brian Stell. Dated 2002 03 24. Current date: June 2001 $Id: README,v 1.12 2002/07/22 01:59:14 bstell Exp $ ========================================================================= INTRODUCTION (Note: Picu is under development and is in an early alpha stage.) (Please see the Picu homepage: http://picu.sourceforge.net/) Perl wrappers for ICU (PICU) provides Perl access to ICU. ICU is an internationalization (i18n) library from IBM which allows the same body of code to work in many languages (locales). Consider formatting monetary units (assume 1 million monetary units and ignore the relative value): American: $1,000,000.00 French: 1 000 000,00 F German: 1.000.000,08 DM Note the difference in the 'thousands' separator and the decimal point between these locales. Without an i18n library, applications tend to end up: 1) only supporting English (actually, American), 2) with a lot of conditional code, or 3) with separate versions for each language. ICU provides core the i18n for Java. The features in ICU include (see http://oss.software.ibm.com/icu/): Calendar support Message formatting Character set conversions Normalization Collation (language-sensitive) Number & currency formatting Date & time formatting Time zones Locales (140+ supported) Transliteration Message catalogs (resources) Word, line & sentence breaks ========================================================================= BUILDING PICU ------------- This package is under development and may be buggy. Please see 'STATUS' for more details. Make sure the requires software is installed. Perl 5.6.1 - type 'perl --version' to get the version ICU 2.1 - see if /usr/local/lib/libicudata.so.21 or /usr/local/lib/icu/2.1 exists See 'REQUIRED SOFTWARE' for more details To build this Picu package: perl Makefile.PL make make test make install ========================================================================= USING PICU ---------- There is sample code in the $TOP/samples/ dir. ========================================================================= STATUS ------ This package is under development. Note: Picu has been successfully built on Redhat Linux 6.2 and 7.0 (Linux 2.2 kernels) and SUSE 8.0 (Linux 2.4 kernel). ICU itself has been ported and tested on numerous platforms, including multiple versions of Unix and Windows. There is no support but you are free to submit patches. If possible, send in patches such a way that the patch program will apply them. Context diffs are the best, then normal diffs. Don't send ed scripts-- The code has probably changed since the version you have. This package is probably incomplete and buggy. This package probably leaks memory and may crash. The APIs may be changed in the future. The tests (make test) need work. See the Picu homepage: http://picu.sourceforge.net/ or http://perlicu.org/ ========================================================================= REQUIRED SOFTWARE ----------------- Requires Perl 5.6.0 (or greater, 5.6.1 recommended because of bugfixes) Picu is known to *NOT* compile on Perl 5.005 Install ICU on you system You should build with ICU 2.1 which is available as a tarball and patch from: http://oss.software.ibm.com/icu/download/2.1/ Picu will not work with ICU 1.6 It has been built with obsolete ICU 1.7, 1.8 and 2.0 . The very latest version (bleeding edge) of ICU is available from the ICU cvs repository but is NOT recommended. To get ICU via cvs go to http://oss.software.ibm.com/icu/ and follow the cvs instructions. ========================================================================= MAILING LISTS ------------- Join the Picu developer mailing list at http://lists.sourceforge.net/mailmanlistinfo/picu-developer There is also an email-based interface that can be used to join the mailing list. For details send a message with just the word `help' as subject or in the body, to: picu-developer-request@lists.sourceforge.net ========================================================================= API DESIGN ---------- The Picu API is patterned after the ICU C++ API. Picu tries to support ICU's C++ function overloading. Picu's API differs slightly from ICU's API in that Picu tries to follow the Perl model and return the result as a return value (lhs) rather than returning the result in an object that was passed in by reference. Picu follows ICU's error status model: the error status is passed in as a reference so that multiple call can be "chained" and the status need only be inspected at the end of the chain. If no error status reference is passed in the Picu cannot return a status code. Regardless of whether or not a status reference is passed in: if an error occurs the Picu API returns an undef. In Perl scripts this package is refered to as 'ICU'. To avoid namespace collision with icu (the IBM package): C/C++ the header files are located in $TOP/include/picu/ (ie: 'picu' is in the path). Environment variables start with 'PICU_' ========================================================================= DIR AND FILE LAYOUT ------------------- $TOP/classes/ the ICU C++ wrappers are in the $TOP/classes/ dir $TOP/CharacterSet character set specific scripts $TOP/samples the sample scripts $TOP/t the test scripts $TOP/util the utility / debug code ========================================================================= ADDING A METHOD TO A CLASS -------------------------- - just cut and paste a method with a similar interface from DateFormat or another class and customize ========================================================================= ADDING A NEW CLASS ------------------ For now: use DateFormat.xs, DateFormat.pm as a template. Be sure to make appropriate tests. Checklist for Adding Class Foo - read the ICU Draft Users Guide for a high level ICU understanding - read the ICU API Reference, especially for class Foo - think of how to design your class to be Perlish using the public methods (some methods are overly C++ ish in nature and not suitable for Perl.) - cd $TOP - create include/picu/Foo.h (optional) - create samples/Foo.pl - create t/Foo.t - add Foo entries in classes/ICU/ICU.xs (otherwise you get "Deep Recursion") - add Foo entries in Makefile.PL (otherwise Foo won't build) - add Foo entries in icu_typemap (otherwise Perl won't know Foo) - mkdir classes/Foo - cd classes/Foo - cp ../DateFormat/DateFormat.pm Foo.pm - cp ../DateFormat/DateFormat.xs Foo.xs - Foo.pm: search and replace s/DateFormat/Foo/g, add/modify enums - Foo.xs: search and replace s/DateFormat/Foo/g, add/modify methods - cd $TOP; make clean; perl Makefile.PL; make; make test; make install - cd samples; perl Foo.pl ========================================================================= USING gdb with perl and XS -------------------------- To debug into XS code using 2 windows: - build perl with -DDEBUGGING - add -ggdb option to CC in picu Makefile.PL to enable debugging - perl Makefile.PL;make;make test;make install - perl -d dateFormat.pl - open a new terminal window - get PID of perl process - ps -ef | grep perl - gdb - attach PID - load $TOP/classes/DateFormat/DateFormat.o - break whatever To debug into XS code using 1 window: - use an expect script to manage the communication - there is a Perl module called Gdb that may also help You may need a proper debugging version of the C libraries for this to work at all. ActiveState has demonstrated this technique. ========================================================================= USING DEBUG_100 --------------- (TBD) ========================================================================= Good luck, Brian Stell and Captain James