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...
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.
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.
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'
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.
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:
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.
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.
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):
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.
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"
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
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.
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)
happy bug hunting.