# ---------------------------------------------------------------------- #
# helper procedure to create a module, set its ports and compute.
# usage:
#     moduleApply <module name> <portA> <valueA> <portB> <valueB> ...
#
# The first argument is the name of the module class to instantiate.
#
# Following arguments are pairs of port names and values.
# Port <value> is one string, sent to the method 'setState' of the port. You
# can find more details about the 'setState' syntax for a given port in the
# method documentation in its C++ header file (ex: hxcore/HxPortFloatSlider.h).
# If the <value> string of the port contains spaces characters, use quotes "".
#
# Ports are set in the order of the arguments.
# A 'fire' is triggered after each port change (Some ports need an immediate 'fire' to apply,
# and there is no generic way to know which, so we do like the GUI, ie always 'fire' on change.)
# A 'fire' is also triggered right after the module creation before ports are modified.
#
# Some special keywords can be used as port name.
# "resultSlot0", "resultSlot1"... are special keywords that can be used to
# connect an already existing data to a result slot of the new module.
# The targeted result slot is identified by the ID following the keyword base "resultSlot".
# Note that the keyword "resultSlot" without digit can be used as a shortcut for resultSlot0.
# No fire is triggered after connect a result slot.
# If the data to connect to the result slot does not yet exist, the given label
# will used to rename the future result data.
#
# When the list of ports changes is processed, the command automatically
# 'hits' and 'fires' the port 'doIt' if there is one, which makes common
# compute modules to execute their tasks. If you wish to apply the module
# task before a given port modification, insert the pair {doIt 0} before that
# modification in the list of port changes.
#
# This command returns the module that has been created.
# If this new module has computed some result data, call its 'getResult'.
#
# example:
#     set somemodule [ moduleApply HxArithmetic inputA foam.im6 expr0 "A + 10" ]
#     moduleApply HxOrthoSlice data [ $somemodule getResult ]
#
# This is not a replacement for the standard way of writing modules.
# This is only a one-line helper that only allows limited control.
# ---------------------------------------------------------------------- #
proc moduleApply {moduleName args} {
    # create the module
    set module [create $moduleName]
    $module fire

    # parse each couple of remaining argument
    foreach {port value} $args {
        # "resultSlot*" is a key word to connect result slot instead of port
        # the ID of the targeted result slot is extracted from the key word : resultSlot1 means result slot #1
        # "resultSlot" without digit is a shortcut for result slot #0
        if {[string match "resultSlot*" $port]} {
            # if the data already exists, connect it to the result slot
            if {[exists $value]} {
                $module setResult $value [ expr [ string replace $port 0 9 "" ] + 0 ]
            }
        } {
            $module $port setState $value
            $module fire
        }
    }

    # hit port doIt if found
    if { [lsearch [$module allPorts] doIt] != -1 } {
        $module doIt hit
        $module fire
    }

    foreach {port value} $args {
        # rename output connected to the listed result slot
        if {[string match "resultSlot*" $port]} {
            [ $module getResult [ expr [ string replace $port 0 9 "" ] + 0 ] ] setLabel $value
        }
    }

    return $module
}