|
BnP - implements the automatic recovery mechanism of "Build'n'Play" |
BnP - implements the automatic recovery mechanism of ``Build'n'Play''
This module provides an automatic recovery mechanism for installation scripts (for installing any kind of Unix software package) written in Perl.
A special log file (called the ``automatic recovery file'') is used by this module in which all the commands (i.e., method calls of command methods provided by this module) are recorded which have been executed successfully.
When you restart your installation script later, the commands found in this automatic recovery file will not be executed again.
The module provides a comprehensive set of command methods for fetching
source distribution files automatically, for manipulating (e.g., unpacking
and building) them in every possible way (using ``system()'' calls), for
making and changing directories, for patching files (in a manner resembling
the Unix tool ``sed''), for defining subsections in your installation scripts
and for commenting out certain parts, plus some functions of general utility.
use BnP;
info
info "MESSAGE", ...; # print
alert
alert "MESSAGE", ...; # warn
fatal
fatal "MESSAGE", ...; # die
find
$path = find("FILENAME", "SEARCHPATH");
indispensable
indispensable("FILENAME", ...);
normalize
$file = normalize("FILENAME");
follow
$file = follow("FILENAME");
absolute
$file = absolute("FILENAME");
expand
$file = expand("FILENAME");
new
$BnP = BnP->new($target,$subset,$prefix,$homedir,$workspace);
target
$target = $BnP->target();
subset
$subset = $BnP->subset();
prefix
$prefix = $BnP->prefix();
homedir
$homedir = $BnP->homedir();
workspace
$workspace = $BnP->workspace();
path
[ @path = ] $BnP->path( @path );
@path = $BnP->path();
stub
[ @stub = ] $BnP->stub( @stub );
@stub = $BnP->stub();
url
[ @url = ] $BnP->url( @url );
@url = $BnP->url();
begin
$BnP->begin();
end
$BnP->end();
begin_section
$BnP->begin_section("NAME", ...);
end_section
$BnP->end_section("NAME", ...);
begin_must_section
$BnP->begin_must_section();
end_must_section
$BnP->end_must_section();
begin_lazy_section
$BnP->begin_lazy_section("NAME", ...);
end_lazy_section
$BnP->end_lazy_section("NAME", ...);
ignore
$BnP->ignore();
resume
$BnP->resume();
active
$flag = $BnP->active();
reset
$BnP->reset();
back
$BnP->back();
$BnP->back(COUNT);
chdir
$BnP->chdir("DIR");
mkdir
$BnP->mkdir("DIR");
fetch
$BnP->fetch("FILENAME", "RELPATH", "SOURCEDIR");
system
$BnP->system("COMMAND", ...);
patch
$BnP->patch("FILENAME", "PERLEXPR", ...);
info "MESSAGE", ...; # print
This function can be used to print informational messages to STDOUT (or to whatever file handle your program has currently ``select''ed).
All parameters of this function are concatenated without any intervening characters (i.e., without adding any spaces).
A prefix of ``BnP: '' and a trailing ``\n'' is added automatically.
Moreover, the output is written unbuffered, i.e., even if it is not sent to a terminal, the output should appear immediately in the corresponding file or pipe.
alert "MESSAGE", ...; # warn
This function can be used to print warning messages to STDERR (using ``warn'', internally).
All parameters of this function are concatenated without any intervening characters (i.e., without adding any spaces).
A prefix of ``BnP: ! '' and a trailing ``\n'' is added automatically.
fatal "MESSAGE", ...; # die
This function can be used to print an error message to STDERR, with immediately ensuing program abortion (using ``die'', internally).
All parameters of this function are concatenated without any intervening characters (i.e., without adding any spaces).
A prefix of ``BnP: ! '' and a trailing ``\n'' is added automatically.
$path = find("FILENAME", "SEARCHPATH");
This function can be used to find any readable (operator ``-r'') and
non-empty (operator ``-s'') file in a given searchpath (i.e., a list
of directories concatenated with ``:'') whose filename is given.
The function returns the absolute path of the requested file if the file was found in the given searchpath, or an empty string otherwise.
For example:
$shell = find('sh', $ENV{'PATH'});
This should return ``/bin/sh''.
indispensable("FILENAME", ...);
This function checks wether all the files whose filenames are given can
be found in the current ``$PATH'' environment variable (``$ENV{'PATH'}'')
using the function ``find()'' (see above) internally.
An error message is printed and program execution is aborted if any of the files in the list cannot be found.
The function returns silently if all the files have been found.
$file = normalize("FILENAME");
This function ``normalizes'' a given filename, i.e., it reduces consecutive
slashes (``/'') and consecutive terms of the form ``/./'' to a single slash,
and removes a dot-slash (``./'') at the beginning and a slash-dot (``/.'')
or slash (``/'') at the end.
Moreover, terms of the form ``/dir/../'' (where ``dir'' is not an empty
string, contains no slashes and is not equal to ``..'') are iteratively
reduced to a single slash each, until no more terms of this kind can be found.
$file = follow("FILENAME");
If the given filename (given as an absolute path or as a path relative to the current working directory) is a symbolic link, this function follows this symbolic link iteratively, as long as the resulting filename is also a symbolic link, until the end of the chain of symbolic links is reached.
This last filename is then returned.
If the given filename is not a symbolic link, it is simply ``normalized''
using the function ``normalize()'' (see above) and then returned.
$file = absolute("FILENAME");
If the given filename is an absolute path, it is returned unchanged.
Otherwise the output of ``/bin/pwd'' is prepended to it and the new
filename is returned.
$file = expand("FILENAME");
While the function ``follow()'' (see above) only expands the ``basename'' part
of a given filename if it is a symbolic link (whereas the ``dirname'' part
remains unchanged), this function expands ALL symbolic links encountered in
a given filename, yielding the true physical (absolute) path of the file or
directory in question.
If the given filename is relative, it is first converted into an absolute
path using the function ``absolute()'' (see above).
If a file or directory of the given name does not exist, all symbolic links are expanded as far as possible (as far as the leading (left) part of the given filename matches existing directories and symbolic links).
$BnP = BnP->new($target,$subset,$prefix,$homedir,$workspace);
This is the ``Build'n'Play'' installation project constructor method.
In theory you can perform several installations simultaneously; each installation thereby has a variable space of its own, which is stored in the object returned by this method.
$target'' specifies a name for the installation project.
This name has only informational character in this module, though.
$subset'' specifies a list of subtargets (as a single
string, in which the different elements are concatenated with ``.'')
which enable the corresponding sections in your installation script
as defined by the ``begin_section()'', ``end_section()'',
``begin_lazy_section()'' and ``end_lazy_section()'' method calls
in your script (see further below for a description of these methods).
$prefix'' specifies the installation prefix,
e.g. ``/usr/local'', ``/opt/pkg/<target>'' etc.
If this parameter is empty or contains only whitespace, the prefix
is set to ``/usr/local'' by default.
$homedir'' specifies the home directory of the
installation project, i.e., the directory where the automatic
recovery file (``recover.bnp'') for this project will be stored.
A subdirectory named ``src'' in this directory is usually the place where all the necessary source distribution files are stored, but this is something controlled entirely by your installation script.
Note that simultaneous installations must have different home
directories, otherwise they will overwrite each other's automatic
recovery file (``recover.bnp'') in that directory.
$workspace'' specifies a directory where the
source distribution files can be temporarily unpacked and compiled.
This is also the directory the method ``reset()'' (see further below)
performs a ``chdir()'' to.
$target = $BnP->target();
This method returns the name of the current installation project as
defined in the call of the installation project constructor method
``new()'' (see above for details).
$subset = $BnP->subset();
This method returns the string containing the names of the sections in
your installation script to be processed, as defined in the call of the
installation project constructor method ``new()'' (see above for details).
$prefix = $BnP->prefix();
This method returns the prefix of the current installation project
as defined in the call of the installation project constructor method
``new()'' (see above for details).
$homedir = $BnP->homedir();
This method returns the home directory of the current installation project
as defined in the call of the installation project constructor method
``new()'' (see above for details).
$workspace = $BnP->workspace();
This method returns the directory used as a temporary workspace by the
current installation project (several simultaneous installations may use
the same workspace directory, unless they try to unpack distributions
which result in a distribution directory of exactly the same name), as
defined in the call of the installation project constructor method
``new()'' (see above for details).
Note also that provisions need to be made (i.e., an appropriate subdirectory has to be created first) if you unpack any misbehaving distributions which do not create a distribution directory first themselves but simply spill their contents into the current working directory.
[ @path = ] $BnP->path( @path );
@path = $BnP->path();
This method allows you to define a number of base directories where to
search for source distribution files (see also the description of the
method ``fetch()'' further below) in your local file system (e.g.,
on your hard disk, on a CD-ROM, etc.).
Several directory names may be concatenated with ``:'' to form a single
argument, or they can be passed as separate arguments. You can also
mix these two forms.
Note that any previous setting is REPLACED by the given arguments, i.e., this method is NOT accumulative.
The method returns a list with all the directory names that have been passed to it (previously, or in the current call).
If you call this method without parameters, the current setting is returned but not changed.
Example:
$BnP->path( '/mirrors:/cdrom', `pwd` );
Trailing slashes (``/'') will be removed automatically.
Note that these directories must be given by their absolute path, because the current directory will usually change frequently over the course of your installation.
Note also that these directories will always be searched in the given order (from left to right).
Finally, note that this setting is cleared by the ``begin()'' and ``end()''
methods (see further below).
(This setting is initialized to an empty list by the constructor method
``new()''.)
[ @stub = ] $BnP->stub( @stub );
@stub = $BnP->stub();
This method allows you to define a number of subdirectories where to
search for source distribution files (see also the description of the
method ``fetch()'' further below) in your local file system (e.g.,
on your hard disk, on a CD-ROM, etc.).
Several subdirectory names may be concatenated with blanks (`` '') to form a single argument, or they can be passed as separate arguments. You can also mix these two forms.
Note that any previous setting is REPLACED by the given arguments, i.e., this method is NOT accumulative.
The method returns a list with all the subdirectory names that have been passed to it (previously, or in the current call).
If you call this method without parameters, the current setting is returned but not changed.
Example:
$BnP->stub( 'CPAN', 'BnP/src', 'BnP', 'src' );
Note that these subdirectories must be given as relative paths (any
leading or trailing slash (``/'') will be stripped anyway, however).
Note also that these subdirectories will always be searched in the given
order (from left to right) and that (moreover) the subdirectory ``.''
is always implicitly assumed to be at the beginning of this list.
(As a consequence, if you don't need this feature of search subdirectories,
you don't need to bother with this method at all, just leave this setting
empty as it is initialized by the constructor method ``new()''.)
When searching for a source distribution file, each of these subdirectories
will in turn be appended to every base directory as defined by the ``path()''
method (see above) to form the list of actual directories to be searched
(i.e., the search path is the set product of the directories defined with
the ``path()'' method and the subdirectories defined with the ``stub()''
method).
Finally, note that this setting is cleared by the ``begin()'' and ``end()''
methods (see further below).
[ @url = ] $BnP->url( @url );
@url = $BnP->url();
This method allows you to define a number of URLs where to download source
distribution files from which haven't been found in your local file system
(see also the description of the method ``fetch()'' further below).
Several URLs may be concatenated using blanks (`` '') to form a single argument, or they can be passed as separate arguments. You can also mix these two forms.
Note that any previous setting is REPLACED by the given arguments, i.e., this method is NOT accumulative.
The method returns a list with all the URLs that have been passed to it (previously, or in the current call).
If you call this method without parameters, the current setting is returned but not changed.
Example:
$BnP->url
(
'ftp://ftp.engelschall.com/pub/bnp ftp://ftp.netsw.org/netsw'
);
Note that these URLs should usually terminate in the name of a directory but should nevertheless NOT have a trailing slash!
Note also that these URLs will always be searched in the given order (from left to right).
Finally, note that this setting is cleared by the ``begin()'' and ``end()''
methods (see below).
$BnP->begin();
This method call starts the actual installation.
A (possibly) still open automatic recovery file is closed, and all internal
attributes of the current installation project (except the ones which contain
the parameters passed to the installation project constructor method
``new()'') are reset to their default values (this is so that you can
use the same installation project object several times in sequence).
The method then checks wether an automatic recovery file ``recover.bnp''
already exists for the current installation project, and if so, reads it in.
(The contents of the automatic recovery file are then stored in memory in the given installation project object for fastest possible access.)
Moreover, if it exists, this automatic recovery file is renamed (its
suffix ``.bnp'' is thereby replaced by a 3-digit number which is the
smallest such number which hasn't been assigned yet, by starting at
``000'' and incrementing as necessary), and a new recovery file is
created and opened for writing.
A header line showing the name and version number of this module as well
as a confirmation for some of your calling parameters is printed to the
screen, and a ``chdir()'' is made via the method ``reset()'' (see also
further below) to the directory ``$workspace'', as defined in the call
of the installation project constructor method ``new()'' (see above
for details).
$BnP->end();
This method call terminates the actual installation.
First the automatic recovery file is closed (nothing is done if the file has already been closed before, for instance by a previous call of this method).
Then all internal attributes of the current installation project (except
the ones which contain the parameters passed to the installation project
constructor method ``new()'') are reset to their default values (this
is so that you can use the same installation project object several
times in sequence).
Finally, a message confirming the successful installation is printed to the screen.
$BnP->begin_section("NAME", ...);
This method call marks the beginning of a named section in your installation script.
You can pass several names (or ``labels'') to this method, which will be treated as synonyms for the section in question.
I.e., specifying ANY of these labels from this method call in the
parameter ``$subset'' at runtime (via the ``new()'' constructor
method - see above) will enable the commands in the corresponding
section.
If none of the subtargets specified in the parameter ``$subset''
matches any of the labels in this method call, then the commands
in the corresponding section will be disabled - unless the parameter
``$subset'' is empty, in which case the ``begin_section()'' and
``end_section()'' (see below) method calls are simply ignored
altogether.
(An empty parameter ``$subset'' means ``install ALL sections'',
therefore the ``begin_section()'' and ``end_section()'' method
calls need not to be evaluated in such a case.)
This way you can also define the section in question as being part of a set of sections forming a larger whole, or mark parts which are prerequisites of other sections, as in the following example:
$BnP->begin_section("net","mail","news");
# install net software (prerequisite for mail and news)
$BnP->end_section("net","mail","news");
...
$BnP->begin_section("mail");
# install mail software
$BnP->end_section("mail");
...
$BnP->begin_section("news");
# install news software
$BnP->end_section("news");
If the runtime parameter ``$subset'' contains ``net'', only the ``net'' portion
will be installed. If it contains ``mail'', the ``net'' portion as well as the
``mail'' part itself will be installed. If it contains ``mail'' AND ``news'',
all three parts will be installed, and so on.
$BnP->end_section("NAME", ...);
This method call marks the end of one or several named sections in your installation script.
If any of the labels listed in this method call matches any of the
subtargets given in the runtime parameter ``$subset'' - provided
that the latter is not empty - then the execution of all commands
following this method call is disabled.
If there is no match, the commands following this method call will continue to be executed.
If the runtime parameter ``$subset'' is empty, this method call is
ignored altogether.
This allows you to terminate different sections at different times, as in the following example:
$BnP->begin_section("net","mail");
# install net software (prerequisite for mail)
$BnP->end_section("net");
# install mail software
$BnP->end_section("mail");
If the runtime parameter ``$subset'' contains ``net'', only the ``net''
portion will be installed. If it contains ``mail'', the ``net'' portion
as well as the ``mail'' part itself will be installed.
$BnP->begin_must_section();
This method call marks the beginning of a section in your installation script which is executed under all circumstances.
This method takes no arguments; all arguments passed to it are ignored.
This method call takes precedence over all other method calls defining the beginning or end of any overlapping section, but it doesn't impede their (invisible) working, as in the following example:
$BnP->begin_section("a");
# commands 1
$BnP->begin_must_section();
# commands 2
$BnP->end_section("a");
# commands 3
$BnP->begin_section("b");
# commands 4
$BnP->end_must_section();
# commands 5
$BnP->end_section("b");
In this example, the commands ``2'', ``3'' and ``4'' are ALWAYS executed,
regardless of the contents of the runtime parameter ``$subset''.
The commands ``1'' will be executed only if the runtime parameter ``$subset''
is empty or if it contains ``a''. The commands ``5'' will be executed only
if the runtime parameter ``$subset'' is empty or if it contains ``b''.
$BnP->end_must_section();
This method call marks the end of a section in your installation script which is executed under all circumstances.
This method takes no arguments; all arguments passed to it are ignored.
$BnP->begin_lazy_section("NAME", ...);
This method call marks the beginning of a section in your installation
script which will be executed ONLY if you specify at least ONE of the
labels listed in this method call EXPLICITLY as part of the runtime
parameter ``$subset'', i.e., this is some kind of a ``lazy'' or ``delayed''
evaluation section.
This method call takes precedence over any overlapping sections defined
via the ``begin_section()'' and ``end_section()'' pair of methods,
as shown in the following example:
$BnP->begin_section("a");
# commands 1
$BnP->begin_lazy_section("x");
# commands 2
$BnP->end_section("a");
# commands 3
$BnP->begin_section("b");
# commands 4
$BnP->end_lazy_section("x");
# commands 5
$BnP->end_section("b");
In this example, the commands ``2'', ``3'' and ``4'' are executed if and only
if the runtime parameter ``$subset'' contains ``x''.
The commands ``1'' will be executed only if the runtime parameter ``$subset''
is empty or if it contains ``a''. The commands ``5'' will be executed only
if the runtime parameter ``$subset'' is empty or if it contains ``b''.
Overlapping ``lazy'' sections behave sligthly differently, as illustrated in the following example:
$BnP->begin_lazy_section("a","c");
# commands 1
$BnP->begin_lazy_section("b");
# commands 2
$BnP->end_lazy_section("a");
# commands 3
$BnP->end_lazy_section("b","c");
In this example, the commands ``1'' and ``2'' are executed if the runtime
parameter ``$subset'' contains ``a'' (or ``c'').
The commands ``2'' and ``3'' are executed if the runtime parameter ``$subset''
contains ``b'' (or ``c'').
None of these commands is executed if the runtime parameter ``$subset''
contains neither ``a'' nor ``b'' (nor ``c''), and all of these commands are
executed if ``$subset'' contains ``a'' as well as ``b'' (or just ``c'').
$BnP->end_lazy_section("NAME", ...);
This method call marks the end of one or several named ``lazy'' sections in your installation script.
$BnP->ignore();
This method call can be used to ``comment out'' all subsequent commands
until the next occurrence of a ``resume()'' method call (see also below).
This method call takes precedence over all others, even ``must'' sections and ``lazy'' sections (see also their corresponding descriptions above).
This method call does not impede the ``section'' method calls from working, however, it just prevents any actions to be actually performed, as shown in the following example:
$BnP->begin_section("a");
# commands 1
$BnP->ignore();
# commands 2
$BnP->end_section("a");
# commands 3
$BnP->begin_section("b");
# commands 4
$BnP->resume();
# commands 5
$BnP->end_section("b");
In this example, the commands ``2'', ``3'' and ``4'' are NEVER executed,
regardless of the contents of the runtime parameter ``$subset''.
The commands ``1'' will be executed only if the runtime parameter ``$subset''
is empty or if it contains ``a''. The commands ``5'' will be executed only
if the runtime parameter ``$subset'' is empty or if it contains ``b''.
$BnP->resume();
This method call ends a section of your installation script which has been ``commented out''.
Normal operation of your installation script resumes after this method call.
Note that you cannot nest ``ignore()'' and ``resume()'' method calls; the
first ``ignore()'' method encountered will disable all following commands,
and the first ``resume()'' method encountered will enable execution again:
$BnP->ignore();
# commands 1
$BnP->ignore();
# commands 2
$BnP->resume();
# commands 3
$BnP->resume();
# commands 4
In this example, the commands ``1'' and ``2'' will never be executed, and execution resumes at commands ``3'', not ``4'' (which means that both commands ``3'' and ``4'' are executed, in this example).
$flag = $BnP->active();
This method returns ``true'' if it is called from within a section which
is currently being executed (for instance, this method ALWAYS returns
``true'' when called from within a ``must'' section), or ``false''
otherwise.
In particular, this method also reports ``false'' if called from within
a part in your installation script that has been ``commented out'' with the
``ignore()'' and ``resume()'' pair of methods.
$BnP->reset();
This method does nothing but a ``chdir()'' (see below) to the directory
``$workspace'', as defined in the call of the installation project
constructor method ``new()'' (see above for details).
$BnP->back();
This method is just a shorthand for ``$BnP->chdir('../');''.
$BnP->back(COUNT);
This method is just a shorthand for ``$BnP->chdir('../' x COUNT);'',
where ``COUNT'' is replaced by ``1'' if it is less than one.
$BnP->chdir("DIR");
This method can be used to change the current working directory for all subsequent commands which implicitly act upon it (all Unix and Perl commands dealing with files and directories normally do, if no absolute paths are given).
The parameter ``DIR'' may be an absolute or a relative path. In the
latter case this path will be relative to the current working directory
as defined previously.
At the beginning of the installation, the method ``begin()'' sets the
current working directory to ``$workspace'', as defined in the call
of the installation project constructor method ``new()'' (see above
for details), using the method ``reset()'' (see above).
$BnP->mkdir("DIR");
This method can be used to create a new directory.
If the directory's path ``DIR'' is not absolute, it will be relative
to the current working directory, as defined previously using the methods
``reset()'', ``chdir()'' and ``back()'' (see above for details).
In contrast to the Unix or Perl ``mkdir'' commands, this method will also
automatically and recursively create any missing intervening directories;
i.e., if the directory ``/tmp'' does not contain any subdirectories, then the
method call ``$BnP->mkdir('/tmp/bnp/hmtl/mod');'' will first create the
directory ``/tmp/bnp'', then the directory ``/tmp/bnp/html'', and finally
the directory ``/tmp/bnp/html/mod''.
The method does nothing (and does NOT produce any error message) if the directory to be created already exists.
$BnP->fetch("FILENAME", "RELPATH", "SOURCEDIR");
This method fetches a distribution file from a predefined search path or (if necessary) a list of URLs and puts it into the specified source directory.
The method does nothing if the distribution file is already found in the given source directory.
Otherwise it searches the directories which have been specified previously
by the ``path()'' and ``stub()'' methods (see further above), in their
given order.
The method thereby cycles through all the directories specified by ``path()''.
It first tests any such directory wether it contains the requested distribution
file. If not, the method cycles through all the subdirectories as specified by
``stub()'' and tests each of these subdirectories in the currently examined
directory. If the test fails for a subdirectory, the method also tests the
subsubdirectory ``RELPATH'' in that subdirectory.
If the requested distribution file is found in any of these directories or (sub-) subdirectories, the method first attempts to create a symbolic link in the given source directory which points to the location where the distribution file has been found.
Should this fail for some reason (e.g. if your system does not support symbolic links), the method alternatively tries to copy the distribution file to the specified source directory.
If this also fails (for instance in case of disk capacity overrun), the method gives up and throws a (fatal) exception.
If the requested distribution file is not found in any of these directories, the method tries to find a tool for the automatic download.
If none of the configured tools (currently ``snarf'' and ``lynx'') can be found on your system, a fatal exception follows.
Otherwise the method searches the URLs which have been specified previously
by the ``url()'' method (see further above), in the given order.
The method thereby cycles through all the URLs specified by ``url()'', to
each of which the relative path ``RELPATH'' and the filename ``FILENAME'' is
appended (for this reason the given URLs should not end in as slash ``/''!).
If the requested distribution file cannot be downloaded successfully from any of these URLs, a corresponding error message is printed to the screen and program execution is aborted.
Note that this may be due to a server being down temporarily, so sometimes you may just need to restart your installation script in order to succeed, or specify a different server.
If the distribution file is found on one of the specified servers, it is downloaded into the given source directory ``SOURCEDIR'' and the method returns to the caller.
$BnP->system("COMMAND", ...);
This method allows you to use any (shell) commands you may need while still benefiting from the automatic recovery mechanism provided by this module.
All the arguments to this method are concatenated using spaces, i.e., you
don't need to include spaces at the beginning and the end of these arguments,
and you don't need to concatenate them with the ``.''-operator yourself
(you will have to supply those spaces yourself if you do, however).
Since all the arguments are concatenated, they form a single command line.
In order to include several different commands on that same command line,
use the semicolon (``;'') to separate them, as usually.
$BnP->patch("FILENAME", "PERLEXPR", ...);
This method resembles the Unix tool ``sed''.
It allows you to apply arbitrary Perl expressions (typically substitution
commands like ``s///'' and ``tr///'') to the lines (or paragraphs or the
entire file at once) of the given file.
(The lines (or paragraphs or the entire file) of the file in question are
thereby successively read into the Perl variable ``$_''.)
Before actually applying any modifications, a new filename for the original file is generated (for later safeguarding), by appending ``.000'' to its name and increasing this number if a file of that name already exists, until a filename is found which doesn't exist yet.
Another new (temporary) filename is generated (in the same manner) for the file which will hold the results of the ``patch'' operation, by using the number found in the previous step plus one, and again by incrementing this number if a file of that name already exists, until a filename is found which doesn't exist yet.
Then the original file is read, all the commands given as arguments to this method are applied successively (in the given order) to each of the lines (or paragraphs or the entire file) being read, and the results are written to a new file with the (temporary) filename (the second of the two filenames generated above).
Note that you can control the ``line'' vs. ``paragraph'' vs. ``entire file'' mode
by setting the Perl variable ``$/'' appropriately (see perlvar(1) for
more details).
(Don't forget to reset this variable to its default value in order to avoid unexpected results in the remaining part of your script, though.)
After reading all of the original file, and only if no errors occurred, the original file is renamed to the first of the two new filenames generated above, and the file containing the results of the ``patch'' operation is renamed to the (original) filename of the original file.
In case of an error (most likely a Perl syntax error in one of the expressions you supplied as arguments to this method), all files are closed, the temporary file containing the results (if any) is deleted, an appropriate error message is displayed and program execution is aborted.
The following methods are subject to be switched ``off'' and ``on'' by the
methods ``begin_section()'', ``end_section()'', ``begin_must_section()'',
``end_must_section()'', ``begin_lazy_section()'', ``end_lazy_section()'',
``ignore()'' and ``resume()'':
- reset() - back() - chdir() - mkdir() - fetch() - system() - patch()
You can always determine wether these methods will currently (i.e., in the
current section of your installation script) be executed or ignored by
calling the method ``active()'', which returns ``true'' if the section
in question is ``active'' and ``false'' if the commands in that section
will currently be ignored.
build(1), genopt(1), make(1), CPAN(3).
This man page documents ``BnP'' version 2.1.0.
Ralf S. Engelschall - original idea and first private versions
rse@engelschall.com www.engelschall.com
Steffen Beyer - complete rewrite and documentation
(first public version)
sb@engelschall.com www.engelschall.com/u/sb/download/
Copyright (c) 1996 - 1998 by Ralf S. Engelschall. All rights reserved.
Copyright (c) 1998 by Steffen Beyer. All rights reserved.
This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e., under the terms of the ``Artistic License'' or the ``GNU General Public License''.
Please refer to the files ``Artistic.txt'' and ``GNU_GPL.txt'' in this distribution for details!
This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the ``GNU General Public License'' for more details.
|
BnP - implements the automatic recovery mechanism of "Build'n'Play" |