view release on metacpan or  search on metacpan

Locations.pm  view on Meta::CPAN

programs as a very interesting and useful application, for instance).

=item *

C<$oldfilename = $location-E<gt>filename($newfilename);>

If the optional parameter is given, this method stores its argument as
the default filename along with the given location.

This filename also serves as an auto-dump flag. If it is set to a non-empty
string, auto-dumping (i.e., an automatic call of the "C<dump()>" method)
occurs when your last reference of the location in question goes out of
scope, or at shutdown time of your script (whichever comes first). See also
the description of the "C<dump()>" method further below for more details.

When a location is auto-dumped, its associated filename is used as the
filename of the file into which the location's contents are dumped.

This method returns the filename that was associated with the given
location before this method call (i.e., the filename given to the
"C<new()>" method or to a previous call of this method), or the
empty string if there was no filename associated with the given
location.

=item *

C<$flag = $location-E<gt>toplevel();>

Use this method to check wether the given location is a "top-level"
location, i.e., if the given location is NOT embedded in any other location.

Note that locations created by the CLASS METHOD "C<new()>" all start their
life-cycle as top-level locations, whereas locations which are embedded in
some other location by using the OBJECT METHOD "C<new()>" (or the method
"C<print()>"; see further below for details) are NOT, by definition,
top-level locations.

Whenever a top-level location is embedded in another location (using the
method "C<print()>" - see further below for more details), it automatically
loses its "top-level" status.

When you throw away the contents of a location (using the method
"C<delete()>" - see further below for details), however, the locations
that may have been embedded in the deleted location can become "orphans"
which have no "parents" anymore, i.e., they may not be embedded in any
other location anymore. These "orphan" locations will automatically
become "top-level" locations.

The method returns "true" ("C<1>") if the given location is a top-level
location, and "false" ("C<0>") otherwise.

=item *

C<$location-E<gt>print(@items);>

This method prints the given list of arguments to the indicated
location, i.e., appends the given items to the given location.

IMPORTANT FEATURE:

Note that you can EMBED any given location IN MORE THAN ONE surrounding
location using this method!

Simply use a statement similar to this one:

        $location->print($sublocation);

This embeds location "C<$sublocation>" in location "C<$location>" at
the current position (defined by what has been printed to location
"C<$location>" till this moment).

(Note that the name "C<$sublocation>" above only refers to the fact
that this location is going to be embedded in the location "C<$location>".
"C<$sublocation>" may actually be ANY location you like, even a top-level
location. Note though that a top-level location will automatically lose
its "top-level" status by doing so.)

This is especially useful if you are generating data once in your
program which you need to include at several places in your output.

This saves a lot of memory because only a reference of the embedded
location is stored in every embedding location, instead of all the
data, which is stored in memory only once.

Note that other references than "Data::Locations" object references are
illegal, trying to "print" such a reference to a location will result
in a warning message (if the "C<-w>" switch is set) and the reference
in question will simply be ignored.

Note also that potential infinite recursions (which would occur when a
given location contained itself, directly or indirectly) are detected
automatically and refused (with an appropriate error message and
program abortion).

Because of the necessity for this check, it is more efficient to embed
locations using the object method "C<new()>", where possible, rather
than with this mechanism, because embedding an empty new location
(as with "C<new()>") is always possible without checking.

Remember that in order to minimize the number of "C<print()>" method calls
in your program (remember that lazyness is a programmer's virtue! C<;-)>)
you can always use the "here-document" syntax:

  $location->print(<<"VERBATIM");
  Article: $article
    Price: $price
    Stock: $stock
  VERBATIM

Remember also that the type of quotes (single/double) around the
terminating string ("VERBATIM" in this example) determines wether
variables inside the given text will be interpolated or not!
(See L<perldata(1)> for more details.)

=item *

C<print $location @items;>

Note that you can also use Perl's built-in operator "C<print>" to
print data to a given location.

Locations.pm  view on Meta::CPAN

This will automatically cause the location to be dumped (by calling the
"C<dump()>" method internally) and then to be destroyed. (This feature
is called "auto-dump".)

Auto-dumping also occurs at shutdown time of your Perl script or program:
All locations that have a non-empty filename associated with them will
automatically be dumped (by calling the "C<dump()>" method internally)
before the global garbage collection (i.e., the destruction of all data
variables) takes place.

In order to prevent auto-dumping, just make sure that there is no filename
associated with the location in question at the time when its last reference
goes out of scope or at shutdown time.

You can ensure this by calling the "C<filename()>" method with an empty
string (C<"">) as argument.

=item *

C<$ok = $location-E<gt>dump($filename);>

The method "C<dump()>" (with a filename argument) in principle does exactly
the same as the variant without arguments described immediately above, except
that it temporarily overrides the default filename associated with the given
location and that it uses the given filename instead.

Note that the location's associated filename is just being temporarily
overridden, BUT NOT CHANGED.

I.e., if you call the method "C<dump()>" again later without a filename
argument, the filename stored along with the given location will be used,
and not the filename specified here.

Should any problem arise while attempting to dump the given location
(for instance if the given filename is invalid or empty or if Perl is
unable to open or close the specified file), a corresponding warning
message will be printed to the screen (provided that the "C<-w>" switch
is set) and the method returns "false" ("C<0>").

The method returns "true" ("C<1>") if and only if the given location
has been successfully written to the specified file.

(Note that if the given filename is empty or contains only white space,
the method does NOT fall back to the filename previously stored along
with the given location, because doing so could overwrite valuable data.)

Note also that a ">" is prepended to the given filename if it does not
begin with ">", "|" or "+" (leading white space is ignored).

Finally, note that this method does not affect the contents of the
location being dumped.

If you want to delete the given location once it has been dumped, you
need to call the method "C<delete()>" (explained below) explicitly.

=item *

C<$location-E<gt>delete();>

The method "C<delete()>" deletes the CONTENTS of the given location -
the location CONTINUES TO EXIST and REMAINS EMBEDDED where it was!

The associated filename stored along with the given location is also
NOT AFFECTED by this method.

BEWARE that any locations which were previously embedded in the given
location might go out of scope by invoking this method!

Note that in order to actually DESTROY a location altogether it suffices
to simply let the last reference to the location in question go out of
scope, or to set the variable containing the last reference to a new
value (e.g. C<$ref = 0;>).

=item *

C<$location-E<gt>tie('FILEHANDLE');>

=item *

C<$location-E<gt>tie(*FILEHANDLE);>

=item *

C<$location-E<gt>tie(\*FILEHANDLE);>

=item *

C<$location-E<gt>tie(*{FILEHANDLE});>

=item *

C<$location-E<gt>tie(\*{FILEHANDLE});>

Although locations behave like file handles themselves, i.e., even though
they allow you to use Perl's built-in operators "C<print>", "C<printf>"
and the diamond operator "C<E<lt>E<gt>>" in order to write data to and
read data from them, it is sometimes desirable to be able to redirect
the output which is sent to other file handles (such as STDOUT and
STDERR, for example) to some location instead (rather than the
screen, for instance).

It may also be useful to be able to read data from a location via some
other file handle (such as STDIN, for example, which allows you to
"remote-control" a program which reads commands from standard input
by redirecting STDIN and then spoon-feeding the program as desired).

(Note that on the Windows NT/95 platform, tying is probably the only
way of redirecting output sent to STDERR, since the command shell
won't allow you to do so!)

The method "C<tie()>" (be careful not to confuse the METHOD "C<tie()>" and
the Perl built-in OPERATOR "C<tie>"!) provides an easy way for doing this.

Simply invoke the method "C<tie()>" for the location which should be
"tied" to a file handle, and provide either the name, a typeglob or a
typeglob reference of the file handle in question as the (only)
parameter to this method.

After that, printing data to this file handle will actually send this
data to its associated ("tied") location, and reading from this file
handle will actually read the data from the tied location instead.