NAME

Parse::H - A parser for C header files that calls the given subroutines when a symbol of a specified type is encountered.

VERSION

Version 0.21

DESCRIPTION

This module provides subroutines for parsing C language header files (*.h files) while calling user-provided callback subroutines on various found elements.

SYNOPSIS

    use Parse::H qw(parse_file);

    open (my $infile, '<', 'test.h') or die "Cannot open test.h: $!\n";

    my $extern_sub = sub { ... }
    my $comment_sub = sub { ... }
    my $preproc_sub = sub { ... }
    my $typedef_sub = sub { ... }
    my $struct_start_sub = sub { ... }
    my $struct_entry_sub = sub { ... }
    my $struct_end_sub = sub { ... }
    my $enum_start_sub = sub { ... }
    my $enum_entry_sub = sub { ... }
    my $enum_end_sub = sub { ... }
    my $union_start_sub = sub { ... }
    my $union_entry_sub = sub { ... }
    my $union_end_sub = sub { ... }
    my $output_sub = sub { ... }

    my %params = (
        'infile' => $infile,
        'output_sub' => $output_sub,
        'comment_sub' => $comment_sub,
        'preproc_sub' => $preproc_sub,
        'extern_sub' => $extern_sub,
        'typedef_sub' => $typedef_sub,
        'struct_start_sub' => $struct_start_sub,
        'struct_entry_sub' => $struct_entry_sub,
        'struct_end_sub' => $struct_end_sub,
        'union_start_sub' => $union_start_sub,
        'union_entry_sub' => $union_entry_sub,
        'union_end_sub' => $union_end_sub,
        'enum_start_sub' => $enum_start_sub,
        'enum_entry_sub' => $enum_entry_sub,
        'enum_end_sub' => $enum_end_sub,
        'pointer_size' => 8,
    );

    parse_file (%params);

    close $infile;

EXPORT

 Nothing is exported by default.

 The following functions are exported on request:
        parse_struct
        parse_union
        parse_file

 These parse a C "struct" type, a C "union" type or a whole C header
 file, respectively.

DATA

parse_struct

 Parses a C "structure" type, calling the provided subroutines when
  a symbol of a specified type is encountered.
 Parameters: a hash containing the input file handle and references to
  the subroutines. All subroutines should return a line of text (which
  may later go to $output_sub) after their processing of the given parameter.
 If a key is not present in the hash, its functionality is not used
  (unless a default value is specified).
 Hash keys:

        'infile' => input file handle (required),
        'line' => the current line to process (default: empty line),
        'output_sub' => a subroutine that processes the output.
                Takes the line to output as its single parameter,
        'comment_sub' => a subroutine that processes comments.
                Takes the current line as its single parameter,
        'preproc_sub' => a subroutine that processes preprocessor lines.
                Takes the current line as its single parameter,
        'struct_start_sub' => a subroutine that processes the beginning of a structure.
                Takes the structure name as its single parameter,
        'struct_entry_sub' => a subroutine that processes an entry of a structure.
                Takes the symbol name as its first parameter, its size as the second and the structure name as the third,
        'struct_end_sub' => a subroutine that processes the end of a structure.
                Takes the structure name as its first parameter and its size as the second,
        'union_start_sub' => a subroutine that processes the beginning of a union.
                Takes the union name as its single parameter,
        'union_entry_sub' => a subroutine that processes an entry of a union.
                Takes the symbol name as its first parameter and its size as the second,
        'union_end_sub' => a subroutine that processes the end of a union.
                Takes the symbol name as its first parameter, its size as the second and the union name as the third,
        'pointer_size' => the pointer size to use, in bytes (default: 8),

parse_union

 Parses a C "union" type, calling the provided subroutines when
  a symbol of a specified type is encountered.
 Parameters: a hash containing the input file handle and references to
  the subroutines. All subroutines should return a line of text (which
  may later go to $output_sub) after their processing of the given parameter.
 If a key is not present in the hash, its functionality is not used
  (unless a default value is specified).
 Hash keys:

        'infile' => input file handle (required),
        'line' => the current line to process (default: empty line),
        'output_sub' => a subroutine that processes the output.
                Takes the line to output as its single parameter,
        'comment_sub' => a subroutine that processes comments.
                Takes the current line as its single parameter,
        'preproc_sub' => a subroutine that processes preprocessor lines.
                Takes the current line as its single parameter,
        'struct_start_sub' => a subroutine that processes the beginning of a structure.
                Takes the structure name as its single parameter,
        'struct_entry_sub' => a subroutine that processes an entry of a structure.
                Takes the symbol name as its first parameter, its size as the second and the structure name as the third,
        'struct_end_sub' => a subroutine that processes the end of a structure.
                Takes the structure name as its first parameter and its size as the second,
        'union_start_sub' => a subroutine that processes the beginning of a union.
                Takes the union name as its single parameter,
        'union_entry_sub' => a subroutine that processes an entry of a union.
                Takes the symbol name as its first parameter and its size as the second,
        'union_end_sub' => a subroutine that processes the end of a union.
                Takes the symbol name as its first parameter, its size as the second and the union name as the third,
        'pointer_size' => the pointer size to use, in bytes (default: 8),

parse_file

 Parses a C header file, calling the provided subroutines when
  a symbol of a specified type is encountered.
 Parameters: a hash containing the input file handle and references to
  the subroutines. All subroutines should return a line of text (which
  may later go to $output_sub) after their processing of the given parameter.
 If a key is not present in the hash, its functionality is not used
  (unless a default value is specified).
 Hash keys:

        'infile' => input file handle (required),
        'output_sub' => a subroutine that processes the output.
                Takes the line to output as its single parameter,
        'comment_sub' => a subroutine that processes comments.
                Takes the current line as its single parameter,
        'preproc_sub' => a subroutine that processes preprocessor lines.
                Takes the current line as its single parameter,
        'extern_sub' => a subroutine that processes external symbol declarations.
                Takes the symbol name as its single parameter,
        'typedef_sub' => a subroutine that processes typedefs.
                Takes the old type's name as its first parameter and the new type's name as the second,
        'struct_start_sub' => a subroutine that processes the beginning of a structure.
                Takes the structure name as its single parameter,
        'struct_entry_sub' => a subroutine that processes an entry of a structure.
                Takes the symbol name as its first parameter, its size as the second and the structure name as the third,
        'struct_end_sub' => a subroutine that processes the end of a structure.
                Takes the structure name as its first parameter and its size as the second,
        'union_start_sub' => a subroutine that processes the beginning of a union.
                Takes the union name as its single parameter,
        'union_entry_sub' => a subroutine that processes an entry of a union.
                Takes the symbol name as its first parameter and its size as the second,
        'union_end_sub' => a subroutine that processes the end of a union.
                Takes the symbol name as its first parameter, its size as the second and the union name as the third,
        'enum_start_sub' => a subroutine that processes the beginning of an enumeration.
                Takes the enum's name as its single parameter,
        'enum_entry_sub' => a subroutine that processes an entry of an enumeration.
                Takes the symbol name as its first parameter and its value as the second,
        'enum_end_sub' => a subroutine that processes the end of an enumeration.
                Takes no parameters,
        'pointer_size' => the pointer size to use, in bytes (default: 8),

SUPPORT AND DOCUMENTATION

After installing, you can find documentation for this module with the perldoc command.

    perldoc Parse::H

You can also look for information at:

    Search CPAN
        https://metacpan.org/release/Parse-H

    CPAN Request Tracker:
        https://rt.cpan.org/Public/Dist/Display.html?Name=Parse-H

AUTHOR

Bogdan Drozdowski, <bogdro /at cpan . org>

COPYRIGHT

Copyright 2022-2023 Bogdan Drozdowski, all rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.