[Libtorrent-devel] Using branch and if commands

[Josef Drexler]

On Nov 27, 2008, at 12:03 PM, Steven Adams wrote:
> I'm just trying to work out how the branch and if commands work  
> with rtorrent on version 0.8.4.
>
> I've read the wiki but still don't really understand.
>
> 1. What does branch do exactly??

branch=condition-command,true-command,false-command
branch=condition1,true1,condition2,true2,false2
etc.

It executes the condition command, and if that returns a true value  
(non-zero number of non-empty string), it executes the true-command.  
Otherwise it checks the next condition (if any) or executes the false- 
command.

The "if" command does the same, but its argument isn't a command name  
but an expression. Functionally, "branch=foo,bar,baz" and "if= 
$foo,bar,baz" do the same, the $ indicates evaluation of its argument  
as a command name (by default it's a plain string which would always  
be true). Both call the "foo" command, and check its return value to  
decide whether to call "bar" or "baz".

> 2. Does an if command execute the command after the comma? So for  
> example the below if will execute all the stuff in the quotes. When  
> rtorrent see's the ; character does it just execute another  
> command? (hope that makes sense)
>
> on_finished = move_complete,"if=d.get_custom4=,\"execute=mv,-u, 
> $d.get_base_path=,$d.get_custom1=;d.set_directory= 
> $d.get_custom1=;print=test\""

This won't work, the if will always be true (because the string  
"d.get_custom4=" is not empty). You need $d.get_custom4= here to  
evaluate the command, or you need to use branch=d.get_custom4= instead.

I think the semicolon is a special feature of on_* handlers only, and  
it only works after a space, to terminate the argument list of the  
previous command and start a new command.

> 3. If i have
>
> if=d.get_custom4=print=test1,print=test2
>
> What does the comma mean?? Does rtorrent just treat it as a  
> delimiter to find what commands to execute?

The comma separates arguments to the function call. In your example  
you have two arguments, "d.get_custom4=print=test1" and  
"print=test2". The first is the condition, but because it's a plain  
string it will always be true. The second is the command to run if  
the condition is true.

You probably meant either
if=$d.get_custom4=,print=test1,print=test2
or
branch=d.get_custom4=,print=test1,print=test2

These will print "test1" in the log if the download's custom4 value  
is set, or "test2" otherwise.

-- 
Josef Drexler
josef at ttdpatch.net