README

qx_example — a worked QuNex extension

A complete, runnable QuNex extension, small enough to read in a few minutes. It is the example carried through The QuNex extensions whitepaper in the QuNex SDK wiki, which installs and runs every command in it and explains what each file is doing.

It contains one of everything:

File	What it demonstrates
python/qx_example_commands.py	a Python utility command and a Python processing command
python/qx_example_options.py	declaring parameters and flags with arglist and flaglist
python/qx_modules	naming the modules QuNex imports on every call
qx_commands.yaml	the built command listing, which ships with the example
matlab/example_matlab_greet.m	a MATLAB command, called with positional arguments
bash/example_bash_greet.sh	a bash script that is a QuNex command
bin/example_helper.sh	a plain script, on PATH, that is not a QuNex command

Installing it

# put it in a folder of your own that will hold extensions
mkdir -p $HOME/qunex_extensions
cp -r qx_example $HOME/qunex_extensions/

# QUNEXEXTENSIONSFOLDERS names the folder *containing* qx_example. QuNex reads
# it on every call, so nothing has to be sourced
export QUNEXEXTENSIONSFOLDERS="$HOME/qunex_extensions"

That is all: the example ships with qx_commands.yaml, the listing that tells QuNex which commands it offers, already built. Rebuild it whenever you change a command's docstring:

# rebuilds this extension's listing and leaves the QuNex installation's own alone
qunex build_qx_extensions --extensions=example

Running it

qunex example_hello --example_name=QuNex --example_times=2

qunex example_greet_sessions \
    --sessions="s01,s02" \
    --sessionsfolder=/path/to/study/sessions \
    --example_greeting=Hi \
    --example_shout

qunex example_matlab_greet --name=QuNex --times=2

qunex example_bash_greet --example_name=QuNex

example_helper.sh    # not a QuNex command; on PATH under its own name

Using it as a starting point

Copy the folder, rename it to qx_<yourname>, and work outwards from python/qx_example_commands.py. Two things to remember as you do:

• Rebuild the registry (qunex build_qx_extensions --extensions=<yourname>) after any change to a command's docstring — a new command, a rename, an edited qx_command block, or an edited Parameters: entry. The registry, not the source, is what QuNex reads. If you lose track of what is installed, qunex build_qx_extensions --extensions=check lists what QuNex can see and builds nothing.
• Keep your parameter module listed in python/qx_modules. Anything declaring arglist or flaglist has to be imported before a command runs, and that file is what asks QuNex to import it.