/ 
CodeGen-Cpppp-0.001_04
River stage zero No dependents
/ CodeGen::Cpppp

NAME

CodeGen::Cpppp - The C Perl-Powered Pre-Processor

VERSION

version 0.001_04

SYNOPSIS

Does that mean it's more powerful? ...Is it more powerful?

Well, it's one layer of abstraction higher, isn't it? It's not m4. You see, most blokes gonna be templating with cpp or m4, you're on m4 here all the way up, all the way up, Where can you go from there? Where?

Nowhere! Exactly.

What we do is if we need that extra, push, over the cliff, you know what we do?

perl, exactly.

These go to perl.

Input:

#! /usr/bin/env cpppp
## param $min_bits = 8;
## param $max_bits = 16;
## param $feature_parent = 0;
## param $feature_count = 0;
## param @extra_node_fields;
##
## for (my $bits= $min_bits; $bits <= $max_bits; $bits <<= 1) {
struct tree_node_$bits {
  uint${bits}_t  left :  ${{$bits-1}},
                 color:  1,
                 right:  ${{$bits-1}},
                 parent,   ## if $feature_parent;
                 count,    ## if $feature_count;
                 $trim_comma $trim_ws;
  @extra_node_fields;
};
## }

Output:

struct tree_node_8 {
  uint8_t  left :  7,
           color:  1,
           right:  7;
};
struct tree_node_16 {
  uint16_t left : 15,
           color:  1,
           right: 15;
};

DESCRIPTION

WARNING: this API is completely and totally unstable.

This module is a preprocessor for C, or maybe more like a perl template engine that specializes in generating C code. Each input file gets translated to Perl in a way that declares a new OO class, and then you can create instances of that class with various parameters to generate your C output, or call methods on it like automatically generating headers or function prototypes.

For the end-user, there is a 'cpppp' command line tool that behaves much like the 'cpp' tool.

If you have an interest in this, contact me, because I could use help brainstorming ideas about how to accommodate the most possibilities, here.

Possible Future Features:

  • Scan existing headers to discover available macros, structs, and functions on the host.

  • Pass a list of headers through the real cpp and analyze the macro output.

  • Shell out to a compiler to find 'sizeof' information for structs.

  • Directly perform the work of inlining one function into another.

ATTRIBUTES

autocomma

Default value for new templates; determines whether expansion of an array variable will automatically join with commas depending on the surrounding generated C code.

autostatementline

Default value for new templates; determines whether expansion of an array variable in statement context automatically joins them with a semicolon and line feed.

autoindent

Default value for new templates; determines whether embedded newlines inside variables that expand in the source code will automatically have indent applied.

autocolumn

Default value for new templates; enables the feature that detects column layout in the source template, and attempts to line up those same elements in the output after variables have been expanded.

include_path

An arrayref of directories to search for template files during require_template.

output

An instance of CodeGen::Cpppp::Output that is used as the default output parameter for all automatically-created templates, thus collecting all their output.

CONSTRUCTOR

new

Bare-bones for now, it accepts whatever hash values you hand to it.

METHODS

require_template

$tpl_class= $cpppp->require_template($filename);

Load a template from a file, and die if not found or if it fails to compile. Subsequent loads of the same file return the same class.

find_template

$abs_path= $cpppp->find_template($filename);

Check the filename itself, and relative to all paths in "include_path", and return the absolute path to the first match.

new_template

$tpl_instance= $cpppp->new_template($class_or_filename, %params);

Load a template by filename (or use an already-loaded class) and construct a new instance using %params but also with the context and output defaulting to this $cpppp instance, and return the template object.

compile_cpppp

$cpppp->compile_cpppp($filename);
$cpppp->compile_cpppp($input_fh, $filename);
$cpppp->compile_cpppp(\$scalar_tpl, $filename, $line_offset);

This reads the input file handle (or scalar-ref) and builds a new perl template class out of it (and dies if there are syntax errors in the template).

Yes, this 'eval's the input, and no, there are not any guards against malicious templates. But you run the same risk any time you run someone's './configure' script.

patch_file

$cpppp->patch_file($filename, $marker, $new_content);

Reads $filename, looking for lines containing "BEGIN $merker" and "END $marker". If not found, it dies. It then replaces all the lines between those two lines with $new_content, and writes it back to the same file handle.

Example:

my $tpl= $cpppp->require_template("example.cp");
my $out= $tpl->new->output;
$cpppp->patch_file("project.h", "example.cp", $out->get('public'));
$cpppp->patch_file("internal.h", "example.cp", $out->get('protected'));

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Michael Conrad.

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