item-list(3)

NAME

item-list - Abbreviated search and list buffer contents.
item-list-find - Find the selected item in the item list
item-list-close - "Close the item list"

SYNOPSIS

item-list (F7) 
item-list-find
item-list-close (esc F7) 

DESCRIPTION

item-list performs a regular expression search of a buffer, presenting a list of the located text and associated types in a separate window which is presented to the left of the buffer window. item-list is a generic function that interacts with the buffer environment variables to present abbreviated buffer information to the user.

The regular expression search strings are predefined in the language templates. To add support for a new buffer type a list of search/replace strings must be created. The search strings must use regex (magic mode) and groups \(..\) to place the located object string into the replace string. Within the template buffer search strings (s) and replace (r) are defined with the following syntax:-

set-variable .hookname.item-list-sx "regexp"
set-variable .hookname.item-list-rx "replace"

Where:-

hookname


The name of the file hook i.e. fhook-c for ANSI 'C'.

x


The search number, this is valid in the range 1..9, commencing from 1. The search is processed in the order of the numeric identity.

regexp


The regular expression to search for. One of the arguments must include a groups \(..\) definition to allow the string to be moved to the replace.

replace


The replace string, this typically includes a type and part of the search string.

On invocation of item-list the buffer is searched and the results are presented in the *item-list* window appearing at the left-hand side of the window. If there is no item list set up for the file type then an error message is displayed.

The user may interact with the *item-list* buffer using the mouse or <RETURN>, on selecting a line then the user is moved to the corresponding line in the original buffer.

item-list-find finds the current item list item and searches for the text in the original buffer. This is typically bound to a mouse or key stroke action.

item-list-close closes the item list buffer.

EXAMPLE

The following example works through the item-list definition for the ME macros e.g. given that the ME macro definition is:

define-macro macro-name 

Searching for "define-macro \([a-z-]+\)" and replacing with "Macro \1" will work most of the time. The space between define-macro and the name does not have to be a single space and the name does not have to contain just lower case letters, so these search strings should be a flexible as possible, try

"define-macro\s +\(\w+\)" 

This however is not as optimal as it could be and if you have large files this could become slow. Performance can be greatly increased if it can be anchored to the start of the line, e.g.

"^define-macro\s +\(\w+\)" 

but to allow for initial white spaces and the optional numeric argument, you really need

"^\s *[0-9]*\s *define-macro\s +\(\w+\)" 

To hilight the function name you need the name encased the name in a magic hilighting string,

"\ecBmacro-name\ecA" 

where \e is an escape char, so the replace string should be

"Macro \ecB\1\ecA" 

Now all thats needed is to set these variables as fhook command variables, for macro files, the file hook command is fhook-emf, therefore the following is required:

set-variable .fhook-emf.item-list-s1 "^\\s *[0-9]*\\s *define-macro\\s +\\(\\w+\\)" 
set-variable .fhook-emf.item-list-r1 "Macro \ecB\\1\ecA" 

Note that you can have as many of these search and replace variables as you require, i.e. .item-list-s1, .item-list-s2, .item-list-s3, ... ; but the more you have the slower it will be, often a good regex can do the job of 2 or 3.

SEE ALSO

occur(3), search-forward(2), Regular Expressions

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12