schnodo / filiverto

File Link Verifier for ToDoList

filiverto

File Link Verifier for AbstractSpoon's ToDoList

About

filiverto checks XML task lists in AbstractSpoon's ToDoList format for dangling file references. Those are most commonly caused by

• moving the task list to another directory or
• by moving/deleting the referenced files or folders.

filiverto checks for "file links" and for links in the comments field.

filiverto can be used as user-defined tool in ToDoList, making it possible to verify the currently active task list.

filiverto is written in Python.

Setup and execution

Assuming that Python is already installed on your system, simply copy the files contained in the repository into a directory and from a console window run:
python filiverto.pyw [optional task list file path]

Starting with ToDoList 8.1.17, filiverto is already part of the official release. In that case, in the ToDoList installation directory, you will find filiverto under ...\Resources\Scripts\File Link Verifier\.

If filiverto does not work, check the console window for error messages:

• If you haven't installed Python yet, you can download the most current version from the Python website.
  filiverto was tested with Python 3.10.
• filiverto uses the lxml package, which is not part of the standard library. If you don't have it installed already, add it by executing this command in the console window:
  pip install lxml

Alternatively, there's a single-file Windows executable available, which was created using Auto PY to EXE. Windows will probably warn you that filiverto "is not commonly downloaded and may be dangerous". I would agree that it is not commonly downloaded but filiverto is definitely not designed to be dangerous. 😊

How it works

Currently, it does the following:

Prepare

1. If one argument is passed to filiverto, this is treated as the file path. Otherwise, users are presented with a file selection dialog, which lets them choose the task list to check.
2. If the file path is invalid or the user cancels the selection, filiverto terminates.
3. The working directory is set to the directory of the task list; that makes it easier to check relative links.
4. An XML parser parses the task list.

Extract and Verify

1. All links and their respective parent's task IDs are extracted into a list. (The ID makes it easier to find the problematic tasks when cleaning up the task list afterwards.) First, FILEREFPATH elements are handled, then COMMENTS.
• Every FILEREFPATH contains one link and nothing else, which makes extraction straightforward.
• For COMMENTS, matching against a few patterns is necessary because a comment field might contain multiple links, which have to be separated from the surrounding text.
2. One by one the links are cleaned up and checked.
1. tdl:// references get special treatment
• Direct links within the task list (tdl://1234) are ignored.
• For links to other task lists (tdl://test.tdl?1234), potential task references (?1234) are removed.
2. Escaped characters (tdl://todolist%20test.tdl) are unescaped.
3. Any kind of URL reference besides tdl:// and file:// is ignored.
4. The protocol identifier (tdl:// and file://) is removed.
5. What remains, hopefully is a file name and its existence is verified.
6. If a file is not found, it is added to the list of missing references.

Report

1. After processing all entries, a messagebox informs the user about the number of processed entries and the number of defective file links.
2. To facilitate sorting by task ID or by file path, the report is stored in CSV format. (In case the report is opened with Excel, a few precautions are taken.) The report lies in same directory as the task list.

Limitations

• filiverto does not verify other kinds of hyperlinks, such as those that typically link to a website on the Internet (http(s)://)
• The search patterns for the COMMENTS element are not fully reliable. They will in some cases
• not match all possible combinations of legal characters or
• match more characters than desired, for example when providing arguments to an executable: todolist.exe -cmd 32828
  Unfortunately that's a semantic problem because this also represents a legal file name as you can see in the screenshot. Maybe next year I'll program the AI to keep them apart. 😉