view release on metacpan or  search on metacpan

bin/iniedit  view on Meta::CPAN

=head1 SYNOPSYS

B<iniedit> [B<-V>] B<-f> I<file> B<-i> I<file> [B<-o> I<file>]

=head1 DESCRIPTION

B<iniedit> edits or patches the C<.ini> file specified
by the B<-f> option using the patch in the file indicated by the B<-i>
option.

If the B<-o> option is used, the result is written the specified file, 
otherwise the original file is over-written with the result.

The patch file basically lists the keys and fields to add, remove
or change - it is typically the result of running B<inidiff>.

=head1 OPTIONS

=over 4

=item B<-f> I<file>

Specifies the C<.ini> file that is to be patched. A "-" means
read the file from standard input.

=item B<-i> I<file>

Specifies the file containing the C<.ini> patch (usually generated by
B<inidiff>).  A "-" means the patch should be read from standard input.

=item B<-o> I<file>

Specifies the file where the result of the edit should be written.
A "-" means the patch should be written to standard output.
If this option is not specified, the original file is overwritten
(if the original file was read from standard input, the result is
written to standard output).

=item B<-V>

Prints the version number - the program then exits immediately.

=back

=head1 FILE FORMATS

=head2 INI File Format

Disclaimer: this is my understanding of C<.ini>, gained from looking at
a few files, and may be incorrect.

B<Terminology NOTE>: The following naming convention is used here:
	
	[key] field=value

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

	[section] key=value

Your typical C<.ini> file looks like this:

    ; A comment
    [firstkey]
    field=value		; More comments
    foo=bar
    
    [Another key name]
    A field=The value
    moreFields="values and ; stuff"

and so on.

In general, C<.ini> files consist of a number of keys, each
key has a number of fields, and each field has a value.  Key names are
inclosed in brackets and appear on a line by themselves - they
may contain pretty much any character except brackets.
Keys can appear in any order in the file, but no two keys should
have the same name.

Field names and their values are separated by an equals.
Field names within a key are usually, but not always, unique.
Double quotes are (somewhat) special in field names and values: they can
be used to quote characters that would otherwise not be allowed
(I<e.g.>, equals and semi-colon).

Quotes should be balanced (though I've seen some C<.ini> files with
a single quote in the value - check your HP printer C<.ini> files).

Blank lines are completely ignored, though they are
typically used to separate keys.

Comments in C<.ini> files begin with a semi-colon and go the the end of
the line.

Comments may be on lines by themselves or they may appear after a key name
or after a I<field>C<=>I<value>.

A semi-colon inside the brackets of a key name is not considered a comment.

=head2 Patch File Format

An C<.ini> patch file is mostly the same as an C<.ini> file with the
following differences:

=over 4

=item *

A minus after a key name (outside the brackets) indicates the key is to be
deleted.

=item *

A minus after a field name indicates the field is to be deleted (the field
has no equals and no value).

=item *

Key names can be repeated - the changes contained in the keys are combined;
the last change mentioned wins.