1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
# 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.
[Lua]: http://www.lua.org
## 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. At first,
it simply loads a module that contains most of Textadept's functionality.
However, you are not restricted to just loading modules. You can run any Lua
code you desire. It is important to realize that Textadept will not load
anything you do not tell it to. If your *~/.textadept/init.lua* exists and is
empty, no modules are loaded (pretty much rendering Textadept useless).
## 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 = require 'textadept'
_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.
[LuaDoc]: api/index.html
### 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 changing its `set_buffer_properties()` function to use tabs, you can do this
from *~/.textadept/modules/lua/post_init.lua*:
function _M.lua.set_buffer_properties()
buffer.use_tabs = true
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](#Key.Bindings) and [snippets](#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>'
[compile and run]: 07_Modules.html#Compile.and.Run
[Adeptsense tags]: api/_M.textadept.adeptsense.html#load_ctags
### 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.textadept = require 'textadept'
_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][].
[key bindings LuaDoc]: api/keys.html
### 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
ncurses) will insert the snippet, regardless of the current programming
language. You can learn about snippet syntax in the [snippets LuaDoc][].
[snippets LuaDoc]: api/_M.textadept.snippets.html
## 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.
[me]: README.html#Contact
## 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.
[Lua pattern syntax]: 14_Appendix.html#Lua.Patterns
|
