A text box appearing on a function's page allows the refactoring of
a function's arguments across all identified calls of the function.
This box will appear only for functions whose identifiers are
writable (i.e. all instances of them appear in writable files),
and where there is a one to one correspondence between the function
name and the corresponding identifier.
If the same identifier is aliased through a macro to refer to various functions
or if a function's name is generated by pasting together multiple identifiers,
then the function argument refactoring facility will not be made available
for that function.
The requirement for the function's identifier to be writable can be overridden
through the options page.
To refactor the function's arguments, one simply enters in the text box
a template describing the argument replacement pattern.
The template consists of text, which is copied verbatim as a function's
argument, and elements starting with the operator @, which have a special
meaning.
The combined effect of this template mechanism allows you to
Introduce new arguments
Remove existing arguments
Change the arguments' order
The following types of @ operator are supported.
N is always an integer starting from 1, and denotes the function's Nth argument.
@N
pastes the original Nth argument passed to the function.
Thus, @1 will get replaced with the function's first argument.
Specifying in a template for a function taking two arguments "@2, @1" will
swap their order, while specifying "@1, sizeof(@1), stdin" as
the arguments for gets will refactor them in a form suitable for
calling fgets (if the original argument refers to a fixed-size character array).
@.N
pastes the Nth argument and all subsequent ones, separated
by commas.
This is useful for handling functions with a variable number of arguments,
like printf.
Specifying in a template for the printf function
"stdout, @1, @.2" will introduce an extra first parameter, named stdout.
(Presumably the function will also be renamed to fprintf.)
@+N{...}
pastes the text in the braces, if the specific
function being replaced has an Nth argument.
The text in the braces can include arbitrary text,
including nested @ operators.
@-N{...}
pastes the text in the braces, if the specific
function being replaced does not have an Nth argument.
The last two operators can often be combined to achieve more complex results.
For instance, the template "@1, @2, @+3{@3}@-3{NULL}" will add to any
call to the function missing a third argument, a third argument with a
value of NULL.
Note that the refactorings will take place on all instances where the
identifier is found to match the function or macro.
This includes declarations and definitions
(which might require some hand-editing if arguments are introduced),
and the appearance of the name in the replacement
text of a macro, when that macro is used in a way that makes the function
match the one being refactored.
The replacements will not be performed to function calls that are executed
through a function pointer.