Preferences - Textadept

# Textadept

- Home |
- Download |
- Lua API |
- Source |
- Language Modules |
- Stats |
- Wiki |
- Mailing List

# Preferences

At this point it is assumed you are at least familiar with the basics of Lua. You do not have to know a lot of the language to configure Textadept.

## User Init

Textadept executes a ~/.textadept/init.lua, your user-init file, on startup. If this file does not exist, Textadept creates it for you. You can use the file to indicate what you want Textadept to do when the application starts, such as loading additional modules. However, you are not restricted to just loading modules. You can run any Lua code you desire.

## Modules

It is never recommended to modify the default modules that come with Textadept, even if you just want to change an option in a generic module, modify the buffer settings for a language-specific module, edit file types, or add a small bit of custom code. Those changes may be overwritten when you upgrade Textadept to a newer version. Instead you have two options: load your own module instead of the default one, or run your custom module code after the default module loads. To load your own module, simply place it appropriately in ~/.textadept/modules/. To run your module code after a default generic module loads, put your code in ~/.textadept/init.lua. To run your module code after a default language-specific module loads, create a post_init.lua Lua script in the appropriate ~/.textadept/modules/ module folder. These methods are discussed below.

### Generic

Many of Textadept’s generic modules have settings you can change from ~/.textadept/init.lua after the module is loaded. These settings are viewed from module’s LuaDoc. For example, to disable character autopairing with typeover and stripping whitespace on save, your ~/.textadept/init.lua might look like:

    _M.textadept.editing.AUTOPAIR = false
    _M.textadept.editing.TYPEOVER_CHARS = false
    _M.textadept.editing.STRIP_WHITESPACE_ON_SAVE = false

Now suppose you wanted to load all of Textadept’s default modules except for the menu. Copy the `textadept` module’s init.lua (located in the modules/textadept/ directory) to ~/.textadept/modules/textadept/ and change

    M.menu = require 'textadept.menu'

to

    --M.menu = require 'textadept.menu'

Now when Textadept looks for modules/textadept/init.lua, it will load yours instead of its own, and load everything but the menu. If instead you wanted to completely change the menu structure, you would first create a new menu.lua and then put it in ~/.textadept/modules/textadept/. Textadept will now load your menu.lua instead of its own.

### Language-Specific

Similar to generic modules, putting your own language-specific module in ~/.textadept/modules/ causes Textadept to load that module for editing the language’s code instead of the default one in modules/ (if the latter exists). For example, copying the default Lua language-specific module from modules/lua/ to ~/.textadept/modules/ causes Textadept to use that module for editing Lua code instead of the default one. If you make custom changes to these kinds of copies of language-specific modules, you will likely want to update them with each new Textadept release. Instead of potentially wasting time merging your changes, you can run custom code independent of a module in the module’s post_init.lua file. For example, instead of copying the `lua` module and creating an `events.LANGUAGE_MODULE_LOADED` event handler to use tabs, you can do this from ~/.textadept/modules/lua/post_init.lua:

    events.connect(events.LANGUAGE_MODULE_LOADED, function(lang)
      if lang == 'lua' then buffer.use_tabs = true end
    end)

Similarly, you can use post_init.lua to change the module’s compile and run commands, load more Adeptsense tags, and add additional key bindings and snippets (instead of in ~/.textadept/init.lua). For example:

    _M.textadept.run.run_command.lua = 'lua5.2'
    _M.lua.sense:load_ctags('/path/to/my/projects/tags')
    keys.lua['c\n'] = function()
      buffer:line_end() buffer:add_text('end') buffer:new_line()
    end
    snippets.lua['ver'] = '%<_VERSION>'

### Loading Modules

Suppose you created or downloaded a generic module called `foo` that you wanted to load along with the default modules Your ~/.textadept/init.lua would contain the following:

    _M.foo = require 'foo'

Language-specific modules are loaded automatically by Textadept when a source file of that language is opened. No additional action is required after installing the module.

### Key Bindings

For simple changes to key bindings, ~/.textadept/init.lua is a good place to put them. For example, maybe you want `Ctrl+Shift+C` to create a new buffer instead of `Ctrl+N`:

    keys.cC = new_buffer
    keys.cn = nil

If you plan on redefining most key bindings, you would probably want to copy or create a new keys.lua and then put it in ~/.textadept/modules/textadept/. You can learn more about key bindings and how to define them in the key bindings LuaDoc.

### Snippets

You can add global snippets in ~/.textadept/init.lua, such as:

    snippets['file'] = '%<buffer.filename>'
    snippets['path'] = "%<(buffer.filename or ''):match('^.+[/\\]')>"

So typing `file` or `path` and then pressing `Tab` (`⇥` on Mac OSX | `Tab` in curses) will insert the snippet, regardless of the current programming language. You can learn about snippet syntax in the snippets LuaDoc.

## Locale

Textadept attempts to auto-detect your locale settings using the “$LANG” environment variable. If it is unsuccessful, the English locale is used by default. To set the locale manually, copy the desired locale file from the core/locales/ folder to ~/.textadept/locale.conf. If your language is not yet supported by Textadept, please translate the English messages in core/locale.conf to your language and send the modified locale.conf file to me. I will include it in a future release.

## File Types

Textadept recognizes a wide range of programming language files by any of the following:

- File extension.
- Keywords in the file’s shebang (“#!/path/to/exe”) line.
- A pattern that matches the text of the file’s first line.

Built-in file types are located in modules/textadept/mime_types.conf. You can override or add to them in your ~/.textadept/mime_types.conf:

    % Recognize .luadoc files as Lua code.
    luadoc lua

    % Change .html files to be recognized as XML files.
    html xml

### Detect by Extension

The syntax for mapping a file extension to a lexer is:

    file_ext lexer

Note: `file_ext` should not start with a ‘.’ (period).

### Detect by Shebang

The syntax for mapping a word contained in a shebang line (the first line of a file whose first two characters are “#!”) to a lexer is:

    #shebang_word lexer

Examples of `shebang_word`s are “lua”, “ruby”, “python” which match lines like “#!/usr/bin/lua”, “#!/usr/env/ruby”, and “#!/usr/bin/python3”, respectively.

### Detect by Pattern

The syntax for mapping a Lua pattern that matches the first line of a file to a lexer is:

    /pattern lexer

Lua pattern syntax is used. Only the last space, the one separating the pattern from the lexer, is significant. No spaces in the pattern need to be escaped.