API

Overview

iceberg uses Lua as a configuration and an extension language. Users can extend the functionality by using lua scripts. icebergsupport package has many APIs for extending iceberg.

Charcter encodings

iceberg uses UTF-8 as an internal encoding, so most APIs accept and return UTF-8 encoded strings. However, icebergsupport.command_output() returns a string output by the command without any character encoding conversion.

Lua does not have multibyte aware string APIs. If you want to correctly iterate over actual characters in a UTF-8 encoded string, you have to use regular expression APIs in the icebergsupport package.

Constants

icebergsupport.EVENT_STATE_*

Constants used for icebergsupport.matches_key() etc. Please refer to icebergsupport.matches_key() for further information.

icebergsupport.COMP_*

Constants mean completion methods.

  • COMP_BEGINSWITH : prefix match
  • COMP_PARTIAL : partial match
  • COMP_ABBR : fuzzy match

Functions

Paths

icebergsupport.dirname(path)

Returns the directory name of the pathname path .

Arguments:
  • path (string) – the path
Returns:

string
icebergsupport.basename(path)

Returns the base name of pathname path .

Arguments:
  • path (string) – the path
Returns:

string
icebergsupport.directory_exists(path)

Returns true if path refers to an existing directory.

Arguments:
  • path (string) – the path
Returns:

bool
icebergsupport.file_exists(path)

Returns true if path refers to an existing file.

Arguments:
  • path (string) – the path
Returns:

bool
icebergsupport.path_exists(path)

Returns true if path refers to an existing file or directory.

Arguments:
  • path (string) – the path
Returns:

bool
icebergsupport.join_path(pathparts[, pathparts, pathparts ...])

Joins one or more path components.

Arguments:
  • pathparts (string) – a path component
Returns:

string
icebergsupport.list_dir(path)

Returns a list containing the names of the entries in the directory given by path .

Arguments:
  • path (string) – the directory path
Returns:

[bool:true if no errors, false otherwise, table or string:a table contains names if no errors, an error message otherwise]
icebergsupport.quote_path(path)

Searches a path for spaces. If spaces are found, the entire path is enclosed in " .

Arguments:
  • path (string) – the path
Returns:

string: a quoted path if spaces found, given path otherwise
icebergsupport.unquote_path(path)

Removes " at beginning or the end of path if path is enclosed in "

Arguments:
  • path (string) – the path
Returns:

string: an unquote path if enclosed in ", given path otherwise

Bitwise operations

icebergsupport.band(number[, number, number ...])

Returns the bitwise and of numbers . numbers are interpreted as a lua_Integer.

Arguments:
  • number ([number]) –
Returns:

number
icebergsupport.bor(number[, number, number ...])

Returns the bitwise and of numbers . numbers are interpreted as a lua_Integer.

Arguments:
  • number ([number]) –
Returns:

number
icebergsupport.bxor(number[, number, number ...])

Returns the bitwise exclusive or of numbers . numbers are interpreted as a lua_Integer.

Arguments:
  • number ([number]) –
Returns:

number
icebergsupport.brshift(number, disp)

Returns the number number shifted disp bits to the right. number and disp are interpreted as a lua_Integer.

Arguments:
  • number (number) –
  • disp (number) –
Returns:

number
icebergsupport.blshift(number, disp)

Returns the number number shifted disp bits to the left. number and disp are interpreted as a lua_Integer.

Arguments:
  • number (number) –
  • disp (number) –
Returns:

number

System information

icebergsupport.build_platform()

Returns the platform where iceberg was compiled.

Returns:string: a string such as win_64
icebergsupport.runtime_platform()

Returns the platform where iceberg are currently running.

Returns:string: a string such as 6.1.7601 x64

Sub processes

icebergsupport.shell_execute(path[, args, workdir, sudo])

Runs the sub process. If path is not a executable file, path will be opened by an application associated with its extension.

Arguments:
  • path (string) – the file path
  • args ([string]) – arguments for the command
  • workdir (string) – a working directory. This defaults to the current directory.

:param bool sudo : If sudo is true, the sub process will be run as an administrator user. :returns: [bool:true if no errors, false otherwise, string:an error message]

icebergsupport.command_output(command)

Runs the sub process and returns contents of stdout and stderr .

Arguments:
  • command (string) –
Returns:

[bool:true if no errors, false otherwise, string:stdout, string:stderr]

Charcter sets

icebergsupport.utf82local(text)

Converts text from utf-8 to the local encoding.

Arguments:
  • text (string) –
Returns:

string
icebergsupport.local2utf8(text)

Converts text from the local encoding to utf-8.

Arguments:
  • text (string) –
Returns:

string
icebergsupport.crlf2lf(text)

Converts newline characters in text from crlf to lf .

Arguments:
  • text (string) –
Returns:

string

Regular expressions

UTF-8 aware regular expression APIs. Flags are a bitwise or of Regex.S , Regex.I and so on. ( icebergsupport.bor() can be used for bitwise operations). You must pass Regex.NONE if no flags.

icebergsupport.regex_match(pattern, flags, string[, startpos, endpos])

Searches for pattern in string . (completely matching)

Arguments:
  • pattern (string) – the regular expression
  • flags (number) – the flags for searching
  • string (string) – the string to be searched
  • startpos (number) – a starting byte position for searching
  • endpos (number) – an ending byte position for searching
Returns:

[bool:true if found, false otherwise, Regex:Regex object]

Searches for pattern in string . (partial matching)

Arguments:
  • pattern (string) – the regular expression
  • flags (number) – the flags for searching
  • string (string) – the string to be searched
  • startpos (number) – a starting byte position for searching
  • endpos (number) – an ending byte position for searching
Returns:

[bool:true if found, false otherwise, Regex:Regex object]
icebergsupport.regex_split(pattern, flags, string)

Splits string by the occurrences of pattern .

Arguments:
  • pattern (string) – the regular expression
  • flags (number) – the flags for searching
  • string (string) – the string to be splitted
Returns:

[string]
icebergsupport.regex_gsub(pattern, flags, string, repl)
Returns the string obtained by replacing the leftmost non-overlapping occurrences of pattern in string by the replacement repl. Backreferences, such as %1, %2, can be used in repl . Examples:
icebergsupport.regex_gsub("ABC([A-Z]+)", Regex.NONE, "ABCDEFG", "REPLACED")

# -> "REPLACED"

icebergsupport.regex_gsub("ABC([A-Z]+)", Regex.NONE, "ABCDEFG", function(re)
 return re:_1()
end))

# -> "DEFG"
Arguments:
  • pattern (string) – the regular expression
  • flags (number) – the flags for searching
  • string (string) – the string to be replaced
  • repl (callback) – the callback function or a string
Returns:

string

Completions and Options

icebergsupport.getopts(args, option[, option, option ...])

Parses options.

Arguments:
  • args (table) – the list of arguments, such as {"-a", "-b", "action"}
  • option (string) – option names to parse, such as -a . An option must have suffix : such as -a: if the option requires a value
Returns:

[table:successfully parsed options, table:rest values]
icebergsupport.comp_state(values, pos, option[, option, option ...])

Creates a list of completion candidates and analyzes a completion state.

Arguments:
  • values (table) – the list of arguments, such as {"-a", "-b", "action"}
  • pos (number) – the position in values that is pointed by the cursor.
  • option (table) – option definitions
Returns:

[string:a completion state, table:a list of completion candidates]

These functions are used for implementing completion functions and analyzing options.

icebergsupport.comp_state() is used in completion functions like the following:

function(values, pos)
  local state, opts = ibs.comp_state(values, pos,
    {opt="-a", description="a option", state="aaa"},
    {opt="--abcd", description="a option"},
    {opt="--aefg", description="a option"},
    {opt="-b", description="b option"},
    {opt="-c", description="b option", exclude={"-a"}}
  )
  if state == "aaa" then
    return {"file1", "file2", "file3"}
  elseif state == "opt" then
    return opts
  else
    return {"action1", "action2", "action3"}
  end
end

An option definition consists of

opt:An option name. This must start with -.
description:A description for this option.
state:A state name when this option is selected. If the input box value is -b -a A and now the cursor is just after A, the state name is aaa in above example.
exclude:Options that cannot be specified if this option is specified. In above example, -c will not be included in completion candidates if -a is specified.

In addition, the input box value is value - and now the cursor is just after the -, the state name is special value "opt" .

icebergsupport.getopts() is used in command functions like the following:

function(a)
  local opts, args = ibs.getopts(a, "-a:", "-b", "-c")
  if opts.a == nil then
    ibs.message("-a must not be empty.")
  else
    if opt.b then
      ibs.shell_execute(args[1])
      -- blah blah blah
    elseif opt.c then
      -- blah blah blah
    end
  end
end

opts is a table with keys that are an option name without - prefix. If the option has a : suffix, the next argument will be evaluated as a value. Unknown options are stored in args .

In above example, If a is {"-a", "file1", "-b", "action", "parameter"}, getopts returns opts.a = "file1"; opts.b = true; args = {"action", "parameter"} .

iceberg operations

icebergsupport.version()

Returns a version string of iceberg.

Returns:string
icebergsupport.hide_application()

Hides all windows of iceberg.

icebergsupport.show_application()

Shows iceberg.

icebergsupport.do_autocomplete()

Runs the autocompletion.

icebergsupport.get_cwd()

Returns the current working directory of iceberg.

Returns:string
icebergsupport.set_cwd(path)

Changes the current working directory of iceberg.

Arguments:
  • path (string) – the directory path
Returns:

[bool:true if no errors, false otherwise, string:an error message]
icebergsupport.set_result_text(text)

Sets text to the input box as a message.

Arguments:
  • text (string) – the message
icebergsupport.find_command(name)

Tries to find a command and returns the command as a table.

Arguments:
  • name (string) – the name of the command
Returns:

[bool:true if the command is found, false otherwise. , table or string:a table if the command is found, an error message otherwise]

table consists of

name:a command name
path:a command path. This is a string or a function
cmdpath:a command path without arguments
workdir:a directory that will be used as the current directory
description:a description
icon:an icon path
terminal:whether this command must be run in the terminal( "yes" , "no" or "auto" )
history:whether this command is added to the history.

icebergsupport.to_path(text)

Returns text if text is a path, otherwise tries to find a command named text and returns path of the command.

Arguments:
  • text (string) –
Returns:

[bool:true if no errors, false otherwise. , string: a path if no errors, an error message otherwise]
icebergsupport.to_directory_path(text)

Returns text if text is a path, otherwise tries to find a command named text and returns path of the command.

Arguments:
  • text (string) –
Returns:

[bool:true if no errors, false otherwise. , string: a path if no errors, an error message otherwise]
icebergsupport.message(text)

Shows a popup message.

Arguments:
  • text (string) – the message
icebergsupport.event_key()

Returns a number corresponds to the current GUI event.

Returns:number
icebergsupport.event_state()

Returns a number that is a bitfield of what modifier keys were on during the most recent GUI event. This bitfield consists of icebergsupport.EVENT_STATE_* .

Returns:number
icebergsupport.matches_key(key)

Returns true if event key is held, false otherwise. key is a string such as ctrl-a and ctrl-alt-space .

Arguments:
  • key (string) –
Returns:

bool
icebergsupport.exit_application()

Shuts iceberg down.

icebergsupport.reboot_application()

Reboots iceberg.

icebergsupport.scan_search_path(category)

Scans the search path that belongs to category .

Arguments:
  • category (string) –
icebergsupport.get_input_text()

Returns a value of the input box.

Returns:string
icebergsupport.set_input_text(text)

Sets text to the input box.

Arguments:
  • text (string) –
icebergsupport.get_input_text_values()

Parses the value of the input box and returns a list of strings. This function parses a text that is shown in the input box, so if you want to parse a value including an autocompleted text, you have to call icebergsupport.do_autocomplete() before calling this function.

Returns:table
icebergsupport.get_clipboard()

Returns the content of the clipboard.

Returns:string
icebergsupport.set_clipboard(text)

Sets text to the clipboard

Arguments:
  • text (string) –
icebergsupport.get_clipboard_histories()

Returns the list of the clipboard histories.

Returns:table
icebergsupport.selected_index()

Returns the index of the selected completion candidate. An index starts at 1(not 0). 0 means no selection.

Returns:number
icebergsupport.command_execute(name[, args])

Runs the command named name .

Arguments:
  • name (string) –
  • args ([string]) – a list of arguments
Returns:

[bool:true if no errors, false otherwise. , string:an error message]
icebergsupport.default_after_command_action(success, message)

Make the default behavior after the command execution. If success is true, this function clears the input box and hides all iceberg windows, otherwise shows message using the popup window. Typically, this function is used in combination with icebergsupport.command_execute() such as icebergsupport.default_after_command_action(icebergsupport.command_execute("cmd", {"arg0", "arg1"}))

Arguments:
  • success (bool) – whether the command was succeeded
  • message (string) –
icebergsupport.add_history(input[, name])

Adds input to the last of the history. If you want to add a command that is registered with iceberg, pass the command name as name .

Arguments:
  • input (string) – the text to be added to the history(including all arguments)
  • name (string) – a command name if input is registered with iceberg, nil otherwise
icebergsupport.open_dir(path)

Opens path with the application system.file_browser .

Arguments:
  • path (string) – the directory path
Returns:

[bool:true if no errors, false otherwise. , string:an error message]
icebergsupport.group_command(command[, commmand, command ...])

Creates a new command that executes several commands in sequence. Each commands are run by icebergsupport.command_execute(), so commands must be registered with iceberg.

group_sample = { path = ibs.group_command({"userdir", {}}, {"np", {}}), description = "runs a group of commands"},
icebergsupport.bind_key(key, func)

Executes func when key is pressed. This function is used in the on_key_down callback function.

Arguments:
  • key (string) – the string such as ctrl-m
  • func (function) –
icebergsupport.is_modifier_pressed(keycode)

Returns true if modifier keys keycode are pressed.

Arguments:
Returns:

bool

Miscs

icebergsupport.dump_lua_object(object, indent, isarrayval)

Converts object to a string that can be interpreted as a Lua code.

Arguments:
  • object (object) –
  • indent (number) – the indent level of the result, this must be 0
  • isarrayval (bool) – pass true if object is an array
Returns:

string
icebergsupport.load_lua_object(text)

Parses text as a lua code and returns a table.

Arguments:
  • text (string) –
Returns:

[bool:true if no errors, false otherwise, table or string: a table if no errors, an error message otherwise]
icebergsupport.grep(text, pattern[, flags])

Returns the lines of text that include a regular expression pattern

Arguments:
  • text (string) –
  • pattern (string) –
  • flags (number) –
Returns:

[string]
icebergsupport.is_array(table)

Returns true if table is an array. table is considered as an array if all indecies are a positive number.

Arguments:
  • table (table) –
Returns:

bool
icebergsupport.merge_table(table[, obj, obj ...])

Merges multiple tables into the first table . Elements will be appended after the last element of table if table is a list.

Arguments:
  • table (table) –
icebergsupport.table_find(table, obj)

Returns the lowest index in the table where the obj is found. Returns 0 if obj is not found.

Arguments:
  • table (table) –
Returns:

number

Windows support functions

winsupport.foreground_explorer()

Returns information of the foreground explorer.exe

Returns:{path= a path of the explorer, selected={a list of the selected file names}}
winsupport.foreground_explorer_path()

Returns a path of the foreground explorer.exe. When no explorer exists, returns an empty string.

Returns:string

Classes

class Regex.new(pattern, flags)

A regular expression object that handles UTF-8 strings correctly. This object is used in icebergsupport.regex_* functions.

Arguments:
  • pattern (string) – the regular expression that can be used in the Oniguruma
  • flags (number) – the regular expression flags(Regex.NONE or a bitwise or of the Regex.S,M and I)
Regex.NONE

A regular expression flag that means no flags are set.

Regex.S

A regular expression flag that is equivalent to the Perl’s s flag.

Regex.M

A regular expression flag that is equivalent to the Perl’s m flag.

Regex.I

A regular expression flag that is equivalent to the Perl’s i flag.

Regex.escape(text)

Escapes all meta characters in text

Arguments:
  • text (string) –
Returns:

string
Regex:_1()

Returns the subgroup string of the match.

Regex:_1() , Regex:_2() … Regex:_9() are defined.

Returns:string
Regex:group(group)

Returns the subgroup string of the match.

Arguments:
  • group (number) –
Returns:

string
Regex:startpos(group)

Returns the index of the start of the substring matched by group .

Arguments:
  • group (number) –
Returns:

number
Regex:endpos(group)

Returns the index of the end of the substring matched by group .

Arguments:
  • group (number) –
Returns:

number