use-case: Rename Item Using its Tied-to File

docs/examples/rename2tied.sh

@@ -0,0 +1,66 @@
+#! /usr/bin/env bash
+#
+# Rename item based on its tied-to file name (BEFORE it is started!)
+#
+# Bind to "R"ename as follows:
+#
+# method.insert = pyro._rename2tied, private|simple, \
+#     "execute.nothrow = ~/rtorrent/scripts/rename2tied.sh, \
+#      (d.hash), (d.name), (d.directory), (d.tied_to_file), (d.is_multi_file)"
+#
+# pyro.bind_key = rename2tied, R, "pyro._rename2tied="
+
+hash="${1:?hash is missing}"
+name="${2:?name is missing}"
+path="${3}"
+tied="${4}"
+multi="${5:?is_multi_file is missing}"
+
+fail() {
+    msg=$(echo -n "$@")
+    rtxmlrpc print '' "ERROR: $msg [$name]"
+    exit 1
+}
+
+test -n "$path" || fail "Empty directory"
+test -n "$tied" || fail "Empty tied file"
+test ! -e "$path" || fail "Cannot rename an item with existing data"
+
+tracker="$(rtcontrol --from-view $hash // -qo alias)"
+
+# Build new name
+new_name="${tied##*/}"  # Reduce path to basename
+new_name="${new_name// /.}"  # Replace spaces with dots
+new_name="${new_name%.torrent}"  # Remove extension
+while test "$new_name" != "${new_name%[.0-9]}"; do
+    new_name="${new_name%[.0-9]}"  # Remove trailing IDs etc.
+done
+
+# Remove bad directory name (that we want to replace) from multi-file item
+new_full_path="${path%/}"
+if test "$multi" -eq 1; then
+    new_full_path="${new_full_path%/*}"
+fi
+
+# Remove common extensions
+for ext in mkv mp4 m4v avi; do
+    new_name="${new_name%.$ext}"
+    new_name="${new_name%.$(tr a-z A-Z <<<$ext)}"
+done
+
+# Change source tags to encode tags (when item has an encoded media type)
+if egrep -i >/dev/null '\.[xh]\.?264' <<<"$new_name"; then
+    new_name=$(sed -re 's~\.DVD\.~.DVDRip.~' -e 's~\.Blu-ray\.~.BDRip.~' <<<"$new_name")
+fi
+
+# Add tracker as group if none is there
+if ! egrep >/dev/null '.-[a-zA-Z0-9]+$' <<<"$new_name"; then
+    new_name="${new_name}-$tracker"
+fi
+
+# Rename / relocate item
+new_full_path="${new_full_path%/}/$new_name"
+rtxmlrpc d.directory_base.set $hash "$new_full_path"
+rtxmlrpc d.custom.set $hash displayname "$new_name"
+
+# End of rename2tied.sh

docs/use-cases.rst

@@ -104,6 +104,67 @@ The ``pyro.log_rotate`` method is used near the end to open log files at startup
 .. _`rtorrent.d/15-logging.rc`: https://github.com/pyroscope/pimp-my-box/blob/master/roles/rtorrent-ps/templates/rtorrent/rtorrent.d/15-logging.rc
 
 
+.. _rename2tied:
+
+Rename Item Using its Tied-to File
+----------------------------------
+
+The `rename2tied.sh`_ script overwrites an item's name using the file name
+of its tied-to file, when you press the ``R`` key with a fresh unstarted item in focus.
+
+This is useful when the metafile names generated by a tracker
+contain more useful information than the ``info.name`` of the metafile content.
+Also, those metafile names typically have a common format,
+which can help with properly organizing your downloads.
+
+.. warning::
+
+    Right now, this only works for items that are not started yet,
+    i.e. were added using ``load.normal`` and have no data files yet.
+
+    Also, the item needs to be loaded from a file, so there actually *is*
+    a tied-to name – items loaded via ruTorrent do *not* have one!
+
+Here is the core script code (minus some boilerplate):
+
+.. literalinclude:: examples/rename2tied.sh
+   :language: shell
+   :start-after: # pyro.bind_key
+   :end-before: # End of
+
+Install the full script by calling these commands:
+
+.. code-block:: shell
+
+    gh_raw="https://raw.githubusercontent.com/rtorrent-community/rtorrent-docs"
+    mkdir -p ~/rtorrent/scripts
+    wget $gh_raw/master/docs/examples/rename2tied.sh -O $_/rename2tied.sh
+    chmod a+rx $_
+
+Note that you also **must** have `pyrocore <http://pyrocore.readthedocs.io/>`_ installed,
+so that the ``rtcontrol`` and ``rtxmlrpc`` commands are available.
+
+This is the configuration snippet that binds calling the script to the ``R`` key.
+For key binding, you need rTorrent-PS though – otherwise leave out the
+``pyro.bind_key`` command, and call ``pyro._rename2tied=`` via a ``Ctrl-X`` prompt.
+
+.. code-block:: ini
+
+    method.insert = pyro._rename2tied, private|simple, \
+        "execute.nothrow = ~/rtorrent/scripts/rename2tied.sh, \
+         (d.hash), (d.name), (d.directory), (d.tied_to_file), (d.is_multi_file)"
+
+    pyro.bind_key = rename2tied, R, "pyro._rename2tied="
+
+Depending on your needs, it can also make sense to call the script in
+an ``inserted_new`` event handler, or as a post-load command in a watch schedule.
+If you do that, you should probably add some checks
+that only apply changes for certain trackers,
+or when the tied-to file name has a certain format.
+
+.. _`rename2tied.sh`: https://github.com/rtorrent-community/rtorrent-docs/blob/master/docs/examples/rename2tied.sh
+
+
 .. _versatile-move:
 
 Versatile Move on Completion