TITLE

call_toolkit_init.pir - PIR code to call toolkits that alter argv

SYNOPSIS

    .sub main :main
        .param pmc argv

        # Load this library and the NCI wrapper for the toolkit
        load_bytecode 'library/NCI/call_toolkit_init.pbc'
        load_bytecode 'library/FooTK.pbc'

        # Find Subs for toolkit's init function, and this helper routine
        .local pmc fooInit, call_toolkit_init
        fooInit           = get_global ['FooTK'], 'fooInit'
        call_toolkit_init = get_global ['NCI'],   'call_toolkit_init'

        # Call toolkit's init function, overwriting argv with mangled copy
        argv = call_toolkit_init(fooInit, argv)

        # Alternately, you can save both the original argv and mangled copy
        .local pmc mangled_argv
        mangled_argv = call_toolkit_init(fooInit, argv)

        # ...
    .end

DESCRIPTION

Calling an NCI toolkit init function that expects to parse and mangle argv is a relatively grotty bit of code that no one should have to write twice. Hence this library, which provides just one routine:

new_argv = call_toolkit_init(pmc init_func, pmc orig_argv)

Call an NCI void function with params (&argc, argv) (and thus having Parrot signature 'v3p'). This is a very common signature for toolkit (AKA framework) init functions that want to filter out command line options that the toolkit itself should process. Since it is expected that the init call will remove some arguments, call_toolkit_init returns an updated argv. orig_argv is never changed; the NCI call is performed using a copy.