XYZCommander uses the two-layered scheme for configuration files:
At startup XYZCommander first reads default values from system configs and then tries to open and parse user’s ones.
XYZCommander configuration files are, in fact, just regular python scripts but in order to simplify configuration editing a bunch of useful functions are available:
Set variable to hold a value. Variable will be available in xyz.conf[section][varname] If section is not provided - local will be used.
Example - Choose a desired skin:
let("skin", "seablue", sect="xyz")
Return whole configuration section contents as a dictionary or None if undefined
Example:
icmd("alias",
lambda _: call(":core:shell:echo",
"\n".join(["alias %s='%s'" % (k, v)
for k, v in section("aliases").iteritems()
])))
Load method[s] from plugin.
Example - load all methods from :sys:cmd plugin:
load(":sys:cmd:*")
Example - load show_binds method from :core:bindlist plugin:
load(":core:bindlist:show_binds")
Bind method to be executed upon pressing shortcut. Method can be either full plugin method pass or python function/method/lambda object. If context is @ - use plugin full path as context. (See Contexts)
Example - run :sys:cmd:execute when ENTER is pressed:
bind(":sys:cmd:execute", kbd("ENTER"))
Example - use system pager to view files:
bind(lambda: shell(env("PAGER", "less"), macro("ACT_PATH")), kbd("F3"))
Transform a string shortcut description into internal representation object.
Example:
kbd("ENTER")
Set up an action to be taken upon pressing action key on file. Action key is by default - ENTER which is bound to :core:panel:action.
Example - when action is pressed on executable file - run it:
action(r'(type{file} and perm{+0111}) or '\
r'(type{link} and link_type{file} and link_perm{+0111})',
lambda obj: shell(obj.path))
Expand macro name.
Availbale macros:
Example - edit current file:
bind(lambda: shell(env("EDITOR", "vi"), macro("ACT_PATH")), kbd("F4"),
":sys:panel")
Call plugin method passing arguments to it.
Example - change directory:
action(r'type{dir} or (link_type{dir} and link_exists{?})',
lambda obj: call(":sys:panel:chdir", obj.path))
Return environment variable or default if is not set
Example:
env("HOME", "/")
Execute command using :core:shell plugin.
Example - run xpdf in background on .pdf files:
action(r'iname{".*\\.pdf$"}', lambda obj: shell("xpdf", obj.path, bg=True))
Set an alias which will be expanded in command line before execution. replace argument can be either string or function.
Example:
alias("ll", "ls -l")
Set an internal command. Internal command do not get passed to shell, instead appropriate function is being called by XYZCommander.
Example:
icmd("cd", lambda path: call(":sys:panel:chdir", path))
Enable plugin[s].
Example:
plugins_on(":sys:run",
":sys:cmd",
":sys:panel",
":sys:logger")
Configure plugin.
Where:
In fact, plugin_conf is only a shortened form of let(plugin, opts, sect="plugins").
Example:
plugin_conf(":sys:cmd", {
# Command line prompt
"prompt": "$ ",
# Size of undo buffer
"undo_depth": 10,
# Size of typed commands history buffer
"history_depth": 50})
Set prefix and VFSObject class for VFS dispatching.
Example:
# Set tar VFS handler
vfs("tar", TarVFSObject)
Register a new hook. Event is an event string and proc is a procedure to be called.
Example:
hook("event:sys:cmd:execute",
lambda cmd: xyzlog.info("About to execute %s" % cmd))
Remove all hooks for the event.
Convert string rule to libxyz.core.FSRule instance. This method primarily used in skin files, where matching fsrules are defined.
Example:
"fs.rules": [
(
# Broken links
fsrule(r'type{link} and not link_exists{?}'),
BG_PALETTE({"foreground": "DARK_RED"})
),
Create internal palette object. It is primarily used in skin files.
Config is a dictionary of form:
{
'foreground': COLOR,
'background': COLOR,
'fg_attributes': [ATTR],
'mono': [ATTR],
'foreground_high': HG_COLOR,
'background_high': HG_COLOR
}
Example:
palette({
"foreground": "DARK_BLUE",
"background": "LIGHT_GRAY",
"fg_attributes": ["BOLD", "UNDERLINE"]
})
Create and register new skin.
kwargs include:
Example (part of XYZCommander default skin):
skin(name="seablue",
author="Max E. Kuznecov <syhpoon@syhpoon.name>",
version="0.3",
description="XYZCommander Seablue skin",
rules = {
"fs.rules": [
(
# Broken links
fsrule(r'type{link} and not link_exists{?}'),
BG_PALETTE({"foreground": "DARK_RED"})
)
]
}
)
Although any XYZCommander configuration file can contain any (or all) of the above functions, it is better to logically separate definitions.
Here’s the list of XYZCommander system configuration files:
Shortcut is a combination of keys pressed. It is specifed as a list of special (libxyz.ui.Keys attributes) and regular keys separated by hiphen:
CTRL-x means Control + x key
META-L means Escape + SHIFT + l key
Note
Please note that not all of the possible combinations make sense.
There is a standard plugin :ui:testinput which can be usefull to determine what kind of shortcuts are corresponding to pressed keys.
When a focus widget receives keyboard input it looks for matching key pressed in KeyManager object accessible as km attribute of XYZData class.
But for different widgets the same keys/shortcuts can have different meanings. For intance key UP pressed while Panel widget is active will move the cursor one entry up. But for BoxYesNo dialog the same key changes the button focus. To handle such a problem a concept of context is introduced. Context is simply a set which shares the shortcuts defined within it. Context has a name and may include an arbritrary amount of widgets. Context named DEFAULT used unless other provided. For example, consider the part of keys configuration file:
# 1.
bind(":sys:cmd:undo", kbd("META-P"))
# 2.
bind(":sys:cmd:undo", kbd("META-P"), "CMD")
In 1. we’ve bound Meta+Shift+p shortcut to undo method of :sys:cmd plugin. As we haven’t provided context name, DEFAULT will be used.
In 2. we’ve explicitly provided CMD context. So box_action will only be executed when a widget with context CMD will be in focus receiving input.
One can provide a special context name: @ to make context name equal to plugin full namespace path:
bind(":sys:cmd:execute", kbd("ENTER"), "@")
In this case, the bind will be saved to context :sys:cmd.