http://invisible-island.net/vile/perl/


vile-perl-api -- Vile/Perl interface reference


NAME

vile-perl-api -- Vile/Perl interface reference


DESCRIPTION

This document describes the interface by which by Perl scripts may access the vile editor's internals when run from an editor in which Perl has been embedded.

There are presently two packages which comprise this interface. They are:

Vile

Subroutines for accessing and controlling vile in general.

Vile::Buffer

Subroutines and methods for accessing individual buffers.

Vile::Window

Subroutines and methods for manipulating Vile's windows.

Calling Perl from Vile

The perl interpreter may be invoked from vile using either the perl or perldo commands.

:perl STMTS

The perl command will cause perl to execute one or more perl statements. The user is usually prompted for the statments to execute immediately after ":perl " is entered. The user is expected to enter legal perl statements or expressions. These statements must all fit on one line. (Vile's :-line will scroll horizontally though, so don't worry about running out of space.)

The perl command may also appear in macros in vile's internal macro language, in which case the perl statements to execute must appear as a double quoted string to the perl command. The user is not prompted in this case.

Regardless, prior to execution, the global variable, $Vile::current_buffer is set to an object of type Vile::Buffer which represents the current buffer. The statements to be executed may choose to act either directly or indirectly on the current buffer via this variable or a suitable alias.

Normally, the cursor's current position, also referred to as dot, is left unchanged upon return from perl. It can be propagated back to a viewable window by explicitly setting via the Vile::Buffer::dot method.

For purposes of reading from the buffer, there is always a region associated with the buffer object. By default, this region is the entire buffer. (Which means that potentially, the entire buffer may be acted upon.) This range may be restricted by the user in the normal way through the use of a range specification which precedes the perl command. E.g,

    30,40perl @l = <$Vile::current_buffer>

will cause lines 30 thru 40 to be placed into the @l array.

:perldo STMTS <Enter> OPTIONS

The perldo command is like the perl command, but it takes various options making it possible to write "one liners" to operate on the current buffer in much the same way that you might write a one line perl command at the prompt of your favorite shell to operate on a file. The options even mimic those provided by the perl interpreter, so if you are familiar with one, you'll be familiar with the other.

After entering the perldo command (preceded by an optional range specification) on the :-line, the user will be prompted for some perl statements to execute. These should usually be written to operate on the $_ variable and leave the result in $_.

After pressing the Enter key, you'll be prompted for a set of options. The default options are -lpi and will even be displayed as such. The -i switch causes the buffer to be edited in place. The -p switch causes the user supplied statements to be placed in a loop which fetches lines one by one place them in $_ for each iteration of the loop along with a trailing print which'll cause whatever's left in $_ to be put back into the buffer. The -l switch causes an initial chomp to be done on each line after it is read. It will also cause the output record separator to be set so that when $_ is written back to the buffer, it will end up on a line of its own.

For example, the command:

    :25,30perldo $_ = sprintf("%4d",$lnum++) . $_
                 -lpi

will cause each line in between 20 and 30 inclusive to be prefixed with a the number given by $lnum, which is also incremented for each line processed. You'll probably want to initialize $lnum to some appropriate value via the perl command first, perhaps like this:

    :perl $lnum = 142;

[I include this example, because this is something that I've wanted to do from time to time, when citing snippets of code which I want to discuss in an email message.]

perldo options

-n

Enclose the perl statement(s) in a loop which iterates of the records (usually lines) of the region. Each record in the region will be placed in $_.

-p

Like -n, but do a print (of $_) at the end of the loop.

-i

Enable the inplace_edit flag for the buffer. When used with either -n or -p, this will cause the lines to be deleted from the buffer as they are read.

Unlike the corresponding perl command line switch, it is not possible to specify a backup file. If you don't like what happens, just hit the 'u' key to undo it.

-l

Only meaningful when used with either -n or -p. This will perform an initial chomp on $_ after a record has been read.

-0

This must be followed by one or more digits which represent the value with which to set $/ (which is the input record separator). The special value 00 indicates that $/ should be set to the empty string which will cause Perl to slurp input in paragraph mode. The special value 0777 indicates that perl should slurp the entire region without paying attention to record separators. Normally, $/ is set to '\n' which corresponds to -012

-a

Turn on autosplit mode. Upon being read, each record is split into the @F array.

-F

When used with -a, specify an alternate pattern to split on.

The default region for the perldo command is the line on which the cursor is currently on. The reason for this is that it is often used like vile's builtin substitute operator is and this is the default region for the substitute command. You can of course use any of the standard means to operate over larger regions, e.g,

    :1,$perldo s/a/b/g

Loading Perl Modules from Vile

A perl module that is usable by vile should probably be located some place on the @INC path. For vile, the @INC array has been augmented to include $HOME/.vile/perl and /usr/local/share/vile. (This latter path may differ depending upon your machine and configuration options.) If you want to see what exactly what these paths are, just issue the following command from within vile:

    :perl print join ':', @INC[0,1]

Let us suppose that the following script is stored in $HOME/.vile/perl/number_lines.pl.

    sub number_lines {
        my ($lnum, $width) = @_;
        $lnum = 1 unless defined($lnum);
        $width = 4 unless defined($width);
        $Vile::current_buffer->inplace_edit(1);
        while (<$Vile::current_buffer>) {
            print $Vile::current_buffer
                  ' ' x ($width - length($lnum) - 1),
                  $lnum, ' ', $_;
            $lnum++;
        }
    }
    1;

Note the trailing "1;" at the end. The reason for this is so that true is returned as the result of the script. If things are not done this way, the loading mechansim might flag an error. (All it needs to do is return a true value somehow.)

Assuming the above code has been placed in the file 'number_lines.pl', the following vile command may be used to load it:

        :perl require 'number_lines.pl'

When writing a new script, I will often test it in the same editor session that I've created the script in. My script may have a bug in it and I'll fix it. In order to reload the script, you can do the following:

        :perl do 'number_lines.pl'

Perl's builtin 'require' function wouldn't have worked to reload the file because it keeps track of files that have been loaded via this facility and refuses to load a file twice. The 'do' function on the other hand is a more general facility for executing the contents of a file and doesn't care how often it's called.

Caveat: Sometimes it's better to start with a clean slate, particularly if you've renamed your subroutines or if there are global variables involved. Just start a fresh copy of vile and start over.

Now to invoke our number_lines program, we do it as follows:

        :perl number_lines(1)

It is also possible to use vile's builtin macro language to load perl modules and call them. The hgrep.pl module comes with the vile distribution. You may want to put the following line in your .vilerc file:

perl "use hgrep"

See also the Vile::register functions.

Package Vile

The Vile package contains subroutines and methods of a general nature. They range from providing an interface to vile's modes to providing facilities for obtaining user input.

Package Vile Subroutines and Methods

Warn

Print a warning message

beep

Rings terminal bell (or equivalent).

buffers

Returns a list of the editor's buffers.

command CMDLINE

executes the given vile command line (as if it were typed on the : line).

This is not exactly safe in all contexts. (It is easy to cause seg faults.) If you need access to some portion of vile that would lead you to want to use this subroutine, let me know and I will work on suitable facilities.

keystroke
keystroke WAITVAL

Returns a single, fairly raw keystroke from the keyboard.

The optional WAITVAL indicates if the editor should wait for the next keystroke. When WAITVAL is false, undef will be returned if no input is ready.

mlreply PROMPT
mlreply PROMPT, INITIALVALUE

Prompts the user with the given prompt and (optional) supplied initial value. Certain characters that the user may input have special meanings to mlreply and may have to be escaped by the user to be input. If this is unacceptable, use mlreply_no_opts instead.

Returns the user's response string. If the user aborts (via the use of the escape key) the query, an undef is returned.

mlreply_no_opts PROMPT
mlreply_no_opts PROMPT, INITIALVALUE

Prompts the user with the given prompt and (optional) supplied initial value. All printable characters may be entered by the user without any special escapes.

Returns the user's response string. If the user aborts (via the use of the escape key) the query, an undef is returned.

mlreply_shell PROMPT
mlreply_shell PROMPT, INITIALVALUE

Like mlreply, but provide completions suitable for fetching shell commands.

mlreply_dir PROMPT
mlreply_dir PROMPT, INITIALVALUE

Prompts the user for a directory name with the given prompt and (optional) initial value. Filename completion (via the TAB key, if enabled) may be used to assist in entering the directory name.

Returns the user's response string. If the user aborts (via the use of the escape key) the query, an undef is returned.

mlreply_file PROMPT
mlreply_file PROMPT, INITIALVALUE

Prompts the user for a filename with the given prompt and (optional) initial value. Filename completion (via the TAB key, if enabled) may be used to assist in entering the filename.

Returns the user's response string. If the user aborts (via the use of the escape key) the query, an undef is returned.

selection_buffer
selection_buffer BUFOBJ
Vile::Buffer::set_selection BUFOBJ

Gets or sets the buffer associated with the current selection.

When getting the selection, the buffer object that has the current selection is returned and its region is set to be the same region as is occupied by the selection. If there is no current selection, undef is returned.

When setting the selection, a buffer object must be passed in. The editor's selection is set to the region associated with the buffer object. If successful, the buffer object is returned; otherwise undef will be returned.

Examples:

$sel = Vile->selection_buffer->fetch; # Put the current selection in $sel

    Vile->selection_buffer($Vile::current_buffer);
                                    # Set the selection to the region
                                    # contained in the current buffer

Vile::Buffer::set_selection is an alias for Vile::selection_buffer, but can only function as a setter. It may be used like this:

    Vile->current_buffer->set_region('w')->set_selection;
                                    # set the selection to be the word
                                    # starting at the current position
                                    # in the current buffer
    Vile->current_buffer->motion('?\/\*' . "\n")
                        ->set_region('%')
                        ->set_selection();
                                    # set the selection to be the nearest
                                    # C-style comment above or at the
                                    # current position.
set PAIRLIST
get LIST
Vile::Buffer::set BUFOBJ PAIRLIST
Vile::Buffer::get BUFOBJ LIST

Provides access to Vile's various modes, buffer and otherwise.

For the set methods, PAIRLIST should be a list of key => value pairs, where key is a mode name and value is an appropriate value for that mode. When used in an array context, the resulting key => value pairs are returned. (The value may be a different, but equivalent string than originally specified.) When used in a scalar context, either the package name or buffer object is returned (depending on how it was invoked) in order that the result may be used as the target of further method calls.

When one of the get forms is used, a list of modes should be supplied. When used in an array context, a list of key => value pairs is returned. When used in a scalar context, only one mode name may be supplied and the value associated with this mode is returned.

The methods in Vile::Buffer attempt to get the local modes associated with the buffer (falling back to the global ones if no specific local mode has been specified up to this point).

Note: Access to certain internal attributes such as the buffer name and file name are not provided via this mechanism yet. There is no good reason for this other than that vile does not provide access to these attributes via its set command.

update

Update the editor's display. It is usually not necessary to call this if you're returning to the editor in fairly short order. It will be necessary to call this, for example, if you write an input loop in perl which writes things to some on-screen buffers, but does not return to the editor immediately.

working
working VAL

Returns value 1 if working message will be printed during substantial pauses, 0 if disabled.

When passed an argument, modifies value of the working message.

register NAME, [SUB, HELP, REQUIRE]

Register a subroutine SUB as Vile function NAME. Once registered, the subroutine may then be invoked as a named command and bound to keystrokes.

SUB may be given either as a string to eval, or a reference to a subroutine. If omitted, SUB defaults to NAME.

HELP provides a description of the subroutine for the [Binding List] functions.

An optional file to require may be given.

Example:

    Vile::register grep => 'hgrep', 'recursive grep', 'hgrep.pl';

or

    require 'hgrep.pl';
    Vile::register grep => \&hgrep, 'recursive grep';

also

    sub foo { print "foo" }
    Vile::register 'foo';
    Vile::register bar => 'print "bar"';
    Vile::register quux => sub { print "quux" };
register_motion NAME, [SUB, HELP, REQUIRE]
register_oper NAME, [SUB, HELP, REQUIRE]

These synonyms for Vile::register allow perl subroutines to behave as motions and operators. For example, these subroutines behave like their builtin counterparts:

    *cb = \$Vile::current_buffer;
    Vile::register_motion 'my-forward-line-at-bol' => sub {
        $cb->dot((scalar $cb->dot) + 1, 0);
    };
    Vile::register_oper 'my-delete-til' => sub { $cb->delete };
watchfd FD, WATCHTYPE, CALLBACK

Adds a callback so that when the file descriptor FD is available for a particular type of I/O activity (specified by WATCHTYPE), the callback associated with CALLBACK is called.

WATCHTYPE must be one of 'read', 'write', or 'except' and have the obvious meanings.

The callback should either be a string representing a vile command to execute (good luck) or (more usefully) a Perl subroutine reference.

unwatchfd FD

Removes the callback associated with FD and frees up the associated data structures.

Package Vile::Buffer

The Vile::Buffer package contains methods for creating new buffers and for accessing already existing buffers in various ways.

A Vile::Buffer object may be viewed as a filehandle. Therefore, the usual sorts of methods for reading from and writing to filehandles will work as expected.

Example:

A word count program that you might invoke from your favorite shell could be written as follows:

    #!/usr/local/bin/perl -w
    my $words;
    while (<>) {
        $words += split;
    }
    print "$words words\n";

A programmer accustomed to the above, will find Vile's perl interface to be a comfortable one. Here is the above script modified slightly to count the words in the current buffer:

    sub wc {
        my $words;
        while (<$Vile::current_buffer>) {
            $words+=split;
        }
        print "$words words";
    }

Package Vile::Buffer Methods

<BUFOBJ>

When used in a scalar context, returns the next line or portion of thereof in the current region.

When used in an array context, returns the rest of the lines (or portions thereof) in the current region.

The current region is either set with set_region or set by default for you when perl is invoked from vile. This region will either be the region that the user specified or the whole buffer if not user specified. Unless you know for sure that the region is set properly, it is probably best to set it explicitly.

After a line is read, DOT is left at the next location in the buffer at which to start reading. Note, however, that the value of DOT (which a convenient name for the current position in the buffer) is not propogated back to any of the users windows unless it has been explicitly set by calling dot (the method).

When the inplace_edit flag has been set via the inplace_edit method, text that is retrieved from the buffer is deleted immediately after retrieval.

Examples:

    # Example 1: Put all lines of the current buffer into
    #            an array
    $Vile::current_buffer->set_region(1,'$$');
                                    # Set the region to be the
                                    # entire buffer.
    my @lines = <$Vile::current_buffer>;
                                    # Fetch all lines and put them
                                    # in the @lines array.
    print $lines[$#lines/2] if @lines;
                                    # Print the middle line to
                                    # the status line
    # Example 2: Selectively delete lines from a buffer
    my $curbuf = $Vile::current_buffer;
                                    # get an easier to type handle
                                    # for the current buffer
    $curbuf->inplace_edit(1);       # set the inplace_edit flag
                                    # so that lines will be deleted
                                    # as they are read
    while (<$curbuf>) {             # fetch line into $_
        unless (/MUST\s+DELETE/) {  # see if we should keep the line
            print $curbuf $_;       # put it back if we should keep it
        }
    }
attribute BUFOBJ LIST

Attach an attributed region to the region associated with BUFOBJ with the attributes found in LIST.

These attributes may be any of the following:

    'color' => NUM          (where NUM is the color number
                             from 0 to 15)
    'underline'
    'bold'
    'reverse'
    'italic'
    'hyper' => HYPERCMD     (where HYPERCMD is a string
                            representing a vile command to
                            execute.  It may also be a
                            (perl) subroutine reference.
    'normal'

Normal is a special case. It will override any other arguments passed in and remove all attributes associated with the region.

attribute_cntl_a_sequences BUFOBJ

Causes the editor to attach attributes to the <Ctrl>A sequences found in the buffer for the current region (which may be set via set_region).

Returns the buffer object.

buffername BUFOBJ

Returns the buffer name associated with BUFOBJ.

buffername BUFOBJ BUFNAME

Sets the buffer name associated with BUFOBJ to the string given by BUFNAME. This string must be unique. If the name given is already being used by another buffer, or if it's malformed in some way, undef will be returned. Otherwise the name of the buffer will be returned.

Note: The name of the buffer returned may be different than that passed in due some adjustments that may be done on the buffer name. (It will be trimmed of spaces and a length limit is imposed.)

filename BUFOBJ

Returns the file name associated with BUFOBJ.

filename BUFOBJ FILENAME

Sets the name of the file associated with BUFOBJ to the string given by FILENAME.

command BUFOBJ CMDLINE

Executes the given vile command line (as if it were typed on the : line) with BUFOBJ as the current buffer.

Returns BUFOBJ if successful, otherwise returns undef.

current_buffer
current_buffer BUFOBJ
current_buffer PKGNAME
current_buffer BUFOBJ NEWBUFOBJ
current_buffer PKGNAME NEWBUFOBJ

Returns the current buffer. When first entering perl from a vile session, the current buffer is the one that the user is actively editing. Several buffers may be on the screen at once, but only one of them is current. The current one will be the one in which the cursor appears.

This method may also be used to set the current buffer. When used in the form

    $oldbuf->current_buffer($newbuf)

then $newbuf will replace $oldbuf in one of the visible windows. (This only makes sense when $oldbuf was visible in some window on the screen. If it wasn't visible, it'll just replace whatever buffer was last both current and visible.)

When used as a setter, the current buffer is still returned. In this case it will be the new buffer object which becomes the current buffer.

Note also that the current_buffer method is in both the Vile package and the Vile::Buffer package. I couldn't decide which package it should be in so I put it into both. It seemed like a real hassle to have to say

    my $curbuf = Vile::Buffer->current_buffer

So instead, you can just say

    my $curbuf = Vile->current_buffer;

current_buffer is also a variable, so you can also do it this way:

    my $curbuf = $Vile::current_buffer;

If you want $main::curbuf (or some other variable) to be an alias to the current buffer, you can do it like this:

    *main::curbuf = \$Vile::current_buffer;

Put this in some bit of initialization code and then you'll never have to call the current_buffer method at all.

One more point, since $Vile::current_buffer is magical, the alias above will be magical too, so you'll be able to do

    $curbuf = $newbuf;

in order to set the buffer. (Yeah, this looks obvious, but realize that doing the assignment actually causes some vile specific code to run which will cause $newbuf to become the new current buffer upon return.)

delete BUFOBJ

Deletes the currently set region.

Returns the buffer object if all went well, undef otherwise.

dot BUFOBJ
dot BUFOBJ LINENUM
dot BUFOBJ LINENUM, OFFSET

Returns the current value of dot (which represents the the current position in the buffer). When used in a scalar context, returns the line number of dot. When used in an array context, returns the line number and position within the line.

When supplied with one argument, the line number, dot is set to the beginning of that line. When supplied with two arguments, both the line number and offset components are set.

Either the line number or offset (or both) may be the special string '$' which represents the last line in the buffer and the last character on a line.

Often times, however, the special string '$$' will be more useful. It truly represents the farthest that it possible to go in both the vertical and horizontal directions. As a line number, this represents the line beyond the last line of the buffer. Characters inserted at this point will form a new line. As an offset, '$$' refers to the newline character at the end of a line. Characters inserted at this point will be inserted before the newline character.

Examples:

    my $cb = $Vile::current_buffer; # Provide a convenient handle
                                    # for the current buffer.
    $linenum = $cb->dot;            # Fetch the line number at which dot
                                    # is located.
    $cb->dot($cb->dot+1);           # Advance dot by one line
    $cb->dot($cb->dot('$') - 1);
                                    # Set dot to the penultimate line of
                                    # the buffer.
    $cb->dot(25, 6);                # Set dot to line 25, character 6
    ($ln,$off) = $cb->dot;          # Fetch the current position
    $cb->dot($ln+1,$off-1);         # and advance one line, but
                                    # back one character.
    $cb->inplace_edit(1);
    $cb->set_region(scalar($cb->dot), $cb->dot+5);
    @lines = <$cb>;
    $cb->dot($cb->dot - 1);
    print $cb @lines;
                                    # The above block takes (at
                                    # most) six lines starting at
                                    # the line DOT is on and moves
                                    # them before the previous
                                    # line.

Note: current_position is an alias for dot.

dotq BUFOBJ
dotq BUFOBJ LINENUM
dotq BUFOBJ LINENUM, OFFSET

Like dot except that it's "quiet" in its operation in the sense that it doesn't attempt to propagate the API's concept of where the current position is back to the editor when control is returned.

This could be useful in situations where you want your Perl script to quietly add some text to a buffer without disturbing any of the user's windows into that buffer.

fetch BUFOBJ

Returns the current region or remainder thereof. The same effect could be achieved by setting $/ to undef and then evaluating the buffer object between angle brackets.

Example:

    $word = $Vile::current_buffer->set_region('w')->fetch;
                            # Fetch the next word and put it in $word
inplace_edit BUFOBJ
inplace_edit BUFOBJ VALUE

Sets the value of the "inplace edit" flag (either true of false). Returns the old value. When used without an argument, merely returns current value without modifying the current value.

This flag determines whether a line is deleted after being read. E.g,

    my $curbuf = $Vile::current_buffer;
    $curbuf->inplace_edit(1);
    while (<$curbuf>) {
        s/foo/bar/g;
        print;
    }

The <$curbuf> operation will cause one line to be read and deleted. DOT will be left at the beginning of the next line. The print statment will cause $_ to get inserted prior the the next line.

Setting this flag to true is very similar to setting the $INPLACE_EDIT flag (or $^I) for normal filehandles or using the -i switch from the command line.

Setting it to false (which is its default value) will cause the lines that are read to be left alone.

motion BUFOBJ MOTIONSTR

Moves dot (the current position) by the given MOTIONSTR in BUFOBJ.

When used in an array context, returns a 4-tuple containing the beginning and ending positions. This 4-tuple is suitable for passing to set_region.

When used in a scalar context, returns the buffer object that it was called with.

In either an array or scalar context, if the motion string was bad, and undef is returned. Motions that don't work are okay, such as 'h' when you're already at the left edge of a line. But attempted "motions" like 'inewstring' will result in an error.

Example:

    # The following code deletes the previous 2 words and then
    # positions the cursor at the next occurrence of the word
    # "foo".
    my $cb = $Vile::current_buffer;
    $cb->set_region($cb->motion("2b"))->delete;
                    # delete the previous two words
    $cb->set_region("2b")->delete;
                    # another way to delete the previous
                    # two words
    $cb->motion("/foo/");
                    # position DOT at the beginning of
                    # "foo".
    $cb->dot($cb->dot);
                    # Make sure DOT gets propogated back.
                    # (It won't get propogated unless
                    # explicitly set.)
new BUFOBJ
new PKGNAME
new BUFOBJ FILENAME
new PKGNAME FILENAME
edit BUFOBJ
edit PKGNAME
edit BUFOBJ FILENAME
edit PKGNAME FILENAME

These methods create a new buffer and return it.

When no filename is supplied, an anonymous buffer is created. These buffer's will be named [unnamed-1], [unnamed-2], etc. and will not have a file name associated with them.

When a name is supplied as an argument to new or edit, a check is made to see if the name is the same as an already existing buffer. If so, that buffer is returned. Otherwise, the name is taken to be a file name. If the file exists, it is opened and read into the newly created buffer. If the file does not exist, a new buffer will be created with the associated file name. The name of the buffer will be based on the file name. The file will be created when the buffer is first written out to disk.

new and edit are synonyms. In each case, PKGNAME is Vile::Buffer. There is no difference between Vile::Buffer->new($fname) and $buf->new($fname). These two different forms are merely provided for convenience.

Example:

    $Vile::current_buffer = new Vile::Buffer 'makefile';
                                    # open makefile and make it visible
                                    # on the screen.
    $abuf = new Vile::Buffer;       # Create an anonymous buffer
    print $abuf "Hello";            # put something in it
    Vile->current_buffer($abuf);    # make the anonymous buffer current
                                    #   (viewable).
    Vile->current_buffer($abuf->edit('makefile'));
                                    # Now makefile is the current
                                    #   buffer
    $abuf->current_buffer(Vile::Buffer->new('makefile'));
                                    # Same thing
print BUFOBJ STR1,..,STRN
insert BUFOBJ STR1,...,STRN

Inserts one or more strings the buffer object at the current position of DOT. DOT will be left at the end of the strings just inserted.

When STDERR or STDOUT are printed to, the output will be directed to the message line.

Examples:

    print "Hello, world!";          # Print a well known greeting on
                                    # the message line.
    print $Vile::current_buffer "new text";
                                    # put some new text in the current
                                    # buffer.
    my $passbuf = new Vile::Buffer '/etc/passwd';
                                    # Fetch the password file
    $passbuf->dot('$$');            # Set the position at the end
    print $passbuf "joeuser::1000:100:Joe User:/home/joeuser:/bin/bash
                                    # Add 'joeuser' to the this buffer
    Vile->current_buffer($passbuf); # Make it visible to the user.
set_region BUFOBJ
set_region BUFOBJ MOTIONSTR
set_region BUFOBJ STARTLINE, ENDLINE
set_region BUFOBJ STARTLINE, STARTOFFSET, ENDLINE, ENDOFFSET
set_region BUFOBJ STARTLINE, STARTOFFSET, ENDLINE, ENDOFFSET, 'rectangle'
set_region BUFOBJ STARTLINE, STARTOFFSET, ENDLINE, ENDOFFSET, 'exact'

Sets the region upon which certain other methods will operate and sets DOT to the beginning of the region.

Either the line number or offset (or both) may be the special string '$' which represents the last line in the buffer and the last character on a line.

Often times, however, the special string '$$' will be more useful. It truly represents the farthest that it possible to go in both the vertical and horizontal directions. As a line number, this represents the line beyond the last line of the buffer. Characters inserted at this point will form a new line. As an offset, '$$' refers to the newline character at the end of a line. Characters inserted at this point will be inserted before the newline character.

When used in an array context, returns a five element array with the start line, start offset, end line, end offset, and a string indicating the type of region (one of 'line', 'rectangle', or 'exact').

When used in a scalar context, returns the buffer object so that cascading method calls may be performed, i.e,

    $Vile::current_buffer->set_region(3,4)
                         ->attribute_cntl_a_sequences;

There is a special form of set_region which may be used as follows:

    $Vile::current_buffer->set_region('j2w');

The above statement will set the region beginning at the current location of DOT and ending at the location arrived at by moving down one line and over two words. This may be viewed as a shorthand way of expressing the following (somewhat cumbersome) statement:

    $Vile::current_buffer->set_region(
            $Vile::current_buffer->motion('j2w'));

Notes:

unmark

Clear the "modified" status of the buffer.

Returns the buffer object.

Package Vile::Window

The Vile::Window package contains methods for manipulating windows in various ways. For the purposes of this discussion, a window is one of the areas of the screen in which a portion of a buffer may be viewed by the user.

This API allows you to do the following things to one of these windows:

In the documentation below, WINOBJ refers to an object of Vile::Window and BUFOBJ refers to an object of Vile::Buffer.

Package Vile::Window Methods

buffer WINOBJ

Returns the buffer associated with WINOBJ.

E.g,

    $buf = Vile::current_window->buffer

would get you the buffer associated with the current window.

buffer WINOBJ BUFOBJ

Sets the buffer associated with WINOBJ to BUFOBJ. Returns BUFOBJ.

current_window

Returns the Vile::Window object representing the current window.

Note: This method is also in the Vile:: package.

current_window WINOBJ

Sets the current window (window with focus) to WINOBJ; Returns WINOBJ.

Note: You'd say

    $curwin = Vile::current_window;

to retrieve the current window and

    $mywin->current_window;

to set it.

delete WINOBJ

Removes the window in question. Screen real estate allocated to the window will be returned to the window from whence it came.

Returns 1 if successful, undef otherwise.

dot WINOBJ
current_position WINOBJ

Retrieves DOT (the current position) for the current window. In a scalar context, only the line number is returned. In an array context, a list containing both the line number and offset within the line are returned.

dot WINOBJ LINENUM, OFFSET
current_position WINOBJ LINENUM, OFFSET

Sets DOT (the current position) to the indicated values.

When used in a scalar context, returns the line number. When used in a list context, returns both the line number and the offset with in the line.

Note: dot and current_position are aliases for each other. Neither provides any additional functionality over the other.

index WINOBJ

Returns the index of WINOBJ. This will be a small integer, with 0 representing the first (top-most) window, 1 representing the window below it, and so on.

new Vile::Window

Allocates and returns a new window. The editor will choose where the window will be located. (It will likely choose a large window to split.) If a new window could not be allocated, return undef.

new Vile::Window BUFOBJ

Like above, but associate BUFOBJ with the new window.

new WINOBJ

Allocate and return a new window, using WINOBJ as the window to split. If this cannot be done, return undef. If the split is possible, the new window returned will be located below WINOBJ.

new WINOBJ BUFOBJ

Like above, but associate BUFOBJ with the new window.

size WINOBJ

In a scalar context, return the height of a window. In a list context, return both the height and width.

size WINOBJ HEIGHT

Set the height of a window. It will attempt to change a windows size by either adding or stealing lines from the window below. (This means that the bottommost window can't be directly changed since it doesn't have a window below it.)

Returns the new size of the window.

size WINOBJ HEIGHT WIDTH

Unimplemented. It is not possible to change the width at the moment, but if the feature ever becomes available, this method will do it.

topline WINOBJ

Returns the line number of the top line in the window.

window_at N

Returns the Nth (starting at 0 from the top-most window) Vile::Window object. If there is no Nth window, undef is returned instead.

Note: This method also appears in the Vile:: package.

window_count

Returns number of (visible) windows.

Note: Non-visible windows are used to represent buffers for the perl API. They are also used for other purposes in which modification of a buffer is desired, but disturbing the position of the buffer within one of its windows is not.

Note: This method also appears in the Vile:: package.