/ 
Text-Modify-0.2
River stage zero No dependents
/ Text::Buffer

NAME

Text::Buffer - oo-style interface for handling a line-based text buffer

SYNOPSIS

use Text::Buffer;

my $text = new Text::Buffer(-file=>'my.txt');

$text->goto(5);                   # goto line 5
$text->delete();                  # return the whole buffer as string
$text->replace("sad","funny");    # replace sad with funny in this line
my $line = $text->next();         # goto next line
$text->set($line);                # exchange current line with $line
$text->next();                    # goto next line
$text->insert("start of story");  # Insert text at start of buffer
$text->append("end of story");    # Append text at end of buffer

DESCRIPTION

Text::Buffer provides a mean of handling a text buffer with an oo-style interface.

It provides basic navigation/editing functionality with an very easy interface. Generally a Text::Buffer object is created by using new. Without an options this will create an empty text buffer. Optionally a file or reference to an array can be provided to load this into the buffer.

my $text = new Text::Buffer();

Now the basic methods for navigation (goto, next, previous), searching (find, findNext, findPrevious) or viewing/editing (get, set, delete, insert, append and replace).

$text->goto("+1");
my $line = $text->get();
$line =~ s/no/NO/g;
$text->set($line);

Methods

new
$text = new Text::Buffer(%options);

This creates a new object, starting with an empty buffer unless the -file or -array options are provided. The available attributes are:

file FILE

File to open and read into the buffer. The file will read immediatly and is closed after reading, as it is read completly into the buffer. Be sure to have enough free memory available when opening large files.

array \@ARRAY

The contents of array will by copied into the buffer. Creates the buff This specifies one or more prompts to scan for. For a single prompt, the value may be a scalar; for more, or for matching of regular expressions, it should be an array reference. For example,

array => \@test
array => ['first line','second line']

# TODO Handling of line endings can be altered with the autoNewLine option.

load
	$text = new Text::Buffer(file => "/tmp/foo.txt")
    $text->load();
    $text->load("/tmp/bar.txt");

Load the specified file (first argument or the one during new with -file option) into the buffer, which is cleared before loading.

save
	$text = new Text::Buffer(file => "/tmp/foo.txt")
	# ... do some modifications here ...
    $text->save();
    $text->save("/tmp/bar.txt");

Load the specified file (first argument or the one during new with -file option) into the buffer, which is cleared before loading

goto
$text->goto(5);
$text->goto("+2");

Sets the current line to edit in the buffer. Returns undef if the requested line is out of range. When supplying a numeric value (matching [0-1]+) the line is set to that absolut position. The prefixes + and - denote a relative target line. The strings "top" or "start" and "bottom" or "end" are used for jumping to the start or end of the buffer. The first line of the buffer is 1, not zero.

next
$text->next();
$text->next(2);

Accepts the same options as goto, which is performed with the option provided and the new line is returned. In array context returns all lines from the current to the new line (expect the current line). Undef is returned if the position is out of range.

previous

Same as next, but in the other editing direction (to start of buffer).

get
    my $line = $text->get();

Get the current line from the buffer.

set
    $text->set("Replace with this text");

Replace the current line in the buffer with the supplied text.

insert
$text->insert("top of the flops");

Adds the string to the top of the buffer.

append

Same as insert, but adds the string at the end of the buffer.

delete
$text->delete();
my $nextline = $this->delete();

Deletes the current editing line and gets the next line (which will have the same line number as the deleted now).

find
my $linenum = $text->find("/regex/");

Search for the supplied string/regex in the buffer (starting at top of buffer). Even if 2 matches are found in the same line, find always returns the next found line and 0 if no more lines are found.

# TODO Implement search wrapping

findNext
my $linenum = $text->findNext();

Repeats the search on the next line, search to the end of the buffer.

findNext
my $linenum = $text->findPreviou();

Repeats the search on the previos line, searching to the top of the buffer.

BUGS

There definitly are some, if you find some, If the command to be run does not exist (or not in the current execution path), it's quite possible that the new method will not throw an exception. It's up to the caller to make sure that the command will run! There's no known workaround for this.

LICENSE

This software is released under the same terms as perl itself. You may find a copy of the GPL and the Artistic license at

http://www.fsf.org/copyleft/gpl.html
http://www.perl.com/pub/a/language/misc/Artistic.html

AUTHOR

Roland Lammel (lammel@cpan.org)