Auxiliary implementations for use in Perl scripts. More...

Collaboration diagram for Perl Utilities:

Files
file	Basis.pm
	BASIS utilities of BASIS package.
file	Utilities.pm
	Main module of project-independent BASIS utilities.
Functions
sub	execute (scalar args, scalar quiet, scalar stdout, scalar allow_fail, scalar verbose, scalar simulate, scalar prefix, hashref targets, scalar base)
	Execute command as subprocess.
sub	exedir (scalar name, scalar prefix, hashref targets, scalar base)
	Get directory of executable file.
sub	exename (scalar name, scalar prefix, hashref targets, scalar base)
	Get name of executable file.
sub	exepath (scalar name, scalar prefix, hashref targets, scalar base)
	Get absolute path of executable file.
sub	istarget (scalar target, scalar prefix, hashref targets)
	Determine whether a given target is known.
sub	print_contact (scalar contact)
	Print contact information.
sub	print_version (scalar name, scalar version, scalar project, scalar copyright, scalar license)
	Print version information including copyright and license notices.
sub	qsplit (scalar str)
	Split quoted string.
sub	targetuid (scalar target, scalar prefix, hashref targets)
	Get UID of build target.
sub	tostring (arrayref args)
	Convert list to double quoted string.
Variables
const	CONTACT
	Default contact to use for help output of executables.
const	CONTACT
	Default contact to use for help output of executables.
const	COPYRIGHT
	Default copyright of executables.
const	COPYRIGHT
	Default copyright of executables.
const	LICENSE
	Default license of executables.
const	LICENSE
	Default license of executables.
const	PROJECT
	Project name.
cmake	PROJECT_NAMESPACE_PERL
	CMake variable of Perl package name of project.
const	RELEASE
	Project release.

Detailed Description

Auxiliary implementations for use in Perl scripts.

Function Documentation

sub execute	(	scalar	args,
		scalar	quiet,
		scalar	stdout,
		scalar	allow_fail,
		scalar	verbose,
		scalar	simulate,
		scalar	prefix,
		hashref	targets,
		scalar	base
	)

Execute command as subprocess.

Note:: This function can be customized when importing it in order to set default values for prefix and targets, which is in particular done by the Basis module.

This command takes either an array reference or a string as first argument. All other arguments are keyword arguments using hash notation.

Example:

 # only returns exit code of command but does not output anything
 my $status = execute(['ls', '/'], quiet => 1);
 # returns exit code of command and returns command output w/o printing to stdout
 my ($status, $stdout) = execute('ls /', quiet => 1, stdout => 1);

Parameters:

[in]	args	Command with arguments given either as single quoted string or array of command name and arguments.
[in]	quiet	Turns off output of `stdout` of child process to `stdout` of parent process.
[in]	stdout	Whether to return the command output.
[in]	allow_fail	If true, does not raise an exception if return value is non-zero. Otherwise, an exception is raised by this function using die.
[in]	verbose	Verbosity of output messages. Does not affect verbosity of executed command.
[in]	simulate	Whether to simulate command execution only.
[in]	prefix	Common target name prefix. If `undef`, the given target name must match excactly. Otherwise, targets within the specified namespace are considered.
[in]	targets	Reference to hash which maps known build targets to executable file paths. If not specified, this function always returns false.
[in]	base	Base directory used for relative paths in `$targets`.

Returns:: The exit code of the subprocess if stdout is false (the default). Otherwise, if stdout is true, a tuple consisting of exit code command output is returned. Note that if allow_fail is false, the returned exit code will always be 0.

Exceptions:

die	If command execution failed. This exception is not raised if the command executed with non-zero exit code but `allow_fail` is true.

sub exedir	(	scalar	name,
		scalar	prefix,
		hashref	targets,
		scalar	base
	)

Get directory of executable file.

Note:: This function can be customized when importing it in order to set default values for prefix and targets, which is in particular done by the Basis module.

Parameters:

[in]	name	Name of command or `undef`.
[in]	prefix	Common target name prefix. If `undef`, the given target name must match excactly. Otherwise, targets within the specified namespace are considered.
[in]	targets	Reference to hash which maps known build targets to executable file paths. If not specified, this function always returns false.
[in]	base	Base directory used for relative paths in `$targets`.

Returns:: Absolute path of directory containing executable or undef if not found. If name is undef, the directory of this executable is returned.

sub exename	(	scalar	name,
		scalar	prefix,
		hashref	targets,
		scalar	base
	)

Get name of executable file.

Note:: This function can be customized when importing it in order to set default values for prefix and targets, which is in particular done by the Basis module.

Parameters:

[in]	name	Name of command or `undef`.
[in]	prefix	Common target name prefix. If `undef`, the given target name must match excactly. Otherwise, targets within the specified namespace are considered.
[in]	targets	Reference to hash which maps known build targets to executable file paths. If not specified, this function always returns false.
[in]	base	Base directory used for relative paths in `$targets`.

Returns:: Name of executable file or undef if not found. If name is undef, the path of this executable is returned.

sub exepath	(	scalar	name,
		scalar	prefix,
		hashref	targets,
		scalar	base
	)

Get absolute path of executable file.

Note:: This function can be customized when importing it in order to set default values for prefix and targets, which is in particular done by the Basis module.

This function determines the absolute file path of an executable. If no arguments are given, the absolute path of this executable is returned. Otherwise, the named command is searched in the system PATH and its absolute path returned if found. If the executable is not found, undef is returned.

Parameters:

[in]	name	Name of command or `undef`.
[in]	prefix	Common target name prefix. If `undef`, the given target name must match excactly. Otherwise, targets within the specified namespace are considered.
[in]	targets	Reference to hash which maps known build targets to executable file paths. If not specified, this function always returns false.
[in]	base	Base directory used for relative paths in `$targets`.

Returns:: Absolute path of executable or undef if not found. If name is undef, the path of this executable is returned.

sub istarget	(	scalar	target,
		scalar	prefix,
		hashref	targets
	)

Determine whether a given target is known.

Note:: This function can be customized when importing it in order to set default values for prefix and targets, which is in particular done by the Basis module.

Parameters:

[in]	target	Name of build target.
[in]	prefix	Common target name prefix. If `undef`, the given target name must match excactly. Otherwise, targets within the specified namespace are considered.
[in]	targets	Reference to hash which maps known build targets to executable file paths. If not specified, this function always returns false.

Returns:: Whether the given build target is known by this module.

sub print_contact ( scalar contact )

Print contact information.

Parameters:

[in] contact Name of contact. If undef, the default contact is used.

sub print_version	(	scalar	name,
		scalar	version,
		scalar	project,
		scalar	copyright,
		scalar	license
	)

Print version information including copyright and license notices.

Note:: This function can be customized when importing it in order to set default values for its parameters, which is in particular done by the Basis module.

Example:

 use BASIS::Utilities qw(print_version);
 print_version('foo', '1.0');
 print_version('foo', version => '1.0');
 print_version(name => 'foo', version => '1.0');

Example:

 use BASIS::Utilities
     print_version => {project   => 'FooBar',
                       version   => '1.0',
                       copyright => '2012 Andreas Schuh',
                       license   => 'Licensed under the Apache License, Version 2.0'};
 print_version('foo');

which results in the output

/// foo (FooBar) 1.0
/// Copyright (c) 2012 Andreas Schuh. All rights reserved.
/// Licensed under the Apache License, Version 2.0
///

Parameters:

[in]	name	Name of executable. Should not be set programmatically to the first argument of the main script, but a string literal instead. This argument is required if no default has been set during customization. The argument can be either given as first argument or as keyword argument as in "name => 'foo'".
[in]	version	Version of executable, e.g., release of project this executable belongs to. This argument is required if no default has been set during customization. The argument can be either given as second argument or as keyword argument as in "version => '1.0'".
[in]	project	Name of project this executable belongs to. If `undef` or an empty string is given, no project information is included in output.
[in]	copyright	The copyright notice. If `undef`, the default copyright is used. If an empty string is given, no copyright notice is printed.
[in]	license	Information regarding licensing. If `undef`, the default software license is used. If an empty string is given, no license information is printed.

sub qsplit ( scalar str )

Split quoted string.

Parameters:

[in] str Quoted string.

sub targetuid	(	scalar	target,
		scalar	prefix,
		hashref	targets
	)

Get UID of build target.

Note:: This function can be customized when importing it in order to set default values for prefix and targets, which is in particular done by the Basis module.

This function prepends the default namespace used for targets build as part of the project this module belongs to if the given target name is yet neither known nor fully-qualified, i.e., in the form "<namespace>::<target>".

Parameters:

[in]	target	Name of build target.
[in]	prefix	Common target name prefix. If `undef`, the given target name must match excactly. Otherwise, targets within the specified namespace are considered.
[in]	targets	Reference to hash which maps known build targets to executable file paths. If not specified, this function always returns the input target name unchanged.

Returns:: Fully-qualified build target name or undef if target is undef or an empty string.

sub tostring ( arrayref args )

Convert list to double quoted string.

Parameters:

[in] args Array of arguments.

Returns:: Double quoted string, i.e., string where array elements are separated by a space character and surrounded by double quotes if necessary. Double quotes within an array element are escaped with a backslash.

Variable Documentation

const CONTACT

Default contact to use for help output of executables.

Definition at line 55 of file Utilities.pm.

const CONTACT

Default contact to use for help output of executables.

Definition at line 61 of file Basis.pm.

const COPYRIGHT

Default copyright of executables.

Definition at line 46 of file Utilities.pm.

const COPYRIGHT

Default copyright of executables.

Definition at line 57 of file Basis.pm.

const LICENSE

Default license of executables.

Definition at line 53 of file Utilities.pm.

const LICENSE

Default license of executables.

Definition at line 59 of file Basis.pm.

const PROJECT

Project name.

The project name.

Definition at line 33 of file Basis.pm.

cmake PROJECT_NAMESPACE_PERL

CMake variable of Perl package name of project.

The Perl package name of a BASIS project is made up of the vendor name and the name of the package itself. Moreover, if the project is a module of another project, the name of the module may optionally be used as part of the namespace as well. Names of packages and sub-packages in Perl are usually in mixed CamelCase starting with an uppercase letter. Note that Perl informally reserves lowercase module names for "pragma" modules such as integer and strict.

Definition at line 117 of file ProjectSettings.cmake.

const RELEASE

Project release.

Complete version information as output by --version option.

Definition at line 55 of file Basis.pm.

Files

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation