perl-Data-Locations/perl-Data-Locations.spec

#
# spec file for package perl-Data-Locations (Version 5.5)
#
# Copyright (c) 2010 SUSE LINUX Products GmbH, Nuernberg, Germany.
#
# All modifications and additions to the file contributed by third parties
# remain the property of their copyright owners, unless otherwise agreed
# upon. The license for this file, and modifications and additions to the
# file, is the same license as for the pristine package itself (unless the
# license for the pristine package is not an Open Source License, in which
# case the license is the MIT License). An "Open Source License" is a
# license that conforms to the Open Source Definition (Version 1.9)
# published by the Open Source Initiative.

# Please submit bugfixes or comments via http://bugs.opensuse.org/
#

Name:           perl-Data-Locations
Version:        5.5
Release:        1
License:        CHECK(GPL+ or Artistic)
%define cpan_name Data-Locations
Summary:        magic insertion points in your data
Url:            http://search.cpan.org/dist/Data-Locations/
Group:          Development/Libraries/Perl
Source:         http://www.cpan.org/authors/id/S/ST/STBEY/%{cpan_name}-%{version}.tar.gz
BuildRoot:      %{_tmppath}/%{name}-%{version}-build
BuildRequires:  perl
BuildRequires:  perl-macros
BuildRequires:  perl(ExtUtils::MakeMaker)
%{perl_requires}

%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(@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 "'$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 @items;'

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

* *

  '$location->printf($format, @items);'

  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, @items;'

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

* *

  '$location->println(@items);'

  This is (in principle) the same method as the "'print()'" method
  described further above, except that it always appends a "newline"
  character ("'\n'") 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 "'\n'" 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.)

* *

  '@list = $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.

* *

  '@list = <$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
  "'\n'" 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!\n";  ##  prints to "$location"

  See the section on "'select()'" in the perlfunc(1) manpage for more
  details.

%prep
%setup -q -n %{cpan_name}-%{version}

%build
%{__perl} Makefile.PL INSTALLDIRS=vendor OPTIMIZE="%{optflags}"
%{__make} %{?_smp_mflags}

%check
%{__make} test

%install
%perl_make_install
%perl_process_packlist
%perl_gen_filelist

%clean
%{__rm} -rf %{buildroot}

%files -f %{name}.files
%defattr(-,root,root,755)
%doc %attr(644,root,root) Artistic.txt CHANGES.txt CREDITS.txt GNU_GPL.txt INSTALL.txt README.txt

%changelog