Manual:

Reference:

Contact:

Site maintained by
Jon Allen (JJ)
Last updated on
23 April 2006
See the project page for more details

Show navigation

-- Perl 5.8.8 documentation --

Show toolbar

Fink::Services

NAME
SYNOPSIS
DESCRIPTION
- Functions

NAME

Fink::Services - functions for text processing and system interaction

SYNOPSIS

DESCRIPTION

These functions handle a variety of text (file and string) parsing and system interaction tasks.

Functions

No functions are exported by default. You can get whichever ones you need with things like:

    use Fink::Services '&read_config';
    use Fink::Services qw(&execute_script &expand_percent);

read_config
```
    my $config = read_config $filename;
    my $config = read_config $filename, \%defaults;
```
Reads a fink.conf file given by $filename into a new Fink::Config object and initializes Fink::Config globals from it. If %defaults is given they will be used as defaults for any keys not in the config file. The new object is returned.
read_properties
```
    my $property_hash = read_properties $filename;
    my $property_hash = read_properties $filename, $notLC;
```
Reads a text file $filename and returns a ref to a hash of its fields. See the description of read_properties_lines for more information.

If $filename cannot be read, program will die with an error message.
read_properties_var
```
    my $property_hash = read_properties_var $filename, $string;
    my $property_hash = read_properties_var $filename, $string, $notLC;
```
Parses the multiline text $string and returns a ref to a hash of its fields. See the description of read_properties_lines for more information. The string $filename is used in parsing-error messages but the file is not accessed.
read_properties_lines
```
    my $property_hash = read_properties_lines $filename, $notLC, @lines;
```
This is function is not exported. You should use read_properties_var, read_properties, or read_properties_multival instead.

Parses the list of text strings @lines and returns a ref to a hash of its fields. The string $filename is used in parsing-error messages but the file is not accessed.

If $notLC is true, fields are treated in a case-sensitive manner. If $notLC is false (including undef), field case is ignored (and cannonicalized to lower-case). In functions where passing $notLC is optional, not passing is equivalent to false.

See the Fink Packaging Manual, section 2.2 "File Format" for information about the format of @lines text.

If errors are encountered while parsing @lines, messages are sent to STDOUT, but whatever (possibly incorrect) parsing is returned anyway. The following situations are checked:
```
  More than one occurance of a key. In this situation, the last
  occurance encountered in @lines is the one returned. Note that the
  same key can occur in the main package and/or different splitoff
  packages, up to one time in each.
```
```
  Use of RFC-822-style multilining (whitespace indent of second and
  subsequent lines). This notation has been deprecated in favor of
  heredoc notation.
```
```
  Any unknown/invalid syntax.
```
```
  Reaching the end of @lines while a heredoc multiline value is still
  open.
```
Note that no check is made for the validity of the fields being in the file in which they were encountered. The filetype (fink.conf, *.info, etc.) is not necessarily known and this routine is used for many different filetypes.

Multiline values (including all the lines of fields in a splitoff) are returned as a single multiline string (i.e., with embedded \n), not as a ref to another hash or array.
read_properties_multival
```
    my $property_hash = read_properties_multival $filename;
    my $property_hash = read_properties_multival $filename, $notLC;
```
Reads a text file $filename and returns a ref to a hash of its fields, with each value being a ref to a list of values for that field. See the description of read_properties_multival_lines for more information.

If $filename cannot be read, program will die with an error message.
read_properties_multival_var
```
    my $property_hash = read_properties_multival_var $filename, $string;
    my $property_hash = read_properties_multival_var $filename, $string, $notLC;
```
Parses the multiline text $string and returns a ref to a hash of its fields, with each value being a ref to a list of values for that field. See the description of read_properties_multival_lines for more information. The string $filename is used in parsing-error messages but the file is not accessed.
read_properties_multival_lines
```
    my $property_hash = read_properties_multival_lines $filename, $notLC, @lines;
```
This is function is not exported. You should use read_properties_var, read_properties, read_properties_multival, or read_properties_multival_var instead.

Parses the list of text strings @lines and returns a ref to a hash of its fields, with each value being a ref to a list of values for that field. The string $filename is used in parsing-error messages but the file is not accessed.

The function is similar to read_properties_lines, with the following differences:
```
  Multiline values are can only be given in RFC-822 style notation,
  not with heredoc.
```
```
  No sanity-checking is performed. Lines that could not be parsed are
  silently ignored.
```
```
  Multiple occurances of a field are allowed.
```
```
  Each hash value is a ref to a list of key values instead of a simple
  value string. The list is in the order the values appear in @lines.
```
execute
```
    my $retval = execute $cmd;
    my $retval = execute $cmd, $quiet;
```
Executes $cmd as a single string via a perl system() call and returns the exit code from it. The command is printed on STDOUT before being executed. If $cmd begins with a # (preceeded optionally by whitespace) it is treated as a comment and is not executed. If $quiet is false (or not given) and the command failed, a message including the return code is sent to STDOUT.
execute_script
```
     my $retval = execute_script $script;
     my $retval = execute_script $script, $quiet;
```
Executes the multiline script $script.

If $script appears to specify an interpretter (i.e., the first line begins with #!) the whole thing is stored in a temp file which is made chmod +x and executed. If the tempfile could not be created, the program dies with an error message. If executing the script fails, the tempfile is not deleted and the failure code is returned.

If $script does not specify an interpretter, each line is executed individually. In this latter case, the first line that fails causes further lines to not be executed and the failure code is returned.

In either case, execution is performed by Fink::Services::execute (which see for more information, including the meaning of $quiet).
expand_percent
```
    my $string = expand_percent $template;
    my $string = expand_percent $template, \%map;
    my $string = expand_percent $template, \%map, $err_info;
```
Performs percent-expansion on the given multiline $template according to %map (if one is defined). If a line in $template begins with # (possibly preceeded with whitespace) it is treated as a comment and no expansion is performed on that line.

The %map is a hash where the keys are the strings to be replaced (not including the percent char). The mapping can be recursive (i.e., a value that itself has a percent char), and multiple substitution passes are made to deal with this situation. Recursing is currently limitted to a single additional level (only (up to) two passes are made). If there are still % chars left after the recursion, that means $template needs more passes (beyond the recursion limit) or there are % patterns in $template that are not in %map. If either of these two cases occurs, the program will die with an error message. If given, $err_info will be appended to this error message.

To get an actual percent char in the string, protect it as %% in $template (similar to printf()). This occurs whether or not there is a %map. This behavior is implemented internally in the function, so you should not have ('%'=>'%') in %map. Pecent-delimited percent chars are left-associative (again as in printf()).

Expansion keys are not limitted to single letters, however, having one expansion key that is the beginning of a longer one (d and dir) will cause unpredictable results (i.e., "a" and "arch" is bad but "c" and "arch" is okay).

Curly-braces can be used to explicitly delimit a key. If both %f and %foo exist, one should use %{foo} and %{f} to avoid ambiguity.
filename
```
    my $file = filename $source_field;
```
Treats $source_field as a URL or "mirror:" construct as might be found in Source: fields of a .info file and returns just the filename (skips URL proto/host or mirror-type, and directory hierarchy). Note that the presence of colons in the filename will break this function.
version_cmp
```
    my $bool = version_cmp $fullversion1, $op, $fullversion2;
```
Compares the two debian version strings $fullversion1 and $fullversion2 according to the binary operator $op. Each version string is of the form epoch:version-revision (though one or more of these components may be omitted as usual--see the Debian Policy Manual, section 5.6.11 "Version" for more information). The operators are those used in the debian-package world: << and>> for strictly-less-than and strictly-greater-than, <= and >= for less-than-or-equal-to and greater-than-or-equal-to, and = for equal-to.

The results of the basic comparison (similar to the perl <=> and cmp operators) are cached in a package variable so repeated queries about the same two version strings does not require repeated parsing and element-by-element comparison. The result is cached in both the order the packages are given and the reverse, so these later requests can be either direction.
raw_version_cmp
```
    my $cmp = raw_version_cmp $item1, $item2;
```
This is function is not exported. You should use version_cmp instead.

Compare $item1 and $item2 as debian epoch or version or revision strings and return -1, 0, 1 as for the perl <=> or cmp operators.
latest_version
```
    my $latest = latest_version @versionstrings;
```
Given a list of one or more debian version strings, return the one that is the highest. See the Debian Policy Manual, section 5.6.11 "Version" for more information.
sort_versions {
```
	my @sorted = sort_versions @versionstrings;
```
Given a list of one or more debian version strings, return the list sorted lowest-to-highest. See the Debian Policy Manual, section 5.6.11 "Version" for more information.
parse_fullversion
```
    my ($epoch, $version, $revision) = parse_fullversion $versionstring;
```
Parses the given $versionstring of the form epoch:version-revision and returns a list of the three components. Epoch and revision are each optional and default to zero if absent. Epoch must contain only numbers and revision must not contain any hyphens.

If there is an error parsing $versionstring, () is returned.
collapse_space
```
    my $pretty_text = collapse_space $original_text;
```
Collapses whitespace inside a string. All whitespace sequences are converted to a single space char. Newlines are removed.
pkglist2lol
```
	my $struct = pkglist2lol $pkglist;
```
Takes a string representing a pkglist field and returns a ref to a list of lists of strings representing each pkg. The elements of the list referenced by $struct are joined by logical AND (commas in $pkglist). The pkgs in each list referenced by an element of @$srtuct are joined by logical OR (delimited by vertical-bar within a comma- delimited cluster). Leading and trailing whitespace are removed from each pkg, and null pkgs are removed. A ref to an array is always returned, though it may contain no elements. Each element of @$struct is always an array ref, even if that list only has one element; none of these will have no elements. A new $struct is returned on each call, so changing one returned value does not afect the data returned by another call or the underlying data.
lol2pkglist
```
	my $pkglist = lol2pkglist $struct;
```
Given a ref to a list of lists of pkgs, reconstitute the Debian pkglist string. Blank/whitespace-only/undef elements are removed. The return is always defined (though it may be null). $struct is not modified.
file_MD5_checksum
```
    my $md5 = file_MD5_checksum $filename;
```
Returns the MD5 checksum of the given $filename. Uses /sbin/md5 if it is available, otherwise uses the first md5sum in PATH. The output of the chosen command is read via an open() pipe and matched against the appropriate regexp. If the command returns failure or its output was not in the expected format, the program dies with an error message.
get_arch
```
    my $arch = get_arch;
```
Returns the architecture string to be used on this platform. For example, "powerpc" for ppc.
enforce_gcc
```
	my $gcc = enforce_gcc($message);
	my $gcc = enforce_gcc($message, $gcc_abi);
```
Check to see if the gcc version optionally supplied in $gcc_abi is the same as the default GCC ABI for the installed version of Mac OS X or Darwin. If it is not, we return the value for the deafult GCC ABI.

If it is, or if $gcc_abi is not supplied, then we check to see if the gcc version obtained from /usr/sbin/gcc_select agrees with the expected (default) gcc version corresponding to the installed version of Mac OS X or Darwin. If the versions agree, the common value is returned. If they do not agree, we print $message and exit fink.

The strings CURRENT_SYSTEM, INSTALLED_GCC, EXPECTED_GCC, and GCC_SELECT_COMMAND within $message are converted to appropriate values.

Sample message:

This package must be compiled with GCC EXPECTED_GCC, but you currently have GCC INSTALLED_GCC selected. To correct this problem, run the command:
```
    sudo gcc_select GCC_SELECT_COMMAND
```
(You may need to install a more recent version of the Developer Tools to be able to do so.)
get_sw_vers
```
    my $os_x_version = get_sw_vers;
```
Returns OS X version (if that's what this platform appears to be, as indicated by being able to run /usr/bin/sw_vers). The output of that command is parsed and cached in a global configuration option in the Fink::Config package so that multiple calls to this function do not result in repeated spawning of sw_vers processes.
get_system_perl_version
```
    my $perlversion = get_system_perl_version;
```
Returns the version of perl in that is /usr/bin/perl by running a program with it to return its $^V variable. The value is cached, so multiple calls to this function do not result in repeated spawning of perl processes.
get_path
```
    my $path_to_file = get_path $filename;
```
Returns the full pathname of the first executable occurance of $filename in PATH. The correct platform-dependent pathname separator is used. This is an all-perl routine that emulates 'which' in csh.
count_files
```
    my $number_of_files = &count_files($path, $regexp);
```
Returns the number of files in $path. If $regexp is set only files matching the regexp are returned.
eval_conditional
```
    my $bool = &eval_conditional($expr, $where);
```
Evaluates the logical expression passed as a string in $expr and returns its logical value. If there is a parsing error, abort and print a message (including $where) is printed. Two syntaxes are supported:

Leading and trailing whitespace is ignored. The strings themselves cannot contain whitespace or any of the op operators (no quoting, delimiting, or protection syntax is implemented).

Search:

Labels:

Add this page