diff options
Diffstat (limited to 'docs/handbook/mnv/scripting.md')
| -rw-r--r-- | docs/handbook/mnv/scripting.md | 541 |
1 files changed, 541 insertions, 0 deletions
diff --git a/docs/handbook/mnv/scripting.md b/docs/handbook/mnv/scripting.md new file mode 100644 index 0000000000..ed8d4cae4a --- /dev/null +++ b/docs/handbook/mnv/scripting.md @@ -0,0 +1,541 @@ +# MNV — Command-Line Interface and Scripting + +## Executable Invocation + +MNV is a single binary that adapts its behaviour based on the name it is +launched with. The `parse_command_name()` function in `src/main.c` determines +the mode: + +```c +static void parse_command_name(mparm_T *parmp); +``` + +| Invocation | Mode | Effect | +|---|---|---| +| `mnv` | Normal | Standard editor | +| `ex` | Ex | Starts in `:` line mode | +| `view` | Read-only | Equivalent to `mnv -R` | +| `rmnv` | Restricted | Disables shell commands, file writes | +| `rview` | Restricted+RO | Restricted + read-only | +| `mnvdiff` | Diff | Opens files in diff mode (`mnv -d`) | +| `vi` / `vim` | Compat aliases | Normal mode | +| `gmnv` | GUI | Starts graphical interface | +| `gview` | GUI+RO | GUI + read-only | +| `gmnvdiff` | GUI+Diff | GUI diff mode | +| `emnv` | Easy GUI | GUI in easy mode (insert mode by default) | +| `eview` | Easy+RO | Easy mode + read-only | + +--- + +## Command-Line Arguments + +The `command_line_scan()` function in `src/main.c` parses all command-line +arguments: + +```c +static void command_line_scan(mparm_T *parmp); +``` + +### File Arguments + +Any non-option arguments are treated as files to edit: + +``` +mnv file1.c file2.c file3.c +``` + +These populate the argument list, managed by `src/arglist.c`. + +### Standard Options + +| Flag | Description | +|---|---| +| `-R` | Read-only mode | +| `-Z` | Restricted mode (no shell access) | +| `-g` | Start GUI (equivalent to `gmnv`) | +| `-d` | Diff mode — open 2-8 files side by side | +| `-b` | Binary mode | +| `-l` | Lisp mode | +| `-M` | Not modifiable — don't allow changes | +| `-e` | Ex mode (`:` prompt) | +| `-E` | Improved Ex mode | +| `-s` | Silent/batch mode (Ex mode, no prompts) | +| `-y` | Easy mode | +| `-f` | Foreground — don't fork (GUI) | +| `-v` | Force terminal mode even if `gmnv` | +| `-n` | No swap file | +| `-r` | Recovery mode (list swap files or recover) | +| `-L` | Same as `-r` | +| `-p[N]` | Open N tab pages | +| `-o[N]` | Open N horizontal splits | +| `-O[N]` | Open N vertical splits | +| `-t tag` | Edit file containing `tag` | +| `-q file` | Start in quickfix mode with `file` | + +### Pre- and Post-Commands + +| Flag | Description | +|---|---| +| `--cmd <command>` | Execute `<command>` **before** sourcing `.mnvrc`. Up to 10. | +| `-c <command>` / `+<command>` | Execute `<command>` **after** loading files. Up to 10. | +| `+` | Start at last line of first file | +| `+{num}` | Start at line `{num}` of first file | + +The error message for too many commands: + +```c +N_("Too many \"+command\", \"-c command\" or \"--cmd command\" arguments"), +#define ME_EXTRA_CMD 4 +``` + +### Startup Control + +| Flag | Description | +|---|---| +| `--clean` | Skip all config files (`.mnvrc`, plugins) | +| `-u <file>` | Use `<file>` instead of `.mnvrc` | +| `-U <file>` | Use `<file>` instead of `.gmnvrc` | +| `-i <file>` | Use `<file>` instead of `.mnvinfo` | +| `--noplugin` | Don't load any plugins | +| `--startuptime <file>` | Log startup timing to `<file>` | +| `--log <file>` | Enable channel/job logging to `<file>` | + +The `--startuptime` flag is scanned in `early_arg_scan()`: + +```c +if (STRICMP(argv[i], "--startuptime") == 0 && time_fd == NULL) +{ + time_fd = mch_fopen(argv[i + 1], "a"); + TIME_MSG("--- MNV STARTING ---"); +} +``` + +### Display Options + +| Flag | Description | +|---|---| +| `-T <terminal>` | Set terminal type | +| `--not-a-term` | Skip terminal checks | +| `--ttyfail` | Exit if stdin is not a terminal | + +### Client-Server + +| Flag | Description | +|---|---| +| `--servername <name>` | Set server name | +| `--serverlist` | List running MNV servers | +| `--remote <files>` | Open files in an existing MNV | +| `--remote-send <keys>` | Send keys to a running MNV | +| `--remote-expr <expr>` | Evaluate expression in a running MNV | +| `--remote-wait` | Like `--remote` but wait for completion | +| `--remote-tab` | Like `--remote` but open in new tab | + +### Information + +| Flag | Description | +|---|---| +| `-h` / `--help` | Print usage and exit | +| `--version` | Print version and exit | + +### Error Handling + +Unrecognised options produce: + +```c +static char *(main_errors[]) = +{ + N_("Unknown option argument"), // ME_UNKNOWN_OPTION + N_("Too many edit arguments"), // ME_TOO_MANY_ARGS + N_("Argument missing after"), // ME_ARG_MISSING + N_("Garbage after option argument"), // ME_GARBAGE + N_("Too many \"+command\", \"-c command\" or \"--cmd command\" arguments"), + N_("Invalid argument for"), // ME_INVALID_ARG +}; +``` + +--- + +## Startup Sequence + +When `main()` runs (see `src/main.c`), parameter processing happens in +several phases: + +### 1. Early Argument Scan + +```c +static void early_arg_scan(mparm_T *parmp); +``` + +Scans specifically for `--startuptime`, `--log`, and `--clean` **before** any +initialisation, because these affect how initialisation proceeds. + +### 2. Common Init Phase 1 + +`common_init_1()` — allocator, hash tables, global options, message system. + +### 3. Common Init Phase 2 + +`common_init_2(¶ms)` — terminal detection, default options, langmap. + +### 4. Full Command-Line Scan + +`command_line_scan(¶ms)` — processes every flag and file argument. + +### 5. TTY Check + +```c +static void check_tty(mparm_T *parmp); +``` + +Verifies stdin/stdout are terminals when running interactively. + +### 6. Source Startup Scripts + +```c +static void source_startup_scripts(mparm_T *parmp); +``` + +Loads scripts in this order (unless `--clean` or `-u NONE`): + +1. System-wide `.mnvrc` (e.g. `/etc/mnv/mnvrc`). +2. User `.mnvrc` (`$HOME/.mnvrc` or `$XDG_CONFIG_HOME/mnv/mnvrc`). +3. The `.gmnvrc` equivalent if GUI. +4. `defaults.mnv` (new-user defaults). + +### 7. Pre-Commands + +```c +static void exe_pre_commands(mparm_T *parmp); +``` + +Executes `--cmd` arguments. + +### 8. Edit Buffers + +```c +static void edit_buffers(mparm_T *parmp, char_u *cwd); +``` + +Opens file arguments into buffers and windows. + +### 9. Post-Commands + +```c +static void exe_commands(mparm_T *parmp); +``` + +Executes `-c` / `+` arguments. + +### 10. GUI Start + +```c +static void main_start_gui(void); +``` + +If GUI mode is detected, starts the GUI event loop. + +--- + +## MNVscript: The Built-in Scripting Language + +MNV includes a full scripting language for automation, plugins, and +configuration. Two variants exist: + +### Legacy MNVscript + +The original `:let`, `:if`, `:while`, `:function` syntax, interpreted at +runtime by `src/eval.c`. Expression parsing uses a recursive-descent parser: + +```c +static int eval0_simple_funccal(...); +static int eval2(char_u **arg, typval_T *rettv, evalarg_T *evalarg); +static int eval3(...); +// ... through eval9() +``` + +The central value type is `typval_T` (`src/structs.h`), a tagged union +supporting: + +- Numbers (`VAR_NUMBER`) +- Strings (`VAR_STRING`) +- Floats (`VAR_FLOAT`) +- Lists (`VAR_LIST`, `src/list.c`) +- Dictionaries (`VAR_DICT`, `src/dict.c`) +- Blobs (`VAR_BLOB`, `src/blob.c`) +- Tuples (`VAR_TUPLE`, `src/tuple.c`) +- Funcref / Partial (`VAR_FUNC`, `VAR_PARTIAL`) +- Jobs (`VAR_JOB`) +- Channels (`VAR_CHANNEL`) +- Classes / Objects (`VAR_CLASS`, `VAR_OBJECT`) + +Variable scoping uses namespace prefixes (`g:`, `b:`, `w:`, `t:`, `l:`, `s:`, +`v:`), managed by `src/evalvars.c`. + +Built-in functions are implemented in `src/evalfunc.c`. + +### MNV9 Script + +The modern dialect, activated by `:mnv9script` at the top of a script file or +by the `:mnv9cmd` modifier. Detection: + +```c +int +in_mnv9script(void) +{ + return (current_sctx.sc_version == SCRIPT_VERSION_MNV9 + || (cmdmod.cmod_flags & CMOD_MNV9CMD)) + && !(cmdmod.cmod_flags & CMOD_LEGACY); +} +``` + +MNV9 features: + +- **Type annotations**: `var name: string = "hello"`. +- **Compiled to bytecode**: `src/mnv9compile.c` compiles, `src/mnv9execute.c` + runs the instructions defined in `src/mnv9instr.c`. +- **Classes and interfaces**: `src/mnv9class.c` — `class`, `interface`, + `extends`, `implements`. +- **Generics**: `src/mnv9generics.c` — `<T>`, `<K, V>`. +- **Import/Export**: `src/mnv9script.c` — `import` / `export` for module + systems. +- **`def` functions**: Compiled functions replacing `function`/`endfunction`. +- **Strict mode**: variables must be declared, types are checked. + +Script version identification: + +```c +#define SCRIPT_VERSION_MAX 4 +#define SCRIPT_VERSION_MNV9 999999 +``` + +### Profiling + +When `FEAT_PROFILE` is defined, MNV can profile scripts and functions: + +``` +:profile start profile.log +:profile func * +:profile file *.mnv +``` + +Profiling is implemented in `src/profiler.c`. + +### Debugging + +MNV includes a built-in script debugger (`src/debugger.c`): + +``` +:breakadd func MyFunction +:debug call MyFunction() +``` + +--- + +## Ex Commands + +Ex commands (`:` commands) are the backbone of MNV's command-line mode. They +are defined in `src/ex_cmds.h` and dispatched by `src/ex_docmd.c`: + +```c +static char_u *do_one_cmd(...); +``` + +Command index tables in `ex_cmdidxs.h` (generated by `create_cmdidxs.mnv`) +enable fast lookup. + +### Command Execution + +Every ex command receives an `exarg_T` struct containing: + +- The command address range (line numbers). +- `:` modifiers (`:silent`, `:verbose`, `:sandbox`, `:lockmarks`, etc.). +- The command argument string. +- Flags for bang (`!`), register, count. + +### Notable Command Families + +| Family | Files | Examples | +|---|---|---| +| File operations | `ex_cmds.c` | `:write`, `:edit`, `:saveas` | +| Buffer management | `ex_cmds.c`, `buffer.c` | `:bnext`, `:bdelete`, `:buffers` | +| Window commands | `window.c` | `:split`, `:vsplit`, `:close`, `:only` | +| Script evaluation | `ex_eval.c` | `:try`, `:catch`, `:throw`, `:finally` | +| Source / Runtime | `ex_cmds2.c`, `scriptfile.c` | `:source`, `:runtime` | +| Help | `help.c` | `:help`, `:helpgrep` | +| Quickfix | `quickfix.c` | `:make`, `:copen`, `:cnext`, `:grep` | +| Autocmds | `autocmd.c` | `:autocmd`, `:doautocmd`, `:augroup` | +| Terminal | `terminal.c` | `:terminal` | +| Session | `session.c` | `:mksession`, `:mkview` | +| Diff | `diff.c` | `:diffthis`, `:diffoff`, `:diffupdate` | +| Fold | `fold.c` | `:fold`, `:foldopen`, `:foldclose` | + +--- + +## Autocommands + +`src/autocmd.c` implements the event-driven scripting system: + +``` +:autocmd BufWritePre *.c call CleanWhitespace() +:autocmd FileType python setlocal tabstop=4 +``` + +Autocommand events cover the full editor lifecycle: buffer loading, writing, +window events, filetype detection, terminal activity, cursor movement, etc. + +The `autocmd_init()` function (called early in `main()`) initialises the +autocommand tables. + +--- + +## Key Mapping + +`src/map.c` handles: + +- `:map` / `:noremap` / `:unmap` for normal mode. +- `:imap` / `:inoremap` for insert mode. +- `:cmap` / `:cnoremap` for command-line mode. +- `:vmap` / `:vnoremap` for visual mode. +- `:tmap` / `:tnoremap` for terminal mode. +- And all operator / select mode variants. + +The mapping engine integrates with `src/getchar.c` (typeahead buffer) to remap +key sequences on the fly. + +--- + +## Registers + +`src/register.c` manages: + +- Named registers (`"a` – `"z`). +- Numbered registers (`"0` – `"9`). +- Small delete register (`"-`). +- System clipboard registers (`"*`, `"+`). +- Expression register (`"=`). +- Search register (`"/`). +- Last inserted text (`".`). +- Read-only registers (`"%` filename, `"#` alternate, `":` last command). +- Black hole register (`"_`). + +The `"+` and `"*` registers bridge to the system clipboard via +`src/clipboard.c` (and on Wayland via `src/wayland.c`). + +--- + +## Configuration Files + +### `.mnvrc` + +The primary user configuration file. Sourced during startup. Can contain any +ex commands, option settings, key mappings, autocommands, and function +definitions. + +### `.gmnvrc` + +GUI-specific configuration. Sourced after `.mnvrc` when the GUI starts. + +### `.mnvinfo` + +Persistent session state across MNV invocations. Implemented in +`src/mnvinfo.c`, controlled by the `FEAT_MNVINFO` guard: + +```c +#ifdef FEAT_NORMAL +# define FEAT_MNVINFO +#endif +``` + +Stores: +- Command-line history. +- Search patterns. +- Named marks. +- Register contents. +- File marks (last cursor positions). +- Jump list. + +--- + +## The `mparm_T` Struct + +The main-parameter struct passed through all startup functions: + +```c +static mparm_T params; +``` + +Key fields: + +- `argc`, `argv` — raw command-line arguments. +- `want_full_screen` — TRUE by default. +- `use_debug_break_level` — debugger break level. +- `window_count` — number of windows requested by `-o`/`-O`. +- `clean` — `--clean` flag. +- `edit_type` — one of `EDIT_NONE`, `EDIT_FILE`, `EDIT_STDIN`, `EDIT_TAG`, + `EDIT_QF`. + +```c +#define EDIT_NONE 0 +#define EDIT_FILE 1 +#define EDIT_STDIN 2 +#define EDIT_TAG 3 +#define EDIT_QF 4 +``` + +--- + +## Standard I/O: Editing from stdin + +When MNV is invoked as part of a pipe: + +```bash +echo "hello world" | mnv - +``` + +The `read_stdin()` function reads data from standard input into the first +buffer: + +```c +static void read_stdin(void); +``` + +The `EDIT_STDIN` edit type is set in `command_line_scan()` when `-` appears as +a file argument. + +--- + +## Example Workflows + +### Quick edit from command line + +```bash +mnv +42 src/main.c # Open at line 42 +mnv -c 'set nu' file.txt # Open with line numbers +mnv -d file1.c file2.c # Diff two files +mnv -R /var/log/syslog # View log read-only +``` + +### Batch processing + +```bash +mnv -es '+%s/foo/bar/g' '+wq' file.txt +echo ":%s/old/new/g" | mnv -s file.txt +``` + +### Remote editing (client-server) + +```bash +mnv --servername MYSERVER file.c & +mnv --servername MYSERVER --remote file2.c +mnv --servername MYSERVER --remote-send ':qa!<CR>' +``` + +### Startup profiling + +```bash +mnv --startuptime startup.log file.c +``` + +--- + +*This document describes MNV 10.0 as of build 287 (2026-04-03).* |