command-line

This plugin turns the status bar into a powerful command line interface for Lite XL and Pragtical. It supports custom prompts, command execution, suggestions, yes or not prompts, and easy integration with other plugins (e.g., Vim emulation). Author: S.Ghamri

Why Multiple Instances?

Using multiple command line instances (such as one for “:” commands, one for “/” search, and one for “?” reverse search) provides several advantages:

• Each instance keeps its own prompt, input history, caret position, and callback functions. This means you can switch between modes (command, search, etc.) and return to each with its previous state intact.
• For example, if you start typing a search query with ”” and then switch to command mode with “:”, your search input is preserved when you return to ””.
• Each instance can have different behaviors: the submit, suggest, and cancel functions can be tailored for each mode, making the UI more flexible and context-aware.
• This separation avoids accidental loss of user input or context when switching modes, and makes the experience more intuitive—especially for users familiar with modal editors like Vim.
• If you use only a single instance and change the prompt and callbacks, you lose separate histories and caret positions, and risk overwriting the user’s input when switching modes.

In summary: multiple instances = independent, robust, and user-friendly command line experiences for each mode.

Why This Plugin?

• Provides a unified, extensible command line interface for Lite XL and Pragtical, making the status bar interactive and programmable.
• Enables modal workflows and advanced integrations (e.g., Vim emulation, custom search, and command execution).
• Simplifies plugin development by offering a clear API for prompts, suggestions, and status bar control.
• Allows users and plugin authors to fully customize the editor’s command experience, including custom messaging and status bar visibility.
• Designed for flexibility: supports multiple independent command line instances, per-mode behaviors, and easy method wrapping.
• Makes the editor more powerful and user-friendly for both keyboard-centric and mouse-centric workflows.

Features

• Status bar becomes a command line input
• Multiple command line instances (“:”, “/”, “?”)
• Customizable prompt and status bar item name
• API for showing messages, adding status items, and controlling visibility
• Easy integration with Vim-like plugins and custom workflows
• Works with both Lite XL and Pragtical
• Confirm yes or no prompt

Install

Clone this repository into your plugins folder:

git clone <repo-url> plugins/command-line

API Reference

local command_line = require "plugins.command-line"
command_line.set_item_name("status:vim")
command_line.add_status_item()
command_line.minimal_status_view = true
command_line.show_message({"Hello, World!"}, 2)
local instance = command_line.new()
instance:set_prompt(":")

Example: Vim Integration

local command_line = require "plugins.command-line"
local instance_command = command_line.new()
instance_command:set_prompt(":")
local forward_search = command_line.new()
forward_search:set_prompt("/")
local backward_search = command_line.new()
backward_search:set_prompt("?")

function enter_command_mode()
  instance_command:start_command {
    submit = function(input)
      vim.run_command(input)
    end,
    suggest = function(input)
      return vim.get_suggests(input)
    end,
    cancel = function()
    end
  }
end

function enter_forward_search()
  forward_search:start_command {
    submit = function(input)
      vim.forward_search(input)
    end,
    suggest = function(input)
      return ""
    end,
    cancel = function()
    end
  }
end

function enter_backward_search()
  backward_search:start_command {
    submit = function(input)
      vim.backward_search(input)
    end,
    suggest = function(input)
      return ""
    end,
    cancel = function()
    end
  }
end

you can wrap start_command and cancel and execute command function to change there behavior please check how it is done in the vim plugin.

Example: Overriding Status Bar Items

command_line.minimal_status_view = true

Example: Custom Message

command_line.show_message({"-- INSERT --"}, 0)

Status Bar Control and Custom Messaging

• The plugin can clear all items from the status bar and show only the command line, using `command_line.minimal_status_view = true`.
• You can replace the status bar message with your own custom function, such as an `echo` function:

function echo(msg)
  command_line.show_message({msg}, 2) -- show for 2 seconds
end

This allows you to display any message in the status bar, either temporarily or permanently, and fully control what the user sees.

Configuration

• set_item_name(name): Set the status bar item name
• add_status_item(): Add the command line to the status bar
• minimal_status_view = true: Show only the command line in the status bar
• show_message(content, timeout): Show a message in the status bar
• new(): Create a new command line instance

Notes

• Suggestions are hints only; selecting a suggestion is not yet implemented
• You may need to restart the editor after changing minimal_status_view
• Compatible with both Lite XL and Pragtical
• Designed for extensibility and integration with other plugins

Full Example: Minimal Vim Integration

local command_line = require "plugins.command-line"
local vim = require "plugins.pragtical-vim"
local instance_command = command_line.new()
instance_command:set_prompt(":")
vim.normal_keys[":"] = function()
  vim.set_mode("command")
  instance_command:start_command {
    submit = function(input)
      vim.run_command(input)
    end,
    suggest = function(input)
      return vim.get_suggests(input)
    end,
    cancel = function()
      vim.set_mode("normal")
    end
  }
end

Example: Decorating a Command Line Instance for Vim Integration

local function decorate_with_vim(instance)
  local orig_start = instance.start_command
  function instance:start_command(opts)
    local result = orig_start(self, opts)
    vim.set_mode("command")
    return result
  end

  local orig_exec = instance.execute_or_return_command
  function instance:execute_or_return_command()
    local result = orig_exec(self)
    if not command_line.is_active() then
      vim.set_mode("normal")
    end
    return result
  end

  local orig_cancel = instance.cancel_command
  function instance:cancel_command()
    local result = orig_cancel(self)
    vim.set_mode("normal")
    return result
  end

  return instance
end

Disclaimer & Feedback

This plugin has not been extensively tested in all environments and workflows. If you encounter any issues, please open an issue on the repository and I will take care of it.

Troubleshooting

• If the command line does not appear, ensure you called add_status_item() and set the correct item name
• For custom integration, always use command_line.new() for each prompt/instance

License

MIT

Related Source

• Vim plugin for Lite XL: https://github.com/mini-lite/vim