C Embedded Perl Library -- Documentation


1. Introduction on C Embedded Perl Library
    a) What is it?
    b) What can it do?
    c) What it needs?
    d) Where can I get it?
2. Using the C Embedded Perl Library API
    a) Init and destroy perl context
    b) Eval from string
    c) Eval from file
    d) Execute functions
    e) Manipulate perl variables
3. Authors, license, etc.


1. Introduction

a) What is it?

C Embedded Perl is an easy-to-use library for executing perl codes from C programs.


b) What can it do?

With C Embeded Perl You can integrate user scripting support, perl based configuration files, perl regexps and text parsers to your program.

c) What it needs?
d) Where can I get it?

You can grab it from http://sourceforge.net/projects/libcep/


2. Using the C Embedded Perl Library API

a) Init and destroy perl context

You can initalize the interpreter with the following code:
#include "cep.h"
[..]
CEP_InitPerl( xs_init );
[..]
(void)CEP_DestroyPerl( );

The xs_init argument is used for preload extended subroutines (XS). For example if you have to use the IO::Socket module, you can generate an xs_init function with:
% perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std IO::Socket
You must link this file to your program, and specify xs_init in to CEP_InitPerl. Otherwise, if you do not need XS based perl module, you can pass NULL as xs_init.


b) Eval from string

You can evaluate perl statements from string with the CEP_PerlEvalVa() function.

for example the:
ret = CEP_PerlEvalVa( "print \"Hello Interpreter!\n\"", NULL); 
prints the "Hello Interpreter!" message. The first argument contains the perl code. The last parameter is always NULL, this indicates the end of the command.

You can also store return values from evaled perl code:

int a;
char * b;
double c;
ret = CEP_PerlEvalVa("$a = 1; $b = \"SUCCESS\"; $c = 3.141592 ; "
"return $a, $b, $c;",
CEP_INT, &a,
CEP_STR, &b,
CEP_DBL, &c,
NULL);

The return value can be CEP_INT, CEP_STR and CEP_DBL which are int, char * and double variables in C. CEP_PerlEvalVa() allocates space for strings (you have to free it with a free() call). CEP_STR strings are always \0 terminated char * arrays.

The return value is negative if an error is occoured, otherwise it returns with the number of the return variables.

c) Eval from file

CEP_FileEvalVa() is similar to CEP_PerlEvalVa(), but the first argument is the requested file.

The following code executes the contents of "tests/file_eval_test" file.

ret = CEP_EvalFileVa( "tests/file_eval_test", NULL);

d) Execute functions

The CEP_PerlExecVa() is capable to execute a perl function with parameters and store its return values. The first argument is the name of the function, the second block is input parameters type-value pairs, the third block is the return values type-value pairs. Between the input and the output blocks you have to add the CEP_OUT keyword. The input arguments have to terminated by NULL.  Of course, you can bypass input or output blocks.

Example for CEP_PerlExecVa():
int a_in, a_out;
double c_in, c_out;
char b_in[128], *b_out;

[..]
CEP_PerlEvalVa("sub main::test_function {"
            "my ($a,$b,$c) = @_;"
            "return $a,$b,$c;"
            "}",
            NULL);
[..]

CEP_PerlCallVa("test_function",
            CEP_INT, a_in,
            CEP_STR, b_in,
            CEP_DBL, c_in,
            CEP_OUT,
            CEP_INT, &a_out,
            CEP_STR, &b_out,
            CEP_DBL, &c_out,
            NULL);

The return value is negative if an error is occoured, otherwise it returns with the number of the return variables. The function allocates space for \0 terminated CEP_STRs.

e) Manipulate perl variables

You can access to perl variables anytime with the following functions:
int CEP_SetInt (
        IN char * variable,
        IN int value );

Set integer variable to value.
int CEP_GetInt (
        IN char * variable,
        OUT int * value );

Get variable's value and store it as integer to value.
int CEP_SetDouble (
        IN char * variable,
        IN double value );
Set double variable to value.
int CEP_GetDouble (
        IN char * variable,
        OUT double * value );
Get variable's value and store it as double to value.
int CEP_SetString(
        IN char * variable,
        IN char * value );
Copy '\0' terminated character array to variable as string. After SetString the value can be reused.
int CEP_SetStringN(
        IN char * variable,
        IN char * value,
        IN size_t len);
Copy len bytes from value to variable.  Value can contains '\0' s.
int CEP_GetString (
        IN char * variable,
        OUT char ** value,
        OUT size_t * len );
Copy variable to value and set len to string's length. The necessary memory is allocated by GetString. Value can contain '\0'.
int CEP_CatStrings(
        IN char * variable,
        IN char * value);
Append value to variable.
int CEP_CatStringsN(
        IN char * variable,
        IN char * value,
        IN size_t len);
Append len bytes from value to variable.
int CEP_CatStringVariables(
        IN char * variable1,
        IN char * variable2);
Concat two perl variables.


Examples:

CEP_SetInt("main::a", 2);
CEP_SetString("main::b", "success");
CEP_SetDouble("main::c", 1.414213f );
CEP_GetInt("main::a", &a);
CEP_GetString("main::b", &b, &len);
CEP_GetDouble("main::c", &c);
CEP_CatStrings("main::b", a2_in );
CEP_CatStringsN("main::b", a3_in, 4 );
CEP_CatStringVariables("main::b", "main::d" );

3. Authors, License, Etc.

The author of CEP package is Tamas Foldi <crow@kapu.hu>

You can distribute it under BSD License.

Hosted by Sourceforge. 
SourceForge.net Logo



$Id: C_Embedded_Perl.html,v 1.1 2002/12/20 10:04:03 crow Exp $