NAME

Parrot::Headerizer::Functions - Functions used in headerizer programs

SYNOPSIS

    use Parrot::Headerizer::Functions qw(
        process_argv
        read_file
        write_file
        qualify_sourcefile
        replace_pod_item
        no_both_PARROT_EXPORT_and_PARROT_INLINE
        validate_prototype_args
        no_both_static_and_PARROT_EXPORT
        handle_split_declaration
        asserts_from_args
        clean_args_for_declarations
        handle_modified_args
        add_asserts_to_declarations
        add_newline_if_multiline
        func_modifies
        add_headerizer_markers
    );

DESCRIPTION

This package holds (non-object-oriented) functions used in tools/dev/headerizer.pl.

SUBROUTINES

`process_argv`

Purpose
Validate (mostly, deduplicate) list of names of object files provided as arguments.
Arguments
```
    @ofiles = process_argv(@ARGV);
```
List of files specified on the command-line.
Return Value
Deduplicated list of object files. Dies if no filenames were specified as arguments.

`read_file()`

Purpose
Read a file into a string.
Arguments
String holding name of file to be read.
Return Value
String holding the file's content.
Comment
We can't alias this to Parrot::BuildUtil::slurp_file() because that function changes DOS line endings to Unix, which we don't necessarily want here.

`write_file()`

Purpose
Write a file.
Arguments
List of two scalars: string holding name of file to be written; text to be written to the file.
Return Value
Implicitly returns true upon success.

`qualify_sourcefile()`

Purpose
Given the name of a C object file, derive the name of its .c or .pmc source code file, verify that file's existence, read in its source code, and verify the existence of the corresponding .h file.
Arguments
```
    my ($sourcefile, $source_code, $hfile) =
        qualify_sourcefile( {
            ofile           => $ofile,
            PConfig         => \%PConfig,
            is_yacc         => $is_yacc,
        } );
```
Reference to hash with 3 key-value pairs:
- ofile
  String holding name of C or yacc object file.
- PConfig
  Reference to Parrot configuration hash.
- is_yacc
  Boolean reporting whether the source code file is a yacc file or not.
Return Value
List of 3 scalars: String holding source code file, string holding the ssource code, string holding header file (or none if no header file is found).
Comment
The subroutine will die if the value provided for ofile does not have a corresponding .c file or if it is a yacc file. The subroutine will also die if it cannot locate an HEADERIZER HFILE directive in the source code file. The subroutine will also die if any header file referenced from the source code cannot be located.

`replace_pod_item()`

Purpose
In the course of headerizing, replaces a POD =item-type line with a heading created by generate_documentation_signature().

Arguments

    $text = replace_pod_item( {
        text        => $text,
        name        => $name,
        heading     => $heading,
        cfile_name  => $cfile_name,
    } );

Return Value
String holding modified text of file.

`no_both_PARROT_EXPORT_and_PARROT_INLINE()`

Purpose
Checks that a given Parrot function cannot simultaneously have both of the macros in the function's name.

Arguments

    no_both_PARROT_EXPORT_and_PARROT_INLINE( {
        file            => $file,
        name            => $name,
        parrot_inline   => $parrot_inline,
        parrot_api      => $parrot_api,
    } );

Return Value
Returns true value upon success.

`validate_prototype_args()`

Purpose
Performs some validation on prototype arguments.

Arguments

    @args = validate_prototype_args( $args, $proto );

Return Value

`no_both_static_and_PARROT_EXPORT()`

Purpose
Checks that a given function cannot be simultaneously labelled as both static and PARROT_EXPORT.

Arguments

    ($return_type, $is_static) = no_both_static_and_PARROT_EXPORT( {
        file            => $file,
        name            => $name,
        return_type     => $return_type,
        parrot_api      => $parrot_api,
    } );

Return Value
List of two items: String holding the return type; Boolean indicating whether function is static or not.

`handle_split_declaration()`

Purpose
Reformats declarations with appropriate line breaks to avoid long, unwieldy lines.

Arguments

    $split_decl = handle_split_declaration(
        $function_decl,
        $line_len,
    );

Return Value
String holding declaration, broken into shorter lines as needed.

`asserts_from_args()`

Purpose
Compose assertions to be added to headers.

Arguments

    @asserts = asserts_from_args( @this_functions_args );

List of function arguments.

Return Value
List of strings holding assertions to be added to that function's header.
Comment
Called within add_asserts_to_declarations().

`clean_args_for_declarations()`

Removes SHIM()s from args for putting into declarations.

`handle_modified_args()`

Purpose
Performs some modifications of arguments.
Arguments
```
    ($decl, $multiline) = handle_modified_args($decl, \@modified_args);
```
List of two arguments: string holding a declaration; reference to an array of modified arguments.
Return Value
List of two elements: String holding declaration, modified as needed; Boolean indicating whether declaration runs over more than one line (multiline) or not.

`add_newline_if_multiline()`

Purpose
Guarantee proper formatting of multiline declarations.
Arguments
```
    $decl = add_newline_if_multiline($decl, $multiline);
```
List of two arguments: String holding declaration; scalar holding Boolean indicating whether declaration runs over more than one line or not.
Return Value
String holding the declaration, with an additional newline added as needed.

`add_asserts_to_declarations()`

Purpose
Formulates an assertion, where needed. Currently, assertions begin like this:
```
    #define ASSERT_ARGS_
```
Arguments
```
    @decls = add_asserts_to_declarations( \@funcs, \@decls );
```
List of two arguments: Reference to array of hash references holding characteristics of functions; reference to array of declarations.
Return Value
List of strings holding declarations.

`func_modifies()`

Purpose
Add FUNC_MODIFIES where needed.
Arguments
```
   @mods = func_modifies($arg, \@mods);
```
List of two items: String holding function text; reference to array of modifications.
Return Value
Augmented list of modifications.

`add_headerizer_markers()`

Purpose
Takes headerizer markers in source code files (like HEADERIZER_BEGIN and HEADERIZER END) and formulates appropriate variants to be placed in the headerfile.

Arguments

    $source_code = add_headerizer_markers( {
        function_decls  => \@function_decls,
        sourcefile      => $sourcefile,
        hfile           => $hfile,
        code            => $source_code,
    } );

Return Value
String holding modified source code.