
  SciTE Key Command Manager by Mitchell
    email: mitchell {att} caladbolg {dott} net

  Copyright (c) 2006-2007 Mitchell Foral. All rights reserved.

  SciTE-tools homepage: http://caladbolg.net/scite.php
  Send email to: mitchell<att>caladbolg<dott>net

  Permission to use, copy, modify, and distribute this
  utility is granted, provided credit is given to Mitchell

  SciTE's key commands are quite customizable as it is, but
  not quite as dynamic as they could be.

  There is no other editor that comes close to matching
  Textmate (sadly, MacOSX only) but SciTE. Of course, SciTE
  in its default state doesn't, but with Lua, it can. This
  key command managing system is designed to come close to
  mimicking Textmate, although it will never be a perfect
  clone.

  Before you start:
    The custom version of SciTE in ../src/ MUST be used. The
    additional Lua Extension functions OnKey and MenuCommand
    are used by keys.lua. Binaries for x86 machines can be
    found in ../src/scite/bin/.

  Syntax:
    Key commands are defined in a user-defined table 'keys'.
    Scopes and Lexers (discussed below) are numeric indices of
    the keys table and are tables themselves. Each string index
    in each of these tables is the key command. The table
    containing the command to execute and an optional parameter
    is equated to this key command. You can have global key
    commands of course.

    For example:
    keys = {
      ['ctrl+f']   = { editor.CharRight, editor },
      ['ctrl+b']   = { editor.CharLeft,  editor },
      [SCLEX_RUBY] = {
        ['ctrl+e']   = { Editing.ruby_exec },
        [SCE_RB_DEFAULT] = {
          ['ctrl+f'] = { Snippets.insert, 'function ${1:name}' }
        }
      }
    }

    The top-level key commands are global, the SCLEX_RUBY
    command is global to a buffer with Ruby syntax highlighting
    enabled, and the SCE_RB_DEFAULT command is executed in that
    buffer only when currently in the default scope.

    Scopes and Lexers:
      SCLEX_RUBY and SCE_RB_DEFAULT are both constants having
      values defined in Scintilla.iface (22 and 0 respectively).

      Scope-insensitive key commands should be placed in the
      lexer table, and lexer-insensitive key commands should be
      placed in the keys table.

    By default scopes are enabled. To disable them, set the
    SCOPES_ENABLED variable to false.

    Order of execution precedence: Scope, Lexer, Global
      Key commands in the current scope have the first priority,
      commands in the current lexer have the second, and global
      commands have the least priority.

    Declaring key commands: ['key_seq'] = { command [, arg] }
      ( e.g. ['ctrl+i'] = { Snippets.insert } )
      key_seq is the key sequence string compiled from the CTRL,
      SHIFT, ALT, and ADD options (discussed below), command is
      the Lua function or SciTE menu command number (defined in
      SciTE.h), and arg is an optional argument. If I wanted to
      redefine the 'Open' menu command to be 'ctrl+r', then I
      would do something like ['ctrl+r'] = { 102 } -- open
      Editor pane commands are kind of tricky at first. Their
      argument is the editor pane itself. You can see this in
      the original example above.
      The key character is ALWAYS lower case. There will be no
      such command as ['ctrl+I'].
      The string representation of characters is used, so
      ['ctrl+/'] is a valid key sequence. (See limitations of
      this below.)
      The order of CTRL, SHIFT, and ALT is important.
      (C, CS, CA, CSA, etc.)

    Chaining key commands:
      Key commands can be chained like in Emacs. All you have
      to do create nested tables as values of key commands.

      For Example:
      keys = {
        ['ctrl+x'] = {
          ['ctrl+s'] = { 106 } -- save
          ['ctrl+c'] = { 140 } -- quit
        }
      }

      Remember to define a clear_sequence key sequence in the
      keys table (Escape by default) in order to stop the
      current chain.
      If a show_completions key sequence is defined, a list of
      completions for the current chain will be displayed in the
      output pane.
      The current key sequence is contained in the SciTE
      variable KeyChain. (Appropriate for statusbar display)

    Additional syntax options:
      The text for CTRL, SHIFT, ALT, and ADD can be changed. ADD
      is the text inserted between modifiers ('+' in the example
      above). They can be as simple as c, s, a, [nothing]
      respectively. ( ['csao'] would be ctrl+shift+alt+o )

  Extensibility:
    You don't have to define all of your key commands in one
    place. I have Ruby-specific key commands in my ruby.lua file
    for example. All you need to do is add to the keys table.
    ( e.g. keys[SCLEX_RUBY] = { ... } )
    Note: additions to the keys table should be at the end of
    your *.lua file. (See the reason behind this below.)

  Limitations:
    Certain keys that have values higher than 255 can not be
      used, except for the keys that are located in the KEYSYMS
      table. When a key value higher than 255 is encountered, its
      string value is looked up in KEYSYMS and used in the
      sequence string.
    In order for key commands to execute Lua functions properly,
      the Lua functions must be defined BEFORE the key command
      references to it. This is why the keys.lua module should be
      loaded LAST, and key commands added at the bottom of *.lua
      scripts, after all global functions are defined.
    The clear_sequence and show_completions key sequences cannot
      be chained.

  Notes:
    Redefining any menu Alt+key sequences will override them.
      So for example if 'alt+f' is defined, using Alt+F to
      access SciTE's File menu will no long work.
    Setting ALTERNATIVE_KEYS to true enables my nano-emacs hybrid
      key layout.

  Questions? Comments? Suggestions? Additions?
    mitchell {att} caladbolg {dott} net
