view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    If cacheing is ON, then after successfully reading the text file (either
    because there was no cache file yet or the cache file was out of date or
    corrupted or otherwise unusable), read() will then try to create a cache
    file. This, of course, takes some time, but the time taken will be more
    than made up in the speedup of the next read() operation on the same
    file.

    If creating the cache file fails (for example, because file permissions
    didn't allow the cache directory to be created or the cache file to be
    written), read() generates a warning explaining why cacheing failed, but
    the read() operation itself still succeeds.

    No parameters in the object itself are set or modified to indicate the
    success or failure of writing the cache file.

    Similarly, there is no way to tell whether a successful read() operation
    read from the cache or from the original data file. If you want to be
    SURE the reading was from the data file, either turn off _CacheOnRead,
    or call the read_file() method instead of read().

    NOTE: because the name of the cache file to be used is calculated just
    before the read() is actually done, the cache file can only be found if
    the _CacheSubDir and _CacheExtension are the same as they were when the
    cache was last created. If you change these parameters after having
    previously cached a file, the older caches could be "orphaned" and just
    sit around wasting disk space.

  Cacheing on write()

    You may optionally set _CacheOnWrite (default = false) to true. If done,
    then a cache file will be saved for files written using the write()
    command. Read about write() below for more about why you might want to
    do this.

AUTOMATIC DIRECTORY CREATION
    When Data::CTable needs to write a file, (a cache file or a data file),
    it automatically tries to create any directories or subdirectories you
    specify in the _FileName or _CacheSubDir parameters.

    If it fails while writing a data file, write() will fail (and you will
    be warned). If it fails to create a directory while writing a cache
    file, a warning will be issued, but the overall read() or write()
    operation will still return a result indicating success.

    Any directories created will have the permissions 0777 (world-write) for
    easy cleanup.

    Generally, the only directory the module will have to create is a
    subdirectory to hold cache files.

    However, since other directories could be created, be sure to exercise
    caution when allowing the module to create any directories for you on
    any system where security might be an issue.

    Also, if the 0666 permissions on the cache files themselves are too
    liberal, you can either 1) turn off cacheing, or 2) call the
    prep_cache_file() method to get the name of the cache file that would
    have been written, if any, and then restrict its permissions:

            chmod (0600, $this->prep_cache_file());

READING DATA FILES
            ## Replacing data in table with data read from a file

            $t->read($Path)     ## Simple calling convention

            $t->read(           ## Named-parameter convention

                 ## Params that override params in the object if supplied...

                 _FileName      => $Path, ## Full or partial path of file to read

                 _FieldList     => [...], ## Fields to read; others to be discarded

                 _HeaderRow     => 0,     ## No header row (_FieldList required!)

                 _LineEnding    => undef, ## Text line ending (undef means guess)
                 _FDelimiter    => undef, ## Field delimiter (undef means guess)

                 _ReturnMap     => 1,     ## Whether to decode internal returns
                 _ReturnEncoding=>"\x0B", ## How to decode returns.
                 _MacRomanMap   => undef, ## Whether/when to read Mac char set 

                 _CacheOnRead   => 0,     ## Enable/disable cacheing behavior
                 _CacheExtension=> ".x",  ## Extension to add to cache file name
                 _CacheSubDir   => "",    ## (Sub-)dir, if any, for cache files

                 ## Params specific to the read()/write() methods...

                 _MaxRecords    => 200,   ## Limit on how many records to read
                 )

            $t->read_file()     ## Internal: same as read(); ignores cacheing

    read() opens a Merge, CSV, or Tab-delimited file and reads in all or
    some fields, and all or some records, REPLACING ANY EXISTING DATA in the
    CTable object.

    Using the simple calling convention, just pass it a file name. All other
    parameters will come from the object (or will be defaulted if absent).
    To specify additional parameters or override any parameters in the
    object while reading, use the named-parameter calling convention.

    See the full PARAMETER LIST, above, or read on for some extra details:

    _ReturnMap controls whether return characters encoded as ASCII 11 should
    be mapped back to real newlines (""\n"") when read into memory. If
    false, they are left as ASCII 11 characters. (default is "true")

    _ReturnEncoding controls the character that returns are encoded as, if
    different from ASCII 11.

    _FieldList is an array (reference) listing the names of fields to
    import, in order (and will become the object's _FieldList upon
    successful completion of the read() operation). If not provided and not
    found in the object, or empty, then all fields found in the file are
    imported and the object's field list will be set from those found in the
    file, in the order found there. If _HeaderRow is false, then this
    parameter is required (either in the object or as a formal parameter)
    and is assumed to give the correct names for the fields as they actually