The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Text-Modify-0.4
River stage zero No dependents
1 ++
/ 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']
autonewline [unix | mac | windows | SPECIAL]

With this option the automatic appending (and replacement) of line-endings can be altered. E.g. if unix is defined, all lines (upon read) will be altered to end with \n.

setAutoNewline

Set the automatic line-end character(s). See option autonewline for possible values.

getAutoNewline

Get the current newline character(s) set. E.g. return "\n" for type unix.

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 ($string)
    $text->set("Replace with this text");

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

insert ($string)
    $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.

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

Replace the a literal string supplied as the first argument with the string from the second argument. No regex escapes are required, the string will be used as provided (e.g. dot is a dot). Returns the number of occurences replaced.

The example above replaces any occurence of the string .foo$ with bar.

replaceRegex
        my $count = $text->replaceRegex("foo\s+foo","bar");

Replace the regex supplied as the first argument with the string from the second argument. Returns the number of occurences.

For the replacement string match variables (e.g. $1) can be used for replacement.

The example above replaces any occurence of the string foo foo with bar.

replaceWildcard
        my $count = $text->replaceWildcard("*foo?","bar");

Replace a wildcard string as the first argument with the string from the second argument. Wildcard * (asterisk, meaning match all characters) and ? (questionmark, meaning match one character) will be expanded and the expanded string replaced with the replacement string provided as the second argument. Returns the number of occurences replaced.

The example above replaces any occurence of the string abcfoo2 (as regex /^.*?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, ...)

setModified

Manually set the buffer to be modified, which will force the next save, even if no changes have been performed on the buffer.

isEmpty

Returns 1 if the buffer is currently empty.

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

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.

convertStringToRegex
        $text->convertStringToRegex("No * have ?");
        Text::Modify->convertStringToRegex("a brace (is a brace)?");

Helper function to convert a string into a regular expression matching the same string (espacing chars). The regex string returned matches the strings as provided.

This function can be called as a class method too.

convertWildcardToRegex
        $text->convertWildcardToRegex("we need ?? beers");
        Text::Modify->convertWildcardToRegex("foo? or more *bar");

Helper function to convert a wildcard string into a regular expression matching the wildcard (having whitespace as a word boundary).

This function can be called as a class method too.

escapeRegexString
        Text::Modify->escapeRegexString();

Helper function to escape regex special chars and treat them as normal characters for matchin.

This function can be called as a class method too.

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