Module `wf.ipc`

The third argument is a function to handle the command. This function is given as its arguments when it is called a Promise and an array of command arguments.

Usage:

-- An example "request-response" command.
-- Can be run with 'wf-msg wait_for <APPID>'.

local wf_ipc = require('wf.ipc')

wf_ipc.def_cmd {
    'wait_for', [[
Wait for a view with the given app id to be mapped.

USAGE:
    wait_for <APPID>

A message will be returned saying 'View mapped!' followed by the title of the
mapped view.
]], function(promise, args)
        if #args == 0 then
            promise:reject_invalid_arguments('No arguments given.')
            return
        end

        local handler
        handler = wf.outputs:hook('view-mapped', function(output, data)
            if data.view:get_app_id() == args[1] then
                promise:resolve('View mapped! ' .. data.view:get_title())
                wf.outputs:unhook('view-mapped', handler)
            end
        end)

        -- Clean up if the client shutsdown the connection before the command
        -- is resolved.
        promise:hook_cancel(function()
            print('Promise cancelled. Cleaning up.')
            wf.outputs:unhook('view-mapped', handler)
        end)
    end
}

-- An example "watcher" command.
-- Can be run with 'wf-msg watch_for <APPID>'.

local wf_ipc = require('wf.ipc')

wf_ipc.def_cmd {
    'watch_for', [[
Watch for views with the given app id to be mapped.

USAGE:
    watch_for <APPID>

A message will be sent saying 'View mapped!' followed by the title of the
mapped view.
]], function(promise, args)
        if #args == 0 then
            promise:reject_invalid_arguments('No arguments given.')
            return
        end

        promise:begin_notifications()

        local handler
        handler = wf.outputs:hook('view-mapped', function(output, data)
            if data.view:get_app_id() == args[1] then
                promise:notify('View mapped! ' .. data.view:get_title())
            end
        end)

        -- Clean up when the client shutsdown the connection.
        promise:hook_cancel(function()
            print('Promise cancelled. Cleaning up.')
            wf.outputs:unhook('view-mapped', handler)
        end)
    end
}

Class Promise

An ipc command promise.

An ipc command is either a simple 'request-response' command or a 'watcher' command. The command should go as follows:

For 'request-response' commands: The command must only resolve or reject the promise. The command may resolve or reject at any time.
For 'watcher' commands: The command must first Promise:begin_notifications before then sending any amount of notifications at any time. The command may Promise:end_notifications to signal the end of the notification stream. The command may reject only before the call to Promise:begin_notifications.

In both types of command, the promise will be cancelled in the event of a connection drop. This event can be listened for with the Promise:hook_cancel method.

function Promise:resolve(result_: string) line 54

Resolve the promise sending a result string to the client.

function Promise:begin_notifications() line 62

Signal the begining of the notification stream.

function Promise:end_notifications() line 72

Signal the end of the notification stream.

function Promise:notify(notification: string) line 82

Send a notification message.

function Promise:reject(result_: string) line 103

Reject the promise with an error message.

function Promise:reject_invalid_arguments(msg: string) line 111

Reject the promise because of invalid arguments.

function Promise:hook_cancel(handler: fn()) line 125

Hook into the promise being cancelled.

A promise can be cancelled if the connection to the client drops while the promise is still pending. It is useful to hook into this event in order to cleanly cancel any pending state for the command.

function Promise:unhook_cancel(handler: fn()) line 133

Unhook from the promise being cancelled.

Module wf.ipc

Info:

Functions

Class Promise

Functions

Usage:

Class Promise

Module `wf.ipc`