view release on metacpan or  search on metacpan

lib/C/Utility.pod  view on Meta::CPAN

=head1 NAME

C::Utility - utilities for generating C programs

=head1 SYNOPSIS

   use C::Utility ':all';

=head1 VERSION

This documents C::Utility version 0.012
corresponding to git commit L<23840f2d0676c73ceefdde8dff0967d1ff4eeecc|https://github.com/benkasminbullock/C-Utility/commit/23840f2d0676c73ceefdde8dff0967d1ff4eeecc> released on Sat Sep 1 11:00:14 2018 +0900.

=head1 DESCRIPTION

This module contains functions which assist in automatic generation of
C programs. For work with strings, L</convert_to_c_string> converts a
string into a string with characters correctly escaped for use in a C
program. L</convert_to_c_string_pc> does the same thing plus escaping
percent signs so that they may be used as format strings for
printf. L</escape_string> escapes double quotes. L</valid_c_variable>
checks whether a string is valid as a C variable. 

The module contains various line directive related
functions. L</line_directive> prints a C line directive. L</linein>
and L</lineout> offer a preprocessor and postprocessor to add line
numbers to files made from templates.

=head1 EXPORTS

All the functions are exported on demand. Nothing is exported by
default. An export tag C<:all> exports all the functions.

    use C::Utility ':all';

=head1 FUNCTIONS

=head2 add_lines

    my $text = add_lines ($file);

Read C<$file>, and replace strings of the form #line in the file with
a C-style line directive using C<$file>. Also add a line directive to
the first line of the file. C<$file> must be in the UTF-8
encoding. The line directives are given the full path name of the file
using L<File::Spec/rel2abs>. The return value is the text of the input
file with the line directives added.

I recommend using L</linein> in combination with L</lineout> rather
than this function, since it does not properly handle line directives
for generated parts of the C file. See L</Line numbering> for an
explanation.

=head2 brute_force_line

    brute_force_line ($input_file, $output_file);

Read C<$input_file>, put #line directives on every single line, and
write that to C<$output_file>.

I recommend using L</linein> in combination with L</lineout> rather
than this function, since it does not properly handle line directives
for generated parts of the C file. See L</Line numbering> for an
explanation.

=head2 c_string

Alias for L</convert_to_c_string>.

=head2 c_to_h_name

    my $h_file = c_to_h_name ("frog.c");
    # $h_file = "frog.h".

Make a C<.h> file name from a C<.c> file name. 

This is not a very useful function, and I do not use it anywhere any
more.

=head2 ch_files

    my $hfile = ch_files ($c_file_name);

This makes a C<.h> filename from a C<.c> filename, and backs up both
the C and the C<.h> files using L<File::Versions>. See also
L</c_to_h_name>. It dies if the input C<$c_file_name> does not end in
C<.c>.

This is not a very useful function, and I use it in only one place.

=head2 convert_to_c_string

    my $c_string = convert_to_c_string ($perl_string);

This converts a Perl string into a C string by converting backslashes
to double backslashes, escaping double quotes with L</escape_string>,
turning newlines into C<\n> characters, and adding double quotes.

For example,

    
    use C::Utility 'convert_to_c_string';
    my $string =<<'EOF';
    The quick "brown" fox\@farm
    jumped %over the lazy dog.
    EOF
    print convert_to_c_string ($string);


produces output

    "The quick \"brown\" fox\@farm\n"
    "jumped %over the lazy dog.\n"


(This example is included as L<F<fox.pl>|https://fastapi.metacpan.org/source/BKB/C-Utility-0.012/examples/fox.pl> in the distribution.)


It also removes backslashes from before the @ symbol, so \@ is
transformed to @. Newlines within the input string are turned into
concatenated strings. Empty inputs are turned into a pair of double
quotes, C<"">.

=head2 convert_to_c_string_pc

    my $c_string = convert_to_c_string_pc ($string);     

This is similar to L</convert_to_c_string>, but it also converts the
percent character C<%> to a double percent, C<%%>. This is for
generating strings which may be used as C format strings without
generating an error because of embedded percent characters.

    
    use C::Utility 'convert_to_c_string_pc';
    my $string =<<'EOF';
    The quick "brown" fox\@farm
    jumped %over the lazy dog.
    EOF
    print convert_to_c_string_pc ($string);


produces output

    "The quick \"brown\" fox\@farm\n"
    "jumped %%over the lazy dog.\n"


(This example is included as L<F<fox-pc.pl>|https://fastapi.metacpan.org/source/BKB/C-Utility-0.012/examples/fox-pc.pl> in the distribution.)


=head2 escape_string

   my $escaped_string = escape_string ($normal_string);

This returns the value of the argument with double quotes C<"> escaped
with a backslash.

=head2 hash_to_c_file

    my $h_file = hash_to_c_file ($c_file_name, \%hash);

This turns a Perl hash into a set of C<const char *> strings and
writes it to a C file specified by C<$c_file_name>, and a header file
with a similar name. For example,

    
    use FindBin '$Bin';
    use C::Utility 'hash_to_c_file';
    use File::Slurper 'read_text';
    my $file = "$Bin/my.c";
    my $hfile = hash_to_c_file ($file, { version => '0.01', author => 'Michael Caine' });
    print "C file:\n\n";
    print read_text ($file);
    print "\nHeader file:\n\n";
    print read_text ($hfile);
    unlink $file, $hfile or die $!;


produces output

    C file:
    
    #include "my.h"
    const char * author = "Michael Caine";
    const char * version = "0.01";
    
    Header file:
    
    #ifndef MY_H
    #define MY_H
    extern const char * author; /* "Michael Caine" */