.\" generated with Ronn-NG/v0.9.1
.TH "TERMINAL\-MEDIA\-LAUNCHER\-CONFIG" 5

.SH "NAME"
terminal-media-launcher-config - terminal-media-launcher configuration file

.SH SYNOPSIS
~/.config/terminal-media-launcher/config.lua (or ~/.terminal-media-launcher/config.lua)

.SH DESCRIPTION
Starting in version 0\.2, Terminal Media Launcher is configured via a lua \fIhttps://www\.lua\.org/\fR script\. This project assumes the configuration will adhere to lua 5\.1, but is written to be as agnostic as possbile\. The general format of the configuration is outlined below:
.P
.nf
.BI "Groups = { "
.BI "    { "
.BI "        name = <string>, "
.BI "        Launcher = <string>, "
.BI "        Flags = <string>, 
.BI "        Entries = { "
.BI "            { "
.BI "                name = <string>, "
.BI "                path = <string> "
.BI "            }, "
.BI "            ... "
.BI "        } "
.BI "    }, "
.BI "    ... "
.BI "}"

.SH COMMANDS
.SS "Creating a Group"
The config must contain at least one valid group\. Groups are to be inserted in the \fBGroups\fR global variable\. \fBGroups\fR is an array of tables\. Each group is a table containing the following keys:

.IP "Mandatory keys:"
.IP "\[ci]" 4
\fBname\fR \fIstring\fR \- a name for the group
.IP "\[ci]" 4
\fBEntries\fR \fItable\fR \- an array of tables\. Each table represents an entry\.
.IP "" 0

.IP "Optional keys:"
.IP "\[ci]" 4
\fBLauncher\fR \fIstring\fR \- the path for a program that launches the entries of this group\. If not set, it assumes the entries in this group are executables (and have no launching program)
.IP "\[ci]" 4
\fBFlags\fR \fIstring\fR \- flags to pass to the launching program\. If not set, no flags are passed
.IP "" 0

.IP "" 0
.P
Here is a helper function you can use in your config to add a group
.P
\fB
.EX
local function addGroup(name, launcher, flags)
	assert(type(name) == "string")

    -- create Groups table if needed
    if Groups == nil then
        Groups = {}
    end

    local new_group = {}
    new_group.name = name
	new_group.Entries = {}
    if launcher ~= nil then
        new_group.Launcher = launcher
    end
    if flags ~= nil then
        new_group.Flags = flags
    end

    table.insert(Groups, new_group)
    return new_group
end
\fR


.SS "Adding Entries"
For a group to be valid, it must contain at least one valid entry\. Entries are to be inserted in the \fBEntries\fR key of a group table\. \fBEntries\fR is an array of tables\. Each entry is a table containing the following keys:
.IP "Mandatory keys:"
.IP "\[ci]" 4
\fBname\fR \fIstring\fR \- a name for the entry
.IP "" 0

.IP "Optional keys:"
.IP "\[ci]" 4
\fBpath\fR \fIstring\fR \- a path to the file associated with this entry\. If not set, the path is the same as the name
.IP "" 0

.IP "" 0
.P
Here is a helper function you can use in your config to add an entry to a group
.P
\fB
.EX
local function addEntry(parentGroup, name, path)
	assert(type(parentGroup) == "table")
	assert(type(parentGroup.Entries) == "table")
	assert(type(name) == "string")

	local new_entry = {}
	new_entry.name = name
	if path ~= nil then
		new_entry.path = path
	end

	table.insert(parentGroup.Entries, new_entry)
	return new_entry
end
\fR

.IP "" 0
.SS "Adding Entries using lfs module"
It is recommended to install the lua\-filesystem \fIhttps://github\.com/lunarmodules/luafilesystem\fR module and use it to add entries more efficiently\. This example can be used to descend into a directory and add files matching a \fBstring\.match\fR pattern to a group\.
\fB
.EX
local lfs = require "lfs"

local function addEntries(parentGroup, startDir, filePattern, recursive)
	-- recursive arg is a boolean for whether or not to descend into subdirectories (false by default)
	assert(type(parentGroup) == "table")
	assert(type(parentGroup.Entries) == "table")
	assert(type(startDir) == "string")
	assert(type(filePattern) == "string")

	for file in lfs.dir(startDir) do
		local fullFilePath = startDir .. "/" .. file
		if file ~= "." and file ~= ".." then
			-- descend into subdirectory if recursive is set to true
			if lfs.attributes(fullFilePath).mode == "directory" and recursive == true then
				addEntries(parentGroup, fullFilePath, filePattern, recursive)
			elseif lfs.attributes(fullFilePath).mode == "file" then
				if string.match(file, filePattern) then
					table.insert(parentGroup.Entries, {
						name = file,
						path = '"' .. fullFilePath .. '"'
					})
				end
			end
		end
	end
end
\fR

.SS "Settings"
Settings can be set via the \fBSettings\fR global variable\.
.P
.nf
.BI "Settings = {} "
.BI "Settings\.sort = <boolean>"

\fBsort\fR will sort entries of each group in alphabetical order (though not the list of groups)\. \fBsort\fR is true by default\.

.SH EXAMPLE
Here is an example \fBconfig\.lua\fR which creates a Music, Pictures, and, Videos group, and adds all the files from the user's Music, Pictures, and Videos home folders to each group\.

\fB
.EX
local lfs = require "lfs"

local function addGroup(name, launcher, flags)
	assert(type(name) == "string")

    -- create Groups table if needed
    if Groups == nil then
        Groups = {}
    end

    local new_group = {}
    new_group.name = name
	new_group.Entries = {}
    if launcher ~= nil then
        new_group.Launcher = launcher
    end
    if flags ~= nil then
        new_group.Flags = flags
    end

    table.insert(Groups, new_group)
    return new_group
end

local function addEntries(parentGroup, startDir, filePattern, recursive)
	-- recursive arg is a boolean for whether or not to descend into subdirectories (false by default)
	assert(type(parentGroup) == "table")
	assert(type(parentGroup.Entries) == "table")
	assert(type(startDir) == "string")
	assert(type(filePattern) == "string")

	for file in lfs.dir(startDir) do
		local fullFilePath = startDir .. "/" .. file
		if file ~= "." and file ~= ".." then
			-- descend into subdirectory if recursive is set to true
			if lfs.attributes(fullFilePath).mode == "directory" and recursive == true then
				addEntries(parentGroup, fullFilePath, filePattern, recursive)
			elseif lfs.attributes(fullFilePath).mode == "file" then
				if string.match(file, filePattern) then
					table.insert(parentGroup.Entries, {
						name = file,
						path = '"' .. fullFilePath .. '"'
					})
				end
			end
		end
	end
end

local music = addGroup("Music", "xdg-open")
addEntries(music, os.getenv("HOME") .. "/Music", ".*", true)

local pictures = addGroup("Pictures", "xdg-open")
addEntries(pictures, os.getenv("HOME") .. "/Pictures", ".*", true)

local videos = addGroup("Videos", "xdg-open")
addEntries(videos, os.getenv("HOME") .. "/Videos", ".*", true)
\fR

.fi
.SH SEE ALSO
\fBterminal-media-launcher\fR(1)