diff options
Diffstat (limited to 'doc/manual.md')
| -rw-r--r-- | doc/manual.md | 877 |
1 files changed, 0 insertions, 877 deletions
diff --git a/doc/manual.md b/doc/manual.md index bbba4540..2779713d 100644 --- a/doc/manual.md +++ b/doc/manual.md @@ -2111,880 +2111,3 @@ files. As a result, Textadept 11 cannot load session files from 10.x or before. * The command entry no longer recognizes a Lua 5.1-style '`=`' prefix for printing return values. Printing return values has been the default for quite some time. - -### Textadept 9 to 10 - -#### API Changes - -Old API |Change |New API ---------------------------------|:------:|------- -**_G** | | -bit32 |Removed |N/A _(use bitwise operators)_ -**buffer** | | -brace\_match(pos) |Changed |[brace\_match][](pos, 0) -**lexer** | | -\_foldsymbols |Replaced|[add\_fold\_point()][] -\_rules |Replaced|[add\_rule()][] -\_tokenstyles |Replaced|[add\_style()][] -embed\_lexer(parent, child, ...)|Renamed |parent:[embed][](child, ...) -\_RULES\[id\] |Replaced|[get\_rule][](id) -\_RULES\[id\] = rule |Replaced|[modify\_rule][](id, rule) -N/A |Added |[new()][] -word\_match(list, wchars, icase)|Changed |[word\_match][](words, icase) -**ui** | | -set\_theme |Renamed |[buffer.set\_theme()][] -**textadept.editing** | | -match\_brace |Replaced|N/A _(menu function)_ -N/A |Added |paste() -N/A |Added |paste\_reindents -**textadept.session** | | -default\_session |Removed | - -[brace\_match]: api.html#buffer.brace_match -[add\_fold\_point()]: api.html#lexer.add_fold_point -[add\_rule()]: api.html#lexer.add_rule -[add\_style()]: api.html#lexer.add_style -[embed]: api.html#lexer.embed -[get\_rule]: api.html#lexer.get_rule -[modify\_rule]: api.html#lexer.modify_rule -[new()]: api.html#lexer.new -[word\_match]: api.html#lexer.word_match -[buffer.set\_theme()]: api.html#buffer.set_theme - -#### Configuration Changes - -Textadept 10 no longer uses a *~/.textadept/properties.lua* file. Instead, all -`buffer` settings are made in *~/.textadept/init.lua*, and apply to the first -and any subsequent buffers. (In Textadept 9, any `buffer` settings made in -*~/.textadept/init.lua* only applied to the first buffer, so a -*~/.textadept/properties.lua* was required in order to define `buffer` settings -that would affect subsequent buffers.) - -Simply copying the contents of your *~/.textadept/properties.lua* into -*~/.textadept/init.lua* should be sufficient. - -#### Lexer Changes - -Lexers are now written in a more object-oriented way. Legacy lexers are still -supported, but it is recommended that you [migrate them][]. - -[migrate them]: api.html#lexer.Migrating.Legacy.Lexers - -#### Key Bindings Changes - -The terminal version's key sequence for `Ctrl+Space` is now `'c '` instead of -`'c@'`. - -#### Regex Changes - -Textadept now uses [C++11's ECMAScript regex syntax](#Regular.Expressions) -instead of [TRE][]. - -[TRE]: https://github.com/laurikari/tre - -#### Mac OSX System Requirements - -Textadept now requires Mac OSX 10.6 (Snow Leopard) at a minimum. The previous -minimum version was 10.5 (Leopard). - -#### LuaJIT Changes - -The LuaJIT version of Textadept has been removed. Any LuaJIT-specific features -used in external modules will no longer function. - -### Textadept 8 to 9 - -Textadept 9 introduces minor API changes (mostly renames of existing functions -and fields) along with some backwards-incompatible simplifications of key -commands, menu commands, and language module handling. - -#### API Changes - -Old API |Change |New API -----------------------------------|:------:|------- -**events** | | -COMPILE\_OUTPUT lexer, output |Changed |[COMPILE\_OUTPUT][] output, ext/lex -RUN\_OUTPUT lexer, output |Changed |[RUN\_OUTPUT][] output, ext/lexer -BUILD\_OUTPUT project, output |Changed |[BUILD\_OUTPUT][] output -**io** | | -snapopen(...) |Changed |[quick\_open][](paths, filter, opts) -snapopen\_filters |Renamed |[quick\_open\_filters][] -SNAPOPEN\_MAX |Renamed |[quick\_open\_max][] -**lfs** | | -FILTER |Renamed |[default\_filter][] -dir\_foreach() |Changed |[dir\_foreach()][] _(changed args)_ -**ui** | | -SILENT\_PRINT |Renamed |[silent\_print][] -goto\_view(n, relative) |Changed |[goto\_view][](view) -**ui.find** | | -FILTER |Renamed |[find\_in\_files\_filter][] -find\_in\_files(dir) |Changed |[find\_in\_files][](dir, filter) -N/A |Added |find\_in\_files\_timeout -lua |Changed |[regex][] -lua\_pattern\_label\_text |Changed |[regex\_label\_text][] -**view** | | -goto\_buffer(n, relative) |Changed |[goto\_buffer][](buffer) -**textadept.editing** | | -AUTOPAIR |Replaced|[auto\_pairs][] -TYPEOVER\_CHARS |Replaced|[typeover\_chars][] -AUTOINDENT |Renamed |[auto\_indent][] -STRIP\_TRAILING\_SPACES |Renamed |[strip\_trailing\_spaces][] -AUTOCOMPLETE\_ALL |Renamed |[autocomplete\_all\_words][] -char\_matches |Replaced|[auto\_pairs][] -braces |Renamed |[brace\_matches][] -[goto\_line][](line) |Changed |_line argument is 0-based_ -**textadept.run** | | -RUN\_IN\_BACKGROUND |Renamed |[run\_in\_background][] -CHECK\_SYNTAX |Removed | -GOTO\_SYNTAX\_ERRORS |Removed | -cwd |Removed | -proc |Removed | -compile() |Changed |[compile][](filename) -run() |Changed |[run][](filename) -build() |Changed |[build][](root\_directory) -[error\_patterns][] |Changed |_(changed format)_ -syntax\_commands |Removed | -syntax\_error\_patterns |Removed | -**textadept.snippets** | | -N/A |Added |\_paths -**textadept.session** | | -DEFAULT\_SESSION |Renamed |default\_session -SAVE\_ON\_QUIT |Renamed |[save\_on\_quit][] -MAX\_RECENT\_FILES |Renamed |max\_recent\_files - -[COMPILE\_OUTPUT]: api.html#events.COMPILE_OUTPUT -[RUN\_OUTPUT]: api.html#events.RUN_OUTPUT -[BUILD\_OUTPUT]: api.html#events.BUILD_OUTPUT -[quick\_open]: api.html#io.quick_open -[quick\_open\_filters]: api.html#io.quick_open_filters -[quick\_open\_max]: api.html#io.quick_open_max -[default\_filter]: api.html#lfs.default_filter -[dir\_foreach()]: api.html#lfs.dir_foreach -[silent\_print]: api.html#ui.silent_print -[goto\_view]: api.html#ui.goto_view -[find\_in\_files\_filter]: api.html#ui.find.find_in_files_filter -[find\_in\_files]: api.html#ui.find.find_in_files -[regex]: api.html#ui.find.regex -[regex\_label\_text]: api.html#ui.find.regex_label_text -[goto\_buffer]: api.html#view.goto_buffer -[auto\_pairs]: api.html#textadept.editing.auto_pairs -[typeover\_chars]: api.html#textadept.editing.typeover_chars -[auto\_indent]: api.html#textadept.editing.auto_indent -[strip\_trailing\_spaces]: api.html#textadept.editing.strip_trailing_spaces -[autocomplete\_all\_words]: api.html#textadept.editing.autocomplete_all_words -[brace\_matches]: api.html#textadept.editing.brace_matches -[goto\_line]: api.html#textadept.editing.goto_line -[run\_in\_background]: api.html#textadept.run.run_in_background -[compile]: api.html#textadept.run.compile -[run]: api.html#textadept.run.run -[build]: api.html#textadept.run.build -[error\_patterns]: api.html#textadept.run.error_patterns -[save\_on\_quit]: api.html#textadept.session.save_on_quit - -#### Key and Menu Command Changes - -Key commands and menu commands can no longer be tables. Instead they must be Lua -functions. Check your *~/.textadept/init.lua* and custom modules and transform -any applicable key bindings or menu items. For example: - - keys.ca = {func, args} => keys.ca = function() func(args) end - {'Menu Item', {func, args}} => {'Menu Item', function() func(args) end} - -Note: If *`func`* returns `true` or `false`, make sure you use -`function() return func(args) end`. - -Textadept's own *modules/textadept/keys.lua* and *modules/textadept/menu.lua* -have been updated appropriately. - -#### Language Module Handling Changes - -Textadept 9 no longer auto-loads a *post_init.lua* in language modules. Instead, -it must be loaded manually from an `events.LEXER_LOADED` event. For example: - - events.connect(events.LEXER_LOADED, function() - if lang == 'ansi_c' then require('ansi_c.extras') end - end) - -will load a *~/.textadept/modules/ansi_c/extras.lua* "sub-module" for C files. -Keep in mind that Lua's `require()` function will only execute module code once. - -If you have a number of *post_init.lua* files that you want Textadept 9 to make -use of, you can put the following in your *~/.textadept/init.lua*: - - events.connect(events.LEXER_LOADED, function(lexer) - local post_init = string.format( - '%s/modules/%s/post_init.lua', _USERHOME, lexer) - if lfs.attributes(post_init) then require(lexer .. '/post_init') end - end) - -#### Find & Replace Changes - -Find & replace with Lua patterns has been superceded by find & replace with -Regular Expressions (regex). The [Regular Expressions](#Regular.Expressions) -section above covers the regex syntax that Textadept supports. - -### Textadept 7 to 8 - -Textadept 8 upgraded its internal copy of Lua from [5.2 to 5.3][]. Nearly all -user scripts will continue to function properly without modification -- -Textadept itself only needed to update some instances of numeric division to -account for Lua's new integer/float distinction. - -Textadept 8 has no major API changes of note. Instead, the table below lists all -API changes during the 7.x cycle. Please consult this table when upgrading from -your particular version of Textadept 7. - -Textadept 8 did introduce changes in language-specific keybindings and macros -for compile and run commands, which are described in the sections below. - -[5.2 to 5.3]: http://www.lua.org/manual/5.3/manual.html#8 - -#### API Changes - -Old API |Change |New API |Since ----------------------------|:------:|------------------------------------|----- -**_G** | | | -N/A |Added |[spawn()][] |7.2 -N/A |Added |[LINUX][] |7.8 -N/A |Added |[BSD][] |7.8 -**_M** | | | -_lang_.context\_menu |Removed | |7.8 -**_SCINTILLA** | | | -N/A |Added |[next\_image\_type()][] |7.8 -**events** | | | -N/A |Added |[FILE\_OPENED][] |7.1 -N/A |Added |[FOCUS][] |7.5 -N/A |Added |[CSI][] |7.8 -N/A |Added |[SUSPEND][] |7.8 -N/A |Added |[RESUME][] |7.8 -FILE\_SAVED\_AS |Replaced|[FILE\_AFTER\_SAVE][] |7.9 -**io** | | | -set\_buffer\_encoding() |Renamed |[buffer:set\_encoding()] |7.3 -boms |Removed | |7.9 -**lexer** | | | -N/A |Added |[\_FOLDBYINDENTATION][] |8.0 -**lfs** | | | -dir\_foreach(...) |Changed |[dir\_foreach][](..., n, incl\_dirs)|7.6 -**textadept.adeptsense** |Removed | | -complete() |Replaced|editing.[autocomplete()][] |7.3 -show\_apidoc() |Replaced|editing.[show\_documentation()][] |7.3 -**textadept.bookmarks** | | | -toggle(on) |Changed |[toggle][](on, line) |8.0 -**textadept.command_entry**| | | -complete\_lua() |Removed | |7.3 -execute\_lua() |Removed | |7.3 -**textadept.editing** | | | -N/A |Added |AUTOCOMPLETE\_ALL |7.3 -N/A |Added |[autocompleters][] |7.3 -autocomplete\_word() |Replaced|autocomplete('word') |7.3 -HIGHLIGHT\_BRACES |Removed | |7.3 -selecte\_indented\_block() |Removed | |7.3 -**textadept.file_types** | | | -shebangs |Replaced|[patterns][]<sup>a</sup> |7.9 -**textadept.menu** | | | -set\_menubar(menubar) |Replaced|[menubar][] = menubar |7.3 -set\_contextmenu(menu) |Replaced|[context_menu][] = menu |7.3 -set\_tabcontextmenu(menu) |Replaced|[tab_context_menu][] = menu |7.3 -**textadept.run** | | | -N/A |Added |[build()][] |7.2 -N/A |Added |[build_commands][] |7.2 -N/A |Added |[stop()][] |7.2 -N/A |Added |RUN\_IN\_BACKGROUND |8.0 -**ui** | | | -N/A |Added |[tabs][] |7.1 -N/A |Added |SILENT\_PRINT |7.2 -**ui.command_entry** | | | -N/A |Added |[editing\_keys][] |7.8 -enter\_mode(mode) |Changed |enter\_mode(mode, lexer, height) |7.8 -**ui.dialogs** | | | -N/A |Added |[optionselect()][] |7.2 - -<sup>a</sup>`shebangs.lua = 'lua'` converts to `patterns['^#!.+/lua'] = 'lua'` - -[spawn()]: api.html#spawn -[LINUX]: api.html#LINUX -[BSD]: api.html#BSD -[next\_image\_type()]: api.html#_SCINTILLA.next_image_type -[FILE\_OPENED]: api.html#events.FILE_OPENED -[FOCUS]: api.html#events.FOCUS -[CSI]: api.html#events.CSI -[SUSPEND]: api.html#events.SUSPEND -[RESUME]: api.html#events.RESUME -[FILE\_AFTER\_SAVE]: api.html#events.FILE_AFTER_SAVE -[buffer:set\_encoding()]: api.html#buffer.set_encoding -[\_FOLDBYINDENTATION]: api.html#lexer.Fold.by.Indentation -[dir\_foreach]: api.html#lfs.dir_foreach -[autocomplete()]: api.html#textadept.editing.autocomplete -[show\_documentation()]: api.html#textadept.editing.show_documentation -[toggle]: api.html#textadept.bookmarks.toggle -[autocompleters]: api.html#textadept.editing.autocompleters -[patterns]: api.html#textadept.file_types.patterns -[menubar]: api.html#textadept.menu.menubar -[context_menu]: api.html#textadept.menu.context_menu -[tab_context_menu]: api.html#textadept.menu.tab_context_menu -[build()]: api.html#textadept.run.build -[build_commands]: api.html#textadept.run.build_commands -[stop()]: api.html#textadept.run.stop -[tabs]: api.html#ui.tabs -[editing\_keys]: api.html#ui.command_entry.editing_keys -[optionselect()]: api.html#ui.dialogs.optionselect - -#### Language-specific Key Changes - -Textadept 8 removed the `keys.LANGUAGE_MODULE_PREFIX` key binding (which has -been `Ctrl+L` for Win32 and Linux, `⌘L` on Mac OSX, and `M-L` in curses), but -only in name. Textadept 8 does not make use of this key, and it is still -traditionally reserved for use by language-specific modules. You can use as such -from your language module like this: - - keys.lua[not OSX and not CURSES and 'cl' or 'ml'] = { - ... - } - -#### Compile and Run Macro Changes - -Textadept 8 removed the long-hand macros for [compile and run commands][] in -favor or shorthand ones (most of which have been available since 7.1). - -Old Macro |New Macro -------------------|--------- -%(filename) |%f -%(filename\_noext)|%e -%(filedir) |%d -%(filepath) |%p - -Any modules and language-specific modules using the long-hand notation must be -updated. - -[compile and run commands]: api.html#_M.Compile.and.Run - -### Textadept 6 to 7 - -Textadept 7 introduces API changes, a change in module mentality and filename -encodings, and a completely new theme implementation. - -#### API Changes - -Old API |Change |New API -----------------------------------|:------:|------- -**_G** | | -RESETTING |Removed |N/A<sup>a</sup> -buffer\_new() |Renamed |\_G.[buffer.new()][] -**_M.textadept** |Renamed |[textadept][] -filter\_through |Removed |N/A -filter\_through.filter\_through() |Renamed |editing.[filter\_through()][] -mime\_types |Renamed |[file\_types][]<sup>b</sup> -**_M.textadept.bookmark** | | -N/A |New |[goto\_mark()][] -N/A |New |[MARK\_BOOKMARK][] -MARK\_BOOKMARK\_COLOR |Removed |N/A<sup>c</sup> -goto\_bookmark |Replaced|goto\_mark() -goto\_next |Replaced|goto\_mark(true) -goto\_prev |Replaced|goto\_mark(false) -**_M.textadept.editing** | | -N/A |New |[INDIC\_BRACEMATCH][] -N/A |New |[INDIC\_HIGHLIGHT][] -INDIC\_HIGHLIGHT\_BACK |Removed |N/A<sup>d</sup> -autocomplete\_word(chars, default)|Changed |autocomplete\_word(default) -grow\_selection() |Replaced|[select\_enclosed()][] -**_M.textadept.menu** | | -menubar |Removed |N/A -contextmenu |Removed |N/A -**_M.textadept.run** | | -N/A |New |[MARK\_WARNING][] -N/A |New |[MARK\_ERROR][] -MARK\_ERROR\_BACK |Removed |N/A<sup>c</sup> -compile\_command |Renamed |[compile\_commands][] -run\_command |Renamed |[run\_commands][] -error\_detail |Renamed |[error\_patterns][]<sup>e</sup> -**_M.textadept.snapopen** |Removed |N/A -open |Changed |\_G.io.snapopen()<sup>f</sup> -**_SCINTILLA.constants** | | -SC\_\* |Renamed |Removed "SC\_" prefix. -SC(FIND\|MOD\|VS\|WS) |Renamed |Removed "SC" prefix. -**buffer** | | -check\_global() |Removed | -get\_style\_name(buffer, n) |Renamed |style\_name\[n\] -reload() |Renamed |io.reload\_file() -save() |Renamed |io.save\_file() -save\_as() |Renamed |io.save\_file\_as() -close() |Renamed |io.close\_buffer() -set\_encoding() |Renamed |io.set\_buffer\_encoding() -convert\_eo\_ls() |Renamed |[buffer.convert\_eols()][] -dirty |Replaced|[buffer.modify][] -**events** | | -N/A |New |[INITIALIZED][] -handlers |Removed |N/A -**gui** |Renamed |[ui][] -docstatusbar\_text |Renamed |[bufstatusbar\_text][] -N/A |New |[maximized][] -find.goto\_file\_in\_list() |Renamed |find.[goto\_file\_found()][] -select\_theme |Removed |N/A -N/A |New |[dialogs][] -filteredlist |Removed |N/A -set\_theme(name, ...) |Changed |set\_theme(name, table) -**io** | | -try\_encodings |Renamed |[encodings][] -open\_file(string) |Changed |[open\_file][](string or table) -snapopen(string, ...) |Changed |snapopen(string or table, ...) -save\_all() |Renamed |[save\_all\_files()][] -close\_all() |Renamed |[close\_all\_buffers()][] - -<sup>a</sup>`arg` is `nil` when resetting. - -<sup>b</sup>Removed *mime_types.conf* files. Interact with Lua tables directly. - -<sup>c</sup>Set [`buffer.marker_back`][] in [`events.VIEW_NEW`][]. - -<sup>d</sup>Set [`buffer.indic_fore`][] in [`events.VIEW_NEW`][]. - -<sup>e</sup>Changed structure too. - -<sup>f</sup>Changed arguments too. - -[buffer.new()]: api.html#buffer.new -[textadept]: api.html#textadept -[filter\_through()]: api.html#textadept.editing.filter_through -[file\_types]: api.html#textadept.file_types -[goto\_mark()]: api.html#textadept.bookmarks.goto_mark -[MARK\_BOOKMARK]: api.html#textadept.bookmarks.MARK_BOOKMARK -[INDIC\_BRACEMATCH]: api.html#textadept.editing.INDIC_BRACEMATCH -[INDIC\_HIGHLIGHT]: api.html#textadept.editing.INDIC_HIGHLIGHT -[select\_enclosed()]: api.html#textadept.editing.select_enclosed -[MARK\_WARNING]: api.html#textadept.run.MARK_WARNING -[MARK\_ERROR]: api.html#textadept.run.MARK_ERROR -[compile\_commands]: api.html#textadept.run.compile_commands -[run\_commands]: api.html#textadept.run.run_commands -[error\_patterns]: api.html#textadept.run.error_patterns -[buffer.convert\_eols()]: api.html#buffer.convert_eols -[buffer.modify]: api.html#buffer.modify -[INITIALIZED]: api.html#events.INITIALIZED -[ui]: api.html#ui -[bufstatusbar\_text]: api.html#ui.bufstatusbar_text -[maximized]: api.html#ui.maximized -[goto\_file\_found()]: api.html#ui.find.goto_file_found -[dialogs]: api.html#ui.dialogs -[encodings]: api.html#io.encodings -[open\_file]: api.html#io.open_file -[save\_all\_files()]: api.html#io.save_all_files -[close\_all\_buffers()]: api.html#io.close_all_buffers -[`buffer.marker_back`]: api.html#buffer.marker_back -[`events.VIEW_NEW`]: api.html#events.VIEW_NEW -[`buffer.indic_fore`]: api.html#buffer.indic_fore - -#### Module Mentality - -Prior to Textadept 7, the `_M` table held all loaded modules (regardless of -whether they were generic modules or language modules) and Textadept encouraged -users to load custom modules into `_M` even though Lua has no such restriction. -The `_M` prefix no longer makes much sense for generic modules like -[`textadept`][], so only language modules are automatically loaded into -[`_M`][]. Textadept 7 does not encourage any prefix for custom, generic modules; -the user is free to choose. - -[`textadept`]: api.html#textadept -[`_M`]: api.html#_M - -#### Filename Encodings - -Prior to Textadept 7, `buffer.filename` was encoded in UTF-8 and any functions -that accepted filenames (such as `io.open_file()`) required the filenames to -also be encoded in UTF-8. This is no longer the case in Textadept 7. -`buffer.filename` is encoded in `_CHARSET` and any filenames passed to functions -should also remain encoded in `_CHARSET`. No more superfluous encoding -conversions. You should only convert to and from UTF-8 when displaying or -retrieving displayed filenames from buffers and/or dialogs. - -#### Theme Changes - -You can use the following as a reference for converting your Textadept 6 themes -to Textadept 7: - - -- File *theme/lexer.lua* | -- File *theme.lua* - -- Textadept 6 | -- Textadept 7 - local l = lexer | local buffer = buffer - local color = l.color | local prop = buffer.property - local style = l.style | local prop_int = - | buffer.property_int - | - l.colors = { | - ... | ... - red = color('99', '4D', '4D'), | prop['color.red'] = 0x4D4D99 - yellow = color('99', '99', '4D'), | prop['color.yellow'] = 0x4D9999 - ... | ... - } | - | - l.style_nothing = style{} | prop['style.nothing'] = '' - l.style_class = style{ | prop['style.class'] = - fore = l.colors.yellow | 'fore:%(color.yellow)' - } | ... - ... | prop['style.identifier'] = - l.style_identifier = l.style_nothing | '%(style.nothing)' - | - ... | ... - | - | prop['font'] = 'Monospace' - local font, size = 'Monospace', 10 | prop['fontsize'] = 10 - l.style_default = style{ | prop['style.default'] = - font = font, size = size, | 'font:%(font),'.. - fore = l.colors.light_black | 'size:%(fontsize),'.. - back = l.colors.white | 'fore:%(color.light_black),'.. - } | 'back:%(color.white)' - ... | ... - - -- File *theme/view.lua* | -- Same file *theme.lua*! - | - ... | ... - -- Caret and Selection Styles. | -- Caret and Selection Styles. - buffer:set_sel_fore(true, 0x333333) | buffer:set_sel_fore(true, - | prop_int['color.light_black']) - buffer:set_sel_back(true, 0x999999) | buffer:set_sel_back(true, - | prop_int['color.light_grey']) - --buffer.sel_alpha = | --buffer.sel_alpha = - --buffer.sel_eol_filled = true | - buffer.caret_fore = 0x4D4D4D | buffer.caret_fore = - | prop_int['color.grey_black'] - ... | ... - -Notes: - -1. Textadept 7's themes share its Lua state and set lexer colors and styles - through named buffer properties. -2. Convert colors from "RRGGBB" string format to the "0xBBGGRR" number format - that Textadept's API documentation uses consistently. -3. The only property names that matter are the "style._name_" ones. Other - property names are arbitrary. -4. Instead of using variables, which are evaluated immediately, use "%(key)" - notation, which substitutes the value of property "key" at a later point in - time. This means you do not have to define properties before use. You can - also modify existing properties without redefining the properties that depend - on them. See the [creating themes](#Creating.Themes) section for an - example. -5. Set view properties related to colors directly in *theme.lua* now instead of - a separate *view.lua*. You may use color properties defined earlier. Try to - refrain from setting properties like `buffer.sel_eol_filled` which belong in - a *properties.lua* file. -6. The separate *buffer.lua* is gone. Use *properties.lua* or a - [language module](#Language-Specific.Buffer.Settings). - -##### Theme Preference - -Textadept 7 ignores the *~/.textadept/theme* and *~/.textadept/theme_term* files -that specified your preferred Textadept 6 theme. Use *~/.textadept/init.lua* to -[set a preferred theme](#Setting.Themes) instead. For example, if you had custom -GUI and terminal themes: - - -- File *~/.textadept/init.lua* - ui.set_theme(not CURSES and 'custom' or 'custom_term') - -You may still use absolute paths for themes instead of names. - -### Textadept 5 to 6 - -Textadept 6 introduces some API changes. These changes affect themes in -particular, so your themes may require upgrading. - -Old API | Change | New API --------------------------------------|:------:|-------- -**buffer** | | -annotation\_get\_text(line) |Renamed |annotation\_text[line] -annotation\_set\_text(line, text) |Renamed |annotation\_text[line] = text -auto\_c\_get\_current() |Renamed |auto\_c\_current -auto\_c\_get\_current\_text() |Renamed |auto\_c\_current\_text -get\_lexer\_language() |Renamed |lexer\_language -get\_property(key) |Renamed |property[key] -get\_property\_expanded(key) |Renamed |property\_expanded[key] -get\_tag(n) |Renamed |tag[n] -margin\_get\_text(line) |Renamed |margin\_text[line] -margin\_set\_text(line, text) |Renamed |margin\_text[line] = text -marker\_set\_alpha(n, alpha) |Renamed |marker\_alpha[n] = alpha -marker\_set\_back(n, color) |Renamed |marker\_back[n] = color -marker\_set\_back\_selected(n, color)|Renamed |marker\_back\_selected[n] = color -marker\_set\_fore(n, color) |Renamed |marker\_fore[n] = color -set\_fold\_flags(flags) |Renamed |fold\_flags = flags -set\_lexer\_language(name) |Renamed |lexer\_language = name -style\_get\_font(n) |Renamed |style\_font[n] -**gui** | | -gtkmenu() |Renamed |[menu()][] -**_G** | | -user\_dofile(file) |Renamed |dofile(\_USERHOME..'/'..file) -**_M** | | -lua.goto\_required() |Removed |N/A -php.goto\_required() |Removed |N/A -ruby.goto\_required() |Removed |N/A -**_M.textadept.adeptsense** | | -complete\_symbol() |Replaced|complete() -show\_documentation() |Replaced|show\_apidoc() -**_M.textadept.bookmarks** | | -N/A |New |[toggle()][] -add() |Renamed |toggle(true) -remove() |Renamed |toggle(false) -**_M.textadept.editing** | | -prepare\_for\_save() |Removed |N/A -**_M.textadept.menu** | | -rebuild\_command\_tables() |Replaced|set\_menubar() -**_M.textadept.run** | | -execute() |Replaced|[run()][] and [compile()][] -**_M.textadept.session** | | -prompt\_load() |Replaced|[load()][] -prompt\_save() |Replaced|[save()][] - -[menu()]: api.html#ui.menu -[toggle()]: api.html#textadept.bookmarks.toggle -[run()]: api.html#textadept.run.run -[compile()]: api.html#textadept.run.compile -[load()]: api.html#textadept.session.load -[save()]: api.html#textadept.session.save - -### Textadept 4 to 5 - -Textadept 5 upgraded its copy of Lua from [5.1 to 5.2][]. Many old scripts are -not compatible and need to be upgraded. Since incompatible scripts may cause -crashes on startup, the following guide will help you migrate your scripts from -Textadept 4 to Textadept 5. While this guide is not exhaustive, it covers the -changes I had to make to Textadept's internals. - -[5.1 to 5.2]: http://www.lua.org/manual/5.2/manual.html#8 - -#### API Changes - -Old API |Change |New API ----------------|:------:|------- -**_G** | | -getfenv(f) |Removed |N/A. Use:<br/>debug.getupvalue(f, 1) -loadstring() |Replaced|load() -module() |Removed |N/A -setfenv(f, env)|Removed |N/A. Use:<br/>debug.setupvalue(f, 1, env)<sup>a</sup> -unpack() |Renamed |table.unpack() -xpcall(f, msgh)|Changed |xpcall(f, msgh, ...) -**\_m** |Renamed |**[\_M][]**<sup>b</sup> -**_m.textadept.editing**| | -current\_word(action) |Renamed|[select\_word()][]<sup>c</sup> -**locale** |Removed|N/A -localize(message) |Renamed|\_G.[\_L][][message] -**os** | | -code = execute(cmd) |Changed|ok, status, code = execute(cmd) - -<sup>a</sup>In some cases, use `load()` with an environment instead: - - setfenv(loadstring(str), env)() --> load(str, nil, 'bt', env)() - -<sup>b</sup>In Textadept, search for "\_m" and replace with "\_M" with the -"Match Case" and "Whole Words" options checked -- this is what I did when -upgrading Textadept's internals. - -<sup>c</sup>To delete, call `_M.textadept.keys.utils.delete_word()` or define -your own: - - local function delete_word() - _M.textadept.editing.select_word() - buffer:delete_back() - end - -[\_M]: api.html#_M -[select\_word()]: api.html#textadept.editing.select_word -[\_L]: api.html#_L - -#### Module Changes - -You can use the following as a reference for converting your Lua 5.1 modules to -Lua 5.2: - - -- File *~/.textadept/modules/foo.lua* - -- Lua 5.1 | -- Lua 5.2 - | - | local M = {} - | --[[ This comment is for LuaDoc - --- | --- - -- This is the documentation | -- This is the documentation - -- for module foo. | -- for module foo. - module('foo', package.seeall) | module('foo')]] - | - --- | --- - -- Documentation for bar. | -- Documentation for bar. - -- ... | -- ... - -- | -- @name bar - function bar() | function M.bar() - ... | ... - end | end - | - function baz() | function M.baz() - bar() | M.bar() - end | end - | - | return M - - -- File *~/.textadept/init.lua* - -- Lua 5.1 | -- Lua 5.2 - | - require 'textadept' | _M.textadept = require 'textadept' - require 'foo' | foo = require 'foo' - -Notes: - -1. Even though Lua 5.2 deprecates Lua 5.1's `module()`, Textadept 5 removes it. -2. Prefix all intern module tables and function calls with `M`. -3. Also, replace all instances (if any) of `_M` (a references created by - `module()` that holds the current module table) with `M`. -4. You can use your existing LuaDoc comments by keeping the `module()` call - commented out and adding `@name` tags. - -#### Theme Changes - -You can use the following as a reference for converting your Lua 5.1 themes to -Lua 5.2: - - -- File *~/.textadept/themes/theme/lexer.lua* - -- Lua 5.1 | -- Lua 5.2 - | - | local l = lexer - module('lexer', package.seeall) | local color = l.color - | local style = l.style - | - colors = { | l.colors = { - ... | ... - } | } - | - style_nothing = style{} | l.style_nothing = style{...} - style_class = style{ | l.style_class = style{ - fore = colors.light_yellow | fore = l.colors.light_yellow - } | } - ... | ... - style_identifier = style_nothing | l.style_identifier = l.style_nothing - | - ... | ... - | - style_default = style{ | l.style_default = style{ - ... | ... - } | } - style_line_number = { | l.style_line_number = { - fore = colors.dark_grey, | fore = l.colors.dark_grey, - back = colors.black | back = l.colors.black - } | } - ... | ... - -Note the `l.` prefix before most identifiers. - -### Textadept 3 to 4 - -#### Key and Menu Changes - -Textadept 4 features a brand new set of key bindings and menu structure. It also -shows simple key bindings (not keychains) in menus. In order for key bindings to -appear in menus, `_m.textadept.menu` must know which commands map to which keys. -Therefore, the menu module needs to be `require`d *after* `_m.textadept.keys`. -If your *~/.textadept/init.lua* calls `require 'textadept'`, you do not have to -make any changes. If you load individual modules from `_m.textadept`, ensure -`_m.textadept.menu` loads after `_m.textadept.keys`. - -Mac OSX has different modifier key definitions. A new `m` indicates ⌘ (command) -and `a` changed from ⌘ to ⌥ (alt/option). `c` remains ^ (control). Keep in mind -that ⌥ functions as a compose key for locale-dependent characters. - -#### API Changes - -Old API |Change | New API --------------------------|:-----:|-------- -**\_m.textadept.editing**| | -select\_scope() |Renamed|select\_style() -SAVE\_STRIPS\_WS |Renamed|STRIP\_WHITESPACE\_ON\_SAVE - -### Textadept 2 to 3 - -#### Module Changes - -##### Core Extensions - -The core extention modules moved from *core/ext/* to *modules/textadept/*. -Putting - - require 'textadept' - -in your *~/.textadept/init.lua* loads all the modules you would expect. The -[loading modules](#Loading.Modules) section has instructions on how to load -specific modules. - -##### Autoloading Keys and Snippets - -Key bindings in *~/.textadept/key_commands.lua* and snippets in -*~/.textadept/snippets.lua* no longer auto-load. Move them to your -*~/.textadept/init.lua* or a file loaded by *~/.textadept/init.lua*. - -#### API Changes - -Textadept has a brand new Lua [API][]. Old scripts and themes are likely not -compatible and need to be upgraded. - -Old API |Change | New API ---------------------------|:-----:|-------- -**_G** | | -N/A |New |[\_SCINTILLA][] -N/A |New |[events][] -N/A |New |[gui][] -**_m.textadept.lsnippets**|Renamed|**[_m.textadept.snippets][]** -**textadept** |Removed|N/A -\_print() |Renamed|\_G.[gui.\_print()][] -buffer\_functions |Renamed|\_G.[\_SCINTILLA.functions][] -buffer\_properties |Renamed|\_G.[\_SCINTILLA.properties][] -buffers |Renamed|\_G.[\_BUFFERS][] -check\_focused\_buffer() |Renamed|\_G.gui.check\_focused\_buffer() -clipboard\_text |Renamed|\_G.[gui.clipboard\_text][] -command\_entry |Renamed|\_G.[gui.command\_entry][] -constants |Renamed|\_G.[\_SCINTILLA.constants][] -context\_menu |Renamed|\_G.[gui.context\_menu][] -dialog |Renamed|\_G.[gui.dialog()][] -docstatusbar\_text |Renamed|\_G.[gui.docstatusbar\_text][] -events |Renamed|\_G.[events][] -events.add\_handler() |Renamed|\_G.[events.connect()][] -events.handle() |Renamed|\_G.[events.emit()][] -find |Renamed|\_G.[gui.find][] -focused\_doc\_pointer |Renamed|\_G.gui.focused\_doc\_pointer -get\_split\_table() |Renamed|\_G.[gui.get\_split\_table()][] -goto\_view() |Renamed|\_G.[gui.goto\_view()][] -gtkmenu() |Renamed|\_G.[gui.gtkmenu()][] -iconv() |Renamed|\_G.[string.iconv()][] -menubar |Renamed|\_G.[gui.menubar][] -new\_buffer() |Renamed|\_G.[new\_buffer()][] -print() |Renamed|\_G.[gui.print()][] -quit() |Renamed|\_G.[quit()][] -reset() |Renamed|\_G.[reset()][] -session\_file |Renamed|\_G.\_SESSIONFILE -size |Renamed|\_G.[gui.size][] -statusbar\_text |Renamed|\_G.[gui.statusbar\_text][] -switch\_buffer() |Renamed|\_G.[gui.switch\_buffer()][] -title |Renamed|\_G.[gui.title][] -user\_dofile() |Renamed|\_G.user\_dofile() -views |Renamed|\_G.[\_VIEWS][] - -[API]: api -[\_SCINTILLA]: api.html#_SCINTILLA -[events]: api.html#events -[gui]: api.html#ui -[_m.textadept.snippets]: api.html#textadept.snippets -[gui.\_print()]: api.html#ui._print -[\_SCINTILLA.functions]: api.html#_SCINTILLA.functions -[\_SCINTILLA.properties]: api.html#_SCINTILLA.properties -[\_BUFFERS]: api.html#_BUFFERS -[gui.clipboard\_text]: api.html#ui.clipboard_text -[gui.command\_entry]: api.html#ui.command_entry -[\_SCINTILLA.constants]: api.html#_SCINTILLA.constants -[gui.context\_menu]: api.html#ui.context_menu -[gui.dialog()]: api.html#ui.dialog -[gui.docstatusbar\_text]: api.html#ui.docstatusbar_text -[events.connect()]: api.html#events.connect -[events.emit()]: api.html#events.emit -[gui.find]: api.html#ui.find -[gui.get\_split\_table()]: api.html#ui.get_split_table -[gui.goto\_view()]: api.html#ui.goto_view -[gui.gtkmenu()]: api.html#ui.menu -[string.iconv()]: api.html#string.iconv -[gui.menubar]: api.html#ui.menubar -[new\_buffer()]: api.html#buffer.new -[gui.print()]: api.html#ui.print -[quit()]: api.html#quit -[reset()]: api.html#reset -[gui.size]: api.html#ui.size -[gui.statusbar\_text]: api.html#ui.statusbar_text -[gui.switch\_buffer()]: api.html#ui.switch_buffer -[gui.title]: api.html#ui.title -[\_VIEWS]: api.html#_VIEWS |