/ 
Win32-InstallShield-0.3
River stage zero No dependents
/ Win32::InstallShield

NAME

Win32::InstallShield - InstallShield data file interface

SYNOPSIS

use InstallShield;

# Constructors
$is = Win32::InstallShield->new();
$is = Win32::InstallShield->new( $ism_file );

ABSTRACT

An OO interface for manipulating InstallShield XML .ism files

DESCRIPTION

This module provides an interface to add, remove and modifify rows in an InstallShield .ism file. It only supports versions of InstallShield that save their data as XML.

EXAMPLES

This example updates the product version.

use Win32::InstallShield;

$is = Win32::InstallShield->new( $ism_file );
$is->UpdateProperty(
    { 
        Property => 'ProductVersion',
        Value    => '1.2.3.4',
    }
);

$is->savefile( $ism_file );

METHODS

new
$is = Win32::InstallShield->new();
$is = Win32::InstallShield->new( $installshield_filename );
$is = Win32::InstallShield->new( $io_file_handle );

The constructor. Can optionally be called with the same arguments as loadfile.

loadfile
$is->loadfile( $filename );
$is->loadfile( $io_file_handle );

Loads an InstallShield ism file. Can be called with either a filename or an IO::File object that is opened in read ("r") mode. Returns 1 on success, 0 on failure.

load
$is->load( $ism_text );

Loads the supplied text of an InstallShield ism file. Returns 1 on success, 0 on failure.

savefile
$is->savefile( );
$is->savefile( $filename );
$is->savefile( $io_file_handle );

Stores the ism data in a file. Can be called with either a filename or an IO::File object that is opened in write ("w") mode. If no argument is passed, and the last load was via a filename, savefile will default to the filename previously supplied. Returns 1 on success, 0 on failure.

save
$is->save();

Returns the ism data as a string.

tables
my $tables = $is->tables();

Returns an arrayref containing a list of all the tables that were found in the ISM file.

column_is_key
my $is_key = $is->column_is_key( $table, $column_name );

Returns true if the column is a key column, false other wise. Returns undef if the column doesn't exist.

column_width
my $width = $is->column_width( $table, $column_name );

Returns the width of the named column. Returns undef if the column doesn't exist.

column_type
my $type = $is->column_type( $table, $column_name );

Returns the type of the named column. Returns undef if the column doesn't exist.

columns
my $columns = $is->columns( $table );

Returns an array ref containing the names of the columns in the given table.

key_columns
my $key_columns = $is->key_columns( $table );

Returns an array ref containing the names of the key columns in the given table.

property
my $version = $is->property('ProductVersion');
$is->property('ProductVersion', $version);

Gets or sets the value associated with a property. If no value is supplied, the current value of the property is returned. If a value is supplied, it will attempt to update the property and return 1 on success and 0 on failure. undef is returned in either case if the property does not exist.

featureComponents
my $components = $is->featureComponents( $feature );

Returns an arrayref of the components in the named feature. Returns undef if the feature does not exist.

purge_row
$is->purge_row( $table, $key_value );
$is->purge_row( 'Component', 'Awesome.dll' );
$is->PurgeComponent( 'Awesome.dll' );

Removes the row with the given key from the given table, and any rows in other tables with foreign keys that reference it. Key values are case sensitive. This only works for tables with a key column that has the same name as the table, which seems to be the only way you can use foreign keys in an ISM in any case. Returns 1 on success, 0 on failure.

ROW MANIPULATION METHOD SYNTAX

Row manipulation methods can be called in different ways. First, they are all case insensitve, and the '_' is optional, so for the 'Property' table, these are equivilent:

$is->add_row( 'Property', $rowdata );
$is->AddRow( 'Property', $rowdata );

Also, you can call each method using the table name in place of the word 'row', so these are equivilent to the two above:

$is->add_property( $rowdata );
$is->AddProperty( $rowdata );

All row manipulation methods are called with a set of data describing a row. In the methods below, it is represented by the variable $rowdata. It can be passed to the function in one of three formats: a list, an array ref or a hash ref.

List

You can simply put the columns in an array in the correct order (which you can get by looking at the ism or calling the columns method), and pass it to the method.

my @rowdata = ( 'Column_1_Value', 'Column_2_value' );
$success = $is->update_row( $table, @rowdata );

Array ref

You can do the same as above, but pass it as a single array reference.

$success = $is->update_row( $table, \@rowdata );

Hash ref

You can also pass a hash ref, using column names as keys.

my %rowdata = (
    Property   => 'ProductVersion',
    Value      => '1.2.3.4',
    ISComments => '',
);
$success = $is->update_row( $table, \%rowdata );

ROW MANIPULATION METHODS

getHash_row
my $row = $is->getHash_row( $table, $rowdata );

Returns a hash ref containing the data that matches the keys supplied in $rowdata. Returns undef if the row is not found.

getArray_row
my $row = $is->getArray_row( $table, $rowdata );

Returns an array ref containing the data that matches the keys supplied in $rowdata. Returns undef if the row is not found.

update_row
my $success = $is->update_row( $table, $rowdata );

Updates the row that matches the keys supplied in $rowdata. Any columns for which an undef is supplied will remain unchanged. An empty string will force the column to be empty. Returns 1 on success, 0 on failure.

add_row
my $success = $is->add_row( $table, $rowdata );

Adds a row containing the data in $rowdata. Returns 1 on success, 0 on failure.

del_row
my $success = $is->del_row( $table, $rowdata );

Deletes the row that matches the keys supplied in $rowdata. Returns 1 on success, 0 on failure.

add_or_update_row
my $success = $is->add_or_update_row( $table, $rowdata );

Adds a row if no row exists with the supplied keys, updates the matching row otherwise.

searchHash_row
my $rows = $is->searchHash_row( $table, $rowdata );

Returns any rows in the given table that match the supplied columns. The return value is an arrayref, where each entry is a hash as would be returned by getHash_row. Returns an empty arrayref if no matches are found. Returns the entire table if no $rowdata argument is provided.

Columns with undefined values will be ignored for matching purposes. Values used for matching can be either literal strings, in which case an exact match is required, or quoted regular expressions such as:

my $rows = $is->searchHash_row( 'Property', { Property=>qr/^_/ } );

This would search for all properties that begin with an underscore.

searchArray_row
my $rows = $is->searchArray_row( $table, $rowdata );

Works the same as searchHash_row, but returns an arrayref containing arrayrefs, like getArray_row instead of hashrefs.

AUTHOR

Kirk Baucom, <kbaucom@schizoid.com>