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


Creating Action Entries

This chapter describes the Agroups actions that can be selected as an operation which creates an entry of a specific instance of that action in the current group. Actions are accumulated into two collections: Predefined Actions and User Defined Actions. Predefined Actions are Agroups given actions. We discuss below how to access Predefined Actions and then describe the Predefined Action collection.

The user can define his own collection of actions using action templates, See section Action Templates. But obviously, since some user needs to define these specific user action templates they can not be described in this document. This chapter just shows how to access user defined actions when and if they are created.

Note that some action entry instances when executed may take optional prefix arguments for doing the action multiple times or for some special effect of the action. Each action description below will discuss the effects of its prefix arguments if any.

Entering Action Data

All actions will allow a user to optionally just hit RET when asking for an entry id and will automatically generate a reasonable id.

All Agroups actions are created using action templates. In the process of selecting an operation that creates an action entry the operation expands the associated action template and it frequently asks the user to enter some data for filling a particular template slot. For example, if you were to try the predefined actions operation

Insert Text (keys: t)

it would prompt you to enter text in the Agroups buffer with the following

Text to insert
    ---- Edit or enter below and type C-cC-c when done ----

After entering the data the action template slot called "Text to insert" will be satisfied. In general after all such slots for an action are satisfied the action entry is added to the current group.

This is the common paradigm to enter and edit data both for action template expansion and entry ids. See the section Entering and Editing Data for a complete description of this paradigm, See section Entering and Editing Data.

Any other kind of specialized data entry will be described in each action description in this chapter. For example some action template expansion will request data that doesn't have to be entered just selected from a list of options. And some actions use special editors for entering data. The Keyboard Macro action is an example of this.

Accessing Predefined Actions

Agroups provides a predefined collection of actions that the user can select to create an action entry with the operation

Add a selected Action to current group (keys: a)

You can see a list of these predefined actions with the operation

View predefined Actions (keys: v a)

This "a" operation is in effect a prefix key for the action operations in this list. For example, one of the predefined actions is

Shell command (keys: s)

and so if you type

KA KO a s

it will prompt for shell commands that will be executed when the resulting action entry is executed. The following section describes all of the predefined actions in detail.

Predefined Action Collection

The following sections describe the Agroups predefined action collection. The "a" operation asks the user to select a predefined action which when selected creates an action entry of that associated action.

File Action

The File Action operation

File or dired (keys: f)

will create an entry that given the current buffer's file or dired will return to that file or dired when the action is executed. For example if the current buffer is visiting some file then

KA KO a f

will create an entry in the current group that will return to that file when executed later. The same applies if the current buffer was a dired, it would later return to that dired.

Note that unlike the Point actions, See section Point Actions, it will not tamper with the buffer's point when executed. This means that you can use a File Action entry to first bring up a commonly used file in a buffer and to subsequently return to that buffer as you work on that file instead of flipping between buffers.

Point Actions

There are two given actions that return to a point in a file

File Point (keys: p)
File region Point (keys: P)

The p operation will create an entry that given the current buffer's file and current point in that buffer will return to that point when executed.

The P operation will create an entry that given the current buffer's file and current point and mark in that buffer will return to that point when executed based on the text between point and mark. In other words, when later executed the region (defined by mark and point) of text will be searched for and the point will be placed after the region if point is after the region or before the region if point is before the region. Note that this is easy to do since C-xC-x swaps point and mark. If you make a mistake with before/after by not positioning point where you desired it then you can always edit the entry and change the before/after slot.

Both point actions have the characteristic that if a specific point action of either type (p or P) already exits in the current group with the same file then it will ask if you want to update that action entry with the new point or create a new point action entry. The former is common usage when one wants to keep moving a specific point around as a tracker.

Keyboard Macro Action

This operation will take the last keyboard macro, ie. the last keyboard you defined starting with start-kbd-macro, and creates an entry in the current group with that keyboard macro

Keyboard macro (keys: k)

When executed this operation will prompt for some options:

How keyboard macro will execute
 0 = Will just execute
 1 = Will execute if user says yes
 2 = Will load into last keyboard macro

Usually the default 0 choice is what you want, ie. just execute the keyboard macro when the action entry is executed. However the 1 choice is useful when the keyboard macro does a difficult to undo sequence. This choice will prompt first before actually executing the keyboard macro. The 2 choice is seldom needed, it will simply load the last keyboard macro so that you can execute it with call-last-kbd-macro.

When you execute a keyboard macro action that was created with the 0 and 1 choice, a prefix argument will repeat the macro exactly the same way a prefix argument will repeat call-last-kbd-macro.

When editing the "Keyboard macro" slot this action's template will bring up the standard Emacs keyboard macro editor and will work the same way including any prefix arguments given to the edit operation. See the Emacs Editor document for how to edit keyboard macros.

Keys Macro Action

The Keys macro action, which is short for Agroups Keys only macro action

Keys macro (keys: K)

is something like the Keyboard Macro action where you can create a keyboard macro that executes Agroups itself followed by some legitimate Agrouos keys. But the Keys Macro has some important differences

All of these differences are designed with the idea of referencing groups and entries, See section Referencing Macros. This referencing is similar to that of symbolic links in Unix. Key Macros are not intended to supplant Keyboard Macros in any way but only to augment in this regard relative to Agroups.

A couple of simple examples will clarify this idea. Suppose that in some group g you want to reference an entry e in a subgroup of g called s. You can then create a Keys Macro entry in g that has contains simply

s e

Note that what we display here is the standard Emacs representation for displaying a sequence of keys and that whitespace is significant in a Keys Macro just like a Keyboard Macro. So the above would actually be entered as "se" with no space in between

For a little more complex example, suppose that in the global group "." you want to create a subgroup t of text insertions that are used by many groups. Then in each group where that is needed you could create a Keys Macro that contains

KG . t

where KG is the actual key-binding of KG. Then in each of these groups executing that entry would act exactly equivalent to having that t subgroup in each group except that modifying the subgroup t or any of its entries would in effect happen for all such references to t. The interesting thing about his example is that this would be impossible with Keyboard Macros without some sort of contrived escaping mechanism since "KG . t" is an incomplete operation. Try to create a Keyboard Macro action that tries to do this if it is not clear!

Note that if you want to create a Keys Macro action that selects an entry that does not have any accelerator keys you can do it with completion. You would do this by including a SPC to initiate completion and then an unambiguous string for the target group entry id followed by a RET. To include a RET just type C-q RET. For example, suppose that you wanted to create a Keys Macro action that executes an entry in the current group whose id is "My file of stuff" and suppose that "My fi" would be unambiguous. Then to create the macro we would enter in the Agroups edit buffer " My fi^M", without the double quotes, where the "^M" was the result of typing C-q RET. As a result this Keys Macro entry contents would be displayed as

SPC M y SPC f i RET

Much like the Keyboard Macro action the Keys Macro action gives you the option to execute or prompt but it does not give you the option to load into last keyboard macro since the Keys Macro is never a legitimate Keyboard Macro. Also the Keyboard Macro action loads its initial slot from the last keyboard macro while the Keys Macro action just pops up an Agroups edit buffer for you to enter the keys. Note that similar to the Keyboard Macro you can use a C-q to enter a control character in the Agroups edit buffer for the Keys Macro.

Elisp Actions

The following three operations

Evaluate ELisp (keys: l)
Evaluate ELisp from file (keys: C-l)
Elisp file to Load (keys: L)

add an action entry that evaluates Elisp. If you don't know what Elisp is you probably should not use the "l" and "C-l" operation actions since you may create something that will execute in error.

However if you do know Elisp then these actions give you the ultimate covering case, since anything that can be possible be done in Emacs can be done with these actions. Having said this, the intent of Agroups with its template feature is to not use Elisp if at all possible. If the automation that you are creating with Elisp fits a pattern that might be repeated with different parameters, you might first consider defining a user defined template so that a new action can be applied to an infinite number of specific instances and it makes it easier for other people and even easier yourself to use later, See section Action Templates.

The "l" operation action evaluates an Elisp s-expression that the user specifies. For example if in the user specifies

Elisp s-expression to be evaluated
    ---- Edit or enter below and type C-cC-c when done ----
(message "Hello World!")

then on executing the resulting action entry

Hello World!

should pop up in the minibuffer. Note that the "l" operation action is asking for a single s-expression, so if multiple s-expressions are needed then a progn could be used.

The "L" operation action finds and opens a file of Elisp code that the user specifies, evaluates all the forms in it, and closes the file. This can be Elisp source code or byte compiled code.

Any Elisp code invoked in these actions can use the Agroups prefix arguments, See section Accessing Agroups Prefix Arguments. For example if using with the "l" operation the user specified the Elisp

(next-line agroups-numeric-arg)

then when the resulting action entry was executed with a C-u prefix argument then point would be advanced 4 lines in the current buffer.

The "C-l" operation action is exactly the same as the "l" operation but the user specifies a file with the s-expression. It might seem like the "C-l" operation action is the same as the "L" operation action but it is different in two ways: First, it only evaluates one s-expression in the file just like the "l" operation action. Second, it does not load a file as the "L" operation action does. This is important to allow the "C-l" operation action to be completely symmetric with the "l" operation action since loading a file causes certain changes of context. For example some Elisp that operates on the current buffer using the "l" operation action would not work using the "L" operation action with that same Elisp in a file, but would work using the "C-l" operation with that same Elisp in a file. A case in point is the next-line Elisp example given above.

Compile Command Action

Emacs has a Compilation Mode paradigm for making and or compiling programs. This operation allows the user to create an action entry that uses this paradigm

Compile command (keys: c)

When this operation is selected the following choice menu is given

Type of compile command 
 0 = A full stand alone command
 1 = A command that will be inserted in a prompt
 2 = A command that will be applied to current buffer's file
     Put a %s in command where buffer file will be substituted

The "0" choice will give you an action such that when executed will automatically do a command and bring up the Compilation Mode. The "1" choice will give you the same thing except that the compile command that you give will be inserted into the minibuffer when this action entry is executed so that it can be edited before the command is executed.

The "2" choice is the same as "0" but will act as a command on the file you are visiting in the current buffer when the action is executed. When you enter the command you need to put a %s in the command somewhere. Then when the action is executed the visited file will be substituted for the %s, or in other words your command will be executed on the buffer's visited file.

Once the type of file command is chosen then the action asks for the command itself. You can specify any number of command lines and unlike the Shell Command the default is to run the commands asynchronously so you do not need to put an & on the end of the last command.

Since this action uses the Emacs compile paradigm you can do the usual things, like repeated "C-x`" (next-error) to jump to the next compile error in the file where the error occurs.

Info File Action

This operation is used to create an action entry to bring up an Emacs Info node

Info File (keys: i)

When selected it asks for

Pathname of Info file to invoke
    ---- Edit or enter below and type C-cC-c when done ----

An absolute pathname of an Emacs Info file must be entered here. When executed then the resulting action entry will pop up the Emacs Info mode with the chosen Info file as the top node.

Insert Text Action

This operation is used to create an action entry that inserts some text in the current buffer at point when executed

Insert text (keys: t)

First it asks for the source of the text, either direct text insertion or to insert text from a file

Source of text to insert
 0 = Insert text directly
 1 = Insert text from file

Then it asks for the text

Text to insert or file to insert text from
    ---- Edit or enter below and type C-cC-c when done ----

If you selected 0 in the first prompt then you enter the actual text to insert here. Otherwise you enter a file pathname that will contain the text to be inserted. If the text that is going to be inserted is going to be quite long it is recommended to use the 1 option above and put the text in a file.

When executed the resulting action entry will insert the text specified above at point in the current buffer. If the executed action entry is given a numeric prefix argument N the text is inserted N times.

Insert Text and Position Point Action

This operation does exactly the same thing as the previous Insert Text Action operation but in addition it allow the positioning of point into the text after it is inserted into the current buffer

Insert text and position point (keys: T)

So all of the prompts are the same as the Insert Text Action except for the last one which asks where to position the point after text insertion

Move point back this number of characters
or the symbol 'begin' to go back to beginning of inserted text
or any Elisp expression to be evaluated after text insertion
    ---- Edit or enter below and type C-cC-c when done ----

To this prompt you can either enter a number N, in which case point will move N characters backward into the text after the text is inserted. Or you can enter the symbol begin which will cause point to be positioned at the beginning of the text. Or you can enter any arbitrary Elisp expression that will be evaluated after the text is inserted.

Shell Command Action

This operation is used to create an entry that runs a shell command when executed

Shell command (keys: s)

it prompts for a command with

Shell commands to execute
    ---- Edit or enter below and type C-cC-c when done ----

Note that is says "Shell commands", so any number of command lines can be entered. The shell commands follow the same rules of the Emacs command shell-command. By default the commands will be run synchronously. If you want them to run asynchronously then put an "&" at the end of the last command.

Normally the results of the shell commands are placed in a buffer called "*Shell Command Output*", but an Agroups prefix argument will place the results in the current buffer. This can only be done synchronously.

Run a program in a process Action

This operation is used to create an entry that runs a program in a process

Run a program in a process (keys: S)

The specified program process runs independently of Emacs. That is, if the Emacs process is killed the specified program process continues to run. When you first execute this operation you get the prompt

Program call to execute
    ---- Edit or enter below and type C-cC-c when done ----

where you enter a program name to execute which in most cases is an operating system command so the program name can be relative to execution search paths or an absolute file specification. You then get the prompt

Mode of process operation
 0 = Asynchronous: Run process in parallel with Emacs
 1 = Synchronous: Emacs waits for process to complete

You can select if the process is to run synchronously where Emacs waits for the process to complete or asynchronous where Emacs runs the process and continues with what it was doing. Then you get a prompt

The name of the buffer where the output of program should go
Leave blank if output should be ignored
    ---- Edit or enter below and type C-cC-c when done ----

where if you type in nothing and just type C-cC-c then the output from the process is ignored. If you type in a name the output from the process will be inserted in a buffer by that name.

Accessing User Defined Actions

Besides the predefined actions the user can create a collection of his own actions using action templates, See section Action Templates. Given that, the user can select one of these new actions to create an action entry with the operation

Add a selected user Action to current group (keys: A)

You can see a list of user defined actions with the operation

View user defined Actions (keys: v A)

This "A" operation is in effect a prefix key for the user defined action operations in this list. Except for the fact that the user creates these new actions in this user collection of actions, the "A" operation is the same as the "a" operation.


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