/ 
Text-Editor-Vip-0.08.1
River stage zero No dependents
/ Text::Editor::Vip::Buffer

NAME

Text::Editor::Vip::Buffer - Editing engine

SYNOPSIS

use Text::Editor::Vip::Buffer ;
my $buffer = new Text::Editor::Vip::Buffer() ;

DESCRIPTION

This module implements the core functionality for an editing engine. It knows about selection, undo and plugins.

MEMBER FUNCTIONS

new

Create a Text::Editor::Vip::Buffer .

my $buffer = new Text::Editor::Vip::Buffer() ;

Setup

Helper sub called by new. This is considerer private.

Reset

Empties the buffer from it's contents as if it was newly created. Plugins are still plugged into the buffer. This is very practical when writting tests.

$buffer->Reset() ;

ExpandedWithOrLoad

See PLUGINS.

If the name passed as first argument doesn't match a sub within the object, the module, passed as second argument, is loaded.

# newly created buffer that is missing a functionality
$buffer->SomeSub(); # perl dies

# load plugin first
$buffer->LoadAndExpandWith('Text::Editor::Vip::Buffer::Plugins::SomePlugin') ;
$buffer->SomeSub(); # ok

# load the plugin only if the sub is available. This doesn't guarantee that 'SomeSub' has been
# loaded from the passed Plugin.

$buffer->ExpandedWithOrLoad('SomeSub', 'Text::Editor::Vip::Buffer::Plugins::SomePlugin') ;
$buffer->SomeSub(); #ok

Returns 1 if the sub existed and 0 if it didn't and the module was loaded or the error type LoadAndExpandWith generated.

LoadAndExpandWith

See PLUGINS.

Loads a perl module (plugin) and adds all it functionality to the buffer

$buffer->LoadAndExpandWith('Text::Editor::Vip::Plugins::Buffer::File') ;

# we can now read files
$buffer->InsertFile(__FILE__) ;

ExpandWith

See PLUGINS.

Adds a sub to a buffer instance.

  $buffer->ExpandWith
		(
		  'GotoBufferStart' # member function name
		, \&some_sub    # implementaton for GotoBufferStart
		) ;
  
  # we can now go  to the buffers start
  $buffer->GotoBufferStart() ;

The second argument is optional, if it is not given, Text::Editor::Vip::Buffer will take the sub from the caller namespace

sub GotoBufferStart
{
my $buffer = shift ; # remember we are a plugin to an object oriented module
$buffer->SetModificationPosition,(0, 0) ;
}

$buffer->ExpandWith( 'GotoBufferStart') ;
$buffer->GotoBufferStart() ;

DEV. WARNING! This is going to give us troubles when using it for macros that are saved to disk! we must find a way to replug when loading the macro back

PrintExpansionHistory

Displays the expansion done to the buffer

Do

Let you run any perl code on the buffer. The variable $buffer is made available in your perl code.

($result, $message) = $buffer->Do("# comment\n\$buffer->Insert('bar') ;") ;
is($buffer->GetText(), "bar", 'buffer contains \'bar\'' ) ;

Returns (1) on success and (0, "error message") on failure.

PrintError

This sub is called when an error occures. It should be overriden by the buffer user. We use this sub to abstract error handling and allow different handling dependind on the buffer user.

If the user is a plain perl script, the error might just be logged while a dialogue might be displayed if the user is a full UI.

GetText

Returns the buffer contents joined with "\n".

See GetTextAsArrayRef.

GetTextAsArrayRef

Returns a copy of the buffers content as an array reference.

See GetText.

SetLineAttribute

Attaches a named attribute to a line.

$buffer->SetLineAttribute(0, 'TEST', $some_data) ;
$retrieved_data = $buffer->GetLineAttribute(0'TEST', $some_data) ;

SetLineAttribute

Retrieves a named attribute from a line.

$buffer->SetLineAttribute(0, 'TEST', $some_data) ;
$retrieved_data = $buffer->GetLineAttribute(0, 'TEST') ;

MarkedBufferAsEdited

Used to mak the buffer as edited after a modification. You should not need to use this function if you access the buffer through it's interface. Which you should always do.

MarkedBufferAsUndited

Used to mak the buffer as unedited You should not need to use this function.

IsBufferMarkedAsEdited

Used to query the buffer about its state. Returns (1) if the buffer was edit. (0) otherwise.

GetLastEditionTImestamp

Returns the time of the last edition.

GetNumberOfLines

Returns the number of lines in the buffer.

GetLastfLineIndex

Returns theindex of the last line. the buffer always contains at least one line thus the last line index is always 0 or more.

GetModificationPosition

Returns the position, line and character, where the next modification will occure.

SetModificationPosition

Sets the position, line and character, where the next modification will occure.

$buffer->SetModificationPosition(0, 15) ;

OffsetModificationPosition

Offset the position, line and character, where the next modification will occure. an exception is thrown if position is not valid

$buffer->OffsetModificationPosition(0, 15) ;

OffsetModificationPositionGuarded

Offsets the position, line and character, where the next modification will occure. Nothing happends if the new position is invalid

$buffer->OffsetModificationPositionGuarded(0, 15) ;

GetModificationLine

Returns the line where the next modification will occure.

SetModificationLine

Set the line where the next modification will occure.

GetModificationLine

Returns the character where the next modification will occure.

GetModificationLine

Sets the character where the next modification will occure.

GetLine

Returns the Line object used by the buffer. This is a private sub and should not be used directly.

See GetLineText.

GetLineText

Returns the text of the line passes as argument or the current modification line if no argument is passed.

my $line_12_text = $buffer->GetLineText(12) ;
my $current_line_text = $buffer->GetLineText() ;

GetLineTextWithNewline

Returns the text of the line passes as argument or the current modification line if no argument is passed. A "\n" is appended if the line is not the last line in the buffer.

my $line_12_text = $buffer->GetLineTextWithNewline(12) ;
my $current_line_text = $buffer->GetLineTextWithNewline() ;

GetLineLength

Returns the length of the text of the line passes as argument or the current modification line if no argument is passed.

my $line_12_text = $buffer->GetLineText(12) ;
my $current_line_text = $buffer->GetLineText() ;

Backspace

Deletes characters backwards. The number of characters to delete is passed as an argument. Doing a Backspace while at the begining of a line warps to the previous line.

ClearLine

Removes all text from the passed line index or the current modification line if no argument is given. The line itself is not deleted and the modification position is not modified.

$buffer->ClearLine(0) ;

Delete

Deleted, from the modification position, the number of characters passed as argument.

Deletes the selection if it exists; the deleted selection decrements the number of character to delete argument

DeleteLine

Deleted, the line passed as argument. if no argument is passed, the current line is deleted. The selection and modification position are not modified.

InsertNewLine

Inserts a new line at the modification position. If the modification position is after the end of the current line, spaces are used to pad the current line.

InsertNewLine takes one parameter that can be set to SMART_INDENTATION or NO_SMART_INDENTATION. If SMART_INDENTATION is used (default) , IndentNewLine is called. IndentNewLine does nothing by default. This lets you define your own indentation strategy. See IndentNewLine.

$buffer->Insert("hi\nThere\nWhats\nYour\nName\n") ;

Stringify

Quotes a string or an array of string so it can be serialized in perl code

Insert

Inserts a string or a list of strings, passed as an array reference, into the buffer.

$buffer->Insert("bar") ;

my @text = ("Someone\n", "wants me\nNow") ;
$buffer->Insert(\@text);

$buffer->Insert("\t something \n new") ;

Only "\n" is considered special and forces the addition of a new line in the buffer.

Insert takes a second argument . When set to SMART_INDENTATION (the default), IndentNewLine is called to indent the newly inserted line. The default IndentNewLine does nothing but you can override it to implement any indentation you please. If you want to insert raw text, pass NO_SMART_INDENTATION as a second argument.

NO_SMART_INDENTATION is defined in Text::Editor::Vip::Buffer::Constants.

PLUGINS

Vip::Buffer has a very simple plugin system. You can add a function to the buffer with ExpandWith, LoadAndExpandWith and ExpandedWithOrLoad. The functions added through plugins are made available to the instance, calling the plugin sub, only.

Think of it as a late inheritence that does the job it needs to do.

Perl is full of wonders.

BUGS

AUTHOR

Khemir Nadim ibn Hamouda
CPAN ID: NKH
mailto:nadim@khemir.net
http:// no web site

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.