Here you can find general information about the available scripting languages and their interaction in priint:comet.

Even though we strive to make as many use cases as possible solvable with standard tools:

In each project, the implementation of own, project-specific functionality is necessary.

As a rule, this is done on the one hand in the preparation of the data (e.g. via data providers in the priint:suite), on the other hand in the priint:comet project via the available query and script languages.
Different languages are available, which serve different requirements and can be used partly interchangeably.
Within a priint:comet project, these languages can be used depending on the use case - a project is not limited to a single implementation language.
We would like to give you an overview of these languages here.

XMLQuery is a proprietary language from priint:comet to read data from XML input.
This language can be used in various places to provide and prepare priint:comet data, but is not suitable for controlling complex logic.

You can find a detailed documentation here.

Some application examples:

XML Path Language (XPath) is a query language developed by the W3 consortium to address and evaluate parts of an XML document.

priint:comet supports XPath version 1.0.

You can find a detailed documentation here.

The use cases correspond to those of XMLQuery.

SQL (Structured Query Language) is a language used to communicate with a relational database.

In priint:comet SQL is used only when connecting to a SQL database via ODBC.
Like XMLQuery or XPATH, this language is used to provide data but not to control complex logic.

The use cases correspond to those of XMLQuery.

cScript is a proprietary language from priint:comet that is based on C.

cScript provides an enormous range of functionality to influence the behavior of priint:comet.
Among other things, this includes reading, editing and outputting data, modifying a document or controlling the priint:comet internal logic itself.

With little 'overhead' in the cScript implementation, cScript is enormously fast, but also requires some care in the implementation on the user side.

Detailed documentation can be found here.

cScript can be used in almost any place where priint:comet allows customization.

Python is scripting language that provides a large native feature set and simplifies many development tasks.

Since priint:comet 4.2 Python is available as an alternative to cScript.
The implementation has the claim to represent the functional range of cScript completely, but to enable a simpler handling.
This includes in particular:

Detailed documentation can be found here..

JavaScript is a scripting language originally developed for web applications.

InDesign® and Illustrator® use a restricted version of JavaScript, called ExtendScript, as a native scripting interface.
The use of JavaScript in priint:comet is limited to the following:

The use of different scripting languages within a project is influenced by several factors:

Depending on the use case, it may be advantageous to implement functionality in Python, for example.
If you want to use functionality already implemented in cScript, you do not have to implement it in Python.
For this case, cScript and Python can call 'each other'.

This is done using the following script functions:

These functions automatically convert already defined context variables (such as gFrame, gDocument, gPage, ....) to the corresponding data type of the target language and make them globally available in the target script.

In addition, it is possible to explicitly pass specially defined variables to these script functions in order to make them immediately available in the target script.

A simple example:

This script transfers a char * string from cScript into a Python call.
In the Python script, the string is parsed and the data are extracted from the resulting JSON object.
Then, in the Python script, the extracted string is inserted into the active frame (gFrame).
Since the global variable gFrame is available in cScript, it is also available in the Python script in the comet module.
Of course, the script can only work in an environment where gFrame exists (e.g. in placeholder scripts). 

// The Python script to be executed is stored here as a string for simplicity.
//
char * script ="#!py
import json
import comet
def main():
	tempData = json.loads(comet.JSONData)
	data = tempData['name']
	comet.gFrame.setText(data)
	comet.setScriptClipboard('insertedLength', len(data))
	return 0
";

int main ()
{
	//JSON Beispiel von https://www.w3schools.com/python/python_json.asp .
	char * JSONData		= "{ \"name\":\"John\", \"age\":30, \"city\":\"New York\" }";

	int mainResult		= 0;
	int insertedLength	= 0;

	//Führe das Python script aus.
	run_python(script, 0, 1, &mainResult, 0,
		JSONData, "String", "JSONData"		// JSONData is made available with the same name as str variable in Python.
	);

	// Get the length of the inserted string from the clipboard.
	// This value was set in the Python script.
	get_script_clipboard("insertedLength", &insertedLength);
	showmessage("Inserted data with length of %d", insertedLength);

	return 0;
}

The passing of variables when calling another script is solved directly in the calls of the respective script function.
In case the return path is also required - i.e. the return of complex variables from the called script to the calling script - an additional tool is needed: The Script Clipboard.

The Script Clipboard is a store for all supported variable types. This memory is preserved as long as a script that is currently being executed is still on the stack.

In addition, when filling the clipboard, the automatic deletion of variables can be turned off, so that the memory is preserved over the entire program session.
This functionality should be used carefully - if the clipboard is never explicitly cleared, the corresponding memory will never be freed!

Both cScript and Python can access the clipboard and fill and read it.
The stored variables are automatically converted to the corresponding data types in the calling script.

The following functions are used to access the clipboard:

A simple example:

Similar to above example, this script transfers a char * string from cScript into a Python call.
In the Python script, the string is parsed and key/value pairs are created from the resulting JSON object.
These pairs are stored in the clipboard as KeyValues.

After the Python script is finished, these pairs are fetched in the calling cScript and output to the logfile. 

// The Python script to be executed is stored here as a string for simplicity.
//
char * script ="#!py
import json
import comet
def main():
	tempData = json.loads(comet.JSONData)
	outData = {}
	for key, value in tempData.items():
		outData[str(key)] = str(value)
	comet.setScriptClipboard('kvData', outData)
	return 0
";

int main ()
{
	// JSON example from https://www.w3schools.com/python/python_json.asp.
	//
	char * JSONData		= "{ \"name\":\"John\", \"age\":30, \"city\":\"New York\" }";
	KeyValues kvData	= keyvalues::alloc();
	StringList keys		= 0;
	char * key			= 0;
	char * value		= 0;

	int mainResult		= 0;
	int length			= 0;
	int i				= 0;

	// Run the Python script.
	//
	run_python(script, 0, 1, &mainResult, 0,
		JSONData, "String", "JSONData"		// JSONData are made available with the same name as str variable in Python.
	);

	// The Python script fills the variable 'kvData' in the script clipboard.
	//
	get_script_clipboard("kvData", kvData);

	// Output all entries of the KeyValues list to the log file.
	//
	keys	= keyvalues::get_keys(kvData);
	length	= stringlist::length(keys);
	for (i = 0; i < length; i++) {
		key		= stringlist::get(keys, i);
		value	= keyvalues::get(kvData, key);

		wlog("", "Key: '%s' Value: '%s'\n", key, value);
	}

	return 0;
}

The following image shows a (highly simplified) representation of the scripting engine and how scripts interact with the clipboard within priint:comet.

When a script is started in priint:comet, it is placed on a stack. As long as this stack is not empty the next script is executed.
The execution consists of the analysis of the script type, the initialization of the script data and the actual execution of the script text.

The called script can again put its own script on the stack: e.g. a script can load all placeholders in the document, which in turn execute the load action, which again can be a script.

If another script is explicitly called within a script (such as with run_python), that script is also placed on the stack.

Each of these scripts can interact with the Clipboard to transfer variables.

As soon as there is no script on the stack, all variables are deleted from the clipboard if they should not be kept explicitly.

The following table shows which data types are available for both the script clipboard and the cross calls between script languages.

cScript Type Type String Python Type InDesign® Support comet_pdf Support Illustrator® Support
int "int" int ✓ ✓ ✓
char * "String" str ✓ ✓ ✓
String "String" str ✓ ✓ ✓
float "float" float ✓ ✓ ✓
int
(Python bool -> cScript int
cScript int -> Python bool)		 "bool" bool ✓ ✓ ✓
ItemRef (Document) "Document" CDocument ✓ ✓ ✓
ItemRef (Frame) "Frame" CFrame ✓ ✓ ✓
ItemRef (Table) "Table" CTable ✓ ✓ ✓
ItemRef (Book) "Book" CBook ✓ ✗ ✗
Element "Element" CElement ✓ ✓ ✗
IDType "IDType" CIDType ✓ ✓ ✓
Parameter "Parameter" CParameter ✓ ✓ ✓
Planning "Planning" CPlanning ✓ ✓ ✓
Product "Product" CProduct ✓ ✓ ✗
Publication "Publication" CPublication ✓ ✓ ✓
PublicationType "PublicationType" CPublicationType ✓ ✓ ✓
Rect "Rect" CRect ✓ ✓ ✓
WorkflowStatus "WorkflowStatus" CWorkflowStatus ✓ ✓ ✓
List "List" list[int] ✓ ✓ ✓
List64 "List64" list[int] ✓ ✓ ✓
FloatList "FloatList" list[float] ✓ ✓ ✓ (4.3+)
StringList "StringList" list[str] ✓ ✓ ✓
ItemList "FrameList" list[CFrame] ✓ ✓ ✓
ItemList "TableList" list[CTable] ✓ ✓ ✓
ElementList "ElementList" list[CElement] ✓ ✓ ✗
IDTypeList "IDTypeList" list[CIDType] ✓ ✓ ✓ (4.3+)
KeyValues "KeyValues" dict[str, str] ✓ ✓ ✓ (4.3+)
ParameterList "ParameterList" list[CParameter] ✓ ✓ ✓ (4.3+)
PlanningList "PlanningList" list[CPlanning] ✓ ✓ ✓ (4.3+)
ProductList "ProductList" list[CProduct] ✓ ✓ ✓ (4.3+)
PublicationList "PublicationList" list[CPublication] ✓ ✓ ✓ (4.3+)
PublicationTypeList "PublicationTypeList" list[CPublicationType] ✓ ✓ ✓ (4.3+)
RectList "RectList" list[CRect] ✓ ✓ ✓ (4.3+)
WorkflowStatusList "WorkflowStatusList" list[CWorkflowStatus] ✓ ✓ ✓ (4.3+)