Referenz

<< Klicke um das Inhaltsverzeichnis anzuzeigen >>

Navigation:  Workflows > Elemente > Script > Funktionen > Script API >

Referenz

Untitled Document.md

System functions

fileExists

Test if a file exists.

Declaration:

bool fileExists(string fileName);

readFile

Reads the whole content of a file.

Declaration:

string readFile(string fileName);

writeFile

Write the content of a file. If the file exists, it will be overwritten.

Declaration:

void writeFile(string fileName, string content);

writeFileWithEncoding

Write the content of a file with defined encoding. If the file exists, it will be overwritten.
Encoding can be “UTF-16” (BOM will be written too), or a single byte encoding like “ISO-8859-1”, “windows-1252”

Declaration:

void writeFileWithEncoding(string fileName, string content, string encoding);

executeProcess

Starts the specified process and waits for it to terminate.

Declaration:

int executeProcess(string processFile);
int executeProcess(string processFile, string arguments);  

Return: the exit code of the process.

sleep

Suspends the execution of the current workflow until the time-out interval elapses.

Declaration:

void sleep(int timeInMilliseconds);

Read commands

Read commands from external file.

Declaration:

void applyCommands(string filename);

Sample:

applyCommands("d:/temp/commands.txt");

expandEnvironmentStrings

Expands the environment strings from the input text (zB. “%TEMP%/myfile.txt”).

Declaration:

string expandEnvironmentStrings(string input);

Return: the input string with any environment strings expanded.

Sample

Write the text from a variable in a file. If the file exists, the value is appended to the old content. It starts notepad.exe with the file as argument.

var myvar = "my var";
var tempFolder = expandEnvironmentStrings("%temp%");
var file = tempFolder + "/output.txt";
var content = "";
if(fileExists(file)) { content = readFile(file) + "\n"; }
content += myvar;
writeFileWithEncoding(file, content,"UTF-16");
executeProcess("notepad.exe", file);

String functions

See also the built-in string function of ChaiScript

replace

Replaces all the occurences of a substring with another text.

Declaration:

string replace(string input, string search, string format);

Return: A copy of the ‘input’ string with all occurences of the ‘search’ replaced with the ‘format’ string.

iequals

Declaration:

bool iequals(string input1, string input2); 

Return: True if input1 and input2 are equal (case insensitive).

to_upper

Declaration:

string to_upper(string input); 

Return: The input string converted to upper-case.

to_lower

Declaration:

string to_lower(string input); 

Return: The input string converted to lower-case.

RegEx

Classes to find and replace text using regular expressions.

RegEx class

The main class that provides regular expression based search&replace.

Declaration:

RegEx();
string pattern;
bool icase = false;
vector<RegExMatches> search(string text);
string replace(string text, string format);

pattern: the regular expression pattern
icase: if the pattern should be case isensitive.

RegExMatch class

A match when searching using regular expressions. RegEx::search returns a vector of objects that represent each match of the pattern in the input text.

Declaration:

string str;
vector<RegExSubMatch> submatches;

str: the text that corresponds to the whole match of the pattern
submatches: if the pattern has capture groups, they are put in this collection

RegExSubMatch class

Represents a capture group in a match. For ex the pattern @@xx([^=]*)=(.*)@@ has 2 capture group.

Declaration:

string str;  

Sample

Simple string replace

var test = "foo bar";
test = replace(test, "a", "o");
// test == "foo bor" 

Searches for @@xx:KEY=VALUE@@ matches in a text.

var re = RegEx(); 
re.pattern = "@@xx:([^=]*)=(.*)@@"; 
var text = "first @@xx:key1=val1@@ \n second @@xx:key2=val2@@";
var matches = re.search(text);
for(match : matches) {
  match.str; // contains the whole match '@@xx:keyX=valX@@'
  match.submatches[0].str; // contains the first capture group 'keyX'
  match.submatches[1].str; // contains the second capture group 'valX'
}

Regular expression replace

var regEx = RegEx();
test = "foo bar";
regEx.pattern = "a|r";
regEx.icase = true;
test = regEx.replace(test, "o");
// test == "foo boo" 

iequals, to_upper, to_lower

if(!iequals("Fooüöä Barüöä", "fooÜÖÄ barÜÖÄ")) {
throw(runtime_error("iequals"));
}

if(to_lower("Fooüöä Barüöä") != "fooüöä barüöä") {
throw(runtime_error("to_lower"));
}

if(to_upper("Fooüöäß Barüöä") != "FOOÜÖÄß BARÜÖÄ") {
throw(runtime_error("to_upper"));
}

Document info and manipulation

Document

In a calculation script, the variable document represents the document being currently processed.

addPages

Appends to the document the pages from the specified document. If you also use stationery, you have the option to not apply it to these new pages.

Declaration:

void addPages(string fileName);
void addPagesWithoutStationery(string fileName);

Sample:

document.addPages("d://general_conditions.pdf");

pages

Represents the collection of document pages

Sample:

var pageCount = document.pages.size;
for(page : document.pages) {
  // do something with each page 
}
page[0].text; // the text from the first page

Page

Represents a page of the document

Declaration:

string text;
string source;
bool disabled;
void setDisabled(bool disabled);

text: holds the text of the page
source: where this page comes from. May be used to test if this is a payment page (source is “Payment”) or was added from stationery (source starts with “Stationery_”).
disabled: if the page was disabled, will not be present in the generated PDF.
setDisabled: disables or enables the page.

Sample

Disable the regular pages starting with the one having in the content the @@xx:END@@ text.

var disable = false;
for(page : document.pages) {
  if(!disable && find(page.text, "@@xx:END@@") != -1) {
    disable = true;
  }
  if(disable && page.source != "Payment") {
    page.setDisabled(true);
  }
}

Stationery

Changes the stationery to be applyed to the document. The stationery profiles must have been previously configured in the settings.

Declaration:

void setStationery(string stationeryName);

Calling with an empty string, removes the stationery: setStationery("");

Save

Saves the converted document in a specified folder.

SaveFileExistsPolicy

How to handle if a file with the requested name already exists in the destination folder.

Declaration:

SaveFileExistsPolicy_Fail
SaveFileExistsPolicy_Overwrite
SaveFileExistsPolicy_CountUp

SaveSettings

The settings used with a save action

Declaration:

SaveSettings();
string folder;
SaveFileExistsPolicy fileExistsPolicy = SaveFileExistsPolicy_Fail;
bool openFile = false;
string openFileCommand;

save

Saves the converted document using the specified settings

Declaration:

void save(SaveSettings settings);

Sample

Saves the document in the d:\temp folder, generating a unique file name, if a file already exists. Will open the generated document with the standard application.

var saveSettings = SaveSettings(); 
saveSettings.folder = "d:/temp"; 
saveSettings.fileExistsPolicy = SaveFileExistsPolicy_CountUp;
saveSettings.openFile = true; 
save(saveSettings);

Email

Sends an email with the generated document

EmailRecipientType

The type of an email recipient

Declaration:

EmailRecipientType_To
EmailRecipientType_Cc
EmailRecipientType_Bcc

EmailAddress

Represents an email address

Declaration:

EmailAddress();
EmailAddress(string address);
EmailAddress(string address, string name);
string address;
string name;

EmailRecipient

Represents an email recipient

Declaration:

EmailRecipient();
EmailRecipient(string address);
EmailRecipient(EmailRecipientType type, string address);
EmailRecipient(EmailRecipientType type, string address, string name);
EmailRecipientType type;
EmailAddress email;

EmailAttachment

Represents an email attachment. If the displayName is not set, the stem from the filePath will be used.

Declaration:

EmailAttachment();
EmailAttachment(string filePath);
string filePath;
string displayName;
bool sendOnlineStorageLink = false;

EmailSettings

The settings used when sending an email.

Declaration:

EmailSettings();
string mailSystem; // empty means 'Standard MAPI'
bool openMailClient = true;
string subject;
string body;
vector<EmailRecipient> recipients;
vector<EmailAttachment> attachments;
bool sendOnlineStorageLink = false; // used for generated files
bool attachGeneratedFiles = true;

sendEmail

Sends an email with the specified settings.

Declaration:

void sendEmail(EmailSettings settings);

Sample

Set the email subject, body, recipients, attachments and send it.

var emailSettings = EmailSettings(); 
emailSettings.subject = "my subject";
emailSettings.body = "the mail body";
emailSettings.attachments.push_back(EmailAttachment("d:/additions.txt"));
emailSettings.recipients.push_back(EmailRecipient("test@test.de"));
emailSettings.recipients.push_back(EmailRecipient(EmailRecipientType_Cc, "cctest@test.de"));
sendEmail(emailSettings);

Print

Print the document to a specified printer.

PrintPageScaling

Options defining how a page should be scaled when printed. Different page margins and sizes may require it.

Declaration:

PrintPageScaling_None
PrintPageScaling_FitToPage
PrintPageScaling_Shrink

PrintSettings

The configuration for a printing action.

Declaration:

PrintSettings();
PrintSettings(string printerName);
string printerName;
int copyCount = 1;
string tray;
PrintPageScaling pageScaling = PrintPageScaling_FitToPage;
bool adjustDestinationPage = false;
bool autoRotate = false;
bool autoCenter = false;
int pagesPerSheet = 1;
int fromPage = -1; // -1 means is not used
int toPage = -1; // -1 means is not used

print

Print the document using the specified settings.

Declaration:

void print(PrintSettings settings);

Sample

Print 2 copies on “\prnserver\EPSON XP-332 335 Series” using a specific tray

var printSettings = PrintSettings("\\\\prnserver\\EPSON XP-332 335 Series");
printSettings.copyCount = 2;
printSettings.tray = "Einzug hinten-Randlos";
print(printSettings);

Letter

Sends a paper/hosted/digital letter

LetterDelivery

The letter delivery options.

Declaration:

LetterDelivery_Paper
LetterDelivery_Hosted
LetterDelivery_Digital

PaperLetterSettings

The configuration for a paper letter.

Declaration:

string destinationCountryCode;
bool color = true;
bool duplex = false;
bool enforceUnfolded = false;
bool hostedCopy = false;
bool overwriteAddress = false;

PortalHashtag

Declared as an alias for pair<string, string>

HostedLetterSettings / DigitalLetterSettings

The configuration for a hosted/digital letter.

Declaration:

vector<EmailRecipient> recipients;
vector<PortalHashtag> hashtags;
string templateId;

LetterSettings

The configuration for a letter.

Declaration:

LetterSettings();
LetterDelivery delivery = LetterDelivery_Paper;
PaperLetterSettings paper;
HostedLetterSettings hosted;
DigitalLetterSettings digital;

sendLetter

Sends a letter with the specified settings.

Declaration:

void sendLetter(LetterSettings settings);

Sample

Sends a paper letter setting the option to keep it also hosted.

var letterSettings = LetterSettings();
letterSettings.paper.destinationCountryCode = "DE";
letterSettings.paper.hostedCopy = true;
letterSettings.hosted.recipients.push_back(EmailRecipient("test@test.de"));
sendLetter(letterSettings);