The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-FixedWidth-0.13
River stage zero No dependents
++
/ Text::FixedWidth

NAME

Text::FixedWidth - Easy OO manipulation of fixed width text files

SYNOPSIS

   use Text::FixedWidth;

   my $fw = new Text::FixedWidth;
   $fw->set_attributes(qw(
      fname            undef  %10s
      lname            undef  %-10s
      points           0      %04d
   ));

   $fw->parse(string => '       JayHannah    0003');
   $fw->get_fname;               # Jay
   $fw->get_lname;               # Hannah
   $fw->get_points;              # 0003

   $fw->set_fname('Chuck');
   $fw->set_lname('Norris');
   $fw->set_points(17);
   $fw->string;                  # '     ChuckNorris    0017'

If you're familiar with printf formats, then this class should make processing fixed width files trivial. Just define your attributes and then you can get_* and set_* all day long. When you're happy w/ your values envoke string() to spit out your object in your defined fixed width format.

When reading a fixed width file, simply pass each line of the file into parse(), and then you can use the get_ methods to retrieve the value of whatever attributes you care about.

METHODS

new

Constructor. Does nothing fancy.

set_attributes

Pass in arguments in sets of 3 and we'll set up attributes for you.

The first argument is the attribute name. The second argument is the default value we should use until told otherwise. The third is the printf format we should use to read and write this attribute from/to a string.

  $fw->set_attributes(qw(
    fname            undef  %10s
    lname            undef  %-10s
    points           0      %04d
  );

set_attribute

Like set_attributes, but only sets one attribute at a time, via named parameters:

  $fw->set_attribute(
    name    => 'lname',
    default => undef,
    format  => '%10s',
  );

If an sprintf 'format' is insufficiently flexible, you can set 'reader' to a code reference and also define 'length'. For example, if you need a money format without a period:

  $fw->set_attribute(
    name    => 'points2',
    reader  => sub { sprintf("%07.0f", $_[0]->get_points2 * 100) },
    length  => 7,
  );
  $fw->set_points2(13.2);
  $fw->get_points2;        # 13.2
  $fw->getf_points2;       # 0001320

Similarly, you can set 'writer' to a code reference for arbitrary manipulations when setting attributes:

  $fw->set_attribute(
    name    => 'points3',
    writer  => sub { $_[1] / 2 },
    format  => '%-6s',
  );
  $fw->set_points3(3);
  $fw->get_points3;        # 1.5
  $fw->getf_points3;       # '1.5   '

parse

Parses the string you hand in. Sets each attribute to the value it finds in the string.

  $fw->parse(string => '       JayHannah    0003');

string

Dump the object to a string. Walks each attribute in order and outputs each in the format that was specified during set_attributes().

  print $fw->string;      #  '     ChuckNorris    0017'

getf_*

For the 'foo' attribute, we provide the getter get_foo() per the SYNOPSIS above. But we also provide getf_foo(). get_* returns the current value in no particular format, while getf_* returns the fixed-width formatted value.

   $fw->get_fname;    # Jay          (no particular format)
   $fw->getf_fname;   # '       Jay' (the format you specified)

auto_truncate

Text::FixedWidth can automatically truncate long values for you. Use this method to tell your $fw object which attributes should behave this way.

  $fw->auto_truncate("fname", "lname");

(The default behavior if you pass in a value that is too long is to carp out a warning, ignore your set(), and return undef.)

clone

Provides a clone of a Text::FixedWidth object. If available it will attempt to use Clone::Fast or Clone::More falling back on "dclone" in Storable.

   my $fw_copy = $fw->clone;

This method is most useful when being called from with in the "parse" method.

   while( my $row = $fw->parse( clone => 1, string => $str ) ) {
      print $row->foobar;
   }

See "parse" for further information.

ALTERNATIVES

Other modules that may do similar things: Parse::FixedLength, Text::FixedLength, Data::FixedFormat, AnyData::Format::Fixed

AUTHOR

Jay Hannah, <jay at jays.net>, http://jays.net

BUGS

Please report any bugs or feature requests to bug-text-fixedwidth at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-FixedWidth. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Text::FixedWidth

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008-2013 Jay Hannah, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.