Go to the first, previous, next, last section, table of contents.

Group Structures

The Action Groups structure is quite simple and mirrors a hierarchical file system directory structure where the group is like a directory and a group entry is like an ordinary file.

Groups and Entries

An Agroups top level group structure is a hierarchical structure composed of groups of entries. A group itself is by definition an entry and therefore groups can have entries that are groups. When a group has an entry that is itself a group then we refer to that entry as a subgroup, See section Subgroups. You can have subgroups inside of subgroups recursively with no limit. Also, any subgroup is referred to as a group and is equivalent to any other group in form.

The whole Agroups group structure is contained in a single top level group. This single top level group has no identity itself so we just refer to all of the entries in this single top level group as top level entries. All of these top level entries are in fact forced to be groups and we also refer to them as top level groups. Each Agroups save file, See section Action Groups Save File, maps a single group of top level groups.

Group entries that are not subgroups will be instances of actions and we call these "action entries". All Agroups entries, including groups, have a uniform set of components, See section Entry Components. This keeps the model simple which is important for example for editing individual groups or entries, See section Editing Entries and Groups.

A major advantage of the equivalence of groups and entries is that any operation that can be applied to an entry can be applied to a group.

Group Information

You can view all top level groups with the operation

Display top level groups (keys: D)

This operation is not only important for viewing all top level groups but also marks the current group and current persistent group. The current group is marked with a small "c" in the left margin and the current persistent group with a capital "C" in the left margin. If the current and current persistent group are the same group then that group will be marked with only a capital "C".

If the current or current persistent group is not a top level group it will still be marked but indented under the top level group that it is a subgroup of. No matter how deeply nested inside the top level group the marked group is it will be indented the same amount. The indenting only serves to indicate that the current or current persistent group is somewhere underneath that top level group. For example in the following display of top level groups

Top level groups (C marks current persistent, c marks current)
   Group green (keys: g)
C  Group blue (keys: b)
   Group red (keys: r)
c    sub-sub-group of red (keys: r 2)
   global (keys: .)
   zzzap (keys: !)

The current persistent group is the top level group "Group blue" but the current group is a subgroup of a subgroup of "Group red". But nothing other than the current group's id text here indicates that it is in fact a subgroup of a subgroup of "Group red".

You can view the entries in the current group or any other group or subgroup with the operation

Display current group entries (keys: d)

For how to view groups or subgroup other than current groups with this operation, See section Current Group One Time. You can also edit groups to see or change detailed information about a group, See section Editing Entries and Groups.

Whenever you display a group with this operation if the group is not the actual current group then it gets recorded and you can easily refer to this displayed group later, See section Last Non-Current Displayed Group.


The top level group entries must all be group entries. So for example a top level entry can not be a keyboard macro. But all entries below the top level can be any kind of entry including another group entry. When an entry is a group entry we call it a subgroup.

Each entry is has an action component like file or dired. If an entry has the action component group then it is a group entry. But the action group can be executed just like any other action and when executed means simply

For any subgroup that can be executed in a sequence, pretend that
subgroup is the current group for the rest of that sequence.

Actually this is a specific instance of the "Current Group One Time" principle and the section, See section Current Group One Time, has examples of the above principle for subgroups.

Entry Components

Every entry has four components

id              Identification of entry
keys            Accelerator keys
action          Action that will happen when entry is selected
object          Object that action will be taken on        

The meaning of these components can be explained with a saying that ties them all together:

The action on object can be achieved by typing
keys of the entry identified by id.

Actually this explanation would be really complete if we just allow the part "typing keys" to allow substitution with "typing completion of id". That is, at any time a user can use completion instead of accelerator keys.

A simple example is

id              My file 1
keys            f 1
action          file
object          ~/somedir/myfile1

So when typing "KA f 1" the file "~/somedir/myfile1" is found in a buffer. Here is an example of a group entry components

id              My group
keys            g
action          group
object          (entry1 entry2 ... entryN)

So when typing "KA g" Agroups selects the object and a subgroup and waits for for your selection of entry1 entry2 ... entryN.

Keys are intended to be strings of any character that can be typed. There is no limit to the number of characters for the keys component and they can be any characters including control, meta and function characters except C-g and RET. The C-g character is used to abort a keys entry and the RET character is used to complete a keys definition entry. Agroups makes a distinction between upper and lower case characters. For instance "A" can be used to select something differently than "a".

First Given Groups

When the user first declares a new empty save file, See section Action Groups Save File, Agroups will automatically create two top level groups. These are the zzzap group and the global group. The global group can be removed by the user but the zzzap group can never be removed since it is used in the mechanism for removing entries and groups, See section Zzzap Group.

The global group is given initially as a courtesy and as a starting top level group other than the zzzap group. It is also used in examples in this document. Even though you may remove the global group you may want to keep it around as a group of actions that are intended to be common to all other groups. For example, we show how access to a global group can be bound to another Emacs key, See section Creating New Agroups Commands.

Zzzap Group

The zzzap group is given to you initially and can never be moved to another group or deleted; however it can be cloned. You can change the id and accelerator keys but not the zzzap group itself. In this document we refer to this group as "the zzzap group" which means the group with initial id "zzzap". So if you were to change the id of this group there is no confusion with the terms zzzap or Zzzap used in this document.

The zzzap group is kind of like the kill stack in Emacs. Even though you can effectively removed unwanted groups and entries from a group by moving them to the zzzap group they still remain there persistently until purged or "zapped" from the zzzap group. When comfortable you can purge the whole zzzap group with the operation

Purge Zzzap group (keys: z)

So, typing


would remove everything in the zzzap group forever. However, even that is not completely true since before the purge operation the Agroups save file is saved to a backup file as does every operation that changes the save file.

In the event that a subgroup of the zzzap group is the current group when it is purged the current persistent group becomes the current group. If such a subgroup is the current persistent group the current group becomes the current persistent group. If both the current group and current persistent group are contained by the zzzap group when purged the zzzap group becomes the current and current persistent group.

Group Organization Example

This section gives no useful information about Agroups itself, it just gives some ideas about how Agroups can be used. Typically a user will associate higher level groups with the actions of some project or class of actions. Here is a typical group organization example

Top level groups    Subgroups and other action entries
----------------    ----------------------------------

  My project 1
      ----- Compiling my files action
      ----- Currently working on file action
      ----- Dired of all source files of this project
      --------------- Other working files (subgroup)
      |                    |
      |                    ------------- file 1 action
      |                    |
      |                     ------------ file 2 action
      --------------- Keyboard macros used on project 1 (subgroup)
      |                    |
      |                    --------------- keyboard macro 1
      |                    |
      |                    --------------- keyboard macro 2
      ---------- My project 1, sub-project 1 (subgroup) ...
      ---------- My project 1, sub-project 2 (subgroup) ...
      ---------- Less used subgroups (subgroup)
      |              |
      |              ---------- subsubgroup 1
      |              |              |
      |              |              ----------- subsubgroup entry 1
      |              |              |
      |              |              ----------- subsubgroup entry 2
      |              |
      |              ---------- subsubgroup 2
      |                                    ... etc
  My project 2
      -------- ... similar kinds of entries
  global group
      --------- Some file action frequently used in all groups
      ------------- Keyboard macros used on all projects (subgroup)
      |                |
      |                --------------- keyboard macro 1
      |                |
      |                --------------- keyboard macro 2
  zzzap group
      ----- Some action that I probably no longer need
      ----- Some group that I probably no longer need

Of course much like file directory structures, your organization is completely your choice. It is also your choice as how to use subgroups to organize your actions or not use them at all. However subgroups can be quit useful and here are a few examples:

1. Manipulating project groups. As an example, when you want to put on hold and stash away a project that you have represented as group you can move to another group called, let's say, "Old Projects".

2. Using a subgroup as a prefix. For example, lets say that you have a project group where you have all sorts of text strings that you need to recall and insert that are specific to that project. You can create a subgroup called "Insert Text" with accelerator keys "i". The "i" then in effect becomes a prefix for inserting text. So if you create in the subgroup "i" actions to insert text then you can type

KA i <one of the text inserts>

In effect it is as if the "i" is a prefix key to all of your insertion automations. If KA is bound to a control key then it may make sense to us "C-i" here as an accelerator keys instead of "i".

3. Category systems. For example, extending the example in (2.) instead of just a subgroup "i" we might have subsubgroups in "i" for different text categories. And we could enter

KA i <select text category> <one of the text inserts>

to get to a specific instance of a category.

4. Sub-projects. You could have a project that has sub-projects and sub-sub-projects etc. Since a subgroup can be made the current and/or current persistent group it makes it easy to switch contexts while associated the sub-projects with the major project.

Go to the first, previous, next, last section, table of contents.