From 57c34e2248ac0cd2a89aa48bb400fee04ddf8370 Mon Sep 17 00:00:00 2001 From: Zachary Yedidia Date: Sat, 8 Feb 2020 18:31:06 -0500 Subject: [PATCH] More plugin docs and improve doc formatting --- internal/action/infocomplete.go | 59 +++---- internal/buffer/message.go | 13 +- internal/config/rtfiles.go | 1 + internal/util/lua.go | 4 + internal/util/util.go | 1 + runtime/help/colors.md | 99 ++++++------ runtime/help/commands.md | 37 ++--- runtime/help/help.md | 30 ++-- runtime/help/keybindings.md | 47 +++--- runtime/help/options.md | 81 +++++----- runtime/help/plugins.md | 272 +++++++++++++++++++++++--------- runtime/help/tutorial.md | 29 ++-- 12 files changed, 404 insertions(+), 269 deletions(-) diff --git a/internal/action/infocomplete.go b/internal/action/infocomplete.go index 598f3873..d6c16cb2 100644 --- a/internal/action/infocomplete.go +++ b/internal/action/infocomplete.go @@ -197,7 +197,7 @@ func OptionValueComplete(b *buffer.Buffer) ([]string, []string) { return completions, suggestions } -// OptionComplete autocompletes options +// PluginCmdComplete autocompletes the plugin command func PluginCmdComplete(b *buffer.Buffer) ([]string, []string) { c := b.GetActiveCursor() input, argstart := buffer.GetArg(b) @@ -253,51 +253,28 @@ func PluginComplete(b *buffer.Buffer) ([]string, []string) { return completions, suggestions } -// // MakeCompletion registers a function from a plugin for autocomplete commands -// func MakeCompletion(function string) Completion { -// pluginCompletions = append(pluginCompletions, LuaFunctionComplete(function)) -// return Completion(-len(pluginCompletions)) -// } +// PluginNameComplete completes with the names of loaded plugins +// func PluginNameComplete(b *buffer.Buffer) ([]string, []string) { +// c := b.GetActiveCursor() +// input, argstart := buffer.GetArg(b) // -// // PluginComplete autocompletes from plugin function -// func PluginComplete(complete Completion, input string) (chosen string, suggestions []string) { -// idx := int(-complete) - 1 -// -// if len(pluginCompletions) <= idx { -// return "", nil -// } -// suggestions = pluginCompletions[idx](input) -// -// if len(suggestions) == 1 { -// chosen = suggestions[0] -// } -// return -// } -// -// // PluginCmdComplete completes with possible choices for the `> plugin` command -// func PluginCmdComplete(input string) (chosen string, suggestions []string) { -// for _, cmd := range []string{"install", "remove", "search", "update", "list"} { -// if strings.HasPrefix(cmd, input) { -// suggestions = append(suggestions, cmd) -// } -// } -// -// if len(suggestions) == 1 { -// chosen = suggestions[0] -// } -// return chosen, suggestions -// } -// -// // PluginnameComplete completes with the names of loaded plugins -// func PluginNameComplete(input string) (chosen string, suggestions []string) { -// for _, pp := range GetAllPluginPackages() { +// var suggestions []string +// for _, pp := range config.GetAllPluginPackages(nil) { // if strings.HasPrefix(pp.Name, input) { // suggestions = append(suggestions, pp.Name) // } // } // -// if len(suggestions) == 1 { -// chosen = suggestions[0] +// sort.Strings(suggestions) +// completions := make([]string, len(suggestions)) +// for i := range suggestions { +// completions[i] = util.SliceEndStr(suggestions[i], c.X-argstart) // } -// return chosen, suggestions +// return completions, suggestions +// } + +// // MakeCompletion registers a function from a plugin for autocomplete commands +// func MakeCompletion(function string) Completion { +// pluginCompletions = append(pluginCompletions, LuaFunctionComplete(function)) +// return Completion(-len(pluginCompletions)) // } diff --git a/internal/buffer/message.go b/internal/buffer/message.go index 065d9666..ad7e6560 100644 --- a/internal/buffer/message.go +++ b/internal/buffer/message.go @@ -13,13 +13,19 @@ const ( MTError ) +// Message represents the information for a gutter message type Message struct { - Msg string + // The Msg iteslf + Msg string + // Start and End locations for the message Start, End Loc - Kind MsgType - Owner string + // The Kind stores the message type + Kind MsgType + // The Owner of the message + Owner string } +// NewMessage creates a new gutter message func NewMessage(owner string, msg string, start, end Loc, kind MsgType) *Message { return &Message{ Msg: msg, @@ -30,6 +36,7 @@ func NewMessage(owner string, msg string, start, end Loc, kind MsgType) *Message } } +// NewMessageAtLine creates a new gutter message at a given line func NewMessageAtLine(owner string, msg string, line int, kind MsgType) *Message { start := Loc{-1, line - 1} end := start diff --git a/internal/config/rtfiles.go b/internal/config/rtfiles.go index 4ce263e9..09e91768 100644 --- a/internal/config/rtfiles.go +++ b/internal/config/rtfiles.go @@ -42,6 +42,7 @@ func init() { realFiles = make([][]RuntimeFile, NumTypes) } +// NewRTFiletype creates a new RTFiletype func NewRTFiletype() int { NumTypes++ allFiles = append(allFiles, []RuntimeFile{}) diff --git a/internal/util/lua.go b/internal/util/lua.go index 3f0393d4..8d1ce772 100644 --- a/internal/util/lua.go +++ b/internal/util/lua.go @@ -4,6 +4,8 @@ import ( "unicode/utf8" ) +// LuaRuneAt is a helper function for lua plugins to return the rune +// at an index within a string func LuaRuneAt(str string, runeidx int) string { i := 0 for len(str) > 0 { @@ -20,6 +22,7 @@ func LuaRuneAt(str string, runeidx int) string { return "" } +// LuaGetLeadingWhitespace returns the leading whitespace of a string (used by lua plugins) func LuaGetLeadingWhitespace(s string) string { ws := []byte{} for len(s) > 0 { @@ -35,6 +38,7 @@ func LuaGetLeadingWhitespace(s string) string { return string(ws) } +// LuaIsWordChar returns true if the first rune in a string is a word character func LuaIsWordChar(s string) bool { r, _ := utf8.DecodeRuneInString(s) return IsWordChar(r) diff --git a/internal/util/util.go b/internal/util/util.go index 2a501e3d..485d4f55 100644 --- a/internal/util/util.go +++ b/internal/util/util.go @@ -418,6 +418,7 @@ func ParseSpecial(s string) string { return strings.Replace(s, "\\t", "\t", -1) } +// String converts a byte array to a string (for lua plugins) func String(s []byte) string { return string(s) } diff --git a/runtime/help/colors.md b/runtime/help/colors.md index e17107d0..40ac92ee 100644 --- a/runtime/help/colors.md +++ b/runtime/help/colors.md @@ -3,7 +3,8 @@ This help page aims to cover two aspects of micro's syntax highlighting engine: * How to create colorschemes and use them. -* How to create syntax files to add to the list of languages micro can highlight. +* How to create syntax files to add to the list of languages micro can + highlight. ## Colorschemes @@ -24,32 +25,34 @@ colors can often be configured in the terminal preferences), and additional color support comes in three flavors. * 16-color: A colorscheme that uses the 16 default colors will always work but - will only look good if the 16 default colors have been configured to the user's - liking. Using a colorscheme that only uses the 16 colors from the terminal palette - will also preserve the terminal's theme from other applications since the terminal - will often use those same colors for other applications. Default colorschemes - of this type include `simple` and `solarized`. + will only look good if the 16 default colors have been configured to the + user's liking. Using a colorscheme that only uses the 16 colors from the + terminal palette will also preserve the terminal's theme from other + applications since the terminal will often use those same colors for other + applications. Default colorschemes of this type include `simple` and + `solarized`. -* 256-color: Almost all terminals support displaying an additional 240 colors on - top of the 16 user-configurable colors (creating 256 colors total). Colorschemes - which use 256-color are portable because they will look the same regardless of - the configured 16-color palette. However, the color range is fairly limited - due to the small number of colors available. Default 256-color colorschemes - include `monokai`, `twilight`, `zenburn`, `darcula` and more. +* 256-color: Almost all terminals support displaying an additional 240 colors + on top of the 16 user-configurable colors (creating 256 colors total). + Colorschemes which use 256-color are portable because they will look the + same regardless of the configured 16-color palette. However, the color + range is fairly limited due to the small number of colors available. + Default 256-color colorschemes include `monokai`, `twilight`, `zenburn`, + `darcula` and more. * true-color: Some terminals support displaying "true color" with 16 million - colors using standard RGB values. This mode will be able to support displaying - any colorscheme, but it should be noted that the user-configured 16-color palette - is ignored when using true-color mode (this means the colors while using the - terminal emulator will be slightly off). Not all terminals support true color - but at this point most do. True color support in micro is off by default but - can be enabled by setting the environment variable `MICRO_TRUECOLOR` to 1. - In addition your terminal must support it (usually indicated by setting `$COLORTERM` - to `truecolor`). - True-color colorschemes in micro typically end with `-tc`, such as `solarized-tc`, - `atom-dark-tc`, `material-tc`, etc... If true color is not enabled but a true - color colorscheme is used, micro will do its best to approximate the colors - to the available 256 colors. + colors using standard RGB values. This mode will be able to support + displaying any colorscheme, but it should be noted that the user-configured + 16-color palette is ignored when using true-color mode (this means the + colors while using the terminal emulator will be slightly off). Not all + terminals support true color but at this point most do. True color + support in micro is off by default but can be enabled by setting the + environment variable `MICRO_TRUECOLOR` to 1. In addition your terminal + must support it (usually indicated by setting `$COLORTERM` to `truecolor`). + True-color colorschemes in micro typically end with `-tc`, such as + `solarized-tc`, `atom-dark-tc`, `material-tc`, etc... If true color is not + enabled but a true color colorscheme is used, micro will do its best to + approximate the colors to the available 256 colors. Here is the list of colorschemes: @@ -71,16 +74,18 @@ themes the most. These may vary widely based on the 16 colors selected for your terminal. * `simple` -* `solarized` (must have the solarized color palette in your terminal to use this colorscheme properly) +* `solarized` (must have the solarized color palette in your terminal to use + this colorscheme properly) * `cmc-16` * `cmc-paper` * `geany` ### True color -True color requires your terminal to support it. This means that the environment variable -`COLORTERM` should have the value `truecolor`, `24bit`, or `24-bit`. In addition, to enable -true color in micro, the environment variable `MICRO_TRUECOLOR` must be set to 1. +True color requires your terminal to support it. This means that the +environment variable `COLORTERM` should have the value `truecolor`, `24bit`, +or `24-bit`. In addition, to enable true color in micro, the environment +variable `MICRO_TRUECOLOR` must be set to 1. * `solarized-tc`: this is the solarized colorscheme for true color. * `atom-dark-tc`: this colorscheme is based off of Atom's "dark" colorscheme. @@ -92,9 +97,11 @@ true color in micro, the environment variable `MICRO_TRUECOLOR` must be set to 1 ## Creating a Colorscheme Micro's colorschemes are also extremely simple to create. The default ones can -be found [here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes). +be found +[here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes). -Custom colorschemes should be placed in the `~/.config/micro/colorschemes` directory. +Custom colorschemes should be placed in the `~/.config/micro/colorschemes` +directory. A number of custom directives are placed in a `.micro` file. Colorschemes are typically only 18-30 lines in total. @@ -193,9 +200,9 @@ safe and recommended to use subgroups in your custom syntax files. For example if `constant.string` is found in your colorscheme, micro will us that for highlighting strings. If it's not found, it will use constant instead. Micro tries to match the largest set of groups it can find in the colorscheme -definitions, so if, for examle `constant.bool.true` is found then micro will use -that. If `constant.bool.true` is not found but `constant.bool` is found micro -will use `constant.bool`. If not, it uses `constant`. +definitions, so if, for examle `constant.bool.true` is found then micro will +use that. If `constant.bool.true` is not found but `constant.bool` is found +micro will use `constant.bool`. If not, it uses `constant`. Here's a list of subgroups used in micro's built-in syntax files. @@ -228,9 +235,9 @@ languages. Micro's builtin syntax highlighting tries very hard to be sane, sensible and provide ample coverage of the meaningful elements of a language. Micro has syntax files built in for over 100 languages now! However, there may be -situations where you find Micro's highlighting to be insufficient or not to your -liking. The good news is that you can create your own syntax files, and place them -in `~/.config/micro/syntax` and Micro will use those instead. +situations where you find Micro's highlighting to be insufficient or not to +your liking. The good news is that you can create your own syntax files, and +place them in `~/.config/micro/syntax` and Micro will use those instead. ### Filetype definition @@ -249,9 +256,9 @@ detect: filename: "\\.go$" ``` -Micro will match this regex against a given filename to detect the filetype. You -may also provide an optional `header` regex that will check the first line of -the file. For example: +Micro will match this regex against a given filename to detect the filetype. +You may also provide an optional `header` regex that will check the first line +of the file. For example: ``` detect: @@ -262,8 +269,8 @@ detect: ### Syntax rules Next you must provide the syntax highlighting rules. There are two types of -rules: patterns and regions. A pattern is matched on a single line and usually a -single word as well. A region highlights between two patterns over multiple +rules: patterns and regions. A pattern is matched on a single line and usually +a single word as well. A region highlights between two patterns over multiple lines and may have rules of its own inside the region. Here are some example patterns in Go: @@ -346,8 +353,8 @@ worry about them. Syntax file headers are files that contain only the filetype and the detection regular expressions for a given syntax file. They have a `.hdr` suffix and are -used by default only for the pre-installed syntax files. Header files allow micro -to parse the syntax files much faster when checking the filetype of a certain -file. Custom syntax files may provide header files in `~/.config/micro/syntax` as -well but it is not necessary (only do this if you have many (100+) custom syntax -files and want to improve performance). +used by default only for the pre-installed syntax files. Header files allow +micro to parse the syntax files much faster when checking the filetype of a +certain file. Custom syntax files may provide header files in +`~/.config/micro/syntax` as well but it is not necessary (only do this if you +have many (100+) custom syntax files and want to improve performance). diff --git a/runtime/help/commands.md b/runtime/help/commands.md index d77e98f5..ff4e9994 100644 --- a/runtime/help/commands.md +++ b/runtime/help/commands.md @@ -12,8 +12,8 @@ does not look up environment variables. # Commands -Micro provides the following commands that can be executed at the command-bar by -pressing `CtrlE` and entering the command. Arguments are placed in single +Micro provides the following commands that can be executed at the command-bar +by pressing `CtrlE` and entering the command. Arguments are placed in single quotes here but these are not necessary when entering the command in micro. * `bind 'key' 'action'`: creates a keybinding from key to action. See the @@ -42,33 +42,33 @@ quotes here but these are not necessary when entering the command in micro. See `replace` command for more information. -* `set 'option' 'value'`: sets the option to value. See the `options` help topic for - a list of options you can set. This will modify your `settings.json` with the - new value. +* `set 'option' 'value'`: sets the option to value. See the `options` help + topic for a list of options you can set. This will modify your + `settings.json` with the new value. -* `setlocal 'option' 'value'`: sets the option to value locally (only in the current - buffer). This will *not* modify `settings.json`. +* `setlocal 'option' 'value'`: sets the option to value locally (only in the + current buffer). This will *not* modify `settings.json`. * `show 'option'`: shows the current value of the given option. * `run 'sh-command'`: runs the given shell command in the background. The command's output will be displayed in one line when it finishes running. -* `vsplit 'filename'`: opens a vertical split with `filename`. If no filename is - provided, a vertical split is opened with an empty buffer. +* `vsplit 'filename'`: opens a vertical split with `filename`. If no filename + is provided, a vertical split is opened with an empty buffer. -* `hsplit 'filename'`: same as `vsplit` but opens a horizontal split instead of a - vertical split. +* `hsplit 'filename'`: same as `vsplit` but opens a horizontal split instead + of a vertical split. * `tab 'filename'`: opens the given file in a new tab. -* `tabswitch 'tab'`: This command will switch to the specified tab. The `tab` can - either be a tab number, or a name of a tab. +* `tabswitch 'tab'`: This command will switch to the specified tab. The `tab` + can either be a tab number, or a name of a tab. -* `textfilter 'sh-command'`: filters the current selection through a shell command - as standard input and replaces the selection with the stdout of the shell command. - For example, to sort a list of numbers, first select them, and then execute - `> textfilter sort -n`. +* `textfilter 'sh-command'`: filters the current selection through a shell + command as standard input and replaces the selection with the stdout of + the shell command. For example, to sort a list of numbers, first select + them, and then execute `> textfilter sort -n`. * `log`: opens a log of all messages and debug statements. @@ -107,7 +107,8 @@ quotes here but these are not necessary when entering the command in micro. running `> showkey CtrlC` will display `Copy`. * `term exec?`: Open a terminal emulator running the given executable. If no - executable is given, this will open the default shell in the terminal emulator. + executable is given, this will open the default shell in the terminal + emulator. --- diff --git a/runtime/help/help.md b/runtime/help/help.md index d284e019..576f7218 100644 --- a/runtime/help/help.md +++ b/runtime/help/help.md @@ -1,29 +1,31 @@ # Micro help text -Micro is a terminal-based text editor that aims to be easy to use and intuitive, -while also taking advantage of the full capabilities of modern terminals. +Micro is a terminal-based text editor that aims to be easy to use and +intuitive, while also taking advantage of the full capabilities of modern +terminals. To open the command bar, press CtrlE. This enables a `>` prompt for typing -commands. From now on when the documentation says to run a command such as -`> help`, this means press CtrlE and type `help` (and press enter to execute -the command). +commands. From now on when the documentation says to run a command such as `> +help`, this means press CtrlE and type `help` (and press enter to execute the +command). For a list of the default keybindings run `> help defaultkeys`. For more information on keybindings see `> help keybindings`. ## Quick-start -Press Ctrl-q to quit, and Ctrl-s to save. Press CtrlE to start typing commands and -you can see which commands are available by pressing tab, or by viewing the help -topic `> help commands`. +Press Ctrl-q to quit, and Ctrl-s to save. Press CtrlE to start typing commands +and you can see which commands are available by pressing tab, or by viewing the +help topic `> help commands`. Move the cursor around with the mouse or the arrow keys. Run `> help defaultkeys` to get a quick, easy overview of the default hotkeys and what they do. For more info on rebinding keys, see type `> help keybindings`. If the colorscheme doesn't look good, you can change it with -`> set colorscheme ...`. You can press tab to see the available colorschemes, or -see more information about colorschemes and syntax highlighting with `> help colors`. +`> set colorscheme ...`. You can press tab to see the available colorschemes, +or see more information about colorschemes and syntax highlighting with `> help +colors`. Press Ctrl-w to move between splits, and type `> vsplit filename` or `> hsplit filename` to open a new split. @@ -41,14 +43,14 @@ Here are the possible help topics that you can read: topics * keybindings: Gives a full list of the default keybindings as well as how to rebind them -* defaultkeys: Gives a more straight-forward list of the hotkey commands and what - they do. +* defaultkeys: Gives a more straight-forward list of the hotkey commands and + what they do. * commands: Gives a list of all the commands and what they do * options: Gives a list of all the options you can customize * plugins: Explains how micro's plugin system works and how to create your own plugins -* colors: Explains micro's colorscheme and syntax highlighting engine and how to - create your own colorschemes or add new languages to the engine +* colors: Explains micro's colorscheme and syntax highlighting engine and how + to create your own colorschemes or add new languages to the engine For example, to open the help page on plugins you would run `> help plugins`. diff --git a/runtime/help/keybindings.md b/runtime/help/keybindings.md index afdb7123..dcb8bb61 100644 --- a/runtime/help/keybindings.md +++ b/runtime/help/keybindings.md @@ -14,16 +14,16 @@ at the end of this document). If `~/.config/micro/bindings.json` does not exist, you can simply create it. Micro will know what to do with it. -You can use the alt keys + arrows to move word by word. Ctrl left and right move -the cursor to the start and end of the line, and ctrl up and down move the +You can use the alt keys + arrows to move word by word. Ctrl left and right +move the cursor to the start and end of the line, and ctrl up and down move the cursor the start and end of the buffer. You can hold shift with all of these movement actions to select while moving. ## Rebinding keys -The bindings may be rebound using the `~/.config/micro/bindings.json` file. Each -key is bound to an action. +The bindings may be rebound using the `~/.config/micro/bindings.json` file. +Each key is bound to an action. For example, to bind `Ctrl-y` to undo and `Ctrl-z` to redo, you could put the following in the `bindings.json` file. @@ -58,9 +58,9 @@ bindings, tab is bound as "Tab": "Autocomplete|IndentSelection|InsertTab" ``` -This means that if the `Autocomplete` action is successful, the chain will abort. -Otherwise, it will try `IndentSelection`, and if that fails too, it will -execute `InsertTab`. +This means that if the `Autocomplete` action is successful, the chain will +abort. Otherwise, it will try `IndentSelection`, and if that fails too, it +will execute `InsertTab`. ## Binding commands @@ -87,8 +87,9 @@ you could rebind `CtrlG` to `> help`: } ``` -Now when you press `CtrlG`, `help` will appear in the command bar and your cursor will -be placed after it (note the space in the json that controls the cursor placement). +Now when you press `CtrlG`, `help` will appear in the command bar and your +cursor will be placed after it (note the space in the json that controls the +cursor placement). ## Binding raw escape sequences @@ -103,15 +104,15 @@ starting with `0x1b`. For example, if micro reads `\x1b[1;5D`, on most terminals this will mean the user pressed CtrlLeft. -For many key chords though, the terminal won't send any escape code or will send -an escape code already in use. For example for `CtrlBackspace`, my terminal -sends `\u007f` (note this doesn't start with `0x1b`), which it also sends for -`Backspace` meaning micro can't bind `CtrlBackspace`. +For many key chords though, the terminal won't send any escape code or will +send an escape code already in use. For example for `CtrlBackspace`, my +terminal sends `\u007f` (note this doesn't start with `0x1b`), which it also +sends for `Backspace` meaning micro can't bind `CtrlBackspace`. However, some terminals do allow you to bind keys to send specific escape sequences you define. Then from micro you can directly bind those escape -sequences to actions. For example, to bind `CtrlBackspace` you can instruct your -terminal to send `\x1bctrlback` and then bind it in `bindings.json`: +sequences to actions. For example, to bind `CtrlBackspace` you can instruct +your terminal to send `\x1bctrlback` and then bind it in `bindings.json`: ```json { @@ -123,9 +124,9 @@ Here are some instructions for sending raw escapes in different terminals ### iTerm2 -In iTerm2, you can do this in `Preferences->Profiles->Keys` then click the `+`, -input your keybinding, and for the `Action` select `Send Escape Sequence`. For -the above example your would type `ctrlback` into the box (the `\x1b`) is +In iTerm2, you can do this in `Preferences->Profiles->Keys` then click the +`+`, input your keybinding, and for the `Action` select `Send Escape Sequence`. +For the above example your would type `ctrlback` into the box (the `\x1b`) is automatically sent by iTerm2. ### Linux using loadkeys @@ -516,8 +517,8 @@ Additionally, alt keys can be bound by using `Alt-key`. For example `Alt-a` or This is why in the default keybindings you can see `AltShiftLeft` instead of `Alt-ShiftLeft` (they are equivalent). -Please note that terminal emulators are strange applications and micro only receives -key events that the terminal decides to send. Some terminal emulators may not -send certain events even if this document says micro can receive the event. To see -exactly what micro receives from the terminal when you press a key, run the `> raw` -command. +Please note that terminal emulators are strange applications and micro only +receives key events that the terminal decides to send. Some terminal emulators +may not send certain events even if this document says micro can receive the +event. To see exactly what micro receives from the terminal when you press a +key, run the `> raw` command. diff --git a/runtime/help/options.md b/runtime/help/options.md index 32f95ec7..b4561655 100644 --- a/runtime/help/options.md +++ b/runtime/help/options.md @@ -2,12 +2,12 @@ Micro stores all of the user configuration in its configuration directory. -Micro uses `$MICRO_CONFIG_HOME` as the configuration directory. If this environment -variable is not set, it uses `$XDG_CONFIG_HOME/micro` instead. If that -environment variable is not set, it uses `~/.config/micro` as the configuration -directory. In the documentation, we use `~/.config/micro` to refer to the -configuration directory (even if it may in fact be somewhere else if you have -set either of the above environment variables). +Micro uses `$MICRO_CONFIG_HOME` as the configuration directory. If this +environment variable is not set, it uses `$XDG_CONFIG_HOME/micro` instead. If +that environment variable is not set, it uses `~/.config/micro` as the +configuration directory. In the documentation, we use `~/.config/micro` to +refer to the configuration directory (even if it may in fact be somewhere else +if you have set either of the above environment variables). Here are the available options: @@ -19,11 +19,12 @@ Here are the available options: * `backup`: micro will automatically keep backups of all open buffers. Backups are stored in `~/.config/micro/backups` and are removed when the buffer is closed cleanly. In the case of a system crash or a micro crash, the contents - of the buffer can be recovered automatically by opening the file that - was being edited before the crash, or manually by searching for the backup - in the backup directory. Backups are made in the background when a buffer is + of the buffer can be recovered automatically by opening the file that was + being edited before the crash, or manually by searching for the backup in + the backup directory. Backups are made in the background when a buffer is modified and the latest backup is more than 8 seconds old, or when micro - detects a crash. It is highly recommended that you leave this feature enabled. + detects a crash. It is highly recommended that you leave this feature + enabled. default value: `true` @@ -43,8 +44,9 @@ Here are the available options: default value: `default` - Note that the default colorschemes (default, solarized, and solarized-tc) - are not located in configDir, because they are embedded in the micro binary. + Note that the default colorschemes (default, solarized, and solarized-tc) + are not located in configDir, because they are embedded in the micro + binary. The colorscheme can be selected from all the files in the ~/.config/micro/colorschemes/ directory. Micro comes by default with three @@ -67,29 +69,29 @@ Here are the available options: default value: `false` -* `fastdirty`: this determines what kind of algorithm micro uses to determine if - a buffer is modified or not. When `fastdirty` is on, micro just uses a +* `fastdirty`: this determines what kind of algorithm micro uses to determine + if a buffer is modified or not. When `fastdirty` is on, micro just uses a boolean `modified` that is set to `true` as soon as the user makes an edit. This is fast, but can be inaccurate. If `fastdirty` is off, then micro will - hash the current buffer against a hash of the original file (created when the - buffer was loaded). This is more accurate but obviously more resource + hash the current buffer against a hash of the original file (created when + the buffer was loaded). This is more accurate but obviously more resource intensive. This option is only for people who really care about having accurate modified status. default value: `true` -* `fileformat`: this determines what kind of line endings micro will use for the - file. UNIX line endings are just `\n` (linefeed) whereas dos line endings are - `\r\n` (carriage return + linefeed). The two possible values for this option - are `unix` and `dos`. The fileformat will be automatically detected (when you - open an existing file) and displayed on the statusline, but this option is - useful if you would like to change the line endings or if you are starting a - new file. +* `fileformat`: this determines what kind of line endings micro will use for + the file. UNIX line endings are just `\n` (linefeed) whereas dos line + endings are `\r\n` (carriage return + linefeed). The two possible values for + this option are `unix` and `dos`. The fileformat will be automatically + detected (when you open an existing file) and displayed on the statusline, + but this option is useful if you would like to change the line endings or if + you are starting a new file. default value: `unix` -* `filetype`: sets the filetype for the current buffer. Set this option to `off` - to completely disable filetype detection. +* `filetype`: sets the filetype for the current buffer. Set this option to + `off` to completely disable filetype detection. default value: `unknown`. This will be automatically overridden depending on the file you open. @@ -109,8 +111,9 @@ Here are the available options: * `keepautoindent`: when using autoindent, whitespace is added for you. This option determines if when you move to the next line without any insertions - the whitespace that was added should be deleted to remove trailing whitespace. - By default, the autoindent whitespace is deleted if the line was left empty. + the whitespace that was added should be deleted to remove trailing + whitespace. By default, the autoindent whitespace is deleted if the line + was left empty. default value: `false` @@ -125,9 +128,9 @@ Here are the available options: default value: `true` -* `mkparents`: if a file is opened on a path that does not exist, the file cannot - be saved because the parent directories don't exist. This option lets micro - automatically create the parent directories in such a situation. +* `mkparents`: if a file is opened on a path that does not exist, the file + cannot be saved because the parent directories don't exist. This option lets + micro automatically create the parent directories in such a situation. default value: `false` @@ -141,10 +144,10 @@ Here are the available options: * `paste`: Treat characters sent from the terminal in a single chunk as a paste event rather than a series of manual key presses. If you are pasting using - the terminal keybinding (not Ctrl-v, which is micro's default paste keybinding) - then it is a good idea to enable this option during the paste and disable - once the paste is over. See `> help copypaste` for details about copying - and pasting in a terminal environment. + the terminal keybinding (not Ctrl-v, which is micro's default paste + keybinding) then it is a good idea to enable this option during the paste + and disable once the paste is over. See `> help copypaste` for details about + copying and pasting in a terminal environment. default value: `false` @@ -262,8 +265,8 @@ Here are the available options: --- -Plugin options: all plugins come with a special option to enable or disable them. The option -is a boolean with the same name as the plugin itself. +Plugin options: all plugins come with a special option to enable or disable +them. The option is a boolean with the same name as the plugin itself. Any option you set in the editor will be saved to the file ~/.config/micro/settings.json so, in effect, your configuration file will be @@ -281,9 +284,9 @@ locally rather than globally. The `colorscheme` option is global only, and the `filetype` option is local only. To set an option locally, use `setlocal` instead of `set`. -In the `settings.json` file you can also put set options locally by specifying either -a glob or a filetype. Here is an example which has `tabstospaces` on for all files except Go -files, and `tabsize` 4 for all files except Ruby files: +In the `settings.json` file you can also put set options locally by specifying +either a glob or a filetype. Here is an example which has `tabstospaces` on for +all files except Go files, and `tabsize` 4 for all files except Ruby files: ```json { diff --git a/runtime/help/plugins.md b/runtime/help/plugins.md index 42902605..87f38e73 100644 --- a/runtime/help/plugins.md +++ b/runtime/help/plugins.md @@ -97,8 +97,8 @@ function onSave(bp) end ``` -The `bp` variable is a reference to the bufpane the action is being executed within. -This is almost always the current bufpane. +The `bp` variable is a reference to the bufpane the action is being executed +within. This is almost always the current bufpane. All available actions are listed in the keybindings section of the help. @@ -112,8 +112,8 @@ function onMousePress(view, event) end ``` -These functions should also return a boolean specifying whether the bufpane should -be relocated to the cursor or not after the action is complete. +These functions should also return a boolean specifying whether the bufpane +should be relocated to the cursor or not after the action is complete. ## Accessing micro functions @@ -129,76 +129,205 @@ micro.Log("Hello") The packages and functions are listed below (in Go type signatures): * `micro` - - `TermMessage(msg interface{}...)` - - `TermError()` - - `InfoBar()` - - `Log(msg interface{}...)` - - `SetStatusInfoFn(fn string)` -* `micro/config` - - `MakeCommand` - - `FileComplete` - - `HelpComplete` - - `OptionComplete` - - `OptionValueComplete` - - `NoComplete` - - `TryBindKey` - - `Reload` - - `AddRuntimeFilesFromDirectory` - - `AddRuntimeFileFromMemory` - - `AddRuntimeFile` - - `ListRuntimeFiles` - - `ReadRuntimeFile` - - `RTColorscheme` - - `RTSyntax` - - `RTHelp` - - `RTPlugin` - - `RegisterCommonOption` - - `RegisterGlobalOption` -* `micro/shell` - - `ExecCommand` - - `RunCommand` - - `RunBackgroundShell` - - `RunInteractiveShell` - - `JobStart` - - `JobSpawn` - - `JobStop` - - `JobStop` - - `RunTermEmulator` - - `TermEmuSupported` -* `micro/buffer` - - `NewMessage` - - `NewMessageAtLine` - - `MTInfo` - - `MTWarning` - - `MTError` - - `Loc` - - `BTDefault` - - `BTLog` - - `BTRaw` - - `BTInfo` - - `NewBufferFromFile` - - `ByteOffset` - - `Log` - - `LogBuf` -* `micro/util` - - `RuneAt` - - `GetLeadingWhitespace` - - `IsWordChar` + - `TermMessage(msg interface{}...)`: temporarily close micro and print a + message + - `TermError(filename string, lineNum int, err string)`: temporarily close + micro and print an error formatted as `filename, lineNum: err`. + + - `InfoBar()`: return the infobar BufPane object. + + - `Log(msg interface{}...)`: write a message to `log.txt` (requires + `-debug` flag, or binary built with `build-dbg`). + + - `SetStatusInfoFn(fn string)`: register the given lua function as + accessible from the statusline formatting options +* `micro/config` + - `MakeCommand(name string, action func(bp *BufPane, args[]string), + completer buffer.Completer)`: + create a command with the given name, and lua callback function when + the command is run. A completer may also be given to specify how + autocompletion should work with the custom command. + + - `FileComplete`: autocomplete using files in the current directory + - `HelpComplete`: autocomplete using names of help documents + - `OptionComplete`: autocomplete using names of options + - `OptionValueComplete`: autocomplete using names of options, and valid + values afterwards + - `NoComplete`: no autocompletion suggestions + + - `TryBindKey(k, v string, overwrite bool) (bool, error)`: bind the key + `k` to the string `v` in the `bindings.json` file. If `overwrite` is + true, this will overwrite any existing binding to key `k`. Returns true + if the binding was made, and a possible error (for example writing to + `bindings.json` can cause an error). + + - `Reload()`: reload configuration files. + + - `AddRuntimeFileFromMemory(filetype RTFiletype, filename, data string)`: + add a runtime file to the `filetype` runtime filetype, with name + `filename` and data `data`. + + - `AddRuntimeFilesFromDirectory(plugin string, filetype RTFiletype, + directory, pattern string)`: + add runtime files for the given plugin with the given RTFiletype from + a directory within the plugin root. Only adds files that match the + pattern using Go's `filepath.Match` + + - `AddRuntimeFile(plugin string, filetype RTFiletype, filepath string)`: + add a given file inside the plugin root directory as a runtime file + to the given RTFiletype category. + + - `ListRuntimeFiles(fileType RTFiletype) []string`: returns a list of + names of runtime files of the given type. + + - `ReadRuntimeFile(fileType RTFiletype, name string) string`: returns the + contents of a given runtime file. + + - `NewRTFiletype() int`: creates a new RTFiletype, and returns its value. + + - `RTColorscheme`: runtime files for colorschemes. + - `RTSyntax`: runtime files for syntax files. + - `RTHelp`: runtime files for help documents. + - `RTPlugin`: runtime files for plugin source code. + + - `RegisterCommonOption(pl string, name string, defaultvalue interface{})`: + registers a new option with for the given plugin. The name of the + option will be `pl.name`, and will have the given default value. Since + this registers a common option, the option will be modifiable on a + per-buffer basis, while also having a global value (in the + GlobalSettings map). + + - `RegisterGlobalOption(pl string, name string, defaultvalue interface{})`: + same as `RegisterCommonOption` but the option cannot be modified + locally to each buffer. + + - `GetGlobalOption(name string) interface{}`: returns the value of a + given plugin in the `GlobalSettings` map. + + - `SetGlobalOption(option, value string) error`: sets an option to a + given value. Same as using the `> set` command. This will parse the + value to the actual value type. + + - `SetGlobalOptionNative(option string, value interface{}) error`: sets + an option to a given value, where the type of value is the actual + type of the value internally. +* `micro/shell` + - `ExecCommand(name string, arg ...string) (string, error)`: runs an + executable with the given arguments, and pipes the output (stderr + and stdout) of the executable to an internal buffer, which is + returned as a string, along with a possible error. + + - `RunCommand(input string) (string, error)`: same as `ExecCommand`, + except this uses micro's argument parser to parse the arguments from + the input. For example `cat 'hello world.txt' file.txt`, will pass + two arguments in the `ExecCommand` argument list (quoting arguments + will preserve spaces). + + - `RunBackgroundShell(input string) (func() string, error)`: returns a + function that will run the given shell command and return its output. + + - `RunInteractiveShell(input string, wait bool, getOutput bool) + (string, error)`: + temporarily closes micro and runs the given command in the terminal. + If `wait` is true, micro will wait for the user to press enter before + returning to text editing. If `getOutput` is true, micro redirect + stdout from the command to the returned string. + + - `JobStart(cmd string, onStdout, onStderr, + onExit func(string, []interface{}), userargs ...interface{}) + *exec.Cmd`: + Starts a background job by running the shell on the given command + (using `sh -c`). Three callbacks can be provided which will be called + when the command generates stdout, stderr, or exits. The userargs will + be passed to the callbacks, along with the output as the first + argument of the callback. + + - `JobSpawn(cmd string, cmdArgs []string, onStdout, onStderr, + onExit func(string, []interface{}), userargs ...interface{}) + *exec.Cmd`: + same as `JobStart`, except doesn't run the command through the shell + and instead takes as inputs the list of arguments. + + - `JobStop(cmd *exec.Cmd)`: kills a job. + - `JobSend(cmd *exec.Cmd, data string)`: sends some data to a job's stdin. + + - `RunTermEmulator(h *BufPane, input string, wait bool, getOutput bool, + callback func(out string, userargs []interface{}), + userargs []interface{}) error`: + starts a terminal emulator from a given BufPane with the input command. + If `wait` is true it will wait for the user to exit by pressing enter + once the executable has terminated and if `getOutput` is true it will + redirect the stdout of the process to a pipe which will be passed to + the callback which is a function that takes a string and a list of + optional user arguments. This function returns an error on systems + where the terminal emulator is not supported. + + - `TermEmuSupported`: true on systems where the terminal emulator is + supported and false otherwise. Supported systems: + * Linux + * MacOS + * Dragonfly + * OpenBSD + * FreeBSD + +* `micro/buffer` + - `NewMessage(owner string, msg string, start, end, Loc, kind MsgType) + *Message`: + creates a new message with an owner over a range given by the start + and end locations. + + - `NewMessageAtLine(owner string, msg string, line int, kindMsgType) + *Message`: + creates a new message with owner, type and message at a given line. + + - `MTInfo`: info message. + - `MTWarning`: warning message. + - `MTError` error message. + + - `Loc(x, y int) Loc`: creates a new location struct. + + - `BTDefault`: default buffer type. + - `BTLog`: log buffer type. + - `BTRaw`: raw buffer type. + - `BTInfo`: info buffer type. + + - `NewBuffer(text, path string) *Buffer`: creates a new buffer with the + given text at a certain path. + + - `NewBufferFromFile(path string) (*Buffer, error)`: creates a new + buffer by reading from disk at the given path. + + - `ByteOffset(pos Loc, buf *Buffer) int`: returns the byte index of the + given position in a buffer. + + - `Log(s string)`: writes a string to the log buffer. + - `LogBuf() *Buffer`: returns the log buffer. +* `micro/util` + - `RuneAt(str string, idx int) string`: returns the utf8 rune at a + given index within a string. + - `GetLeadingWhitespace(s string) string`: returns the leading + whitespace of a string. + - `IsWordChar(s string) bool`: returns true if the first rune in a + string is a word character. + - `String(b []byte) string`: converts a byte array to a string. + - `RuneStr(r rune) string`: converts a rune to a string. This may seem like a small list of available functions but some of the objects returned by the functions have many methods. The Lua plugin may access any -public methods of an object returned by any of the functions above. Unfortunately -it is not possible to list all the available functions on this page. Please -go to the internal documentation at https://godoc.org/github.com/zyedidia/micro -to see the full list of available methods. Note that only methods of types that -are available to plugins via the functions above can be called from a plugin. -For an even more detailed reference see the source code on Github. +public methods of an object returned by any of the functions above. +Unfortunately it is not possible to list all the available functions on this +page. Please go to the internal documentation at +https://godoc.org/github.com/zyedidia/micro to see the full list of available +methods. Note that only methods of types that are available to plugins via +the functions above can be called from a plugin. For an even more detailed +reference see the source code on Github. -For example, with a BufPane object called `bp`, you could call the `Save` function -in Lua with `bp:Save()`. +For example, with a BufPane object called `bp`, you could call the `Save` +function in Lua with `bp:Save()`. -Note that Lua uses the `:` syntax to call a function rather than Go's `.` syntax. +Note that Lua uses the `:` syntax to call a function rather than Go's `.` +syntax. ```go micro.InfoBar().Message() @@ -265,7 +394,8 @@ to plugins though it is rather small. ## Adding help files, syntax files, or colorschemes in your plugin -You can use the `AddRuntimeFile(name string, type config.RTFiletype, path string)` +You can use the `AddRuntimeFile(name string, type config.RTFiletype, + path string)` function to add various kinds of files to your plugin. For example, if you'd like to add a help topic to your plugin called `test`, you would create a `test.md` file, and call the function: @@ -337,8 +467,8 @@ This file will contain the metadata for your plugin. Here is an example: }] ``` -Then open a pull request at github.com/micro-editor/plugin-channel adding a link -to the raw `repo.json` that is in your plugin repository. +Then open a pull request at github.com/micro-editor/plugin-channel adding a +link to the raw `repo.json` that is in your plugin repository. To make updating the plugin work, the first line of your plugins lua code should contain the version of the plugin. (Like this: `VERSION = "1.0.0"`) diff --git a/runtime/help/tutorial.md b/runtime/help/tutorial.md index bdc4f6de..2245fc36 100644 --- a/runtime/help/tutorial.md +++ b/runtime/help/tutorial.md @@ -1,8 +1,8 @@ # Tutorial -This is a brief intro to micro's configuration system that will give some simple -examples showing how to configure settings, rebind keys, and use `init.lua` to -configure micro to your liking. +This is a brief intro to micro's configuration system that will give some +simple examples showing how to configure settings, rebind keys, and use +`init.lua` to configure micro to your liking. Hopefully you'll find this useful. @@ -21,8 +21,8 @@ future, I will use `> set option value` to indicate pressing CtrlE). The change will take effect immediately and will also be saved to the `settings.json` file so that the setting will stick even after you close micro. -You can also set options locally which means that the setting will only have the -value you give it in the buffer you set it in. For example, if you have two +You can also set options locally which means that the setting will only have +the value you give it in the buffer you set it in. For example, if you have two splits open, and you type `> setlocal tabsize 2`, the tabsize will only be 2 in the current buffer. Also micro will not save this local change to the `settings.json` file. However, you can still set options locally in the @@ -60,20 +60,21 @@ following in `bindings.json`: Very simple. You can also bind keys while in micro by using the `> bind key action` command, -but the bindings you make with the command won't be saved to the `bindings.json` -file. +but the bindings you make with the command won't be saved to the +`bindings.json` file. -For more information about keybindings, like which keys can be bound, and -what actions are available, see the `keybindings` help topic (`> help keybindings`). +For more information about keybindings, like which keys can be bound, and what +actions are available, see the `keybindings` help topic (`> help keybindings`). ### Configuration with Lua If you need more power than the json files provide, you can use the `init.lua` file. Create it in `~/.config/micro`. This file is a lua file that is run when -micro starts and is essentially a one-file plugin. The plugin name is `initlua`. +micro starts and is essentially a one-file plugin. The plugin name is +`initlua`. -This example will show you how to use the `init.lua` file by creating -a binding to `CtrlR` which will execute the bash command `go run` on the current file, +This example will show you how to use the `init.lua` file by creating a binding +to `CtrlR` which will execute the bash command `go run` on the current file, given that the current file is a Go file. You can do that by putting the following in `init.lua`: @@ -98,8 +99,8 @@ function gorun(bp) end ``` -Alternatively, you could get rid of the `TryBindKey` line, and put this line in the -`bindings.json` file: +Alternatively, you could get rid of the `TryBindKey` line, and put this line in +the `bindings.json` file: ```json {