Bit Che - Script Engine 2.0 - Function List

[chip!]

NOTE:  PLEASE REVIEW THE SCRIPT ENGINE DOCUMENTATION FOR BIT CHE 3.0:   http://convivea.com/forums/index.php?board=25.0


Below is old and for Bit Che 2.0

Initial Notes: Scripts are designed to parse HTML output into 2 arrays (@R and @Q). The first array '@r' stores the data that contains all of the 'results' and is parsed based on whatever delimiter is required to put each complete result into its own array element of '@r'. The delimiter for '@r' is typically "</TR>". The second array '@q' is used when looping through each result in '@r' and splits the data into a organized data array. The delimiter for '@q' is typically something like "/TD>". Then we loop through the information array and store the torrent information to special variables.



Variable Handling:

Strings -- all strings must be escaped with ` -- for example this specifies test as a string: `test`

Variables -- anything not a String or a Special Variable is treated as a Variable -- for example this specifies test as a variable: test

$Special Result Variables -- variables that hold info regarding the result

@Special Data Variables -- variables that act special


With the exception of certain functions, basic script commands follow this pattern:


varName=Function(p1,p2,p3)


where varName is the return variable, Function is the function name, and p1..p3 are parameters (Strings, Variables (any type), or Numeric)

Note: the return variable can be either a Variable, $Special Result Variables, or @Special Data Variables



$Special Result Variables:

$name - Result Name
$size - Result Size
$page - Page/URL to view more info about the Result
$date - Result Date
$seeds - Result seeds/peers
$leeches - Result leeches/downloaders
$torrent - URL for the .torrent
$source - Site Name where the Result came from


@Special Data Variables:

@r -- (array) - the entire results table split into the array 
@q -- (array) - 'result' from the @r array further split to parse the single 'result' 
@data -- (string) - the HTML data sent to the script engine 
@i -- (integer) - index counter. always reset to '0' after =array() function 
@home -- (string) - the URL for the source of the @data (as supplied in the script file)


Standard Engine Functions:
array
split
put
find - searches for a string [i(]
findrev
findh - searches for a string and halts if not found [h(]
mid
crop
replace
&
extract
vacuum
len
scrub
code
save (no longer needed in v2)


Conditional/Loop Functions
if () then
else
elseif () then
end if

while
wend

Script Control Functions
start
loop
add
aloop
reset
die

Special functions:
urldecode
utf8decode

msgbox




IF THEN EXAMPLES:


if (x>0 and x<1) then
...code...
elseif (x=5) then
...code...
else
...code...
end if



WHILE EXAMPLE:

while(x!0 or y!0)
...code...
wend



NOTE: for the above 2 examples, the following is true:

1. evaluation:
">" - greater than
"<" - less than
"!" - NOT equal
"=" - equal to

2. multiple conditions (IF, ELSEIF, WHILE can accept a SINGLE evaluation or a SECOND evaluation using):
"and" -- both evaluations are valid
"or" -- either evaluation are valid







Script Engine 2.0 Functions List (NOTE: VERSION 1.0 NAME IN BOLD):
find - i( - searches for a string
findh - h( - searches for a string(s) and HALTS if not found
findrev - r( - searches for a string in reverse
crop - c( - crops/cuts a string
split - split( - split a data block into an array
array - array( - access data from the 'q' array
replace - replace( - replace a string with another
save( - (v2: not needed)
extract - e( - extract: combines search, crop/cut, and clean.
extract - x( - eXtract: combines search, crop/cut, clean, and save. (v2: same as 'extract' when specifying the result to be a $result variable)
put - p( - store a string into a variable (v2: not needed much)
& - &( - combine strings OR variables
+ - +( - add a number from a variable
- - -( - subtract a number from a variable
start - start - indicates the start of the result parsing loop
aloop - aloop - adds the current torrent to the results list and loops back to 'start'


Basic Functions Detailed - Script Engine 2.0:

findh -- Searches a string for another string but HALTS the script if it is not found. Typically the first line of the script. Stores the location of the found string as a integer into the return variable.

   

vRes = findh ( vStart, vData, sSearch )

z=findh(x,@data,`</td>`) 

   
   searches the data variable '@data' for '</td>' starting at position stored in variable 'x' and stores the result into variable 'z'. if '</td>' is not found, the script halts (dies).


   Optional extended use, can search for successive terms (up to 10):

   

vRes = findh ( vStart, vData, sSearch , sSearch2, sSearch3...etc ) 

z=findh(x,@data,`</font>`,`<bc><bc>`,`</b>`)

   
   Note: this will halt the script if the last '' is not found in order starting from the location of the first term. This us useful to make sure you are working with the expected HTML output.



find -- Searches a string for another string. Typically Stores the location of the string as a integer into the return variable.
   Returns: Number

   

vRes = find ( vStart, vData, sSearch )

x=find(x,@data,`</td>`)

   
   if the String is NOT found, will return `0`


findrev -- Searches in reverse for a string in a variable.
   Returns: Number

   

vRes = findrev ( vStart, vData, sSearch)

x=findrev(-1,t,`title=`)

   
   searches from the end of 't' for the location of 'title=' and stores it in 'x'
   Note: '-1' for the vStart always searches from the END of the string.
   

crop -- Crops a string based on a starting and ending locations
   Returns: String

   

vRes = crop ( vData, vStart, vEnd)

d=crop(d,x,z)

mid -- Cuts a string based on a starting location and length (number of characters to include)
   Returns: String

   

vRes = mid ( vData, vStart, vLength)

d=mid(d,x,z)

   Note: vLength is optional -- if not supplied, then the string will be cut from the starting location and include everything after that position.

   

split -- Used to split up a data block into the arrays.
   Returns: String() Array

   This is a special function any only 2 result variables are allowed: r & q

   

@r=split(@data,`</tr>`) - sets up the '@r' array delimiting with </tr>

@q=split(@r,`</td>`) - sets up the '@q' array delimiting with </td>

   
   Note: the delimiter can be anything you like, the result variables can not be changed. The use of '@r' is automatically the STRING of the array starting at Array(0). Each time the 'loop' or 'aloop' is used, then the Array(#) is automatically increased when you access '@r' next, so that '@r' always is the current array of the 'results'.


array -- Used to access data from the '@q' array and stores into a variable for manipulation.
   Returns: String

   

t=array(@q,2)

   
   stores the 3rd item in the '@q' array to the string varriable 't'.
   note: arrays always start numbering with 0 for the first item which means when accessing the array items:
   0=1st 1=2nd 2=3rd ..etc



replace -- searches a string variable for a specific string and replaces it with another
   Returns: String

   

vRes = replace ( vData, sSearch, sReplace)

d=replace(d,`</td>`,`[-bc-]</td>`)

   
   Useful when Bit Che needs to parse tricky HTML code,etc.



save -- not needed in 2.0:


extract -- special function that combines searching, cutting, extracting, and cleaning.
   Returns: String

   

vRes = extract ( vStart, vData, vEnd)

$name=extract(z,t,`<bc>`,`[-bc-]`)

   
   searches variable 't' starting at the value of 'z' for '<bc>' and extracts the data until '[-bc-]'. this extracted data is then saved into variable $name. The extracted data is automatically 'scrubbed' and cleaned from unwanted HTML codes.

   OPTIONAL:

   

vRes = extract ( vStart, vData, vEnd, sAddFront, sAddEnd)

$page=extract(z,t,`<bc>`,`[-bc-]`, `http://www.example.com/`,`?action=view`)

   both sAddFront and sAddEnd are OPTIONAL. the function is the same as without, but if present, then sAddFront will be added to the FRONT of the new string, and sAddEnd will be added to the END of the new result string.



put -- allows you to store a string/number into a variable
   Returns: String/Number

   

vRes = put ( sString )

t=put(`hello world`)

      
   stores 'hello world' into 't'

   

t=put(1)

      
   stores '1' into 't'

   Note: you can store numbers or strings into variables.



& -- allows you to combine strings OR variables into one variable.
   Returns: String

   

vRes = & ( vFirst, vSecond, etc..)

t=&(k,m)

   
   combines 'k' with 'm' and saves it as variable 't'

   Note: You can also combine text strings instead of variables. Example:
   t = & ( `http://www.domain.com`, q, `.torrent`)
   If variable q = "/download.php?name=file", then t would equal
   http://www.domain.com/download.php?name=file.torrent



len -- returns the Length of a string Variable
   Returns: Number
   
   

vRes = len ( sVar)

x=len(d)

   if 'd' contains the string "hello world" then x would be set to the Length: 11



+/- -- allows you to add or subtract a number from a variable
   Returns: Number
   
   

vRes = + ( sNum)

x=+(1)

variable 'x' = 'x' + 1

x=-(5)

variable 'x' = 'x' - 5

   

start -- indicates the line number in the script where Bit Che should 'loop' back to to process the next array item in the result array '@r'.
   Returns: <none>

   start


aloop -- adds the currently stored special torrent information variables to a torrent result in Bit Che and loops back to the 'start' of the script. automatically advances to the next '@r' array item.
   Returns: <none>

   aloop


loop -- loops back to the 'start' of the script. automatically advances to the next '@r' array item. does NOT save the special torrent information to a result in Bit Che
   Returns: <none>

   loop




Other Special Functions:

vacuum -- removes characters like 'tab' and 'line return/breaks' from a string
   Returns: String

   d=vacuum(d)


scrub -- removes HTML from a string (note: done automatically when saving a function's result to a $special variable)
   Returns: String

   d=scrub(d)


die-- halts the script execution
   Returns: <none>

   die


Currently Undocument:
reset &nbsp; &nbsp;-- &nbsp;reset @data back to the original HTML (as it was at the beginning of the script execution) (used for debugging)
msgbox(vName) -- displays a message box with the 'vName' variable contents (used for debugging)
urldecode(sString) &nbsp;-- converts/decodes a URL coded string.
utf8decode(sString) &nbsp;-- converts/decodes a UTF8 coded string.
code(sString, sNum) -- used to specify a second code section. &nbsp;this is used when Bit Che must fetch a 2nd page, execute another script, and extract more info. &nbsp;MORE DOCUMENTATION TO COME.

[Bovski]

Thanks chip!
Any chance of knowing what the arguments to the functions are.
and what they do.

[CuF]

Thanks chip!
Any chance of knowing what the arguments to the functions are.
and what they do.

Shh.  It's a secret.

[chip!]

updated

let me know if you have any questions!

[Bovski]

Why a urldecode but not a urlencode ?

[ajmal1075]

How to get registered version of Bit Che 2.0 to make it fully functional

[chip!]

Why a urldecode but not a urlencode ?

added urlencode... not sure it would ever be needed..

also added ucase() and lcase() for UPPER or lower case formatting..

[Bovski]

why no mention of % variables ?

%SEARCH%
&
%FORM%

P.S.
What the hell is %FORM% I noticed it in a script on git hub.

Cons
A Serious lack of documentation

[chip!]

Ahh thanks for reminding me.  That was a work around fix to keep compatibility but it fixes an issue with being able to POST to URLs that have ?stuff in the URL and also control the post-form.


Here was the change. I will have to update the documentation.

https://github.com/convivea/bit-che-2-scripts/commit/d3e13f443e7a57d1b831f106999392c281480361

[Bovski]

Yep that was the page I came across it on.

Though I still have no idea how to use %FORM% or what is stored in it.