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.

cpanm Rakudo::Star

perl -MCPAN -e shell
install Rakudo::Star