NAME

Parrot::Headerizer - Parrot header generation functionality

SYNOPSIS

use Parrot::Headerizer;

$headerizer = Parrot::Headerizer->new( {
    macro_match => $macro_match, # optional
} );

$headerizer->get_sources(@ofiles);
$headerizer->process_sources();
$headerizer->print_final_message();
$headerizer->print_warnings();

@function_decls = $headerizer->extract_function_declarations($buf);
$escaped_decl = $headerizer->generate_documentation_signature($function_decl);

DESCRIPTION

Parrot::Headerizer knows how to extract all kinds of information out of C-language files. Its methods are used in tools/dev/headerizer.pl and t/codingstd/c_function_docs.t.

METHODS

new()

• Purpose

  Constructor of headerizer object. The object is initialized with a list of valid PARROT_XXX macros.

• Arguments

  $headerizer = Parrot::Headerizer->new();

  No mandatory arguments, but one special use-case takes a hash reference.

  $headerizer = Parrot::Headerizer->new( {
      macro_match => $macro_match, # optional
  } );

  Currently, the only meaningful element in that hash reference is macro_match. See process_sources() below for discussion of how that is used.

• Return Value

  Parrot::Headerizer object.

get_sources()

• Purpose

  Identify the source code files which need to have header information extracted. The header information is extracted and stored inside the headerizer object in appropriate ways.

• Arguments

  $headerizer->get_sources(@ofiles);

  List of names of C object (.o) files.

• Return Value

  No defined return value.

extract_function_declarations()

• Purpose

  Extracts the function declarations from the text argument, and returns an array of strings containing the function declarations.

• Arguments

  @function_decls = $headerizer->extract_function_declarations($text)

  String holding the slurped-in content of a source code file.

• Return Value

  List of strings holding function declarations.

• Comment

  Called within get_sources(), but also called on its own within t/codingstd/c_function_docs.t.

extract_function_declaration_and_update_source()

• Purpose

  Extract all the function declarations from a source code file and update the comment blocks within it.

• Arguments

  @function_declarations =
      $headerizer->extract_function_declaration_and_update_source($cfile_name);

  String holding source code filename.

• Return Value

  List of strings holding function declarations.

• Comment

  Called within get_sources(). Wraps around extract_function_declarations() but differs from that method by generating signatures, correcting POD, etc.

function_components_from_declaration($file, $proto)

• Purpose

  Creates a data structure in which information about a particular function can be looked up.

• Arguments

  List of two strings, the filename and the function declaration.

• Return Value

  Returns a reference to a hash of these function components:

  file
  name
  args
  macros
  is_static
  is_inline
  is_api
  is_ignorable
  return_type

• Comment

  Currently called within both extract_function_declarations() and extract_function_declarations_and_update_source().

check_pointer_return_type()

• Purpose

  Performs some validation in the case where a function's return value is a pointer.

• Arguments

  $headerizer->check_pointer_return_type( {
      return_type     => $return_type,
      macros          => \%macros,
      name            => $name,
      file            => $file,
  } );

  Reference to a hash with the four elements listed above.

• Return Value

  No defined return value.

generate_documentation_signature()

• Purpose

  Given an extracted function signature, return a modified version suitable for inclusion in POD documentation.

• Arguments

  $heading = $headerizer->generate_documentation_signature($decl);

  String holding a function declaration.

• Return Value

  String holding a function header, split over multiple lines as needed.

valid_macro()

• Purpose

  Tests the validity of a given macro.

• Arguments

  $headerizer->valid_macro( $macro )

  String holding a macro.

• Return Value

  Boolean: true value for valid macro; false value for invalid macro.

valid_macros()

• Purpose

  Identify all valid macros whose names are of the form PARROT_XXX.

• Arguments

  @marcros = $headerizer->valid_macros();

  None.

• Return Value

  List of all the valid PARROT_XXX macros.

squawk()

• Purpose

  Builds a data structure with headerizer-specific ways of complaining if something went wrong.

• Arguments

  $headerizer->squawk($file, $func, $error);

  List of 3 arguments: the file containing the error; the function containing the error; the text of the error message.

• Return Value

  Undefined value.

• Comment

  squawk() does not print any warnings or errors itself. Use print_warnings() to report those.

process_sources()

• Purpose

  Once the source files needing headerization have been identified, this method serves as a wrapper around that headerization. Both .h and .c files are handled.

• Arguments

  None.

• Return Value

  None.

• Comment

  If a hash reference with an element named macro_match was passed to new(), process_sources() merely prints to STDOUT a list of files and functions using the macro named as the value of that element. No headerization or revision of headers is performed.

replace_headerized_declarations()

• Purpose

• Arguments

• Return Value

make_function_decls()

• Purpose

  Composes proper function declarations.

• Arguments

  @function_decls = $self->make_function_decls(@funcs);

  List of functions.

• Return Value

  List of function declarations.

• Comment

  Called within replace_headerized_declarations().

attrs_from_args()

• Purpose

  Adds to headers strings of the form __attribute__nonnull__(1).

• Arguments

  @attrs   = $headerizer->attrs_from_args( $func, @args );

  List whose first element is a hash reference holding characteristics about a given function, followed by list of arguments.

• Return Value

  List.

• Comment

  Called within make_function_decls().

print_final_message()

• Purpose

  Prints a concluding message whose content reflects either normal headerization or macro matching.

• Arguments

  None.

• Return Value

  Implicitly returns true value upon success.

print_headerizer_warnings()

• Purpose

  Print all warnings accumulated in the course of the headerization process.

• Arguments

  None.

• Return Value

  Implicitly returns true value upon success.

cpanm Rakudo::Star

perl -MCPAN -e shell
install Rakudo::Star