Plugins

Plugins are Lua 5.4 files. strata loads every *.lua file and every */init.lua in ~/.config/strata/plugins/ when it starts. List names under plugins.disabled to skip some.

-- ~/.config/strata/plugins/hello.lua
strata.map("g p", function(ctx)
  strata.cd(os.getenv("HOME") .. "/projects")
end, "Go to projects")
 
strata.command("hello", function(ctx, args)
  strata.notify("hello " .. args .. " from " .. ctx.cwd)
end, "Say hello")

Installing plugins

strata plugin installs plugins from git repositories. A repository holds one plugin, with init.lua at its root or in the folder --path names:

strata plugin add someone/strata-foo              # GitHub owner/repo; installed as "foo"
strata plugin add https://example.com/x/bar.git --ref v1.2
strata plugin add someone/plugins --path baz      # one plugin from a repository with several
strata plugin list                                # installed plugins and their commits
strata plugin update                              # newest commit of each plugin's branch
strata plugin remove foo

Each plugin is copied, without its git history, to ~/.config/strata/plugins/<name>/. ~/.config/strata/plugins.toml records its source and the commit installed. Keep that file with your dotfiles and run strata plugin install on another machine to get the same plugins at the same commits. --ref follows a branch, or pins a tag or commit; without it a plugin follows the repository's default branch. Restart strata to load new plugins. You need git for all of this.

A plugin runs with your permissions, like any program you install, so add only ones you trust.

Official plugins

Enable them with plugins.enabled in the config. All but protect are on by default.

Options

If a plugin returns a table with a setup function, strata calls it with the plugin's options:

local M = {}
function M.setup(opts)          -- [plugins.options.hello] greeting = "hi"
  strata.statusline(function() return opts.greeting end)
end
return M

Context

Callbacks receive a ctx table:

API

Registration

Actions

Events

Handlers get the context and a data table describing what happened:

strata.on("rename", function(ctx, e)
  strata.notify(e.from .. " → " .. e.to)
end)

Refusing operations

before_* events fire before an operation starts. A handler cancels it by returning false (optionally followed by a reason) or { cancel = true, reason = "..." }, and the reason is shown.

Each also carries tags: a table from path to tags for the items in paths and every tagged item inside them.

strata.on("before_delete", function(ctx, e)
  for path, tags in pairs(e.tags) do
    for _, t in ipairs(tags) do
      if t == "keep" then return false, path .. " is tagged keep" end
    end
  end
end)

A handler that fails or runs longer than half a second is reported and cancels nothing. Undo and redo do not ask.

Columns and sort orders

Column and sort functions get an entry: path, name, is_dir, size, modified (epoch seconds or nil), ext and tags.

A column function returns the text and optionally a colour (muted, accent, error, warning, success, info, a tag colour, a colour name or #rrggbb). Cells are worked out only for rows on screen and kept until the listing changes. A sort function returns a key: numbers before text, nil last, ties by name; folders-first and reverse still apply (not in the tree view).

strata.column({ name = "lines", width = 6, fn = function(entry)
  if entry.is_dir or entry.size > 1e6 then return nil end
  local n = 0
  for _ in io.lines(entry.path) do n = n + 1 end
  return tostring(n), "muted"
end })
 
strata.sort({ name = "tagged", title = "Tagged first", fn = function(entry)
  return #entry.tags > 0 and 0 or 1
end })

Helpers

Lua's io, os and string libraries are available too.

The official plugins are good examples to start from.