/ 
App-IniDiff-IniFile-0.19
River stage zero No dependents
/ inifilter

NAME

inifilter - filter an .ini file by making substitutions and deletions to keys and entries

SYNOPSYS

inifilter [-f inifile] [-V] filter-file -e -p

DESCRIPTION

inifilter is used to modify an ini file (or an ini file patch) by applying to it the substitutions and deletions specified in one or more filter files.

Such filtering is useful when one needs to do common transformations (such as changing where the windows system directory is, etc.) to a number of ini files.

It is also useful for filtering out common ignorable changes from an ini diff, so only important changes remain.

Filter File Format

Terminology NOTE: The following naming convention is used here:

[key pattern] 
entry line : name=value

This corresponds to the INI File Format described in the other tools:

[key] field=value

Whereas in other documentation of INI files the naming convention is:

[section] key=value

The filter files that control what inifilter does consist of a number of ini key patterns (enclosed in brackets). Each key pattern contains lines indicating which entries in matching keys are to be modified (entries can be matched based on their name or their value).

Finally, actions can be specified for each matching entry: an entry's name or value can be changed or it may be deleted entirely. Key patterns and entry name or value patterns are specified as case insensitive perl regular expressions, while name and value changes are specified perl substitution commands.

Comments are indicated by lines beginning with a # or ; character (a # in the middle of a line does not introduce a comment).

The following example demonstrates the syntax of filter files:

    # Read contents of another filter file:
    include "anotherFile"

    # Check for matching entries in keys starting with 'option'
    [option.*]
	# Change C:\PROGRA~1\ to F:\Program files\ in matching value entries
	value .*C:\\\\PROGRA~1\\\\.*
	    subst value s/C:\\\\PROGRA~1\\\\/F:\\\\Program Files\\\\/gi
	# Do the same for entry names
	name .*C:\\\\PROGRA~1\\\\.*
	    subst name s/C:\\\\PROGRA~1\\\\/F:\\\\Program Files\\\\/gi

    # Delete any entries under the Explorer key, and delete the key section
    # (- at end of line means delete any keys matching the pattern)
    [Explorer]-

    # Delete a particular entry by name
    [UuidPersistentData]
    name LastTimeAllocated
	delete 

    # Change both the name and value of some key
    [foo]
    name something
	    subst name s/X/Y/gi
	    subst value s/A/B/gi

Some things to note about these files: you need lots of backslashes in windows path key names (since backslash is used as a path separator, and since it is special to perl).

The key, name and value patterns are always anchored, so don't forget to put an explicit .* in front of or after patterns where you want a substring match.

The include command is used to read filter commands from another file. The file is first looked for relative to the same directory as the file that included it, then in the process's current directory.

OPTIONS

-f inifile

Read the specified ini file instead of from standard input.

-V

Prints the version number - the program then exits immediately.

-e

Exports the filter results to a text format (debug purposes)

-p

Preserves the order of Ordered Field names (such as mod_1, mod_2, etc.)

SEE ALSO

inidiff, iniedit, inicat.

AUTHOR

Michael Rendell, Memorial University of Newfoundland

MAINTAINERS

Jeremy Squires <j.squires at computer.org>

SOURCE

KNOWN BUGS

Deleting a section containing blank lines with the
filter statement [section]- deletes the entire section
and whatever section follows it.

ACKNOWLEDGEMENTS

Michael Rendell, Memorial University of Newfoundland
produced the first version of the Regutils package from which
this package was derived.

BUGS

Please report any bugs or feature requests to bug-app-inidiff-inifile at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-IniDiff-IniFile. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::IniDiff::IniFile

You can also look for information at:

LICENSE AND COPYRIGHT

This software is Copyright (c) 1998 Memorial University of Newfoundland

This is free software, licensed under:

The GNU General Public License, Version 3, July 2007

See LICENSE