Recent Posts

thanks    i've tried to rework a little of the documentation to cover some of the new stuff (multipage, initialize, code0, resubmit function)....   http://convivea.com/forums/index.php?board=25.0

also, i will try to do a 'whats new from the 2.0 engine' page as well in the near future...

bovski, any others who which to edit the 3.0 scripts, they are now located here:  https://github.com/convivea/bit-che-3-scripts

[SiteName.ini]

Script files should be non-unicode saved as SiteName.ini


1. [script] - Required. At the top of the file:

Code:

[script]
name=SiteName.com
source=ShortSiteName
author=AuthorName
modified=author yyyy/dd/mm
version=3

Optional fields:
pwd=1 - flags the script to use the Login (site requires user/pass and login)
initialize=1 - flags the script to use the [initialize] section to process the search url and search terms before submitting a HTTP request
enabled=0 - flags the script to be disabled
notes= - just to store notes
cookie=COOKIENAME=VALUE; COOKIENAME2=VALUE; (force a cookie value or multiple cookies before searching)
referer= - force a referer URL for the search





2. [home] - Required. These are the base URL or mirrors for a Site. At least 1=URL is required.

Code:

[home]
1=http://sitename.com
2=http://sitename2.com

3. [profiles] - Required. "search type profiles" - These are the additional page strings which combined with the 'home' will create the Search URL. Put a specific string for the different profiles if the site supports it.

Code:

[profiles]
all=/search/%SEARCH%/%PAGENUM%/
audio=/search/%SEARCH%/%PAGENUM%/?categories[]=music
video=/search/%SEARCH%/%PAGENUM%/?categories[]=movies
apps=/search/%SEARCH%/%PAGENUM%/?categories[]=applications

Notes: %SEARCH% will be replaced with the Search query and %PAGENUM% (if used for multipage support) will be replaced with the current page.
Also, "all, audio, video, apps" are the default profiles, but if you are adding other profiles, such as "anime" then include a profile URL here for "anime=URL".





4. [nextpage] - Optional. If the site supports multiple page results:

Code:

[nextpage]
type=1
initial=1
morepages='INSERT EXACT HTML TO SEARCH FOR, IF FOUND THEN MEANS THERE IS ANOTHER PAGE'

Example Script: https://github.com/convivea/bit-che-3-scripts/blob/master/default/KickassTorrents.com.ini

Notes:

type=1 or 2
1 is for sequential order starting from the value of "initial=". For example, the first page is "1". Next it goes to "2". This is the most typical.
2 is for 'result count based', starting from value of "initial=". For example, if initial is "0", then the first page is "0". If 35 results are returned, then the next page is "35" (0 + 35). If "35" more results are returned, then page 3 is "70").

initial= the initial value for the "page" (typically this should be 1).





5. [initialize] - Optional. Used if you have initialize=1 in the [script] header.

Code:

[initialize]
code section
[/initalize]

Example Script: https://github.com/convivea/bit-che-3-scripts/blob/master/default/iptorrents.ini

Notes:
can manipulate pretty much anything prior to starting the search, such as: @search, @profile, @descriptions, @form (form= from [login] section), or $login (login= from [login] section), $referer, $cookie, etc





6. [login] - Optional. Used if you have pwd=1 in the [script] header. Here is an example:

Code:

[login]
referer=https://www.site.com/
prelogin=https://www.site.com/login
login=https://www.site.com/login_check
form=_username=%USER%&_password=%PASS%&_remember_me=on
failed=>Site Login</
failed2=class="error">

Optional fields:
referer= - force a referer URL for the search
special=1 - force using the Special Login tool (sites that require captcha)

Example Script:
Normal Login: https://github.com/convivea/bit-che-3-scripts/blob/master/default/waffles.fm.ini
Special Login: https://github.com/convivea/bit-che-3-scripts/blob/master/default/bt-chat.ini



7. [code0] - Optional. Used if prelogin= is set to: code(`URL`,0), then it will fetch "URL" and return to Code0 for processing BEFORE attempting to login.

[code0]
code section
[/code0]

Example Script: https://github.com/convivea/bit-che-3-scripts/blob/master/default/hdbits.org.ini



8. [code1] - Required. The main code section for all scripts.

[code1]
code section
[/code1]

Example Script: https://github.com/convivea/bit-che-3-scripts/blob/master/default/bt.etree.org.ini



9. [code2 through 9] - Optional. Used if $torrent URL is created with code() function. This allows you to fetch a 2nd,3rd,(etc) page, execute another code block and extract $torrent.

[code0]
code section
[/code0]

Example Script: https://github.com/convivea/bit-che-3-scripts/blob/master/default/rlsbb.com.ini

[Basic Functions Detailed - Script Engine 3.0:]

WORK IN PROGRESS.


Basic Functions Detailed - Script Engine 3.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.



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 -- reset @data back to the original HTML (as it was at the beginning of the script execution) (used for debugging)
urlencode(sString) -- URL encodes a string for HTTP.
urldecode(sString) -- converts/decodes a URL coded string.
utf8decode(sString) -- converts/decodes a UTF8 coded string.
code(sString, sNum) -- used to specify a second code section. this is used when Bit Che must fetch a 2nd page, execute another script, and extract more info.
resubmit(sPage) -- used to redirect or resubmit a HTTP request

Wow, thanks.  I had no idea this was coming.

[Variable Handling:]

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


Most basic script commands follow this pattern:

varName=Function(p1,p2,p3)

where:

• varName is the return variable (can be either a Variable, $Special Result Variables, or @Special Data Variables)
• Function() is the function name
• p1..p3 are parameters (can be Strings, Variables (any type), or Numeric) and separated by comma

$Special Result Variables:

$name - Result Name
$size - Result Size
$page - Page/URL to view more info about the Result
$date - Result Date (or time, etc)
$seeds - Result seeds/peers
$leeches - Result leeches/downloaders
$torrent - URL for the .torrent or magnet link
$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 response data sent to the script engine
@i - (integer) - index counter. initialized as 1 and always reset to 1 after =array() function
@home - (string) - the URL for the source of the @data (as supplied in the script file from [profile])

@Additional (available only during [initialize] section)

@descriptions - (numeric) - either 1 for include description results OR 0 for no description results
@search - (string) - the search terms
@profile - (string) - the search URL
$form  - (string) - the FORM string from [login] section
$cookie  - (string) - set or update a cookie  (format of the input string must be  "COOKIE=VALUE;")



Script Engine 3.0 Functions List:

find - searches for a string
findh - searches for a string(s) and HALTS if not found
findrev - searches for a string in reverse
crop - 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
extract - extract: combines search, crop/cut, and clean.
put - store a String into a variable
& - combine Strings OR variables
+ - add a Number from a variable
- - subtract a Number from a variable
len - returns the length
ucase - returns a string in uppercase
lcase - returns a string in lowercase

urlencode - URL encodes a string for HTML
urldecode - decodes a string for HTML
utf8decode - decodes a UTF8 string

vacuum - removes extra characters
scrub - removes HTML tags
code - used to add functionality for second code section

getcookie - retrieves a specific cookie's data
resubmit - stops script execution and resubmits/redirects to a new url


Script Control Functions
start - indicates the start of the result parsing loop
add - adds the current torrent to the results list
aloop - adds the current torrent to the results list and loops back to 'start' with the next result in @q
loop - loops back to 'start' with the next result in @q
die - ends the script
reset - resets the @data variable back to its original value


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

while
wend


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




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.

Nice thanks chip!

[new: able to fetch results from searches with multiple pages]

first build of bit che 3.0 attached  happy bug hunting.

this will run along side a bit che 2.0 installation (and import your previous settings.ini).

running change log from last public 2.60, and bold items are new since 2.70.

Since build 62:

new: able to fetch results from searches with multiple pages (requires Bit Che Plus and scripts to be updated, and setting ENABLED in Preferences)
new: allows launching torrents/magnets in external applications (Synology, uTorrent Remote, Trans. Remote GUI, etc)  - thanks skywalka & regi100
new: export results list to .CSV file  - thanks rgrun1
new: script engine function 'resubmit' to allow url resubmitting/redirection/forwarding
new: now supports http redirection to a magnet link while fetching url
improved: 'Save Torrent', 'Open Torrent', and 'Open Torrent With' actions from results list now support multi code sections to fetch torrent/magnet (as 'View Torrent' dialog does)
improved: does not fetch torrent again if already loaded for 'View Torrent' dialog (duh! reduces bandwidth and speeds up torrent launching)
improved: modified size filters to be more practical  
improved: added 3 more result context menu actions - open with external, copy result name to clipboard, and launch google search
improved: results list mouse middle click now supports new context menu options
improved: allows search request to use POST
improved: profile editor reworked - thanks Bovski
improved: support for Basic HTTP Authentication for login sites
fixed: urlencode function
fixed: properly ignores scripts without given profile search url (even if set with '/') - thanks bovski
fixed: allows search profiles set with '/' to use main search profile url when manually enabled - thanks bovski
fixed: fetching URLs prefixed with '//' to use HTTP or HTTPs protocol based on referer
fixed: HTTP authentication error (bug in winhttp - seen on Windows 8.1)
fixed: cookies lost on redirection request (seen on Windows 8.1)
fixed: not detecting certain .torrent handlers applications - thanks BugMagnet
fixed: other minor bugs

Since build 60:

new: added a new script header flag "initialize=1" which will trigger the code section labeled [initialize] to be processed before beginning the search.  
new: this allows the ability to modify any of the search variables, including new @search, @profile and also use the read-only $descriptions (1 if turned on and 0 if turned off).  
improved: some language translation widths and heights based on feedback from gojko and Exoskeletor (thanks guys!)
fixed: the redirect '//' bug for toggling same HTTP or HTTPS protocol as the referrer
fixed: 'Locate' button in the script debugger for 'find() and extract()'
fixed: properly urlencode the @search (uses Win32 API.. so for example " " is converted to "%20" instead of "+"... also takes care of all the other characters)

i found and fixed this, for next build

Done ! : https://www.facebook.com/pablo.d.chavez 

Bit Che RuLeS ! ! ! .

Awesome