rTorrent Scripting Reference

This page is to become the comprehensive reference to rTorrent's command language that was always missing, by joining forces and spreading the workload to many shoulders. If you're a developer or power user, this will be an invaluable tool, so please take the time and contribute what you know. See XmlRpcReference for an overview of all commands.

1. Introduction

TODO The big picture...

2. rTorrent scripting basics

2.1. Basic syntax rules

• All commands are defined in the files rtorrent/src/command_* of the source code, which is the ultimate reference.

• $cmd evaluates cmd

• Arguments are a comma-separated list: cmd=arg1,arg2,...

• Escaping is done by "", {} and \ (but when use what?!); and recently also ()

2.2. Commands

A command is ... It's called by ... A full command reference can be found on XmlRpcReference.

2.3. Escaping

Man, I'd be very interested in details on some rules for that myself...

The most basic form of escaping is when you have to supply a command with multiple arguments to another command as part of an argument list. You have to tell rTorrent which comma belongs to the inner argument list, and which to the outer one, by quoting the inner command using double quotation marks:

• outer=arg1,"inner=arg21,arg22",arg3
  

2.4. Values, types and variables

string / integer / more? data type conversion (to_xx) custom_* fields

2.5. rTorrent entities

download items, files, trackers, peers, ...

2.6. Other useful information

• use less= for ascending and greater= for descending sorting

• "closed" vs. "stopped": The "closed" state refers to all files being closed. In the "stopped" state, rtorrent may keep files open (or at least mmap'ed) which also allows it to keep partially transferred chunks for later resuming. When closing a download, all partial chunks have to be discarded.

• use d.set_custom=key,value and d.get_custom=key for named custom fields

3. Advanced scripting

This section shows how to combine the basic language elements to implement actual features.

3.1. Conditional processing

There are two commands that allow conditional execution of other commands, and they only differ in one tiny detail regarding the evaluation of the condition.

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

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.

if=expression,true-command,false-command

The if command does the same as branch, 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.

3.2. Defining your own commands

system.method.insert = my_print_command,simple,"print=one ;print=two ;print=three"

This way you can avoid most of the quoting/escaping/bracing madness that you'd have to deal with to include quotes and spaces in a command argument.

3.3. Events

• Add event handlers by using system.method.set_key = event.download.<type>,<name>,<command>

• <name> must be unique

• <type> is one of 'closed', 'erased', 'finished', 'hash_done', 'hash_queued', 'hash_removed', 'inserted', 'inserted_new', 'inserted_session', 'opened', 'paused', or 'resumed'.

3.4. Scheduling

3.5. Calling external commands

execute={command,arg1,arg2,...}

This will execute the external command with arguments arg1,arg2,.... It will throw an error if the exit status is not 0, and return 0 itself otherwise.

execute_nothrow={command,arg1,arg2,...}

This will execute the external command with arguments arg1,arg2,.... It will return the return value of the command.

execute_capture={command,arg1,arg2,...}

This will execute the external command with arguments arg1,arg2,.... It will throw an error if the exit status is not 0, and return the stdout output of the command otherwise.

execute_capture_nothrow={command,arg1,arg2,...}

This will execute the external command with arguments arg1,arg2,.... It will return the stdout output of the command.

3.6. ...