A Textadept Module

A story of love

I have guided you with the abilities of Textadept. First we spoke of the simplicity of making Textadept visually pleasing. Then, I opened your mind to the level of lazy you can reach with snippets, which by the way is getting a nice overhaul by yours truly. Finally, you have received some tips and tricks on making a whole language lexer on the beast. Now, we are going to the fourth article of the TTGT series. Here is where the real dragons and unicorns of Textadept reside; Modules.

So what are modules on Textadept? Modules are what Textadept uses to make plug-ins. Simple enough, but they are so much more. You can extend Textadept abilities to the point of it becoming and entirely different existence from whence you ventured. You come from a vim background(like all of the chosen ones)? Then you must get a little wonder called textadept-vi, by the glorious Chris Emerson. What if you want some fuzzy search navigation like those old days in Sublime Text? My friend, look no further and install this instant Robert Gieseke’s textredux.

However, modules don’t have to be complete beasts like the two listed above. Say you only want snippets for a language that you often use. You would make a module for that purpose. It doesn’t even have to be complicated at all. You can have one file in that module and call your task accomplished. Same can be said if you want specific configurations for your languages. It’s all done in modules. Textadept’s modules are the do all ability of Textadept for extending what the text editor is capable of. The best part of it all is it’s not difficult at all. All you really need is some basic knowledge of Lua and have a tab with Textadept’s Reference Manual(API) open and ready for help.

Before even starting your module though, you should figure out what you actually want. You don’t want to spend a couple of hours(days) coding up a monstrosity to find out you could’ve been done with a simple search. That means, checking good ol’ github or bitbucket for Textadept modules. Do note, currently there’s in development of a Textadept package manager for modules and etc to ease the help in search of such jewels. However, as of the writing this article, it is not yet published for public use. Until then, we have to use the power known as Google or DuckDuckGo to help us on our path.

Now, if you end up needing to develop a module, here is where the construction gets interesting. The first step you should go about doing is make a directory with the name of your module inside the _USERHOME/modules of your Textadept install. If it’s for a language you don’t have a module already for, then name the module the name of the language. Otherwise, go right ahead and name it whatever you desire.

Afterwards, you will write up an `init.lua` file inside the directory for your module. The init file is how Textadept knows where to look for your module when needed. So go ahead and write up what you want. I do suggest, if you are building something more than just an extension to a language module, build a language module first. You may want to get some practice of how Textadept works and language modules are quite easy to write. Heck, Mitchell even has a glorious guide on how to do so in the API.

But what if you want to only make a function or two to extend what you can do on Textadept and after reading up, you don’t want to write a full module? Here is where the magical “common” module comes to play. With a “common” module, you can go ahead and scratch that itch with very little unicorn discovery or dragon slaying. There are multiple ways of going about making one of these, but I’m going to use the way I enjoy from my own “common” module.

You are going to make a lua file in a “common” module directory. The lua file can be named whatever you want. It will contain the function you want to add to Textadept. Afterwards, you will use the first few lines in my `init.lua` file of the “common” module in your own `init.lua` file of your “common” module:

local lfs = require ‘lfs’
local M = {}
for filename in lfs.dir(_USERHOME..’/modules/common/’) do
  if filename:find(‘%.lua$’) and filename ~= ‘init.lua’ then
    -- using the name of the module as the key. ;)
    local key = filename:match(‘^(.+)%.lua$’)
    M[key] = require(‘common.’..key)
  end
end

These magical lines initialize any Lua file you have contained in the “common” module’s directory for use on Textadept. Instead of having to manually enter each one of those algorithms tricks you mocked up or cool internet unicorns, you can use those lines for the module to do it for you. And since I doubt you are going to have a Google database of algorithms stored on your “common” module, the overhead is quite minimal.

Anyway, the rest of the same init file should contain whatever requirement you may need for those functions you wanted to work on textadept. Take the example of my own init file linked above for more help on getting those tasks working.

I hope you have gained a little bit more insight in the wonders of Textadept modules through your reading. The Textadept text editor is only going to get better the more you navigate its mutability.