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

Editing Entries and Groups

Once you create entries and groups you may not be happy with one of the components. Agroups has an Editor and edit operations that you can use to both look at the details of entries or groups and edit them. When creating new entries action template expansion may also use the Agroups editor to fill slots that need data from the user. Special editors for certain slot data can also be invoked.

Editing Operations

There are three operations for editing

Edit an entry (keys: e)
Edit current group (keys: E)
Edit last edited or added entry (keys: C-e)

The "e" operation will ask the user to select an entry from the current group to edit. The "E" operation will edit the current group. The "C-e" operation will re-edit the last entry you edited or the last entry, subgroup or clone that was added. Re-editing is useful when you want to continuously edit components of the same entry or prototyping an entry.

When you edit an entry or group the Agroups editor asks you to choose one of the components of the entry to edit, See section Entry Components. Thus, when you edit an entry Agroups displays the group that the entry is in followed by the components of that entry and prompts you with

Enter to edit: id: i, keys: k, object: RET, exit: SPC:

where each of these choices represents one of the components. SPC just exits the edit mode so enter SPC if you just wanted to view the contents of the entry or skip editing it. Selecting RET will edit the object of the entry which we say more about later.

When you select to edit the id with "i" the Agroups editor brings up an Agroups edit buffer with the current id and waits for you to edit and save it. See the section Entering and Editing Data for how to do this, See section Entering and Editing Data.

When you select to edit the keys with "k" Agroups prompts you in the minibuffer to enter one or more keys terminated by a RET. Note that there is no way to edit this minibuffer since, except for C-g and RET anything is possible to type for keys. For example a C-b normally bound to backward-char would just be accepted as a legitimate key. So if you make an error in typing the keys you just have to abort and retype the keys or accept and re-edit the keys.

When you edit a non-group entry the Agroups editor displays the object component of that entry as

object: This is a template based entry with slot values:

followed by a list of the description of slots with their values. When the user selects to edit the object with RET the Agroups template editor will list and ask for a slot to edit. When you select the slot Agroups then pops up an Agroups edit buffer with the value of the slot in that buffer for editing. See the section Entering and Editing Data for how this is done, See section Entering and Editing Data.

Editing the object of a group entry is equivalent to the process of selecting and editing an entry in that group. This is evident when the object of the group entry is displayed

object: This is a group entry who's object is more entries
        Editing this object will select and edit one of those entries

Entering and Editing Data

When you edit entry component data the Agroups editor uses a simple and consistent paradigm. This section describes this data entry paradigm. Templates also use the Agroups editor for entering data and thus the paradigm outlined in this section applies to editing and entering the template data as well.

As an example, when you edit the id component of an entry an Agroups edit buffer pops up with the following

Entry id (one line only)
    ---- Edit or enter below and type C-cC-c when done ----

This is the common buffer layout for both editing action components and template expansion that needs similar kinds of data. The first lines in this buffer ending and including the line with the C-cC-c prompt are called the header. The first line in the header will start the description of the kind of data it is expecting you to enter or edit and varies from one action component to another. In this particular component it suggests you enter one line only for the id since ids of one line look better and are easier to deal with and if you enter more than one line Agroups will truncate the id to the first line. The object component slot data though could have any number of header lines to describe the data to be entered and allow any number of user entered lines after the C-cC-c prompt line.

The completion directive line with the "type C-cC-c" is always the same and directs you to type C-cC-c when you are done entering or editing your data. You should not tamper with these header lines. You simply start entering and editing your data after the completion directive line and finish with a C-cC-c.

In the case of editing an existing object component slot, the lines following the directive line will reflect the existing slot value. The mode of the Agroups edit buffer will also reflect the type of data there. For example if it is text it will be in text-mode, if it is Elisp it will be in lisp-interaction-mode.

In the event that you do not want what you have done so far in an entry component edit buffer then you can just ignore or kill this buffer. This is always safe since entering or editing entry component data never takes any action until it has all of its data.

It is a general rule of thumb that putting a RET at the end of data entered this way is usually not a concern unless that return will be used in some way by the user actually executing the entry action. For example in the Insert Text action if the user wants a final RET in his data when inserted into a buffer he will put it there otherwise he would not. And in the above case of "Entry id (one line only)" the editor constrains the input to one line so any RET or second or more lines will be ignored. We say "usually not a concern" since in the space of user defined action templates anything is possible, however a well designed template will make this transparent.

Special Slot Editors

Every slot in a template does not have to be edited by the standard Agroups editor paradigm discussed in the previous section. Action templates allow the designer to specify a special editor for chosen template slots. When the user chooses to edit a particular action object slot that had such a special slot editor specified Agroups will automatically send that slot value to the special editor and then when the special editor paradigm completion takes place the resulting value will be placed in the slot just like in the standard editor paradigm.

The given actions in this document will specify when and where a special editor is used. The Keyboard Macro action is a typical example of this. Editing the Keyboard Macro action entry slot for the macro's keys string will bring up the Emacs keyboard macro editor on that slot, See section Keyboard Macro Action.

Setting Entry Actions

All components of an entry can be edited except the action component. This is deliberate. Allowing the user to edit entry actions would cause chaos since there is little chance that any two given actions are congruent, ie. that all of their slots match in type and number. However, in very special circumstances Agroups allows a controlled form of doing this to some extent.

Agroups provides an operation for setting all entry actions of an existing action in a user's Agroups save file to another action

Set save file Actions (experts only) (keys: s A)

It will prompt for an existing action and then a new action to replace it with. The existing action can be any possible action name except the "group" action.

This operation should only be done by experts or on the advice of experts since the unwary user can create bogus entries in his Agroups save file by using this operation. It should only be done where the new action is congruent to the existing action. For example, if the new action is just a renaming of an existing one they would be congruent. Most use of this operation is by user template designers who have to change the name of an action in their template for some reason.

This operation will replace all occurrences of an existing action name with of a new action name in the users Agroups save file. If it finds any occurrences of the old action it will first save the user's save file in a file called

<save file name>-with-<old action name>        

and then do the replacements; possibly needed to revert back to if a mistake was made in performing this operation.

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