{"id":13466585,"url":"https://github.com/skx/kilua","last_synced_at":"2025-07-11T01:09:53.289Z","repository":{"id":150430167,"uuid":"63314903","full_name":"skx/kilua","owner":"skx","description":"A minimal text-editor with lua scripting.","archived":false,"fork":false,"pushed_at":"2019-08-25T05:51:04.000Z","size":560,"stargazers_count":165,"open_issues_count":0,"forks_count":15,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-14T13:11:59.078Z","etag":null,"topics":["console-application","editor","lua","syntax-highlighting"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":"skx","custom":"https://steve.fi/donate/"}},"created_at":"2016-07-14T07:55:01.000Z","updated_at":"2025-04-11T22:26:16.000Z","dependencies_parsed_at":"2023-04-24T17:24:28.608Z","dependency_job_id":null,"html_url":"https://github.com/skx/kilua","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/skx/kilua","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fkilua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fkilua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fkilua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fkilua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skx","download_url":"https://codeload.github.com/skx/kilua/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fkilua/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264703195,"owners_count":23651917,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["console-application","editor","lua","syntax-highlighting"],"created_at":"2024-07-31T15:00:46.790Z","updated_at":"2025-07-11T01:09:53.269Z","avatar_url":"https://github.com/skx.png","language":"C++","funding_links":["https://github.com/sponsors/skx","https://steve.fi/donate/"],"categories":["C++"],"sub_categories":[],"readme":"[![license](https://img.shields.io/github/license/skx/kilua.svg)]()\n\n\n# Kilua\n\nKilua is an small, extensible, and Lua-powered text editor.\n\n[![screenshot](kilua.png)]()\n\nThe project was originally based upon the minimal [kilo editor](https://github.com/antirez/kilo) originally written by @antirez, and [introduced here on his blog](http://antirez.com/news/108), but now shares no code with that project, just ancestry.\n\nkilua was written by [Steve Kemp](https://steve.kemp.fi/) and features many updates and additions compared to the original project:\n\n* Complete handling for UTF-8 and multi-byte text.\n* The ability to open/edit/view multiple files\n   * This is done [via buffers](#buffers).\n* The addition of an embedded Lua instance.\n   * You can define functions in your [init-files](#lua-support), and invoke them via `M-x function()`.\n* Regular expression support for searching.\n* The addition of [syntax-highlighting](#syntax-highlighting) via the `lua-lpeg` library.\n    * **NOTE**: You should see the [installation](#installation) section for caveats here.\n    * Syntax-highlighting is updated in the background, when the editor is idle, to avoid stalls and redraw delays.\n    * Syntax-highlighting supports up to 256 colours, if your terminal supports them too.\n* The notion of [named marks](#bookmarks).\n* The [status bar](#status-bar) is configured via Lua.\n* Several bugfixes.\n\nLaunching `kilua` works as you would expect:\n\n    $ kilua [options] [file1] [file2] ... [fileN]\n\nOnce launched the arrow keys will move you around, and the main keybindings\nto learn are:\n\n    Ctrl-x Ctrl-o Open an existing file.\n    Ctrl-x Ctrl-f Open an existing file.\n\n    Ctrl-x Ctrl-s Save the current file.\n\n    Ctrl-x Ctrl-c Quit.\n\n    Ctrl-x c      Create a new buffer\n    Ctrl-x n      Move to the next buffer.\n    Ctrl-x p      Move to the previous buffer.\n    Ctrl-x b      Select buffer from a list\n\n    M-x           Evaluate lua at the prompt.\n\n    Ctrl-s        Regular expression search.\n\n\n\n## Command Line Options\n\nThe following command-line options are recognized and understood:\n\n* `--config file`\n    * Load the named (lua) configuration file, in addition to the defaults.\n* `--dump-config`\n    * Display the (embedded) default configuration file.\n* `--eval`\n    * Evaluate the given lua, post-load.\n* `--syntax-path`\n    * Specify the location of syntax-highlighting functions.\n* `--version`\n    * Report the version and exit.\n\n\n\n## Installation\n\nInstallation should be straight-forward, to build the code run:\n\n    make\n\nOnce built you can run the binary in a portable fashion, like so:\n\n    ./kilua --syntax-path ./syntax [options] [file1] [file2] .. [fileN]\n\nThe usage of `--syntax-path` is required to load the syntax files, but\nyou can remove the option if you copy the contents of the `./syntax/`\ndirectory to either:\n\n* `/etc/kilua/syntax/`\n* `~/.kilua/syntax/`\n\nIf you don't specify the location of the syntax-highlighting libraries,\nor you don't install them then you'll have zero syntax-highlighting support.\n\nThis is a consequence of placing the syntax-highlighting code in external\nlibraries: If you can't load those libraries then the functionality will\nnot be available.\n\n\n\n## Lua Support\n\nWe build with Lua 5.2 by default, but if you edit `src/Makefile` you\nshould also be able to build successfully with Lua 5.1.\n\nOn startup the following configuration-files are read if present:\n\n* `~/.kilua/init.lua`.\n* `./.kilua/$hostname.lua`.\n   * This is useful for those who store their dotfiles under revision control and share them across hosts.\n   * You can use the `*Messages*` buffer to see which was found, if any.\n\nIf neither file is read then the embedded copy of `kilua.lua`, which\nwas generated at build-time, will be executed, which ensures that the\nminimum functionality is present.  (i.e. If you load zero config\nfiles then there won't be any keybindings setup so you can neither\nnavigate nor edit!)\n\nIt is assumed you'll edit the [supplied startup](kilua.lua) file, to\nchange the bindings to suit your needs, add functionality via\nthe [supplied lua primitives](PRIMITIVES.md), and then copy into\n`~/.kilua/init.lua` (perhaps extending that with a per-host file too).\n\nWithout any changes you'll get a functional editor which follows my\nparticular preferences.\n\n\u003e **Pull-requests** implementing useful functionality will be received with thanks, even if just to add syntax-highlighting for additional languages.\n\n\n\n## Callbacks\n\nIn the future more callbacks might be implemented, which are functions the\nC-core calls at various points.\n\nRight now the following callbacks exist and are invoked via the C-core:\n\n* `get_status_bar()`\n    * This function is called to populate the status-bar in the footer.\n* `on_complete(str)`\n    * This function is invoked to implement TAB-completion at the prompt.\n* `on_idle()`\n    * Called roughly once a second, can be used to run background things.\n    * If this function isn't defined it will not be invoked.\n    * This is used to update syntax in the background.\n* `on_key(key)`\n    * Called to process a single key input.\n    * If this function isn't defined then input will not work, it is required.\n* `on_loaded(filename)`\n    * Called when a file is loaded.\n    * This sets up syntax highlighting in our default implementation for C and Lua files.\n    * If this function is not defined then it will not be invoked.\n* `on_save(filename)`\n    * Called __before__ a file is saved.\n    * Can be used to strip trailing whitespace, etc.\n    * If this function is not defined then it will not be invoked.\n* `on_saved(filename)`\n    * Called __after__ a file is saved.\n    * Can be used to make files executable, etc.\n    * If this function is not defined then it will not be invoked.\n\n\n\n## Buffers\n\n`kilua` allows multiple files to be opened, via the use of buffers.  If `kilua` is launched without any filename parameters there will be two buffers:\n\n* `*Messages*`\n    * This receives copies of the status-message.\n* An unnamed buffer for working with.\n    * Enter your text here, then use `Ctrl-x Ctrl-s`, or `M-x save(\"name\")`, to save it.\n\nOtherwise there will be one buffer for each file named upon the command-line,\nas well as the `*Messages*` buffer.  (You can kill the `*Messages*` buffer\nif you wish, but it's a handy thing to have around.)\n\nThe default key-bindings for working with buffers are:\n\nAction                             | Binding\n---------------------------------- | --------------\nCreate a new buffer.               | `Ctrl-x c`\nKill the current buffer.           | `Ctrl-x k`\nKill the current buffer, forcibly. | `Ctrl-x K`\nSelect the next buffer.            | `Ctrl-x n` or `M-right`\nSelect the previous buffer.        | `Ctrl-x p` or `M-left`\nChoose a buffer, via menu.         | `Ctrl-x b` or `Ctrl-x B`\n\nIt's worth noting that you can easily create buffers dynamically, via lua, for\nexample the following function can be called by `M-x uptime()`, and does\nwhat you expect:\n\n* Select the buffer with the name `*uptime*`.\n     * If that buffer doesn't exist then create it.\n* Move to the end of the buffer.\n     * Insert the output of running `/usr/bin/uptime` into the buffer.\n\nUptime sample:\n\n      -- Run `uptime`, and show the result in a dedicated buffer.\n      function uptime()\n          local result = buffer( \"*uptime*\" )\n          if ( result == -1 ) then create_buffer(\"*uptime*\") end\n          -- move to end of file.\n          eof()\n          insert(cmd_output(\"uptime\"))\n      end\n\n\n\n## Bookmarks\n\nYou can record your position (i.e. \"mark\") in a named key, and\nlater jump to it, just like in `vi`.\n\nTo record the current position use `M-m`, and press the key\nyou wish to use.  To return to it use `M-b XX` where XX was the\nkey you chose. (Marks record the buffer, as well as the current cursor-position.)\n\n\n## Status Bar\n\nThe status-bar, shown as the penultimate line in the display, contains\nthe name of the current file/buffer, as well as the cursor position, etc.\n\nThe contents of the status-bar are generated via Lua, so it is simple\nto modify.  The default display shows:\n\n     \"${buffer}/${buffers} - ${file} ${mode} ${modified} #BLANK# Col:${x} Row:${y} [${point}] ${time}\"\n\n\nValues inside \"`${...}`\" are expanded via substitutions and the following\nare provided by default:\n\nName             | Meaning\n---------------- | --------------\n`${buffers}`     | The count of open buffers.\n`${buffer}`      | The number of the current buffer.\n`${date}`        | The current date.\n`${file}`        | The name of the file/buffer.\n`${mode}`        | The syntax-highlighting mode in use, if any.\n`${modified}`    | A string that reports whether the buffer is modified.\n`${point}`       | The character under the point.\n`${time}`        | The current time.\n`${words}`       | The count of words in the buffer.\n`${x}`           | The X-coordinate of the cursor.\n`${y}`           | The Y-coordinate of the cursor.\n\n\u003e **Pull-requests** adding more options here would be most welcome.\n\n\n## Syntax Highlighting\n\nSyntax highlighting is handled via the `lua-lpeg` library, and so if\nthat is not installed it will not be available.\n\nEach buffer has an associated syntax-highlighting mode, which is a string\nsuch as \"c\", \"markdown\", or \"lua\".  The default configuration file sets\nthe mode based upon the suffix of the file you're editing.\n\nIf you wish to change the mode interactively to Lua, for example, then run:\n\n    M-x syntax(\"lua\")\n\nThe implementation of syntax highlighting requires the loading of\na library.  For example the syntax highlighting of lua requires\nthat the library `lua.lua` is loaded - The syntax modes are looked\nfor in these locations:\n\n* `/etc/kilua/syntax`\n    * Global syntax-modes.\n* `~/.kilua/syntax`\n    * Per-user syntax-modes.\n* The path specified via the `--syntax-path` command-line option.\n\nThe implementation is pretty simple:\n\n* A buffer consists of rows of text.\n     * Each row contains both the character(s) in the row and the colour of each character.\n     * The Lua function `update_colours` will allow the colour of each single character in the buffer to be set.\n\nTo avoid delays when inserting text the rendering is updated in the background,\nvia the `on_idle()` callback.  This function does the obvious thing:\n\n* Retrieves the current contents of the buffer, via `text()`.\n* Invokes the LPEG parser on it.\n    * This will generate a long string containing the colour of each byte of the text.\n* Set those colours, via `update_colours()`.\n\nAs a concrete example, if the buffer contains the string \"Steve Kemp\" then\nthe call to `update_colours` should contain:\n\n     `RED RED RED RED RED WHITE GREEN GREEN GREEN GREEN`\n\nThat would result in \"Steve\" being displayed in red, and \"Kemp\" in green.\n\nCurrently we include syntax-highlighting for:\n\n* C\n* C++\n* Go\n* HTML\n* Lua\n* Lisp\n* `Makefile`s.\n* Plain-text/markdown\n    * This is a simple implementation which only highlights URLs and trailing whitespace.\n\n\u003e **Pull-requests** adding more syntax modes would be most welcome.\n\n\n\n## Discussion on Hacker News\n\nhttps://news.ycombinator.com/item?id=12137698\n\n\n\n## The Future\n\nThere are no obvious future plans, but [bug reports](https://github.com/skx/kilua/issues) may be made if you have a feature to suggest (or bug to report)!\n\nOne thing that might be useful is a split-display, to view two files\nside by side, or one above the other.  This is not yet planned, but\nI think it could be done reasonably cleanly.\n\nSteve\n\\--\nhttps://steve.kemp.fi/\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskx%2Fkilua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskx%2Fkilua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskx%2Fkilua/lists"}