=head1 NAME

Inline::CPR - C Perl Run. Embed Perl in C, ala Inline

=head1 SYNOPSIS

    #!/usr/local/bin/cpr

    int main(void) {
        
        printf("Hello World, I'm running under Perl version %s\n",
               CPR_eval("use Config; $Config{version}")
              );

        return 0;
    }

=head1 DESCRIPTION

Is it C? Is it Perl? It's neither, it's both. It's CPR!

CPR (C Perl Run) is a "new language" that looks like C. You don't need to compile it. You just run it, much like Perl. As an added bonus, you'll get access to the full internals of Perl via the CPR API.

The idea is that you just put a CPR hashbang at the top of your C program and run it like a script. The CPR interpreter will run your C code under Perl.

If your 'hash' doesn't 'bang', you can run your program like this:

    cpr synopsis.cpr

=head1 How does it work?

To understand CPR, you need to understand the Perl module, C<Inline.pm>. Inline lets you write Perl subroutines in other languages, like C. CPR is a natural extension of this.

The CPR interpreter (C</usr/local/bin/cpr>) is a small binary program which performs a bootstrap process that goes like this: 

- The C<cpr> interpreter C<exec>s C<perl> and tells it to run the script C</usr/local/bin/cpr.pl>. 

- The name of your CPR program is passed to C<cpr.pl>. 

- C<cpr.pl> loads your CPR source code and uses C<Inline::CPR> to compile it and bind your C<main()> function to Perl. 

- Then C<cpr.pl> simply invokes the C<main()> function and you're off and running.

=head1 Notes on Usage

=over 4

=item 1

The CPR tools will get installed in the same directory as the C<perl> binary on your system. (I just used C</usr/local/bin/> as an example)

=item 2

If you installed C<Inline::CPR> by hand, the C<make> command will have created the file C<'./examples/synopsis.cpr'>. This is a sample CPR program that you can try running. It's the same as the SYNOPSIS example above, except that the hashbang will point to your newly installed CPR interpreter.

=item 3

Although Inline::CPR is a module, it is only used to support the C<cpr> interpreter program. You don't ever actually C<use> it in a Perl script.

=item 4

You must have a C<main()> function in your CPR program. This is what C<cpr> binds to.

=item 5

The C<cpr> interpreter internally changes your function C<main()> to C<cpr_main()>. Otherwise it would conflict with Perl's C<main()> function.

=item 6

The first time you run a CPR program it will seem to "hang" for several
seconds. This is normal. The C code is being compiled. Experienced Inline 
users will be familiar with this. (Since your compiled code is cached to disk, subsequent runs will be fast)

=item 7

CPR builds and caches your compiled CPR code in the directory C<'./.cpr/'>.

=item 8

CPR will return (to the system) whatever integer value your C<main()> function returns.

=item 9

You don't need to C<#include> most of the standard header files. These are automatically included by Inline::CPR.

=item 10

CPR will work with Perl 5.005 and higher. The CPR API will be made to work with those versions. (Maybe even with Perl6)

=back

=head1 The CPR API

The CPR API is just a set of C macros that you can use to access the internals of Perl5. You can also use the Perl5 API. See C<perldoc perlapi>. 

The main focus of CPR will be to develop a wrapper API around the current Perl5 one. It will be more consistent, flexible and easy to use. 

Since it should be well thought out, I have currently only implemented one function: CPR_eval. But you should be able to do quite a bit with just that one.

=head2 CPR_eval()

Eval a string (char*) in Perl and return the result as a string.

    const char* CPR_eval(char*);

=head1 Why?

Several reasons, (none great).

=over 4

=item 1

It's a cute Perl trick. After explaining CPR to an uninitiated friend, he said "My head feels like it's been wrapped around a brick". That should be reason enough :)

=item 2

A dead simple way to embed Perl into C. You're not really embedding Perl into C. Your C is being embedded seamlessly into Perl. But since you never see the Perl, you can just B<think> of it the first way. 

=item 3

A mechanism for designing a new Perl5 API. The current one is very adhoc. Some macros come from XS and others from the P5P. There's a lot of room for improvement. Also, with Perl6 looming, finding a wrapper API for Perl5 that might possibly be upwards compatible, is at least worth considering.

=item 4

Inline::CPR is a good example of how a CPAN module can be used to build and install a binary program. It is interesting to note that the C program C<cpr.c> is actually generated by the Perl script C<cpr.plc> at C<make> time.

=back

Even if there is no "real world" use for the CPR language, it is at least an easy-to-use tool for playing around with the internals of Perl5. The more "regular people" there are playing in the guts, the more useful we'll be for helping improve our language.

=head1 LIMITATIONS

=over 4

=item 1

CPR only binds to a C<main()> function with a signature of:

    int main(void);

It will not yet bind to:

    int main(int argc, char* argv[]);

and friends.

=item 2

There is currently no way to specify configuration options. This will be added soon. Then you'll be able to link in shared libraries and such.

=item 3

Does not yet support MSWin32.

=back

=head1 MAILING LIST

The mailing list for C<Inline.pm> and related projects is: inline@perl.org

To subscribe, send a message to inline-subscribe@perl.org

=head1 AUTHOR

Brian Ingerson <INGY@cpan.org>

=head1 COPYRIGHT

Copyright (c) 2001, Brian Ingerson. All Rights Reserved.  

This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License.

(see http://www.perl.com/perl/misc/Artistic.html)

=cut
