|
|
|
|
perl-Data-Locations rpm build for : openSUSE Leap 42. For other distributions click perl-Data-Locations.
Name : perl-Data-Locations
| | Version : 5.5
| Vendor : obs://build_opensuse_org/devel:languages:perl
| Release : 3.2
| Date : 2015-10-05 01:57:06
| Group : Development/Libraries/Perl
| Source RPM : perl-Data-Locations-5.5-3.2.src.rpm
| Size : 0.13 MB
| | Packager : (none)
| | Summary : Magic insertion points in your data
| Description :
* *
\'use Data::Locations;\'
Enables the use of locations in your program.
* *
\'$toplocation = Data::Locations->new();\'
The CLASS METHOD \"\'new()\'\" creates a new top-level location.
A \"top-level\" location is a location which isn\'t embedded (nested) in any other location.
Note that CLASS METHODS are invoked using the NAME of their respective class, i.e., \"\'Data::Locations\'\" in this case, in contrast to OBJECT METHODS which are invoked using an OBJECT REFERENCE such as returned by the class\'s object constructor method (which \"\'new()\'\" happens to be).
Any location that you intend to dump to a file later on in your program needs to have a filename associated with it, which you can either specify using the \"\'new()\'\" method (where you can optionally supply a filename, as shown below), or by setting this filename using the method \"\'filename()\'\" (see further below), or by specifying an explicit filename when invoking the \"\'dump()\'\" method itself (see also further below).
* *
\'$toplocation = Data::Locations->new($filename);\'
This variant of the CLASS METHOD \"\'new()\'\" creates a new top-level location (where \"top-level\" means a location which isn\'t embedded in any other location) and assigns a default filename to it.
Note that this filename is simply passed through to the Perl \"\'open()\'\" function later on (which is called internally when you dump your locations to a file), which means that any legal Perl filename may be used such as \">-\" (for writing to STDOUT) and \"| more\", to give you just two of the more exotic examples.
See the section on \"\'open()\'\" in the perlfunc(1) manpage for more details.
* *
\'$sublocation = $location->new();\'
The OBJECT METHOD \"\'new()\'\" creates a new location which is embedded in the given location \"\'$location\'\" at the current position (defined by what has been printed to the embedding location till this moment).
Such a nested location usually does not need a filename associated with it (because it will be dumped to the same file as the location in which it is embedded anyway), unless you want to additionally dump this location to a file of its own.
In the latter case use the variant of the \"\'new()\'\" method shown immediately below, or the method \"\'filename()\'\" (see below) to set this filename, or call the method \"\'dump()\'\" (described further below) with an appropriate filename argument.
* *
\'$sublocation = $location->new($filename);\'
This variant of the OBJECT METHOD \"\'new()\'\" creates a new location which is embedded in the given location \"\'$location\'\" at the current position (defined by what has been printed to the embedding location till this moment) and assigns a default filename to it.
See the section on \"\'open()\'\" in the perlfunc(1) manpage for details about the exact syntax of Perl filenames (this includes opening pipes to other programs as a very interesting and useful application, for instance).
* *
\'$oldfilename = $location->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 \"\'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 \"\'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 \"\'new()\'\" method or to a previous call of this method), or the empty string if there was no filename associated with the given location.
* *
\'$flag = $location->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 \"\'new()\'\" all start their life-cycle as top-level locations, whereas locations which are embedded in some other location by using the OBJECT METHOD \"\'new()\'\" (or the method \"\'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 \"\'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 \"\'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\" (\"\'1\'\") if the given location is a top-level location, and \"false\" (\"\'0\'\") otherwise.
* *
\'$location->print(AATTitems);\'
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 \"\'$sublocation\'\" in location \"\'$location\'\" at the current position (defined by what has been printed to location \"\'$location\'\" till this moment).
(Note that the name \"\'$sublocation\'\" above only refers to the fact that this location is going to be embedded in the location \"\'$location\'\". \"\'$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 \"\'-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 \"\'new()\'\", where possible, rather than with this mechanism, because embedding an empty new location (as with \"\'new()\'\") is always possible without checking.
Remember that in order to minimize the number of \"\'print()\'\" method calls in your program (remember that lazyness is a programmer\'s virtue! \';-)\') 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 the perldata(1) manpage for more details.)
* *
\'print $location AATTitems;\'
Note that you can also use Perl\'s built-in operator \"\'print\'\" to print data to a given location.
* *
\'$location->printf($format, AATTitems);\'
This method is an analogue of the Perl (and C library) function \"\'printf()\'\".
See the section on \"\'printf()\'\" in the perlfunc(1) manpage and the printf(3) manpage (or the sprintf(3) manpage) on your system for a description.
* *
\'printf $location $format, AATTitems;\'
Note that you can also use Perl\'s built-in operator \"\'printf\'\" to print data to a given location.
* *
\'$location->println(AATTitems);\'
This is (in principle) the same method as the \"\'print()\'\" method described further above, except that it always appends a \"newline\" character (\"\'\ \'\") to the list of items being printed to the given location.
Note that this newline character is NOT appended to (i.e., concatenated with) the last item of the given list of items, but that it is rather stored as an item of its own.
This is mainly because the last item of the given list could be a reference (of another location), and also to make sure that the data (which could be binary data) being stored in the given location is not altered (i.e., falsified) in any way.
This also allows the given list of items to be empty (in that case, there wouldn\'t be a \"last item\" anyway to which the newline character could be appended).
* *
\'$item = $location->read();\'
In \"scalar\" context, the method \"\'read()\'\" returns the next item of data from the given location.
If that item happens to have the value \"\'undef\'\", this method returns the empty string instead.
If you have never read from this particular location before, \"\'read()\'\" will automatically start reading at the beginning of the given location.
Otherwise each call of \"\'read()\'\" will return successive items from the given location, thereby traversing the given location recursively through all embedded locations (which it may or may not contain), thus returning the contents of the given location (and any locations embedded therein) in a \"flattened\" way.
To start reading at the beginning of the given location again, invoke the method \"\'reset()\'\" (see a little further below for its description) on that location.
The method returns \"\'undef\'\" when there is no more data to read.
Calling \"\'read()\'\" again thereafter will simply continue to return \"\'undef\'\", even if you print some more data to the given location in the meantime.
However, if you have read the last item from the given location, but you haven\'t got the \"\'undef\'\" return value yet, it is possible to print more data to the location in question and to subsequently continue to read this new data.
Remember to use \"\'reset()\'\" if you want to read data from the beginning of the given location again.
Finally, note that you can read from two (or any number of) different locations at the same time, even if any of them is embedded (directly or indirectly) in any other of the locations you are currently reading from, without any interference.
This is because the state information associated with each \"\'read()\'\" operation is stored along with the (given) location for which the \"\'read()\'\" method has been called, and NOT with the locations the \"\'read()\'\" visits during its recursive descent.
* *
\'$item = < $location>\'
Note that you can also use Perl\'s diamond operator syntax (\"\'< >\'\") in order to read data from the given location.
BEWARE that unlike reading from a file, reading from a location in this manner will return the items that have been stored in the given location in EXACTLY the same way as they have been written previously to that location, i.e., the data is NOT read back line by line, with \"\'\ \'\" as the line separator, but item by item, whatever these items are!
(Note that you can also store binary data in locations, which will likewise be read back in exactly the same way as it has been stored previously.)
* *
\'AATTlist = $location->read();\'
In \"array\" or \"list\" context, the method \"\'read()\'\" returns the rest of the contents of the given location, starting where the last \"\'read()\'\" left off, or from the beginning of the given location if you never read from this particular location before or if you called the method \"\'reset()\'\" (see a little further below for its description) for this location just before calling \"\'read()\'\".
The method returns a single (possibly very long!) list containing all the items of data the given location and all of its embedded locations (if any) contain - in other words, the data contained in all these nested locations is returned in a \"flattened\" way (in \"infix\" order, for the mathematically inclined).
If any of the items in the list happens to have the value \"\'undef\'\", it is replaced by an empty string.
The method returns an empty list if the given location is empty or if a previous \"\'read()\'\" read past the end of the data in the given location.
Remember to use \"\'reset()\'\" whenever you want to be sure to read the contents of the given location from the very beginning!
For an explanation of \"scalar\" versus \"array\" or \"list\" context, see the section on \"Context\" in the perldata(1) manpage.
* *
\'AATTlist = < $location>\'
Note that you can also use Perl\'s diamond operator syntax (\"\'< >\'\") in order to read data from the given location.
BEWARE that unlike reading from a file, reading from a location in this manner will return the list of items that have been stored in the given location in EXACTLY the same way as they have been written previously to that location, i.e., the data is NOT read back as a list of lines, with \"\'\ \'\" as the line separator, but as a list of items, whatever these items are!
(Note that you can also store binary data in locations, which will likewise be read back in exactly the same way as it has been stored previously.)
* *
\'$location->reset();\'
The method \"\'reset()\'\" deletes the state information associated with the given location which is used by the \"\'read()\'\" method in order to determine the next item of data to be returned.
After using \"\'reset()\'\" on a given location, any subsequent \"\'read()\'\" on the same location will start reading at the beginning of that location.
This method has no other (side) effects whatsoever.
The method does nothing if there is no state information associated with the given location, i.e., if the location has never been accessed before using the \"\'read()\'\" method or if \"\'reset()\'\" has already been called previously.
* *
\'$location->traverse(\\&callback_function);\'
The method \"\'traverse()\'\" performs a recursive descent on the given location just as the methods \"\'read()\'\" and \"\'dump()\'\" do internally, but instead of immediately returning the items of data contained in the location or printing them to a file, this method calls the callback function you specify as a parameter once for each item stored in the location.
Expect one parameter handed over to your callback function which consists of the next item of data contained in the given location (or the locations embedded therein).
Note that unlike the \"\'read()\'\" method, items returned by this method which happen to have the value \"\'undef\'\" are NOT replaced by the empty string, i.e., the parameter your callback function receives might be undefined. You should therefore take appropriate measures in your callback function to handle this special case.
Moreover, since callback functions can do a lot of unwanted things, use this method with precaution!
Please refer to the \"examples\" section at the bottom of this document for an example of how to use this method.
Using the method \"\'traverse()\'\" is actually an alternate way of reading back the contents of a given location (besides using the method \"\'read()\'\") completely in memory (i.e., without writing the contents of the given location to a file and reading that file back in).
Note that the method \"\'traverse()\'\" is completely independent from the method \"\'read()\'\" and from the state information associated with the \"\'read()\'\" method (the one which can be reset to point to the beginning of the location using the method \"\'reset()\'\").
This means that you can \"\'traverse()\'\" and \"\'read()\'\" (and \"\'reset()\'\") the same location at the same time without any interference.
* *
\'$ok = $location->dump();\'
The method \"\'dump()\'\" (without parameters) dumps the contents of the given location to its associated default file (whose filename must have been stored along with the given location previously using the method \"\'new()\'\" or \"\'filename()\'\").
Note that a warning message will be printed (if the \"\'-w\'\" switch is set) if the location happens to lack a default filename and that the location will simply not be dumped to a file in that case. Moreover, the method returns \"false\" (\"\'0\'\") to indicate the failure.
Should any other problem arise while attempting to dump the given location (for instance an invalid filename or an error while trying to open or close the specified file), a corresponding warning message will be printed to the screen (provided that the \"\'-w\'\" switch is set) and the method will also return \"false\" (\"\'0\'\").
The method returns \"true\" (\"\'1\'\") if and only if the given location has been successfully written to its respective file.
Note that a \">\" is prepended to the default filename just before opening the file if the default filename does not begin with \">\", \"|\" or \"+\" (leading white space is ignored).
This does NOT change the filename which is stored along with the given location, however.
Finally, note that this method does not affect the contents of the location being dumped.
If you want to delete the contents of the given location once they have been dumped, call the method \"\'delete()\'\" (explained further below) thereafter.
If you want to dump and immediately afterwards destroy a location, you don\'t need to call the method \"\'dump()\'\" explicitly. It suffices to store a filename along with the location in question using the method \"\'new()\'\" or \"\'filename()\'\" and then to make sure that all references to this location are destroyed (this happens for instance whenever the last \"my\" variable containing a reference to the location in question goes out of scope - provided there are no global variables containing references to the location in question).
This will automatically cause the location to be dumped (by calling the \"\'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 \"\'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 \"\'filename()\'\" method with an empty string (\'\"\"\') as argument.
* *
\'$ok = $location->dump($filename);\'
The method \"\'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 \"\'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 \"\'-w\'\" switch is set) and the method returns \"false\" (\"\'0\'\").
The method returns \"true\" (\"\'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 \"\'delete()\'\" (explained below) explicitly.
* *
\'$location->delete();\'
The method \"\'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. \'$ref = 0;\').
* *
\'$location->tie(\'FILEHANDLE\');\'
* *
\'$location->tie(*FILEHANDLE);\'
* *
\'$location->tie(\\*FILEHANDLE);\'
* *
\'$location->tie(*{FILEHANDLE});\'
* *
\'$location->tie(\\*{FILEHANDLE});\'
Although locations behave like file handles themselves, i.e., even though they allow you to use Perl\'s built-in operators \"\'print\'\", \"\'printf\'\" and the diamond operator \"\'< >\'\" 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 \"\'tie()\'\" (be careful not to confuse the METHOD \"\'tie()\'\" and the Perl built-in OPERATOR \"\'tie\'\"!) provides an easy way for doing this.
Simply invoke the method \"\'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.
Note that you don\'t need to explicitly \"\'open()\'\" or \"\'close()\'\" such a tied file handle in order to be able to access its associated location (regardless wether you want to read from or write to the location or both), even if this file handle has never been explicitly (or implicitly) opened (or even used) before.
The physical file or terminal the tied file handle may have been connected to previously is simply put on hold, i.e., it is NOT written to or read from anymore, until you \"\'untie\'\" the connection between the file handle and the location (see further below for more details about \"\'untie\'\").
Note also that if you do not \"\'untie\'\" the file handle before your program ends, Perl will try to close it for you, which under Perl 5.005 will lead to a warning message (provided that the \"\'-w\'\" switch is set) saying that the attempted \"\'close()\'\" operation was ignored. This is because under Perl 5.005, a \"\'close()\'\" on a tied file handle is forwarded to the associated (i.e., tied) object instead.
Under Perl 5.004, the behaviour of \"\'close()\'\" is different: When used on a location it is simply ignored (without any warning message), and a close on a tied file handle will close the underlying file or pipe (if there is one).
Finally, note that you don\'t need to qualify the built-in file handles STDIN, STDOUT and STDERR, which are enforced by Perl to be in package \"main\", and file handles belonging to your own package, but that it causes no harm if you do (provided that you supply the correct package name).
The only file handles you need to qualify are custom file handles belonging to packages other than the one in which the method \"\'tie()\'\" is called.
Some examples:
$location->tie(\'STDOUT\'); $location->tie(\'MYFILE\'); $location->tie(\'My::Class::FILE\'); $location->tie(*STDERR); $location->tie(\\*main::TEMP);
Please also refer to the example given at the bottom of this document for more details about tying file handles to locations (especially for STDERR).
See the perlfunc(1) manpage and the perltie(1) manpage for more details about \"tying\" in general.
* *
\'$location->tie($filehandle);\'
Note that you can also tie file handles to locations which have been created by using the standard Perl modules \"\'FileHandle\'\" and \"\'IO::File\'\":
use FileHandle; $fh = FileHandle->new(); $location->tie($fh);
use IO::File; $fh = IO::File->new(); $location->tie($fh);
* *
\'tie(*FILEHANDLE, \"Data::Locations\", $location);\'
* *
\'tie(*{$filehandle}, \"Data::Locations\", $location);\'
Finally, note that you are not forced to use the METHOD \"\'tie()\'\", and that you can of course also use the OPERATOR \"\'tie\'\" directly, as shown in the two examples above.
* *
\'$location = tied *FILEHANDLE;\'
* *
\'$location = tied *{$filehandle};\'
The Perl operator \"\'tied\'\" can be used to get back a reference to the object the given file handle is \"tied\" to.
This can be used to invoke methods for this object, as follows:
(tied *FILEHANDLE)->method(); (tied *{$filehandle})->method();
Note that \"\'tied *{$location}\'\" is identical with \"\'$location\'\" itself.
See the perlfunc(1) manpage and the perltie(1) manpage for more details.
* *
\'untie *FILEHANDLE;\'
* *
\'untie *{$filehandle};\'
The Perl operator \"\'untie\'\" is used to \"cut\" the magic connection between a file handle and its associated object.
Note that a warning message such as
untie attempted while 1 inner references still exist
will be issued (provided the \"\'-w\'\" switch is set) whenever you try to \"\'untie\'\" a file handle from a location.
To get rid of this warning message, use the following approach:
{ local($^W) = 0; ## Temporarily disable the \"-w\" switch untie *FILEHANDLE; }
(Note the surrounding braces which limit the effect of disabling the \"\'-w\'\" switch.)
See the perlfunc(1) manpage and the perltie(1) manpage for more details.
* *
\'$filehandle = select();\'
* *
\'select($location);\'
* *
\'$oldfilehandle = select($newlocation);\'
Remember that you can define the default output file handle using Perl\'s built-in function \"\'select()\'\".
\"\'print\'\" and \"\'printf\'\" statements without explicit file handle (note that \"\'println\'\" ALWAYS needs an explicit location where to send its output to!) always send their output to the currently selected default file handle (which is usually \"STDOUT\").
\"\'select()\'\" always returns the current default file handle and allows you to define a new default file handle at the same time.
By selecting a location as the default file handle, all subsequent \"\'print\'\" and \"\'printf\'\" statements (without explicit file handle) will send their output to that location:
select($location); print \"Hello, World!\ \"; ## prints to \"$location\"
See the section on \"\'select()\'\" in the perlfunc(1) manpage for more details.
| RPM found in directory: /packages/linux-pbone/ftp5.gwdg.de/pub/opensuse/repositories/devel:/languages:/perl/openSUSE_Leap_42.1/x86_64 |
Content of RPM
Changelog
Provides
Requires
Hmm ... It's impossible ;-) This RPM doesn't exist on any FTP server
Provides : Locations.so()(64bit) perl(Data::Locations) perl-Data-Locations perl-Data-Locations(x86-64)
Requires :
Content of RPM : /usr/lib/perl5/vendor_perl/5.18.2/x86_64-linux-thread-multi
/usr/lib/perl5/vendor_perl/5.18.2/x86_64-linux-thread-multi/Data
/usr/lib/perl5/vendor_perl/5.18.2/x86_64-linux-thread-multi/Data/Locations.pm
/usr/lib/perl5/vendor_perl/5.18.2/x86_64-linux-thread-multi/auto/Data
/usr/lib/perl5/vendor_perl/5.18.2/x86_64-linux-thread-multi/auto/Data/Locations
/usr/lib/perl5/vendor_perl/5.18.2/x86_64-linux-thread-multi/auto/Data/Locations/Locations.bs
/usr/lib/perl5/vendor_perl/5.18.2/x86_64-linux-thread-multi/auto/Data/Locations/Locations.so
/usr/share/doc/packages/perl-Data-Locations
/usr/share/doc/packages/perl-Data-Locations/Artistic.txt
/usr/share/doc/packages/perl-Data-Locations/CHANGES.txt
/usr/share/doc/packages/perl-Data-Locations/CREDITS.txt
/usr/share/doc/packages/perl-Data-Locations/GNU_GPL.txt
/usr/share/doc/packages/perl-Data-Locations/INSTALL.txt
/usr/share/doc/packages/perl-Data-Locations/README.txt
/usr/share/man/man3/Data::Locations.3pm.gz
|
|
|