STrans is a powerfull tool to transform data massively.
Data are taken from a string.
Syntax
| 5: input string |
the data to read. can be fixed lenght string are separated by a char... |
| 4 : "separator"/{col description} |
this describe how to pick data. |
| 3: { « pgm » « pgm » ...} |
a list of program (to be applyed on each data field) |
| 2: « a program » |
a program to determine if the line can be treated or not |
| 1: "template output" |
a string that describe how the output must be. |
Overview
Follow these concept draws to understand how it works :
To works we need :
the input string(the data we want to transform)
a list of program (to be applyed on each peice of data
a template output line.
each « program » receives data for treatments...
Ok, now lets take a look at how data are read.
As you see, you can work with fixed lenght or separator (like CVS).
Ok, now lets discuss about the line program :
The line program : This program must return 0 or 1.
depending on this, STrans build the line or not.
Example
Simple
we have the following input file :
"1;Box of CD;1;25.50
2;Magazine;1;3.10
3;red pen;2;1.00"
|
we want the following output file :
"item 'Box of CD' costs $25.50
item 'Magazine' costs $3.10
item 'red pen' costs $1.00"
|
To transform the input string into the requested output string, just enter this into the stack :
"...input string..."
";"
{ « » « » « » « » }
« 1 »
"item '\2' costs $\4" |
Ok this is just a stupid example,
there are nothing to perform on data.
it's just to start training. |
Explanations
Lets see what happens :
First STrans take the first line, "1;Box of CD;1;25.50"
It starts to split the line into data field : {"1" "Box of CD" "1" "25.50" }
Then it run each data field program (they are empty for this simple example), each of these program are run in an independant stack, and they got two argument : the list of field and the corresponding data.
For example, first program is run with these argument on stack :
2: {"1" "Box of CD" "1" "25.50"}
1: "1"
The data field program can works like you want, at the end it must return a value back, this value is stored as beeing the up-to-date value for the field.
in this example, the program is empty, it leave "1" as beeing the correct data.
Then it perform the same for each 4 data (4 empty programs here)
It run the "line program", (here it's « 1 »)
such program receive two arguments on the stack : the line number and the line itself.
example here :
2: 1
1: "1;Box of CD;1;25.50"
the program must return 0 or 1, here it return 1
Now it build the line, it use the template, replacing in the string each \x by the corresponding field number.
That's it.
Advanced features
Extra programs
One important thing is the ability to add new field at runtime !
For example you can add two program fields even if there are no data in the input string for these.
as every program can reach already computed value, it can works with them.
For example, for the previous example, take the input string.
and now we want this output string :
"item 'Box of CD' costs $25.50 Qty:1 price $25.50
item 'Magazine' costs $3.10 Qty:1 price $3.10
item 'red pen' costs $1.00 Qty:3 price $3.00"
Yo usee the price is the unit cost multiplyed by the Qty.
"...input string..."
";"
{ « » « » « str-> » « str-> » « dup 4 GET SWAP 3 get * »}
« 1 »
"item '\2' costs $\4 Qty:\3 price $\5" |
« str-> » is used to convert strings into numerical values (for cost and Qty)
|
Registers
You can use registers (r1,r2,r3 or/and r4) to share data.
You just to keep in mind, in which order program are launch.
This is the order :
"...input string..."
";"
{ « »[1] « »[2] « »[3] « »[4] }
« »[5]
"template line"
You can store something in [2] (=>r1) and read it in [4] or [5] (r1=>)
If you store in [5] and want to read in [1], it will be on next line.
the stack
Programs (line program or data program) are each executed in a independant/private stack.
That means there are no risk to disturb main stack, and you don't need to clean stack.
Stack are automaticaly destroyed at the end of each execution.
Sumarization
You can use registers to sumarize,
For example if you have amount to sumarize into input file :
"1;Box of CD;1;25.50
2;Magazine;1;3.10
3;red pen;2;1.00"
you create a program like this :
«
0 =>r1
";"
{« » « » « » « str-> r1=> + =>r1 » }
« »
"" STrans
Drop
r1=>
» |
First I clear register r1
sumarize 4th data into r1
run STrans with an empty template.
drop the result
and give the sum. |
template format
The template string is a standart string where some items are replaced :
\1 |
replaced with data value 1 |
\2 |
replaced with data value 2 |
\(10) |
replaced with data value 10 |
\i |
replaced with the line number |
\\ |
replaced with a \ |
|
|