Evaluate tagui step for improvement, added many examples to usage guide - done

[kensoh]

Met CK today, a long time TagUI user and teacher since 2018. He was saying at the moment, using tagui step to call subflows is the way to run modules and functions. In a scenario when there are 10 'functions', then 10 subflow files will be needed.

Could it be possible and if it make sense to combine different subflows into 1 subflow file and then be able to reference individual subflows? So that instead of 10 files there is only 1 file. More resembling usual programming language structure.

Raising this issue to track and do a review.

Also, I personally find tagui step the naming is not very human language. Instead of tagui login_sequence to run the subflow login_sequence, do login_sequence or run login_sequence or even login_sequence feels more readable to me.

Copying @ruthtxh

[kensoh]

Related to #960

[kensoh]

Some train of thoughts...

---

taking inspiration from Python's design

import rpa as r
r.init()
r.url()
r.click()
r.close()

import rpa
rpa.init()
rpa.url()
rpa.click()
rpa.close()

functional style - not good, not really functions

// rpa.tag
def main()

def init()

def url()

def click()

def close()

macro style - better, avoid function naming limitations

// rpa.tag or rpa.mac?
main begin
main finish

init begin
init finish

url begin
url finish

click begin
click finish

close begin
close finish

how a TagUI package might look like

// xero.tag
main begin
main finish

login begin
// userid = ''
// password = ''
...
// login_result = ''
login finish

print report begin
...
print report finish

send invoice begin
...
send invoice finish

logout begin
...
logout finish

some ideas on calling package

tagui xero login
tagui xero print report
tagui xero logout

xero login
xero print report
xero logout

xero begin
login
print report
logout
xero finish

import xero as x
x.login
x.logout

[kensoh]

Maybe do away with the plugins and packages concept. Ie no pypi no npm.

Those are all centralised package distribution channels.

If tool is made easy to use enough, there is no need for such centralised sharing of packages.

[kensoh]

Maybe reuse frame syntax?

tagui xero.tag | download monthly report
tagui gmail.tag | send email

[kensoh]

PS - check with Kuan Seng, then document best practice

tagui step1.tag
tagui step2.tag
tagui step3.tag

tagui accounting.tag | login
tagui accounting.tag | get balance

tagui accounting_v3\log_in_v1.tag
tagui accounting_v5\get_balance_v2.tag

viewer / editor limitation

user_name = “jenny”
user_password = “123”
tagui steps.tag | login

tagui steps.tag | 
current_balance = 123

[kensoh]

Spoke to Kuan Seng,

Revised issue's engineering goal to explore subflows taking in own parameters similar to command line -

Main.tag

echo start…
tagui subflow.tag aaa
tagui subflow.tag bbb
tagui subflow.tag ccc

subflow.tag

echo `p1`
// where p1 will be ‘aaa’, ‘bbb’ or ‘ccc’

[kensoh]

Creating a backup of the WIP code. After discussing with Ruth, we concluded it is a bad idea. There are is an existing way to do it like below. And calling parameters in-line will introduce problems like data integrity when there are spaces in the string, or the variable provided. Also, variables can be prefixed with subflow name to be clearer.

action = 'print_report'; name = 'Zen'; country = 'Africa'
tagui subflow.tag

if action equals to "print_report"
    type name_selector as `name`

function expand_intent($script_line, $indentation_for_tagui_step) { // function to call other scripts for reusability
if ((strpos(strtolower(trim($script_line)),'tagui ') === 0) or (strtolower(trim($script_line)) == 'tagui')) {
$params = trim(substr(trim($script_line)." ",1+strpos(trim($script_line)." "," ")));
$indent_prefix = ""; $indent_postfix = ""; $subflow = substr($params, 0, stripos($params, ".tag") + 4));
params_array = explode(" ", trim(substr($params, strlen($subflow)))); if (@count($params_array) != 0)
{$intent_prefix = "js begin\ntagui_parameters = '';\nif (!p1) tagui_parameters += p1;\n";
$intent_prefix .= "if (!p2) tagui_parameters += '[PARAMETERS_DELIMITER]' + p2;\n";
$intent_prefix .= "if (!p3) tagui_parameters += '[PARAMETERS_DELIMITER]' + p3;\n";
$intent_prefix .= "if (!p4) tagui_parameters += '[PARAMETERS_DELIMITER]' + p4;\n";
$intent_prefix .= "if (!p5) tagui_parameters += '[PARAMETERS_DELIMITER]' + p5;\n";
$intent_prefix .= "if (!p6) tagui_parameters += '[PARAMETERS_DELIMITER]' + p6;\n";
$intent_prefix .= "if (!p7) tagui_parameters += '[PARAMETERS_DELIMITER]' + p7;\n";
$intent_prefix .= "if (!p8) tagui_parameters += '[PARAMETERS_DELIMITER]' + p8;\n";
$intent_postfix = "\n";}
if ($subflow == "") die("ERROR - filename missing for step " . trim($script_line) . "\n");
else if (!file_exists(abs_file($subflow))) die("ERROR - file not found for step " . trim($script_line) . "\n");
else {$indentation_for_tagui_step .= str_replace(ltrim($script_line),'',$script_line);
$expanded_intent = ""; $temp_input_file = fopen(abs_file($subflow),'r'); if ($temp_input_file == false)
die("ERROR - cannot open file for step " . trim($script_line) . "\n");
while(!feof($temp_input_file)) {$expanded_intent .= expand_intent(fgets($temp_input_file),$indentation_for_tagui_step);}
fclose($temp_input_file); return $expanded_intent;}} else return $indentation_for_tagui_step . rtrim($script_line) . "\n";}

[kensoh]

After getting feedback and discussing with Ruth, we decided not to add parameters support, because existing design can already support that. And adding parameters directly into tagui step is likely to cause problems and waste user's time debugging. For eg, a simple thing like passing a value that has space will be treated as 2 separate variables.

Updated usage guide instead with more context and many examples, including how to combine multiple sequences of steps (like functions), into a single subflow file and calling them accordingly -

https://tagui.readthedocs.io/en/latest/advanced.html#running-flows-within-a-flow

[kensoh]

Closing since this change has made its way into the latest packaged release.