NAME ^

src/pmc/exporter.pmc - Export globals from one namespace to another

SYNOPSIS ^

You can use Exporter in PIR to import subs from a library. At its simplest:

 .sub main :main
     load_bytecode 'Test/More.pir'

     .local pmc exporter, test_ns
     test_ns  = get_namespace [ 'Test'; 'More' ]
     exporter = new 'Exporter'

     exporter.'import'( test_ns :named('source'), 'plan ok' :named('globals') )
     plan(1)
     ok(1, 'exporter has imported the requested functions')
 .end

Fancier options exist which allow you to import to an alternate namespace, or export globals so they can be called using a different name. See t/pmc/exporter.t for examples.

DESCRIPTION ^

Exports globals from one namespace to another. Exporter always uses the typed namespace interface, as outlined in docs/pdds/pdd21_namespaces.pod.

Exporter is not derived from any other PMC, and does not provide any vtable interface--its interface consists solely of non-vtable methods.

Structure ^

The Exporter PMC structure (Parrot_Exporter) consists of three items:

ns_src

The source namespace -- a NameSpace PMC. A Null PMC is allocated during initialization.

ns_dest

The destination namespace -- a NameSpace PMC. A PMC representing the current namespace is allocated upon initialization.

globals

The globals to export -- a PMC that implements the hash interface, or Null. A Null PMC is allocated during initialization.

Functions ^

void init()

Initializes an Exporter PMC.

void destroy()

Free the memory associated with the object's underlying struct.

void mark()

Mark referenced strings and PMCs in the structure as live.

Methods ^

PCCMETHOD source(PMC *src :optional, int got_src :opt_flag)

Accessor for the source NameSpace object (ns_src.) Sets the value if src is passed, otherwise returns the value. Throws an exception if a non-NameSpace PMC is passed.

PCCMETHOD destination(PMC *dest :optional, int got_dest :opt_flag)

Accessor for the destination NameSpace object (ns_dest.) Sets the value if dest is passed, otherwise returns the value. Throws an exception if a non-NameSpace PMC is passed.

PCCMETHOD globals(PMC *glb :optional, int got_glb :opt_flag)

Accessor for the globals to export (globals.) Sets the value if glb is passed, otherwise returns the value. If glb is a String, it is split on ascii whitespace, and each array member is added as a hash key. If glb implements the array interface, each member is added as a hash key. if glb implements the hash interface, it is assigned to Exporter's globals attribute. Throws an exception if an unknown PMC type is passed.

PCCMETHOD import(PMC *dest :optional :named["destination"], int got_dest :opt_flag, PMC *src :optional :named["source"], int got_src :opt_flag, PMC *globals :optional :named["globals"], int got_globals :opt_flag)

Import globals from the src namespace to the dest namespace. If src, dest, or globals are passed, they override the current value. import follows the semantics of the export_to method of the NameSpace PMC. in particular, if a NULL value is passed for globals, the default set of items will be imported. Throws an exception upon error.

STABILITY ^

Unstable. This PMC is under active development; major portions of the interface have not yet been completed.

SEE ALSO ^

docs/pdds/pdd17_basic_types.pod, docs/pdds/pdd21_namespaces.pod.


 parrot