Merge pull request #1329 from Elv13/prompt_refactor

Prompt documentation & fixes

docs/config.ld

@@ -64,6 +64,8 @@ new_type("deprecated", "Deprecated functions", false, "param")
 new_type("legacylayout", "Layout related functions", false, "param")
 -- Have a category for the client layouts
 new_type("clientlayout", "Client layouts", false, "param")
+-- Document some callback prototypes
+new_type("callback", "Callback functions prototype", false, "Parameters")
 
 -- More fitting section names
 kind_names={topic='Documentation', module='Libraries'}

lib/awful/prompt.lua

@@ -1,21 +1,52 @@
 ---------------------------------------------------------------------------
 --- Prompt module for awful.
 --
+-- **Keyboard navigation**:
+--
+-- The following readline keyboard shortcuts are implemented as expected:
+-- <table class='widget_list' border=1>
+--   <tr><th>Name</th><th>Usage</th></tr>
+--   <tr><td><kbd>CTRL+A</kbd></td><td>beginning-of-line</td></tr>
+--   <tr><td><kbd>CTRL+B</kbd></td><td>backward-char</td></tr>
+--   <tr><td><kbd>CTRL+C</kbd></td><td>cancel</td></tr>
+--   <tr><td><kbd>CTRL+D</kbd></td><td>delete-char</td></tr>
+--   <tr><td><kbd>CTRL+E</kbd></td><td>end-of-line</td></tr>
+--   <tr><td><kbd>CTRL+J</kbd></td><td>accept-line</td></tr>
+--   <tr><td><kbd>CTRL+M</kbd></td><td>accept-line</td></tr>
+--   <tr><td><kbd>CTRL+F</kbd></td><td>move-cursor-right</td></tr>
+--   <tr><td><kbd>CTRL+H</kbd></td><td>backward-delete-char</td></tr>
+--   <tr><td><kbd>CTRL+K</kbd></td><td>kill-line</td></tr>
+--   <tr><td><kbd>CTRL+U</kbd></td><td>unix-line-discard</td></tr>
+--   <tr><td><kbd>CTRL+W</kbd></td><td>unix-word-rubout</td></tr>
+--   <tr><td><kbd>CTRL+BACKSPACE</kbd></td><td>unix-word-rubout</td></tr>
+--   <tr><td><kbd>SHIFT+INSERT</kbd></td><td>paste</td></tr>
+--   <tr><td><kbd>HOME</kbd></td><td>beginning-of-line</td></tr>
+--   <tr><td><kbd>END</kbd></td><td>end-of-line</td></tr>
+-- </table>
+--
+-- The following shortcuts implement additional history manipulation commands
+-- where the search term is defined as the substring of the command from first
+-- character to cursor position.
+--
+-- * <kbd>CTRL+R</kbd>: reverse history search, matches any history entry
+-- containing search term.
+-- * <kbd>CTRL+S</kbd>: forward history search, matches any history entry
+-- containing search term.
+-- * <kbd>CTRL+UP</kbd>: ZSH up line or search, matches any history entry
+-- starting with search term.
+-- * <kbd>CTRL+DOWN</kbd>: ZSH down line or search, matches any history
+-- entry starting with search term.
+-- * <kbd>CTRL+DELETE</kbd>: delete the currently visible history entry from
+-- history file. This does not delete new commands or history entries under
+-- user editing.
+--
+-- **Basic usage**:
+--
 -- By default, `rc.lua` will create one `awful.widget.prompt` per screen called
 -- `mypromptbox`. It is used for both the command execution (`mod4+r`) and
 -- Lua prompt (`mod4+x`). It can be re-used for random inputs using:
 --
---    -- Create a shortcut function
+-- @DOC_wibox_awidget_prompt_simple_EXAMPLE@
---    local function echo_test()
---        awful.prompt.run {
---            prompt       = "Echo: ",
---            textbox      = mouse.screen.mypromptbox.widget,
---            exe_callback = function(input)
---                if not input or #input == 0 then return end
---                naughty.notify{ text = "The input was: "..input }
---            end
---        }
---    end
 --
 --     -- Then **IN THE globalkeys TABLE** add a new shortcut
 --     awful.key({ modkey }, "e", echo_test,
@@ -24,6 +55,40 @@
 -- Note that this assumes an `rc.lua` file based on the default one. The way
 -- to access the screen prompt may vary.
 --
+-- **Extra key hooks**:
+--
+-- The Awesome prompt also supports adding custom extensions to specific
+-- keyboard keybindings. Those keybindings have precedence over the built-in
+-- ones. Therefor, they can be used to override the default ones.
+--
+-- *[Example one] Adding pre-configured `awful.spawn` commands:*
+--
+-- @DOC_wibox_awidget_prompt_hooks_EXAMPLE@
+--
+-- *[Example two] Modifying the command (+ vi like input)*:
+--
+-- The hook system also allows to modify the command before interpreting it in
+-- the `exe_callback`.
+--
+-- @DOC_wibox_awidget_prompt_vilike_EXAMPLE@
+--
+-- *[Example three] Key listener*:
+--
+-- The 2 previous examples were focused on changing the prompt behavior. This
+-- one explains how to "spy" on the prompt events. This can be used for
+--
+-- * Implementing more complex mutator
+-- * Synchronising other widgets
+-- * Showing extra tips to the user
+--
+-- @DOC_wibox_awidget_prompt_keypress_EXAMPLE@
+--
+-- **highlighting**:
+--
+-- The prompt also support custom highlighters:
+--
+-- @DOC_wibox_awidget_prompt_highlight_EXAMPLE@
+--
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008 Julien Danjou
 -- @module awful.prompt
@@ -214,37 +279,100 @@ local function prompt_text_with_cursor(args)
     local cursor_color = util.ensure_pango_color(args.cursor_color)
     local text_color = util.ensure_pango_color(args.text_color)
 
+    if args.highlighter then
+        text_start, text_end = args.highlighter(text_start, text_end)
+    end
+
     ret = _prompt .. text_start .. "<span background=\"" .. cursor_color ..
         "\" foreground=\"" .. text_color .. "\" underline=\"" .. underline ..
         "\">" .. char .. "</span>" .. text_end .. spacer
     return ret
 end
 
+--- The callback function to call with command as argument when finished.
+-- @usage local function my_exe_cb(command)
+--    -- do something
+-- end
+-- @callback exe_callback
+-- @tparam string command The command (as entered).
+
+--- The callback function to call to get completion.
+-- @usage local function my_completion_cb(command_before_comp, cur_pos_before_comp, ncomp)
+--    return command_before_comp.."foo", cur_pos_before_comp+3, 1
+-- end
+--
+-- @callback completion_callback
+-- @tparam string command_before_comp The current command.
+-- @tparam number cur_pos_before_comp The current cursor position.
+-- @tparam number ncomp The number of completion elements.
+-- @treturn string command
+-- @treturn number cur_pos
+-- @treturn number matches
+
+--- The callback function to always call without arguments, regardless of
+-- whether the prompt was cancelled.
+-- @usage local function my_done_cb()
+--    -- do something
+-- end
+-- @callback done_callback
+
+---  The callback function to call with command as argument when a command was
+-- changed.
+-- @usage local function my_changed_cb(command)
+--    -- do something
+-- end
+-- @callback changed_callback
+-- @tparam string command The current command.
+
+--- The callback function to call with mod table, key and command as arguments
+-- when a key was pressed.
+-- @usage local function my_keypressed_cb(mod, key, command)
+--    -- do something
+-- end
+-- @callback keypressed_callback
+-- @tparam table mod The current modifiers (like "Control" or "Shift").
+-- @tparam string key The key name.
+-- @tparam string command The current command.
+
+--- The callback function to call with mod table, key and command as arguments
+-- when a key was released.
+-- @usage local function my_keyreleased_cb(mod, key, command)
+--    -- do something
+-- end
+-- @callback keyreleased_callback
+-- @tparam table mod The current modifiers (like "Control" or "Shift").
+-- @tparam string key The key name.
+-- @tparam string command The current command.
+
+--- A function to add syntax highlighting to the command.
+-- @usage local function my_highlighter(before_cursor, after_cursor)
+--    -- do something
+--    return before_cursor, after_cursor
+-- end
+-- @callback highlighter
+-- @tparam string before_cursor
+-- @tparam string after_cursor
+
+--- A callback when a key combination is triggered.
+-- This callback can return many things:
+--
+-- * a modified command
+-- * `true` If the command is successful (then it won't exit)
+-- * nothing or `nil` to execute the `exe_callback` and `done_callback` and exit
+--
+-- An optional second return value controls if the prompt should exit or simply
+-- update the command (from the first return value) and keep going. The default
+-- is to execute the `exe_callback` and `done_callback` before exiting.
+--
+-- @usage local function my_hook(command)
+--    return command.."foo", false
+-- end
+--
+-- @callback hook
+-- @tparam string command The current command.
+
 --- Run a prompt in a box.
 --
--- The following readline keyboard shortcuts are implemented as expected:
--- <kbd>CTRL+A</kbd>, <kbd>CTRL+B</kbd>, <kbd>CTRL+C</kbd>, <kbd>CTRL+D</kbd>,
--- <kbd>CTRL+E</kbd>, <kbd>CTRL+J</kbd>, <kbd>CTRL+M</kbd>, <kbd>CTRL+F</kbd>,
--- <kbd>CTRL+H</kbd>, <kbd>CTRL+K</kbd>, <kbd>CTRL+U</kbd>, <kbd>CTRL+W</kbd>,
--- <kbd>CTRL+BACKSPACE</kbd>, <kbd>SHIFT+INSERT</kbd>, <kbd>HOME</kbd>,
--- <kbd>END</kbd> and arrow keys.
---
--- The following shortcuts implement additional history manipulation commands
--- where the search term is defined as the substring of the command from first
--- character to cursor position.
---
--- * <kbd>CTRL+R</kbd>: reverse history search, matches any history entry
--- containing search term.
--- * <kbd>CTRL+S</kbd>: forward history search, matches any history entry
--- containing search term.
--- * <kbd>CTRL+UP</kbd>: ZSH up line or search, matches any history entry
--- starting with search term.
--- * <kbd>CTRL+DOWN</kbd>: ZSH down line or search, matches any history
--- entry starting with search term.
--- * <kbd>CTRL+DELETE</kbd>: delete the currently visible history entry from
--- history file. This does not delete new commands or history entries under
--- user editing.
---
 -- @tparam[opt={}] table args A table with optional arguments
 -- @tparam[opt] gears.color args.fg_cursor
 -- @tparam[opt] gears.color args.bg_cursor
@@ -255,6 +383,8 @@ end
 -- @tparam[opt] string args.font
 -- @tparam[opt] boolean args.autoexec
 -- @tparam widget args.textbox The textbox to use for the prompt.
+-- @tparam[opt] function args.highlighter A function to add syntax highlighting to
+--  the command.
 -- @tparam function args.exe_callback The callback function to call with command as argument
 -- when finished.
 -- @tparam function args.completion_callback The callback function to call to get completion.
@@ -325,6 +455,7 @@ function prompt.run(args, textbox, exe_callback, completion_callback,
     local text = args.text or ""
     local font = args.font or theme.font
     local selectall = args.selectall
+    local highlighter = args.highlighter
     local hooks = {}
 
     -- A function with 9 parameters deserve to die
@@ -409,7 +540,7 @@ function prompt.run(args, textbox, exe_callback, completion_callback,
     textbox:set_markup(prompt_text_with_cursor{
         text = text, text_color = inv_col, cursor_color = cur_col,
         cursor_pos = cur_pos, cursor_ul = cur_ul, selectall = selectall,
-        prompt = prettyprompt })
+        prompt = prettyprompt, highlighter =  highlighter})
 
     local function exec(cb, command_to_history)
         textbox:set_markup("")
@@ -425,7 +556,7 @@ function prompt.run(args, textbox, exe_callback, completion_callback,
         textbox:set_markup(prompt_text_with_cursor{
                                text = command, text_color = inv_col, cursor_color = cur_col,
                                cursor_pos = cur_pos, cursor_ul = cur_ul, selectall = selectall,
-                               prompt = prettyprompt })
+                               prompt = prettyprompt, highlighter =  highlighter })
     end
 
     grabber = keygrabber.run(
@@ -485,16 +616,33 @@ function prompt.run(args, textbox, exe_callback, completion_callback,
                     end
                     if match then
                         local cb
-                        local ret = v[3](command)
+                        local ret, quit = v[3](command)
                         local original_command = command
-                        if ret then
+
-                            command = ret
+                        -- Support both a "simple" and a "complex" way to
+                        -- control if the prompt should quit.
+                        quit = quit == nil and (ret ~= true) or (quit~=false)
+
+                        -- Allow the callback to change the command
+                        command = (ret ~= true) and ret or command
+
+                        -- Quit by default, but allow it to be disabled
+                        if ret and type(ret) ~= "boolean" then
                             cb = exe_callback
-                        else
+                            if not quit then
+                                cur_pos = ret:wlen() + 1
+                                update()
+                            end
+                        elseif quit then
                             -- No callback.
                             cb = function() end
                         end
+
+                        -- Execute the callback
+                        if cb then
                             exec(cb, original_command)
+                        end
+
                         return
                     end
                 end

lib/gears/timer.lua

@@ -1,6 +1,48 @@
 ---------------------------------------------------------------------------
 --- Timer objects and functions.
 --
+-- @usage
+--    -- Create a widget and update its content using the output of a shell
+--    -- command every 10 seconds:
+--    local mybatterybar = wibox.widget {
+--        {
+--            min_value    = 0,
+--            max_value    = 100,
+--            value        = 0,
+--            paddings     = 1,
+--            border_width = 1,
+--            forced_width = 50,
+--            border_color = "#0000ff",
+--            id           = "mypb",
+--            widget       = wibox.widget.progressbar,
+--        },
+--        {
+--            id           = "mytb",
+--            text         = "100%",
+--            widget       = wibox.widget.textbox,
+--        },
+--        layout      = wibox.layout.stack,
+--        set_battery = function(self, val)
+--            self.mytb.text  = tonumber(val).."%"
+--            self.mypb.value = tonumber(val)
+--        end,
+--    }
+--
+--    gears.timer {
+--        timeout   = 10,
+--        autostart = true,
+--        callback  = function()
+--            -- You should read it from `/sys/class/power_supply/` (on Linux)
+--            -- instead of spawning a shell. This is only an example.
+--            awful.spawn.easy_async(
+--                {"sh", "-c", "acpi | sed -n 's/^.*, \([0-9]*\)%/\1/p'"},
+--                function(out)
+--                    mybatterybar.battery = out
+--                end
+--            )
+--        end
+--    }
+--
 -- @author Uli Schlachter
 -- @copyright 2014 Uli Schlachter
 -- @classmod gears.timer
@@ -104,9 +146,14 @@ local timer_instance_mt = {
 --- Create a new timer object.
 -- @tparam table args Arguments.
 -- @tparam number args.timeout Timeout in seconds (e.g. 1.5).
+-- @tparam[opt=false] boolean args.autostart Automatically start the timer.
+-- @tparam[opt=nil] function args.callback Callback function to connect to the
+--  "timeout" signal.
+-- @tparam[opt=false] boolean args.single_shot Run only once then stop.
 -- @treturn timer
 -- @function gears.timer
-timer.new = function(args)
+function timer.new(args)
+    args = args or {}
     local ret = object()
 
     ret.data = { timeout = 0 }
@@ -116,6 +163,18 @@ timer.new = function(args)
         ret[k] = v
     end
 
+    if args.autostart then
+        ret:start()
+    end
+
+    if args.callback then
+        ret:connect_signal("timeout", args.callback)
+    end
+
+    if args.single_shot then
+        ret:connect_signal("timeout", function() ret:stop() end)
+    end
+
     return ret
 end
 

tests/examples/shims/_common_template.lua

@@ -1,7 +1,13 @@
+-- luacheck: globals string
+function string.wlen(self)
+    return #self
+end
+
 return function(_, _)
 
     -- Set the global shims
     -- luacheck: globals awesome root tag screen client mouse drawin button
+    -- luacheck: globals mousegrabber keygrabber
     awesome      = require( "awesome"      )
     root         = require( "root"         )
     tag          = require( "tag"          )
@@ -10,6 +16,8 @@ return function(_, _)
     mouse        = require( "mouse"        )
     drawin       = require( "drawin"       )
     button       = require( "button"       )
+    keygrabber   = require( "keygrabber"   )
+    mousegrabber = require( "mousegrabber" )
 
     -- Force luacheck to be silent about setting those as unused globals
     assert(awesome and root and tag and screen and client and mouse)

tests/examples/shims/beautiful.lua

@@ -51,6 +51,10 @@ function module.get_font()
     return f
 end
 
+function module.get()
+    return module
+end
+
 return module
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/shims/keygrabber.lua

@@ -0,0 +1,11 @@
+
+local keygrabber = {
+    run = function() end,
+    stop = function() end,
+    is_running = function() return false end,
+}
+
+
+return keygrabber
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/shims/mousegrabber.lua

@@ -0,0 +1,9 @@
+local mousegrabber = {
+    run = function() end,
+    stop = function() end,
+    is_running = function() return false end,
+}
+
+return mousegrabber
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/awidget/prompt/highlight.lua

@@ -0,0 +1,66 @@
+local parent    = ... --DOC_NO_USAGE --DOC_HIDE
+local wibox     = require( "wibox"     ) --DOC_HIDE
+local awful     = { prompt = require("awful.prompt") }--DOC_HIDE
+local beautiful = require( "beautiful" ) --DOC_HIDE
+
+    local amp = "&amp"..string.char(0x3B)
+    local quot = "&quot"..string.char(0x3B)
+
+    local atextbox = wibox.widget.textbox()
+
+    -- Create a shortcut function
+    local function echo_test()
+        awful.prompt.run {
+            prompt       = "<b>Echo: </b>",
+            text         = 'a_very "nice" $SHELL && command', --DOC_HIDE
+            bg_cursor    = "#ff0000",
+            -- To use the default `rc.lua` prompt:
+            --textbox      = mouse.screen.mypromptbox.widget,
+            textbox      = atextbox,
+            highlighter  = function(b, a)
+                -- Add a random marker to delimitate the cursor
+                local cmd = b.."ZZZCURSORZZZ"..a
+
+                -- Find shell variables
+                local sub = "<span foreground='#CFBA5D'>%1</span>"
+                cmd = cmd:gsub("($[A-Za-z][a-zA-Z0-9]*)", sub)
+
+                -- Highlight " && "
+                sub = "<span foreground='#159040'>%1</span>"
+                cmd = cmd:gsub("( "..amp..amp..")", sub)
+
+                -- Highlight double quotes
+                local quote_pos = cmd:find("[^\\]"..quot)
+                while quote_pos do
+                    local old_pos = quote_pos
+                    quote_pos = cmd:find("[^\\]"..quot, old_pos+2)
+
+                    if quote_pos then
+                        local content = cmd:sub(old_pos+1, quote_pos+6)
+                        cmd = table.concat({
+                                cmd:sub(1, old_pos),
+                                "<span foreground='#2977CF'>",
+                                content,
+                                "</span>",
+                                cmd:sub(quote_pos+7, #cmd)
+                        }, "")
+                        quote_pos = cmd:find("[^\\]"..quot, old_pos+38)
+                    end
+                end
+
+                -- Split the string back to the original content
+                -- (ignore the recursive and escaped ones)
+                local pos = cmd:find("ZZZCURSORZZZ")
+                b,a = cmd:sub(1, pos-1), cmd:sub(pos+12, #cmd)
+                return b,a
+            end,
+        }
+    end
+
+echo_test() --DOC_HIDE
+
+parent:add( wibox.widget {    --DOC_HIDE
+    atextbox,  --DOC_HIDE
+    bg = beautiful.bg_normal,  --DOC_HIDE
+    widget = wibox.container.background  --DOC_HIDE
+}) --DOC_HIDE

tests/examples/wibox/awidget/prompt/hooks.lua

@@ -0,0 +1,63 @@
+local parent    = ... --DOC_NO_USAGE --DOC_HIDE
+local wibox     = require( "wibox"     ) --DOC_HIDE
+local awful     = { prompt = require("awful.prompt"),--DOC_HIDE
+                    util   = require("awful.util")}--DOC_HIDE
+local beautiful = require( "beautiful" ) --DOC_HIDE
+
+    local atextbox = wibox.widget.textbox()
+
+    -- Custom handler for the return value. This implementation does nothing,
+    -- but you might want be notified of the failure, so it is part of this
+    -- example.
+    local function clear(result)
+        atextbox.widget.text =
+            type(result) == "string" and result or ""
+    end
+
+    local hooks = {
+        -- Replace the "normal" `Return` with a custom one
+        {{         }, "Return", awful.spawn},
+
+        -- Spawn method to spawn in the current tag
+        {{"Mod1"   }, "Return", function(command)
+            clear(awful.spawn(command,{
+                intrusive = true,
+                tag       = mouse.screen.selected_tag
+            }))
+        end},
+
+        -- Spawn in the current tag as floating and on top
+        {{"Shift"  }, "Return", function(command)
+            clear(awful.spawn(command,{
+                ontop     = true,
+                floating  = true,
+                tag       = mouse.screen.selected_tag
+            }))
+        end},
+
+        -- Spawn in a new tag
+        {{"Control"}, "Return", function(command)
+            clear(awful.spawn(command,{
+                new_tag = true
+            }))
+        end},
+
+        -- Cancel
+        {{         }, "Escape", function(_)
+            clear()
+        end},
+    }
+
+    awful.prompt.run {
+        prompt        = "<b>Run: </b>",
+        hooks         = hooks,
+        textbox       = atextbox,
+        history_path  = awful.util.getdir("cache") .. "/history",
+        done_callback = clear,
+    }
+
+parent:add( wibox.widget {    --DOC_HIDE
+    atextbox,  --DOC_HIDE
+    bg = beautiful.bg_normal,  --DOC_HIDE
+    widget = wibox.container.background  --DOC_HIDE
+}) --DOC_HIDE

tests/examples/wibox/awidget/prompt/keypress.lua

@@ -0,0 +1,33 @@
+local parent    = ... --DOC_NO_USAGE --DOC_HIDE
+local wibox     = require( "wibox"     ) --DOC_HIDE
+local awful     = { prompt = require("awful.prompt"),--DOC_HIDE
+                    util   = require("awful.util"),--DOC_HIDE
+                    screen = require("awful.screen")}--DOC_HIDE
+local beautiful = require( "beautiful" ) --DOC_HIDE
+local naughty   = {} --DOC_HIDE
+
+    local atextbox = wibox.widget.textbox()
+
+    local notif = nil
+    awful.prompt.run {
+        prompt               = "<b>Run: </b>",
+        keypressed_callback  = function(mod, key, cmd) --luacheck: no unused args
+            if key == "Shift_L" then
+                notif = naughty.notify { text = "Shift pressed" }
+            end
+        end,
+        keyreleased_callback = function(mod, key, cmd) --luacheck: no unused args
+            if notif then
+                naughty.destroy(notif)
+                notif = nil
+            end
+        end,
+        textbox              = atextbox,
+        history_path         = awful.util.getdir("cache") .. "/history",
+    }
+
+parent:add( wibox.widget {    --DOC_HIDE
+    atextbox,  --DOC_HIDE
+    bg = beautiful.bg_normal,  --DOC_HIDE
+    widget = wibox.container.background  --DOC_HIDE
+}) --DOC_HIDE

tests/examples/wibox/awidget/prompt/simple.lua

@@ -0,0 +1,31 @@
+local parent    = ... --DOC_NO_USAGE --DOC_HIDE
+local wibox     = require( "wibox"     ) --DOC_HIDE
+local awful     = { prompt = require("awful.prompt") }--DOC_HIDE
+local beautiful = require( "beautiful" ) --DOC_HIDE
+local naughty   = {} --DOC_HIDE
+
+    local atextbox = wibox.widget.textbox()
+
+    -- Create a shortcut function
+    local function echo_test()
+        awful.prompt.run {
+            prompt       = "<b>Echo: </b>",
+            text         = "default command",
+            bg_cursor    = "#ff0000",
+            -- To use the default `rc.lua` prompt:
+            --textbox      = mouse.screen.mypromptbox.widget,
+            textbox      = atextbox,
+            exe_callback = function(input)
+                if not input or #input == 0 then return end
+                naughty.notify{ text = "The input was: "..input }
+            end
+        }
+    end
+
+echo_test() --DOC_HIDE
+
+parent:add( wibox.widget {    --DOC_HIDE
+    atextbox,  --DOC_HIDE
+    bg = beautiful.bg_normal,  --DOC_HIDE
+    widget = wibox.container.background  --DOC_HIDE
+}) --DOC_HIDE

tests/examples/wibox/awidget/prompt/vilike.lua

@@ -0,0 +1,55 @@
+local parent    = ... --DOC_NO_USAGE --DOC_HIDE
+local wibox     = require( "wibox"     ) --DOC_HIDE
+local awful     = { prompt = require("awful.prompt"),--DOC_HIDE
+                    util   = require("awful.util")}--DOC_HIDE
+local beautiful = require( "beautiful" ) --DOC_HIDE
+local terminal  = "xterm"  --DOC_HIDE
+
+    local atextbox = wibox.widget.textbox()
+
+    -- Store a list of verbs characters in a hash
+    local verbs = {
+        -- Spawn in a terminal
+        t = function(adjs, count, cmd) return {terminal, "-e", cmd} end,  --luacheck: no unused args
+        -- Spawn with a shell
+        s = function(adjs, count, cmd) return {awful.util.shell, '-c', cmd} end, --luacheck: no unused args
+    }
+
+    local function vi_parse(action, command)
+        local req, ret = {count={}, adjectives={}}
+        -- Quite dumb, don't do something like <num>+<adj>+<num>+<verb>
+        for char in action:gmatch('(.)') do
+            if     tonumber(char)  then table.insert(req.count, char)
+            elseif verbs[char]     then req.verb = char
+            else   table.insert(ret.adjectives, char) end
+            if req.verb then
+                req.count = tonumber(table.concat(req.count)) or 1
+                ret = ret or verbs[req.verb](req.adjectives, req.count, command)
+                req = {count={}, adjectives={}}
+            end
+        end
+        return ret
+    end
+
+    awful.prompt.run {
+        prompt       = '<b>Run: </b>',
+        text         = ':t htop', --DOC_HIDE
+        hooks        = {
+            {{},'Return', function(cmd)
+                if (not cmd) or cmd:sub(1,1) ~= ':' then return cmd end
+                local act, cmd2 = cmd:gmatch(':([a-zA-Z1-9]+)[ ]+(.*)')()
+                if not act then return cmd end
+                return vi_parse(act, cmd2)
+            end},
+        },
+        textbox      = atextbox,
+        history_path = awful.util.getdir('cache') .. '/history',
+        exe_callback = function(cmd) awful.spawn(cmd) end
+    }
+
+
+parent:add( wibox.widget {    --DOC_HIDE
+    atextbox,  --DOC_HIDE
+    bg = beautiful.bg_normal,  --DOC_HIDE
+    widget = wibox.container.background  --DOC_HIDE
+}) --DOC_HIDE