Bit Che - Script Documentation v.01a (READ)

[chip!]

For Bit Che version 2.0, please read:  http://convivea.com/forums/index.php?topic=1972.0


EDIT: THIS PAGE IS OUT DATED AND IS REFERENCE ONLY

Bit Che Script Documentation v.01a

NOTE: The easiest way to learn how to write scripts is to read over these first few paragraphs and the Quick Functions List, and then "debug" one of the existing scripts so that you can watch the functions and the script in action. Once you get the idea of how the script works, then attempts to write your own will be far easier.


Before you begin working on a script, first edit "settings.ini" and add a line "debug=1" in the "[options]" section. This file is found in the installation directory. Now, a menu item appears, "Debug Script" (or you can hit F12) to bring up a step-by-step debugger when working with Bit Che scripts.


Initial Notes: Scripts are designed to parse HTML output into 2 arrays (R & Q). &nbsp;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>". &nbsp;Then we loop through the information array and store the torrent information to special variables.

Note: You might like to use the Quick Array Display tool to help you break down the HTML when parsing the data into the arrays: Quick Array Display



Variable Handling:

Variables &nbsp;a to z can be used (lower case) with the exception of a few special ones.
r = assigned to the array containing ALL results
q = assigned to the information array of a single result
d = always the HTML data output sent to the script (can be edited/changed by the script at anytime).
z = is always reset to 1 after the array( function is used.

numbers 1 - 7 are used for the torrent's information and can not be accessed as normal a-z character variables.
 &nbsp; 1 = name
 &nbsp; 2 = size
 &nbsp; 3 = source page
 &nbsp; 5 = seeds
 &nbsp; 6 = leeches
 &nbsp; 7 = .torrent url


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

X=F(p1,p2,p3)

where X is the return variable letter (a-z) for the function, F is the function name, and p1..p3 are string parameters



Quick Functions List:

i( - searches for a string
h( - searches for a string and halts if not found
r( - searches for a string in reverse
c( - crops/cuts a string
split( - split a data block into an array
array( - access data from the 'q' array
replace( - replace a string with another
save( - saves specific torrent information to # &nbsp; (see above)
e( - extract: combines search, crop/cut, and clean.
x( - eXtract: combines search, crop/cut, clean, and save.
p( - store a string into a variable
&( - combine strings OR variables
+( - add a number from a variable
-( - subtract a number from a variable
start - indicates the start of the result parsing loop
aloop - adds the current torrent to the results list and loops back to 'start'




Basic Functions Detailed:

h &nbsp;-- &nbsp;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 = h ( vStart, vData, sSearch )
   z=h(x,d,</td>) &nbsp; &nbsp;

   searches the data variable 'd' 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 = h ( vStart, vData, sSearch , sSearch2, sSearch3...etc ) &nbsp;
   z=h(x,d,</font>,<bc><bc>,)

   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.



i &nbsp;-- &nbsp;Searches a string for another string. Typically Stores the location of the string as a integer into the return variable.

   vRes = i ( vStart, vData, sSearch )
   x=i(x,d,</td>)

   exact same as 'h' function but does not halt.


r &nbsp;-- &nbsp;Searches in reverse for a string in a variable.

   vRes = r ( vStart, vData, sSearch)
   x=r(-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. A number or a variable can be used here.
   

c &nbsp;-- Crops a string into a variable based on a starting and ending location

   vRes = c ( vData, vStart, VEnd)
   d=c(d,x,z)


split -- Used to split up a data block into the arrays.

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

   r=split(d,</tr>) &nbsp;- sets up the 'r' array delimiting with </tr>
   q=split(r,</td>) &nbsp;- sets up the 'q' array delimiting with </td>

   Note: the delimiter can be anything you like, the result variables and the array variables can not be changed.


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

   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 &nbsp; &nbsp;1=2nd &nbsp; &nbsp;2=3rd &nbsp;..etc



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

   vRes = replace ( vData, sSearch, sReplace)
   d=replace(d,</td>,[-bc-]</td>)
   Useful when Bit Che needs to parse tricky HTML code,etc.



save &nbsp;-- saves a variable to a specific torrent information variable number:
   
   1=save(k)

   saves the string in variable 'k' to torrent information variable '1' (name)

   1 = name
   2 = size
   3 = source page

   5 = seeds
   6 = leeches
   7 = .torrent url


x &nbsp;-- &nbsp;special function that combines searching, cutting, extracting, cleaning, and saving.

   vRes = x ( vData, vStart, vEnd)
   2=x(t,z,<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 as special torrent information variable '2' (file size). The extracted data is automatically 'scrubbed' and cleaned from unwanted HTML codes.



e &nbsp;-- &nbsp;special function that combines searching, cutting, extracting, and cleaning.

   vRes = e ( vData, vStart, vEnd)
   q=e(t,z,<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 q. The extracted data is automatically 'scrubbed' and cleaned from unwanted HTML codes.
   Note: This is the same as function 'x' except it does not save the result into the special torrent variable. This is useful if you want to use or manipulate the result before you save it to the special torrent # variable.



p &nbsp;-- &nbsp;allows you to store a string into a variable

   vRes = p ( sString )
   t=p(hello world)
   
   stores 'hello world' into 't'
   Note: you can store numbers or strings into variables.


& &nbsp;-- &nbsp;allows you to combine strings OR variables into one variable.

   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 by placing ' in front of the string. 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


+/- &nbsp;-- allows you to add or subtract a number from a variable
   
   vRes = + ( sNum)
   
   x=+(1)
   variable 'x' = 'x' + 1

   x=-(5)
   variable 'x' = 'x' - 5


start -- &nbsp;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'.

aloop &nbsp;-- adds the currently stored special torrent information variables to a torrent result in Bit Che and loops back to the 'start' of the script.




other special functions:

vacuum -- removes characters like 'tab' and 'line return' from a string

   d=vacuum(d)



A few other undocumented ones or modifications/extra parameters of the above functions might appear in some scripts. These will be addressed within time.





For some clarity here, lets use a blank TABLE example (typical of HTML output).

Code: [Select]

<TABLE width="100%" border="1" cellspacing="0" cellpadding="2">
<tr>
 &nbsp; &nbsp; &nbsp;<td>Torrent Name 1</td>
 &nbsp; &nbsp; &nbsp;<td>File Size 1</td>
 &nbsp; &nbsp; &nbsp;<td>URL 1</td>
 &nbsp; &nbsp;</tr>
 &nbsp; &nbsp;<tr>
 &nbsp; &nbsp; &nbsp;<td>Torrent Name 2</td>
 &nbsp; &nbsp; &nbsp;<td>File Size 2</td>
 &nbsp; &nbsp; &nbsp;<td>URL 2</td>
 &nbsp; &nbsp;</tr>
 &nbsp; &nbsp;<tr>
 &nbsp; &nbsp; &nbsp;<td>Torrent Name 3</td>
 &nbsp; &nbsp; &nbsp;<td>File Size 3</td>
 &nbsp; &nbsp; &nbsp;<td>URL 3</td>
 &nbsp; &nbsp;</tr>

</TABLE>


1. First we would trim the HTML data (always variable 'd') to hold what is between the first <tr> and the last </td>.

Code: [Select]

x=h(x,d,<tr>,<td)
z=i(x,d,</TABLE>)
d=c(d,x,z)


2. Next we would split the data into the 'r' array (always 'r').

Code: [Select]

r=split(d,</tr>)

3. Next we start the loop because we want to loop through all the different results in 'r'.

Code: [Select]

start

4. At the beginning of the loop, we need to split the current result from the 'r' array into the 'q' array. This puts a single result's data into a single organized array 'q' from which we can then easily work with.

Code: [Select]

q=split(r,/td>)

This splits the current item 'r' into 'q'. the 'q' array will hypothetically look like (in memory):

q(0): <td>Torrent Name 1<
q(1): <td>File Size 1<
q(2): <td>URL 1<


5. Store the first array item from the information array 'q' into a string varriable.

Code: [Select]

t=array(q,0)

6. Extract and save the torrent name.

Code: [Select]

1=x(t,z,>,<)

7. Store the second array item from the information array 'q' into a string varriable.

Code: [Select]

t=array(q,1)

8. Extract and save the torrent file size.

Code: [Select]

2=x(t,z,>,<)

9. Store the third (last) array item from the information array 'q' into a string varriable.

Code: [Select]

t=array(q,2)

10. Extract and save the torrent url.

Code: [Select]

7=x(t,z,>,<)

11. Add the stored torrent result and loop back to the 'start' line to parse the next item in the results 'r' array.

Code: [Select]

aloop


12. &nbsp;Completed Example Script for the basic TABLE output:

Code: [Select]

'[code]
x=h(x,d,<tr>,<td)
z=i(x,d,</TABLE>)
d=c(d,x,z)
r=split(d,</tr>)
start
q=split(r,/td>)
t=array(q,0)
1=x(t,z,>,<)
t=array(q,1)
2=x(t,z,>,<)
t=array(q,2)
7=x(t,z,>,<)
aloop[/code]



Example Working Script for TorrentSpy.com:

Code: [Select]

'[code]
x=h(x,d,table class="list")
x=i(x,d,</tr>)
x=+(5)
z=i(x,d,</table>)
d=c(d,x,z)
r=split(d,</tr)
start
q=split(r,/td>,2)
t=array(q,0)
x=p(1)
z=i(x,t,href)
3=x(t,z,",",http://torrentspy.com)
x=p(1)
x=i(x,t,/,/)
x=+(1)
z=i(x,t,/)
n=c(t,x,z)
u=p(http://www.torrentspy.com/download.asp?id=)
u=&(u,n)
7=save(u)
x=r(-1,t,title=)
1=x(t,x,",")
t=array(q,2)
z=p(1)
2=x(t,z,>,<)
t=array(q,4)
z=p(1)
5=x(t,z,>,<)
t=array(q,5)
z=p(1)
6=x(t,z,>,<)
aloop[/code]




ok thats all for now.. &nbsp;please ask questions if I can help clarify anything. since i am used to working with this script 'language', i dont know what needs more information, examples, etc.


oh and remember to edit "settings.ini" and write a line "debug=1" and then restart Bit Che if you would like to see some basic debug output from your script when you are testing/writing a script

[Quantum]

Ohh, thanks, this doesn't look too difficult 

I'll have a go at trying to write a script for a site or 2 and bring up any problems I have. Think I'll see if I have any free time between lectures tomorrow and give it a go then.

[DC]

ummm... yeah, you and Quantum should have a great time with this! lol
(only 2 that understand it!)
p.s. i know some of you other guys understand too, so no need to tell me you do... hehehe

[chip!]

lol...  well i think i just made things a whole lot easier to write scripts, I'm going to be uploading a build right now that has a built in basic Debugger with step-by-step processing of the scripts..

writing scripts is pretty easy once you get down what the functions do.. its really just a super-dumbed down programming language though, so if you have no programming experience, it might be a little awkward at first..

[chip!]

I just posted a very small tool thats designed to break up the HTML into an array based on a delimiter. In the past I have been doing this by hand which proved to be tedious. This tool might help others save a few minutes off of the development of new scripts..

Quick Array Display

[deckkeeper]

Ah, wonderful. I had been practicing writing a few scripts, but it was slow work. This should help a lot. Thanks! 

Edit:
I've got a question about function x. I was reading through scripts and found one where the function had an extra parameter. I think it takes what's in it and puts it in front of the extracted data. Am I right?

Edit2:
'nother question. In the scripts I checked, they didn't use the save(var) function, just #=var. Is there any difference?

[chip!]

Question 1:

function x  (aka super extract)..

yes, i forgot to document those extra optional parameters..

you can add a string on to either the front or the end of the extracted text by adding optional parameters:

   vRes = x ( vData, vStart, vEnd, sAddFRONT, sAddEND)

   2=x(t,z,<bc>,[-bc-],http://www.google.com,&name=test)


note, you CAN add only the FRONT or only the END or neither.

Only the END:
   2=x(t,z,<bc>,[-bc-],,&ADDSTHISTOTHEEND)   <-- note the extra ',' place holder for text at the front is blank. this is fine.





Question 2:

which script did you see do #=var? I will look at it because that technically shouldnt do anything, as there is no 'function' defined, which would mean the script parser should skip over the line.. the only 2 functions that store into the special Torrent Info # variables are 'save' and 'x'..  at least thats how it should be, and i'll be confused if its working otherwise (but maybe i forgot something from the earliest versions of the script engine)

[chip!]

would scripting be easier if all of the functions had more descriptive names rather than short 1 letter names? 

like instead of function i and h, we could use something like 'find' and 'findH' (respectively)..


any thoughts?

[deckkeeper]

Hmm, I guess they all used the x function.

Yes, it would probably be helpful to give them descriptive names, but there aren't too many to remember.

[chip!]

okay

hey..  feel free to post any scripts you're working on if you need any help with figuring out how to code for the site, or whatever.. i'm glad to help and get a few more people up to speed on script development..     some sites are trickier than others because you'll find out that you have to use some manipulation tricks to for the HTML into a fashion that can be spliced up into arrays.. or generate the proper URL's for the torrent, page, etc.. 



so if anyone gets stuck on anything, post here and i'll attend to it and try to provide an answer/support asap!

cheers!

[Bovski]

There is also a non stackable

if
else
endif

example.

t=array(q,8)
n=i(z,t,times)
if (n=0) then
t=array(q,9)
else
t=array(q,10)
endif

the If supports the Following operators
! = Not
< = Less than
> = Greater than
= = Equal to



Also note in the superextract commands x and e

vRes = x ( vData, vStart, vEnd, sAddFRONT, sAddEND)
var = e ( vData, vStart, vEnd, sAddFRONT, sAddEND)

Modify the variable vStart is modified to point to the position in vData after vEnd

[chip!]

thanks bovski


also note, 'ELSE' is not required.. you can do just

IF THEN
ENDIF

[The IceMan]

Little problem\bug  !?

the variable 'd' is size limited, if the output page, that return is too big
'd' will have only part of the results ==> Data Lost

Any Help with that ?

[Bovski]

That only appears to be in the debugger and as it only works on the first entry it isn't a problem.

[Bovski]

If you are having problems logging in you may want to try adding


referer=http://www.site.com/login.php
prelogin=http://www.site.com/login.php

Where www.site.com is your sites address