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.

replace

my $count = $text->replace("foo","bar");

Replace the string/regex supplied as the first argument with the string from the second argument. Returns the number of occurences. The example above replaces any occurence of the string foo with bar.

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).

clear

$text->clear();

Resets the buffer to be empty. No save is performed.

getLineCount

Returns the number of lines in the buffer. Returns 0 if buffer is empty.

getLineNumber

Returns the current line position in the buffer (always starting at 1).

isModified

Returns 1 if the buffer has been modified, by using any of the editing methods (replace, set, insert, append, ...)

isEmpty

Returns 1 if the buffer is currently empty.

isEOF =item isEndOfBuffer

while (!$text->isEndOfBuffer()) { $text->next(); }

Returns 1 if the current position is at the end of file.

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.

findPrevious

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

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

isError =item getError

if ($text->isError()) { print "Error: " . $text->getError() . "\n"; }

Simple error handling routines. isError returns 1 if an internal error has been raised. getError returns the textual error.

dumpAsString

print $text->dumpAsString();

Returns (dumps) the whole buffer as a string. Can be used to directly write to a file or postprocess manually.

BUGS

There definitly are some, if you find some, please report them, by contacting the author.

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)