NAME

aconfig - perl extension API

DESCRIPTION

This describes the interface exported by aconfig to perl.

SYNOPSIS

  use aconfig;

OVERVIEW

Aconfig provides an interface to an embedded perl interpreter. Perl commands can be invoked from within aconfig, and there are perl functions which can be used to control aconfig, from within the interpreter.

WARNING

The interface defined here is preliminary, and may change in the future, in non-backward compatible ways.

General commands

doline(CMD)

Passes text to aconfig to be executed as though it had been read from an aconfig file. Example:

  aconfig::doline "module some_module";
  aconfig::doline "set time = " . time();

add_perl_command(ARGS)

Adds a new command to aconfig which is implemented via a perl function callback. The callback is passed the remainder of the aconfig command line as a single scalar argument.

Example:

  sub my_perl_function {
      my $args = shift @_;
      print "Hello world: $args\n";
  }

  aconfig::add_perl_command('my_new_command', \&my_perl_function);

command_is_defined(CMD)

Reports whether a particular aconfig command is defined or not.

error(MESSAGE)

Invokes the aconfig error function, causing aconfig to stop, reporting the current aconfig stack..

set_aconfig_event_handler(FUNCTION)

Aconfig can call a perl callback function when certain interesting events occur. A string is passed to the callback describing the event. Only a single event handler can be set at a time, in the expectation that a perl wrapper around this facility will be provided.

The events passed back are:

   processed-all-input-files  - all input files have been processed
   init-files-generated       - the init files have been generated
   makefiles-generated        - the makefiles have been generated
   completed                  - aconfig has completed

Manipulating aconfig symbols

var_is_set(VARNAME)

Returns whether or not an aconfig set variable is set or not.

var_set(VARNAME)

Sets an aconfig variable to be set. This is equivalent to the aconfig syntax:

  set varname

var_set_value(VARNAME,VALUE)

Sets an aconfig variable to a value. This is equivalent to the aconfig syntax:

  set varname = value

var_get_value(VARNAME)

Returns the value of an aconfig set variable.

Querying Aconfig Parse State

aconfig_module(): This returns the name of the current module, or undef or undef if not in a module. Obviously this is equivalent to fetching the aconfig symbol of the same name.
aconfig_module_src(): This returns the source directory of the current module, or undef if not in a module. Obviously this is equivalent to fetching the aconfig symbol of the same name.
readline(): This returns the next line from the aconfig input, with whitespace preserved, and aconfig variables expanded.