Tom Legrady > Text-ASED-1.12 > Text::ASED

Download:
Text-ASED-1.12.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.12   Source  

NAME ^

ASED.pm - Perl extension providing an Advanced Stream EDitor

Synopsis ^

    use ASED;

    my $editor = new ASED;

    $editor->prep( search  => $pattern1
                   replace => $patther2); 
    $editor->edit( infile   => $infile, 
                   outfile  => $outfile);
    $editor->scrub();

or

    $editor->snr(  $search1, $replace1, 
                   $search2, $replace2, 
                   $search3, $replace3 );
    $editor->prep( search  => $search2,
                   replace => $pattern5 );
    $editor->edit( $infile1 );
    $editor->reuse();
    $editor->edit( $infile2 );

or

    $editor->snr(  $search1, $replace1, 
                   $search2, $replace2, 
                   $search2, $replace2,
                   $file_or_string );

Description ^

An ASED object provides five commands, besides the constructor: prep(), edit(), snr(), scrub() and reuse().

prep() describes the modifications which are to be performed on a file. Each invocation of prep() describes a single set of edits, thus three search-and-replace operations require three invocations of prep(). The various parameters to prep() are described in Options.

Note that parameter keywords can be contracted. Intead of specifying begincontext, it is possible to use any unique subset of this string. While b would work, I would suggest begin as optimally combining brevity and clarity.

Once all the modifications are described, the editing is performed by invoking edit(). edit() can be invoked with a single argument, the name of the file to edit, with several named arguments specifying several file names, or with the string to edit.

If all the modifications to be performed are simple search-and-replace operations, and there is no need for separate output files, log files, etc., a simplified form is provided. snr() stands for search-and-replace. Arguments are taken two at a time and interpretated as a search string and a replace string. After all pairs have been processed, if there remains a single argument, it specifies the file or string to process. The final argument is tested to see if it specifies the name of an existing file. if it does, that file is processed in place. If no matching file is found, the argument is considered to specify a string which is to be modified.

If you are finished with an ASED object, there is no need to invoke reuse() or scrub(), but one or the other of these must be called if an ASED object will be used several times. Whether using predefined Perl edit commands or sed scripts invoked from shell scripts, a common mistake (i.e., one I tend to make) is to forget to re-initialize the edit sequence. This may result in accidentally making unintended changes to a file, or simply in producing error messages concerning failed edits. In the worst case, not removing the old set of edits may prevent the new, intended edits from occurring properly. This is the reason for requiring the use of reuse() and scrub().

reuse() is used when a set of edits is to be applied to more than one file. The identical set of edits can be applied to the next file, or additional edits can be added.

Once you are finished with a set of edits, scrub() it. This empties the edit set, causing new snr() or prep() commands to generate a new set of edits.

    $editor->snr( $pattern1, $pattern2 );
    $editor->edit( $file1 );
    $editor->reuse();

    $editor->edit( $file2 );
    $editor->reuse();

    $editor->snr( $pattern3, $pattern4 );
    $editor->edit( $file3 );
    $editor->scrub();

    $editor->snr( $pattern5, $pattern6 );
    $editor->edit( $file4 );

Options ^

The patterns provided to options are automatically adjusted so that the use of / or of \/n are passed on to the intended string, rather than being interpreted too early.

The prep() command takes the following options:

Action Specifying Options

search pattern

The pattern specified is used as the first component in s///. Any Perl regexp component can be used.

replace pattern

The second component in s///. Any appropriate Perl regexp component can be used

append string

Normally, this command would be used in conjunction with match to locate lines to be modified. The specified string is added to the current line.

Lines of the input string are not chomped, thus append adds text to beginning of the following line. Make sure there is a \/n at the end of the append string if you want a new line.

prepend string

Like append, this is used with line-specifying options such as match. The specified text is added to the beginning of the line. Use a \/n at the end of the new string, if you want a new line before the matched line.

delete pattern

delete specifies a pattern and deletes matching lines.

Note the difference between this and the behaviour of append and prepend.

Region Specifying Options

match pattern

Attempt other commands only to lines which match this pattern.

match makes it possible to simplify search-and-replace patterns which require some text to isolate the correct line, but need to modify different components. Instead of:

    s{(My_Complicated_variable_name)\s*=\s*Complicated_value}
     {\1 = New_Value}

it becomes possible to use the clearer:

    $editor->prep( match => "My_Complicated_variable_name\s*="
                   search => "=\s*Complicated_value",
                   replace => "= New_Value" );

match nests within contexts.

ignore pattern

Do not attempt other commands on lines which match this pattern.

ignore nests within contexts.

begincontext pattern

Sometimes match isn't enough. In Apache's httpd.conf file, you might want to modify only DocumentRoot lines within a certain VirtualHost section. In a script, you might want to modify my $tmp only within a certain subroutine.

begincontext specifies the first line of the region which will have other options applied to it.

Contexts can be nested without limit, usign the pattern:

    begin                       # 1
    begin                       # 2
    begin                       # 3
    end                         # 3
    end                         # 2
    end                         # 1
endcontext pattern

Specifies the last line of a context region.

The edit() command takes the following options:

AUTHOR ^

Tom Legrady tdl@cpan.org

COPYRIGRHT ^

Copyright (c) 2002 Tom Legrady tdl@cpan.org

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

If you use my module, I would appreciate an email (tdl@cpan.org) letting me know about it. Even better, let me know what you like, what different features you would like, what could be done better.

syntax highlighting: