(c) 2011, PIDA Authors License GPL v3 (http://www.gnu.org/copyleft/gpl.html)
The One True IDE™, successor to the PIDA IDE. An ultra-lightweight IDE, that embeds Vim, a terminal emulator, and a file browser and makes them work together.
- Installation
- Configuration
- Keyboard Shortcuts
- Extensions
- FAQ
- Intentional Breakages
- SSH Tips and Tricks
⠠⠊⠝⠎⠞⠁⠇⠇⠁⠞⠊⠕⠝
$ pip install a8
Remember the system dependencies:
# apt-get install vim-gtk python-gtk2 python-vte python-dbus
(non debian distros, please drop me a line to add you.)
a8 is a bit configurable. Not so much because I never planned on using it in more than one way.
Create a config file at ~/.a8/config.yaml
As the name suggests it will be in Yaml, as a map of key values:
foo1: blah
foo2:
foo3: blah
Is the biggest bit, terminal options live under the temrinal key, and these
are them, with default values if they exist (or Unset otherwise):
terminal:
'color_foreground': Unset,
'color_background': Unset,
'backspace_binding': Unset,
'cursor_blink_mode': Unset,
'cursor_shape': Unset,
'font': Unset,
'allow_bold': Unset,
'audible_bell': Unset,
'emulation': Unset,
'pointer_autohide': Unset,
'scroll_on_keystroke': Unset,
'scroll_on_output': Unset,
'scrollback_lines': 1000,
'visible_bell': Unset,
'word_chars': '-A-Za-z0-9,./?%&#:_',
To turn on the toolbar:
toolbar: true
Abominade 0.11 supports 3 session types:
session_type: 'none' # don't remember sessions (alias for "session: false")
session_type: 'local' # stores session in the ./.a8 wherever abominade runs
session_type: 'user' # default, stores session in ~/.a8
To turn off sessions in 0.10 and earlier:
session: false
Useful for multiple screens:
terminal_window: true
⠠⠅⠑⠽⠃⠕⠁⠗⠙ ⠠⠎⠓⠕⠗⠞⠉⠥⠞⠎
Keyboard shortucts are of two types:
- Internal a8 actions
- Custom shell commands
Define keyboard shortcuts by creating the file:
~/.a8/shortcuts.yaml
This file should contain keys and values of the form:
<action>: <shortcut>
or of the form
key: <shortcut>
[cmd: <command>]
[cwd: <working directory>]
[env: <environment>]
Where action is a string defining the action to be performed, and shortcut is a shortcut string.
Available actions are (with defaults):
shell (<Alt>t)focus_vim (<Alt>e)focus_terminal (<Alt>r)focus_buffers (<Alt>b)focus_files (<Alt>m)focus_terminals (<Alt>i)focus_bookmarks (<Alt>k)prev_buffer (<Alt>Up)next_buffer (<Alt>Down)prev_terminal (<Alt>Left)next_terminal (<Alt>Right)refresh_files (<Alt>g)toggle_expanded_files (<Alt>x)(0.11 and later)close_all_buffers (<Alt>c)browse_home (<Alt>h)
- pressing
<Shift>Upand<Shift>Downin terminals will jump to prev/next prompt (or at least the scrollbar position where you last hit Enter)
The format looks like <Control>a or <Shift><Alt>F1 or <Release>z (the last
one is for key release). The parser is fairly liberal and allows lower or upper
case, and also abbreviations such as <Ctl> and <Ctrl>. Keys such as Up,
Down, Left, Right etc are available, but be careful, the keypress will not
pass through to the underlying app, terminal or Vim.
These are custom shell commands bound to a keyboard shortcut. Their format is different from internal a8 shortcuts. They should be part of a list in the value of the custom key. Each item in the list should define at least the key key as a shortcut string in the format above. Additionally they may define cmd, cwd and env keys. These are used to execute a new terminal with the command.
An example shortcut file might look like:
shell: <Control>o
focus_vim: <Alt>Space
custom:
- key: <Alt>j
cmd: ifconfig
⠠⠑⠭⠞⠑⠝⠎⠊⠕⠝⠎
A8 is slightly extensible, to the absolute minimal degree to add functionality without having the burden of a massive framework. This is achieved by the concepts of:
- Extensions
- Signals
Since we are just using Python, all the a8 API is public to any Python code in the same process, and that is intentional. If you want to break it by abusing this, go for it, break it.
Extensions are any Python module or instance with a callable setup attribute. The signature of setup should be:
def setup(app):
"""My setup function."""
Of course this can be in an object where the signature would be:
class MyExtension(object):
def setup(self, app):
"My setup function."""
Extensions are listed in the configuration file under the extensions key, and should be importable names, such as a8.a8_example_ext, an example to get you started. If importing an attribute from a module, the : notation can be used, such as path.mymodule:myattr, which would be suitable for an instance as an extension.
The app that is passed to the setup function is an instance of a8.app.Abominade which is the main monolith for a8, i.e., it has access to everything. Terrible, but intentional.
The setup function can be used to create user interface features and to connect to signals, and as mentioned above, since all the API is public, anything can be achieved using this.
A8 exports a number of signals for use by extensions. They are not used internally, so mostly behave as a no op. These are connected using app.connect and can be emitted by using app.emit.
app.connect takes a signal name, and a callback to be called. Callbacks are only passed keyword arguments, so it is important to get the names of the arguments correct. here is an example of connecting to the file-saved signal in a plugin. All available signals and arguments are listed below.
def on_file_saved(filename):
print filename, 'was saved.'
def setup(app):
app.connect('file-saved', on_file_saved)
| Name | Arguments | Description |
|---|---|---|
file-item-added |
filename |
File item is shown in the file manager |
file-opened |
filename |
File opened in the editor |
file-closed |
filename |
File closed in the editor |
bookmark-item-added |
filename |
Bookmark to filename is added |
terminal-executed |
argv env cwd |
New terminal has been executed |
If you need more signals, just let us know. Since they are not used internally, there is basically no cost.
⠠⠋⠠⠁⠠⠟
Abominade doesn't hope to replace [http://pida.co.uk PIDA], how could it? So if you require some special PIDA features, please go ahead and use PIDA. Intentional Breakages
Probably, with difficulty. You'll need X, Gtk, DBus, all with Python support. (and possibly psychiatric help)
⠠⠊⠝⠞⠑⠝⠞⠊⠕⠝⠁⠇ ⠠⠃⠗⠑⠁⠅⠁⠛⠑⠎
Features intentionally left out of Abominade that make it simpler, but essentially a tool written for me. If you want a real application, try [https://bitbucket.org/aafshar/pida-main/wiki/Home PIDA]. The motivation for Abominade is to make an IDE that is tailor-made to me.
- Internationalization (I only ever use English)
- Non-Vim editors (I only ever use Vim)
- Language support (I don't find those outliners useful)
- Version control support (Command line is enough)
- Project support (Replaced with bookmarks)
- Gui configuration (Plain text is enough)
- Gui shortcut config (As Gui config)
- Window management (Detaching, moving, hovering, floating)
- Saving layout
- Documentation (ok, so PIDA doesn't have any, either!)
- Lots of options (No need to make stuff optional that I use.)
- GTK's Actions are a pain
- Glade/GTKBuilder is a pain
- GTK's stock icons are totally useless
- Statusbar/Toolbar/menubar
⠠⠎⠠⠎⠠⠓⠀⠠⠞⠊⠏⠎⠀⠁⠝⠙⠀⠠⠞⠗⠊⠉⠅⠎
Abominade's features work surprisingly well for working remotely over SSH.
If you edit a lot of code on remote hosts, you can mount your project directory locally via SSHFS.
If you then SSH directly from a mounted local dir to the corresponding remote dir, Abominade's terminal filename recognition will still catch relative filenames. This will break if you cd in your SSH session so that relative paths don't match your local current dir anymore, but if you configure SSH's !EscapeChar setting, you can suspend SSH, cd locally, and resume SSH.
Another interesting trick is you start Abominade in an SSHFS dir while using a local session, the session will be shared with remote instances at the same path, and can be resumed on a different host.
It's a good idea to use GNU screen or tmux for some terminals in Abominade's terminals pane, since it's easy to accidentally close Abominade and lose your terminal history.
Haven't used this much in Abominade...