7 Jul 2009 Pistos   » (Journeyer)

Diakonos - version 0.8.11

Version 0.8.11 of Diakonos is now available.

This release brings a handful of minor feature enhancements and fixes, but the most important addition is the new extension system.

Diakonos Extensions

Diakonos has been scriptable for many versions now, but with this release I have baked in an official system and structure for extensions. Diakonos dances to the same tune as Ruby, insofar as it exposes pretty much the entire core to any enterprising developer who wants to add new features. Later on, I’ll describe some of the ways a programmer might extend Diakonos, but first, let’s take a look at the Hello World extension that comes with the Diakonos tarball.

The Anatomy of an Extension

Every extension must have an info.yaml file. This YAML file contains lots of information about the extension. Here are the contents of the info.yaml file of the Hello World extension:

name: Hello World
description: An example of a Diakonos extension
author:
    name: Pistos
    email: somebody@example.com
    uri: http://blog.purepistos.net
version: 1.0.0
uris:
    homepage: http://github.com/Pistos/diakonos/tree/master/extensions/dk-hello-world
    repository: git://github.com/Pistos/diakonos.git
licence: MIT
requirements:
    diakonos:
        minimum: 0.8.11
        tested:
            - 0.8.11
    gems:
        # - gemname:
            # minimum: 1.0.0
            # tested:
                # - 1.0.0
                # - 1.1.0
notes: >
    This extension adds a hello_world function to Diakonos.
 
    Pressing Shift-F11 will activate the function.

I think the file contents and format are self-explanatory. The only thing to keep in mind is that the requirements key is required. All other items are optional. The fields are all fully described in Diakonos’ built-in help.

Besides the info.yaml file, an extension can have one or more .conf and .rb files. The .conf files are of the same format as normal Diakonos configuration files. The Ruby (.rb) files are where all the code of the extension is placed.

Here is the code of the Hello World extension:

module Diakonos
  module Functions
    def hello_world
      @current_buffer.paste "Hello, world!"
    end
  end
end

In it, a new function, hello_world, is defined. Obviously, it pastes “Hello, world!” into the current buffer (at the current cursor position).

The Hello World conf file has just this line:

key f23   hello_world

So, once the Hello World extension is loaded, you can press Shift-F11, and you’ll receive the well-known greeting.

Managing Extensions

Extensions are simply self-contained directories of files, and so can be packaged into tarballs, made into git repositories, or whatever strikes your fancy.

To install an extension, just copy or unpack (or even symlink) its directory under ~/.diakonos/extensions/. For example, ~/.diakonos/extensions/dk-hello-world/.

To activate an extension, use the load_extension directive in your Diakonos configuration. For example:

load_extension dk-hello-world

You can see what extensions are loaded and active with the new About page, accessible with default hotkey F11. Any extensions that failed to load will also be listed.

What Extensions Can Do

An extension might do any number of things, like:

  • provide a new language definition
  • set up an alternative key mapping
  • provide an alternative shared or default colour scheme
  • share a user’s personal configuration settings
  • add new functions to Diakonos, and map them to keys
  • provide new status line variables
  • install code to run on Diakonos hooks

The range of possibilities is very broad. I have begun filling out source code documentation for Diakonos. I hope to add more and more documentation with each release. The current docs can be accessed at http://purepistos.net/diakonos/rdoc/. As of this writing, it’s quite incomplete, but at least the classes and methods are enumerated. Since this documentation is sparse, don’t be afraid to dive right into the source code. Although I am continually refactoring, and some [very] old code is still hanging around, I think most of the codebase is readable and understandable. Also, of course, you can always come and ask questions in our IRC channel if you need help with writing extensions, or using Diakonos in general.

Example Extensions

A few extensions have already been made to help exemplify the new extension system. Check out their source to learn more about extending Diakonos.

  • Hello World - A minimal example extension
  • git - A git extension
  • Selector - An extension for CSS/XPath selecting on the current HTML/XML buffer
  • Comment Toggle - Smart (un)commenting for Diakonos

Release Changelog

Here is the detailed changelog for this release:

  • Added join_lines_upward (Alt-Shift-J).
  • Added one-key selection in buffer list.
  • Added support for single line indentation.
  • Added extension system.
  • Added surround_selection and related functions.
  • Added “about” page.
  • Various bug fixes and refactorings.

Report any bugs here, or come visit me in IRC!

Share/Save/Bookmark

Related posts:

  1. Diakonos - version 0.8.8
  2. Diakonos - version 0.8.6
  3. Diakonos - version 0.8.7

Syndicated 2009-07-07 10:18:31 from Catholicism Computes

Latest blog entries     Older blog entries

New Advogato Features

New HTML Parser: The long-awaited libxml2 based HTML parser code is live. It needs further work but already handles most markup better than the original parser.

Keep up with the latest Advogato features by reading the Advogato status blog.

If you're a C programmer with some spare time, take a look at the mod_virgule project page and help us with one of the tasks on the ToDo list!