Get Pallavi

What is Pallavi?

Pallavi is an extremely versatile and extensible text editor written in Python using the wxPython toolkit. The primary focus is to keep the core very small and streamlined, while providing an extensible plugin mechanism and widely varied set of plugins to allow the system to be used for anything anything from a simple Notepad replacement to a full-fledged integrated development environment for development in any language.

The process behind this goal is to place the editor's design in the user's hands. You shouldn't have to load a bunch of features you don't need just to edit a small amount of text or some source code. On the other hand you shouldn't have to give up those features you love just because they are typically only supported in the biggest and most bloated tools. You should be able to pick your tools.

The idea is that a community of plugin developers will grow around Pallavi. These users will be able to create, share, adapt, and improve Pallavi plugins so that an infinite variety of editors can be created from this simple core. If you would be interested in developing plugins or working on the Pallavi core, please don't hesitate to contact the mailing list.

Bug reports and feature requests are handled through the project page on Sourceforge. Screenshots are also distributed using Sourceforge's screenshot manager.

Status Getting Using Developing Support This Project

Features & Status

The current stable release is Pallavi 0.5. The current beta release is Pallavi 0.6 beta 3. It runs well under Linux and Windows, but has not yet been tested on the Macintosh platform.

Pallavi is now a fully featured text editor, ready for use by interested developers or end users. There is also core support for IDE style features to be added as plugins, but few of these have been written yet.

Pallavi currently supports, the following features and then some:

Further testing and bug reports will be very much appreciated, especially on the non-free operating systems. Additional contributions are also welcome, including code, feature ideas, graphics and icons, website suggestions, documentation, etc.

Top

Obtaining & Running Pallavi

Depending on your interests, you can choose to download the latest release or to install the development version from subversion. If you want a stable editor, go with the latest release. If you're looking for the latest features, check out subversion and see what you think. The subversion repositiory is usually left quite stable, but this isn't always the case. Development is happening in fits and spurts, but major changes tend to stabilize rapidly.

Dependencies

Before installing Pallavi, you need to install Python and WXPython. Use your Linux distribution's package manager to install these, or if you use Windows you can grab installers from the source sites linked above. WXPython also depends on several other projects, so check their Prerequisites page to make sure you have everything you need. As of Pallavi 0.5, Pallavi requires at least wxPython 2.8. Earlier releases of Pallavi should work with older wxPython installations.

Download Current Release

The latest beta is version 0.6b3, released on November 21, 2007. It can be downloaded from the Sourceforge Project Page.

There are currently four packages available, including two source packages (tar.gz and zip files), a debian package installer, and a Windows installer for both Python 2.4 and 2.5.

Installing from Source

To install a source package, you can extract the archive with tar zxf Pallavi-0.6b3.tar.gz or unzip Pallavi-0.6b3.zip, or use your favourite archive manager. Then cd into the directory. You can run Pallavi from that directory with the command ./run-pallavi. Alternatively, you can install the editor using the command python setup.py install as root or Administrator. This will install the modules and script and allows the editor to be run from your PATH using the command run-pallavi.

Installing on Debian-based systems

Debian/Ubuntu users can download the package from the Project Page. The package can be installed using your OS's graphical package manager or using the command dpkg -i pallavi-0.6b3-1-i386.deb. This will add the runpallavi command to your PATH and you can create a desktop shortcut or menu item for it.

Installing on Windows systems

Windows users can download the installer from the Project Page. Install by double clicking the icon and running the setup wizard. Once installed, you can double click the C:\Python2.5\Scripts\run-pallavi.pyw script to run Pallavi. You can create a shortcut to this file on your Desktop or in your Start Menu.

Installing under Arch Linux

Arch Linux users can visit the Arch User Repository to download the PKGBUILD for Pallavi and install with the command makepkg. Alternatively, if you use an AUR scraper program such as Aurbuild, you can download and install with aurbuild -s pallavi. This package now includes a .desktop file, so it should automatically be added to your desktop environment's menu. Alternatively, you can use the command pallavi on your path from the command line.

Install Development Release

The development system is distributed via Sourceforge's Subversion Server. Run the following command to check out the sources:

svn co https://pallavi.svn.sourceforge.net/svnroot/pallavi/core/trunk pallavi

This will check out the core code and default plugins into a directory called pallavi. You can then cd into that directory and run the editor with the command ./run-pallavi.

You can also check out the non-default set of plugins available for Pallavi using this command:

svn co https://pallavi.svn.sourceforge.net/svnroot/pallavi/plugins pallavi-plugins

Copy any interesting plugins into your $HOME/.pallavi/plugins directory and enable them by editing $HOME/.pallavi/pallavi_config.py.

If you wish to do configuration development, you can use the development configuration file by running pallavi with the command ./runpallavi -c config

Updating Pallavi

Pallavi is currently in a state of rapid change. If you update to a new version or a copy of the development version, you may have to remove your $HOME/.pallavi directory to allow the latest configuration to be repropagated. Alternatively, you can compare $HOME/.pallavi/pallavi_config.py to the new configuration file, stored in the config/ directory on source releases and subversion checkouts, and installed to (usually) /usr/share/pallavi or C:\Python25\share\pallavi with installed versions. If you want to have parallel configurations, you can pass the location of an alternative configuration directory on the command line using: run-pallavi -c path/to/config.

Top

Using Pallavi

Mostly, Pallavi responds much like any editor, by default -- this behaviour can be changed by adapting or creating plugins. You can split the view by dragging the buffer tabs to the left, right, or bottom of the screen. Docked windows can be moved by dragging them to other docks or over an open area to leave them floating. It is not possible to drag dock windows between multiple open views, but if you invoke the toggleDockWindow action on a specific window (the action can be bound to a key), it will attach the docked window to the currently docked window. For example, by default, CTRL-F is bound to displaying the Incremental Find and Replace dialog; if you press that key combination when the dialog is hidden it will be popped up in the current frame. If it is currently attached to a different frame, it will be moved to the current frame.

Most default keybindings are as you would expect for any text editor, as is mouse interaction. Several keybindings are bound to plugin actions, and these are also set to normally accepted defaults. You can read the default pallavi_config.py configuration file to determine what plugins are enabled and what keybinding actions are bound.

Pallavi can be configured to behave in radically different ways by modifying existing plugins or installing new ones. For example, there is no toolbar by default, but it can be turned on to change the interface. Or if you prefer vim-style modal editing, you could create a replacement keybinding plugin to make it happen.

Configuring Pallavi

Pallavi is designed to be extremely extensible and highly configurable. A configuration file is required to tell Pallavi how you would like it to be set up. It seems a natural way to configure a text editor is by using a text configuration file. Of course, it would be possible to create a plugin for GUI configuration instead, but the default is to simply edit this configuration file. Happily, a default config is created if you do not have one. This file is well commented, and describes most of the features you can currently configure in Pallavi. Run Pallavi once to generate the file $HOME/.pallavi/pallavi_config.py (or C:\Documents and Settings\yourname\Application Data\pallavi\pallavi_config), and then open this file (in Pallavi, of course!) to edit and understand it. This file utilizes Python syntax, which is relatively easy to read, even if you aren't familiar with the language.

As of Pallavi 0.6, there are a few additional configuration files in the Pallavi share directory (typically /usr/share/pallavi under Linux and C:\Python2x\share\pallavi under Windows.) These files can be used as starting points if you wish to build a minimal editor, a Python IDE, or a default text editor.

Most of the core plugins and some of the external plugins are described in the default pallavi_config.py file. You may also find additional documentation in the developer API. External plugins, especially if they are developed by third-party developers may require additional setup to be enabled. For example, if the plugin supplies actions that need to be bound to a key, the keybinding will need to be added to the configuration file. Conventionally, the setup and configuration instructions for a plugin are included in docstrings at the top of the plugin's module. This will tell you what actions can be bound to keybindings, menus, or other events, and also if there are any configuration options for that plugin. Naturally, if you are writing your own plugins for distribution, it is good practice to follow this convention.

Currently, any time pallavi_config.py is altered, you will have to restart the editor to see the changes.

Extending Pallavi

Pallavi can be extended by writing a macro or a plugin in Python. A Pallavi Plugin is a simple python module that has a setup() function with no arguments. Before the setup method is called, several variables are set in the module, including:

pallavi
A top-level configuration object containing convenience methods and views
pallavi.views
A list of available top-level windows
pallavi.focusedView
The currently focused top-level window
eventBus
A simple message passing system to allow plugins to communicate in a decoupled manner
actions
A list of actions that can be invoked by any plugin
pluginManager
The plugin manager that manages all installed plugins and allows execution of code
config
The configuration module for Pallavi. This may contain plugin-specific configuration instructions

A plugin can do essentially anything (for example, play a game of pacman!). The general idea, however, is for code in the setup() method to register event listeners with the eventBus, register Actions with the actions list, or both. It can then respond to events and spawn actions that perform some change on the views' buffers and their contents. The Pallavi API has been extensively documented.. Also, take a look at the source code of existing plugns (its surprisingly short and easy to read) to get a feel for what each variable does and how it can be accessed (modelling your plugin on an existing plugin is a great start.)

Since most plugins will want to somehow manipulate the current textview, you will probably want to know how to get a reference to this. This is accessed through the View class. You can access the currently focused textview via the pallavi.focusedView.focusedTextView object. This is a StyledTextControl that can be manipulated in many text-editing ways.

Many plugins will want to utilize Pallavi's built-in window docking functionality. This can be done easily by creating a wx.Panel in your setup() method and adding it to the managed windows by calling view.AddDockPane(panel, caption) The caption is used to identify the window in configuration (users can use the caption to specify where they want the window docked, and also to bind a keybinding to display the window if it is hidden or attached to a different view), and also as a label on the floating or docked window created for the panel. Docked windows can be dragged anywhere on the current view, hidden, or left floating.

It will be helpfulif new plugin developers follow the practice of documenting all the actions, events, and docking windows that a plugin provides and utilizes in a docstring at the top of the module (see exsiting plugins for formatting options). Actions and events are meant to be the only way plugins communicate with each other. This is important, as it allows a plugin to be replaced with a completely different plugin that provides the same set of actions or responds to the same set of events, but possibly in a very different way. Thus, for example, a more robust statusbar might be provided, or a replacement I/O plugin that takes care of Subversion or FTP access could be written.

Creating New Lexers (Syntax Modes)

Lexer configurations are very simple Python files that are stored either in the global share directory (typically /usr/share/pallavi/lexing_languages) or in the user-specific configuration directory ($HOME/.pallavi/lexing_languages). The easiest way to create a new lexing configuration is to adapt an existing lexing file. The short introduction below will tell you how to create a lexer for css from the existing HTML lexer. (Note: Since Pallavi 0.4, the css lexer is included with Pallavi)

  1. Enable the Lexing plugin in the default_plugins section of $HOME/.pallavi/pallavi_config.py if it has not already been enabled.
  2. Create the directory $HOME/.pallavi/lexing_languages/.
  3. Copy the HTML lexer (or a lexer related to the one you are creating) from /usr/share/pallavi/lexing_languages/html.py to $HOME/.pallavi/lexing_languages/css.py replacing css.py with an id for the language you are creating a lexer for.

    If you simply want to modify the lexing behaviour of an existing lexer, you can copy the file without renaming it, or even create a new file. Any variables not set in the home directory version of a lexer will be taken from the global version. This way, you can, for example, adjust the extensions of a lexer without touching the keywords (see below). This will become more important in future versions when indenting, soft tabs or code folding options are supported on a per-language basis.

  4. Open the new file and edit the variables for the new language:
    Extensions
    A list of filename extensions to be associated with that file type so the lexer can be automatically loaded when the file is loaded
    Shebangs
    A list of keywords to be searcched for in the first line of a file assuming the line begins with #!. These are useful under Linux for identifying interpretted files that lack an extension, such as bash, python, and perl scripts. This list can be empty (use []) if it is not an executable language.
    Lexer
    A string keyword identifying what kind of lexing backend should be used. It should be taken from this list, though I think the list is outdated and more lexers have been added since that document was written.
    Folding
    A folding plugin has not yet been implemented, so this option is redundant.
    Keywords
    a string of keywords associated with the language. Most languages have their keyword lists posted on the Internet. You can also 'borrow' keyword lists from SciTE's sources, as wxSTC and SciTE both use Scintilla as their underlying editor component.
    As of Pallavi 0.6, other arbitrary mode-specific variables can be associated with each lexer, for use by external plugins. For example a line-comment character can be associated with a lexer to allow the ProgrammerActions plugin to comment out selected lines.
  5. Restart Pallavi, and open a file that uses your new syntax

If you develop new lexers for popular languages, it would be great if you contributed them for inclusion in future Pallavi releases.

Top

Developing Pallavi

There is a folder under Subversion for contributed non-core plugins. If you would like to start and maintain a plugin project, feel free to request subversion access. If your plugin becomes so useful it seems likely it will be used by almost all users of Pallavi, it well eventually be distributed with the core plugins.

If you would like to develop on the core, feel free to edit it and submit concise patches. It won't take many decent ones before you're given subversion access. Naturally, please stick to the coding style used in th code, and its a good idea to contact me with your ideas before committing to a lot of work, mostly in case somebody else is already working on it.

Top