view release on metacpan or  search on metacpan

lib/AnyData.pm  view on Meta::CPAN

=back

=head2 Multiple Row Operations

The AnyData hash returned by adTie() may use either single values as keys, or a reference to a hash of comparisons as a key.  If the key to the hash is a single value, the hash operates on a single row but if the key to the hash is itself a hash refe...

 my $num_deleted = delete $table->{Sue};

This example deletes a single row where the key column has the value 'Sue'.  If multiple rows have the value 'Sue' in that column, only the first is deleted.  It uses a simple string as a key, therefore it operates on only a single row.

 my $num_deleted = delete $table->{ {name=>'Sue'} };

This example deletes all rows where the column 'name' is equal to 'Sue'.  It uses a hashref as a key and therefore operates on multiple rows.

The hashref used in this example is a single column comparison but the hashref could also include multiple column comparisons.  This deletes all rows where the the values listed for the country, gender, and age columns are equal to those specified:

  my $num_deleted = delete $table->{{ country => 'us',
                                       gender => 'm',
                                          age => '25'
                                   }}


In addition to simple strings, the values may be specified as regular expressions or as numeric or alphabetic comparisons.  This will delete all North American males under the age of 25:

  my $num_deleted = delete $table->{{ country => qr/mx|us|ca/,
                                      gender  => 'm',
                                      age     => '< 25'
                                   }}

If numeric or alphabetic comparisons are used, they should be a string with the comparison operator separated from the value by a space, e.g. '> 4' or 'lt b'.

This kind of search hashref can be used not only to delete multiple rows, but also to update rows.  In fact you *must* use a hashref key in order to update your table.  Updating is the only operation that can not be done with a single string key.

The search hashref can be used with a select statement, in which case it returns a reference to an array of rows matching the criteria:

 my $male_players = $table->{{gender=>'m'}};
 for my $player( @$male_players ) { print $player->{name},"\n" }

This should be used with caution with a large table since it gathers all of the selected rows into an array in memory.  Again, 'each' is a much better way for large tables.  This accomplishes the same thing as the example above, but without ever pull...

 while( my $row= each %$table ) {
   print $row->{name}, "\n" if $row->{gender}=>'m';
 }

Search criteria for multiple rows can also be used with the adRows() function:

  my $num_of_women = adRows( $table, gender => 'w' );

That does *not* pull the entire table into memory, it counts the rows a record at a time.

=head2 Using Remote Files

If the first file parameter of adTie() or adConvert() begins with "http://" or "ftp://", the file is treated as a remote URL and the LWP module is called behind the scenes to fetch the file.  If the files are in an area that requires authentication, ...

For example:

  # read a remote file and access it via a tied hash
  #
  my $table = adTie( 'XML', 'http://www.foo.edu/bar.xml' );

  # same with username/password
  #
  my $table = ( 'XML', 'ftp://www.foo.edu/pub/bar.xml', 'r'
                { user => 'me', pass => 'x7dy4'
              );

  # read a remote file, convert it to an HTML table, and print it
  #
  print adConvert( 'XML', 'ftp://www.foo.edu/pub/bar.xml', 'HTMLtable' );

=head2 Using Strings and Arrays

Strings and arrays may be used as either the source of data input or as the target of data output.  Strings should be passed as the only element of an array reference (in other words, inside square brackets).  Arrays should be a reference to an array...

For example:

  my $table = adTie( 'XML', ["<x><motto id='perl'>TIMTOWTDI</motto></x>"] );

  This uses the XML format to parse the supplied string and returns a tied
  hash to the resulting table.


  my $table = adTie( 'ARRAY', [['id','motto'],['perl','TIMTOWTDI']] );

  This uses the column names "id" and "motto" and the supplied row values
  and returns a tied hash to the resulting table.

It is also possible to use an empty array to create a new empty tied hash in any format, for example:

  my $table = adTie('XML',[],'c');

  creates a new empty tied hash;

See adConvert() and adExport() for further examples of using strings and arrays.

=head2 Ties, Flocks, I/O, and Atomicity

AnyData provides flocking which works under the limitations of flock -- that it only works if other processes accessing the files are also using flock and only on platforms that support flock.  See the flock() man page for details.

Here is what the user supplied open modes actually do:

 r = read only  (LOCK_SH)  O_RDONLY
 u = update     (LOCK_EX)  O_RDWR
 c = create     (LOCK_EX)  O_CREAT | O_RDWR | O_EXCL
 o = overwrite  (LOCK_EX)  O_CREAT | O_RDWR | O_TRUNC

When you use something like "my $table = adTie(...)", it opens
the file with a lock and leaves the file and lock open until
1) the hash variable ($table) goes out of scope or 2) the
hash is undefined (e.g. "undef $table") or 3) the hash is
re-assigned to another tie.  In all cases the file is closed
and the lock released.

If adTie is called without creating a tied hash variable, the file
is closed and the lock released immediately after the call to adTie.

 For example:  print adTie('XML','foo.xml')->{main_office}->{phone}.

 That obtains a shared lock, opens the file, retrieves the one value
 requested, closes the file and releases the lock.