# Lua Function Calls

xplr allows you to define lua functions using the `xplr.fn.custom` Lua API.

These functions can be called using messages like `CallLua`, `CallLuaSilently`.

When called the function receives a special argument that contains some useful information. The function can optionally return a list of messages which will be handled by xplr.

## Example: Using Lua Function Calls

    -- Define the function
    xplr.fn.custom.ask_name_and_greet = function(app)
      print("What's your name?")

      local name = io.read()
      local greeting = "Hello " .. name .. "!"
      local message = greeting .. " You are inside " .. app.pwd

      return {
        { LogSuccess = message },
      }
    end

    -- Map the function to a key (space)
    xplr.config.modes.builtin.default.key_bindings.on_key.space = {
      help = "ask name and greet",
      messages = {
        { CallLua = "custom.ask_name_and_greet" }
      }
    }

    -- Now, when you press "space" in default mode, you will be prompted for your
    -- name. Enter your name to receive a nice greeting and to know your location.

Visit the xplr.util API docs for some useful utility / helper functions that you can use in your Lua function calls.

## Lua Context

This is a special argument passed to the lua functions when called using the `CallLua`, `CallLuaSilently` messages.

It contains the following information:

- version
- pwd
- initial_pwd
- vroot
- focused_node
- directory_buffer
- selection
- mode
- layout
- input_buffer
- pid
- session_path
- explorer_config
- history
- last_modes

### version

Type: string

xplr version. Can be used to test compatibility.

### pwd

Type: string

The present working directory.

### initial_pwd

Type: string

The initial working directory when xplr started.

### vroot

Type: nullable string

The current virtual root.

### focused_node

Type: nullable Node

The node under focus.

### directory_buffer

Type: nullable Directory Buffer

The directory buffer being rendered.

### selection

Type: list of selected Nodes

The selected nodes.

### mode

Type: Mode

Current mode.

### layout

Type: Layout

Current layout.

### input_buffer

Type: nullable string

The input buffer.

### pid

Type: integer

The xplr session PID.

### session_path

Type: string

The session path.

### explorer_config

Type: Explorer Config

The configuration for exploring paths.

### history

Type: History

### last_modes

Type: list of Mode

Last modes, not popped yet.

## Node

A node contains the following fields:

- parent
- relative_path
- absolute_path
- extension
- is_symlink
- is_broken
- is_dir
- is_file
- is_readonly
- mime_essence
- size
- human_size
- permissions
- created
- last_modified
- uid
- gid
- canonical
- symlink

### parent

Type: string

The parent path of the node.

### relative_path

Type: string

The path relative to the parent, i.e. the file/directory name with extension.

### absolute_path

Type: string

The absolute path (without resolving symlinks) of the node.

### extension

Type: string

The extension of the node.

### is_symlink

Type: boolean

`true` if the node is a symlink.

### is_broken

Type: boolean

`true` if the node is a broken symlink.

### is_dir

Type: boolean

`true` if the node is a directory.

### is_file

Type: boolean

`true` if the node is a file.

### is_readonly

Type: boolean

`true` if the node is real-only.

### mime_essence

Type: string

The mime type of the node. For e.g. `text/csv`, `image/jpeg` etc.

### size

Type: integer

The size of the exact node. The size of a directory won't be calculated recursively.

### human_size

Type: string

Like size but in human readable format.

### permissions

Type: Permission

The permissions applied to the node.

### created

Type: nullable integer

Creation time in nanosecond since UNIX epoch.

### last_modified

Type: nullable integer

Last modification time in nanosecond since UNIX epoch.

### uid

Type: integer

User ID of the file owner.

### gid

Type: integer

Group ID of the file owner.

### canonical

Type: nullable Resolved Node Metadata

If the node is a symlink, it will hold information about the symlink resolved node. Else, it will hold information the actual node. It the symlink is broken, it will be null.

### symlink

Type: nullable Resolved Node Metadata

If the node is a symlink and is not broken, it will hold information about the symlink resolved node. However, it will never hold information about the actual node. It will instead be null.

## Directory Buffer

Directory buffer contains the following fields:

- parent
- nodes
- total
- focus

### parent

Type: string

The parent path of the node.

### nodes

Type: list of Nodes

A list of visible nodes.

### total

Type: int

The count of nodes being rendered.

### focus

Type: int

The index of the node under focus. It can be `0` even when there's no node to focus on.

## History

History contains the following fields:

- loc
- paths

### loc

Type: int

Location of the current path in history.

### paths

Type: list of string

Visited paths.

## Explorer Config

Explorer config contains the following fields:

- filters
- sorters
- searcher

### filters

List of filters to apply.

Type: list of Node Filter Applicable

### sorters

Add list or sorters to the pipeline.

Type: list of Node Sorter Applicable

### searcher

The searcher to use (if any).

Type: nullable Node Searcher Applicable

## Also See:

- xplr.util