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!
Related posts: