6.1 User Defined Functions are Registered ¶

User defined functions are always passed as a code reference to a registering function, together with a string describing what the function formats. In the following made up example, my_formatting_function is passed as a function reference \&my_formatting_function to the registering function texinfo_register_command_formatting, with the string specifying the formatting done by the function being ‘format_thing’:

sub my_formatting_function {
  my $arg1 = shift;
  my $arg2 = shift;
  # prepare $formatted_text
  ...
  return $formatted_text;
}

texinfo_register_command_formatting ('format_thing', \&my_formatting_function);

As such functions are defined by a reference name associated with a string we will always use the string in function prototypes. For the function arguments we will use \@array to indicate a reference to an array (a.k.a. list, in Perl terminology), \%hash for a reference to a hash and \&function for a reference on a function.

To illustrate these conventions, here is the prototype for the function associated with ‘format_thing’:

Function Reference: $text format_thing ($arg1, \@arg2) ¶

A function reference associated with ‘format_thing’ has a first argument $arg1, a second argument a reference to an array \@arg2, and returns the formatted text $text.