Package: urial
UrialUrial (URIaddition tool) is a simple but intelligent command-line tool to add, view, or replace URIs in macOS Finder comments.Table of contentsIntroductionInstallationUsageGetting helpContributingLicenseAcknowledgmentsIntroductionUrial(a loose acronym ofURIaddition tool) is a command-line program written in Python 3 that allows you to read, write and update URIs in the macOS Finder comments of a file. Urial makes it easier to create scripts (e.g., in Bash/Bourne shell syntax, or AppleScripts) that keep those URIs updated.  You can find an example of how the author uses this program withDEVONthinkin the projectwiki.Incidentally, theurial(properly known asOvis vignei) are a kind of wild sheep native to Central and South Asia.  They are listed by theIUCNas avulnerable speciesand their population continues to twindle due to human activity, hunting, and climate change.InstallationThere are multiple ways of installing the programurial, ranging from downloading a self-contained, single-file, ready-to-run program, to installing it as a typical Python program usingpip.  Please choose the alternative that suits you.Alternative 1: downloading the ready-to-run programA binary, ready-to-run version ofurialis available that only needs a Python interpreter version 3.8 or higher on your computer. Happily, that's the case for macOS 10.15 and later. To be sure, first check the version of the programpython3that you get by running the following command in a terminal and inspecting the results:python3--version(Note: if this is the first time you've runpython3on your system, macOS will ask if you want to install certain additional software components. Let it do so.) Make sure the version is at least 3.8. Note that if you are running a macOS version before 10.15, you will need to manually install Python 3.8 or later.Next,Go to thelatest release on GitHuband find theAssetsDownloadthe ZIP file whose name contains the version of Python on your computerUnzipthe file (if your browser didn't unzip it)Open the folderthat gets created (it will have a name likeurial-1.0.0-macos-python3.8)Look inside forurialandmove itto a location where you put other command-line programs (such as/usr/local/bin).If you want to put it in/usr/local/binbut that folder does not exist on your computer yet, you can create it by opening a terminal window and running the following command (priorto movingurialinto/usr/local/bin):sudomkdir/usr/local/binThe following is an example command that you can type in a terminal to moveurialthere:sudomvurial/usr/local/binAlternative 2: installation usingpipxYou can usepipxto installurial. Pipx will install it into a separate Python environment that isolates the dependencies needed byurialfrom other Python programs on your system, and yet the resultingurialprogram wil be executable from any shell – like any normal program on your computer. If you do not already havepipxon your system, it can be installed in a variety of easy ways and it is best to consultPipx's installation guidefor instructions. Once you have pipx on your system, you can installurialwith the following command:pipxinstallurialPipx can also let you runurialdirectly usingpipx run urial, although in that case, you must always prefix everyurialcommand withpipx run.  Consult thedocumentation forpipx runfor more information.Alternative 3: installation usingpipThe instructions below assume you have a Python 3 interpreter installed on your computer.  Note that the default on macOS at least through 10.14 (Mojave) is Python2– please first install Python version 3 and familiarize yourself with running Python programs on your system before proceeding further.You should be able to installurialwithpipfor Python 3.  To installurialfrom thePython package repository (PyPI), run the following command:python3-mpipinstallurialAs an alternative to getting it fromPyPI, you can usepipto installurialdirectly from GitHub:python3-mpipinstallgit+https://github.com/mhucka/urial.gitIf you already installedurialonce before, and want to update to the latest version, add--upgradeto the end of either command line above.Alternative 4: installation from sourcesIf  you prefer to installurialdirectly from the source code, you can do that too. To get a copy of the files, you can clone the GitHub repository:gitclonehttps://github.com/mhucka/urialAlternatively, you can download the files as a ZIP archive using this link directly from your browser using this link:https://github.com/mhucka/urial/archive/refs/heads/main.zipNext, after getting a copy of the files,  runsetup.pyinside the code directory:cdurial
python3setup.pyinstallUsageThis program expects to be given one or more arguments on the command line, as described below.  Optional arguments begin with dashes and modify the program's behavior.Default behaviorWithout any optional flags or arguments to modify its behavior,urialexpects to be given at least two argument values.  The first value should be a URI, and the second value should be the path of a file whose Finder comment is to be updated with the given URI.If the current Finder comment for the file is empty, thenurialwill simply write the URI into the Finder comment. An example of the result is shown in the screenshot at right.If the Finder comment isnotempty,urialwill edit the comment to update the substring that has the same kind of URI (meaning, one that uses the same URI scheme), and then only ifurialfinds such a substring in the Finder comment.  For example, if the file "somefile.md" has a Finder comment with an existingx-devonthink-itemURI string somewhere inside of it, then the following command,urialx-devonthink-item://8A1A0F18-0686-802-26F33443somefile.mdwill makeurialrewritejust the URI part of the commentto be the new URI given on the command line.If the Finder comment is not empty but also doesnotcontain a URI with the same scheme as the one given on the command line, then the Finder comment is not changed, unless a suitable value for the option--modeis given (see below).urialis careful to match based on URI schemes to make it more robust against accidentally matching other URIs that may exist in a Finder comment. So, for example, If you supply a URI that has ax-devonthink-itemscheme type, it willlookonly forx-devonthink-itemURIs and will not match other URIs; if you supply a URI that has azoteroscheme type, it will look only forzoteroURIs; and so on.URI detectionThe full syntax of URIs is complex. The characters that can appear in URIs (according toRFC 3986) include periods, semicolons, question marks, dollar signs, exclamation points, parentheses, square brackets, and more. Here are some examples of valid yet potentially surprising URIs:paparazzi:http://www.caltech.edu
https://en.wikipedia.org/wiki/Bracket_(disambiguation)
z39.50s://lx2.loc.gov:210/lcdb?9=84243207
ldap://[2001:db8::7]/c=GB?a?b
http://wayback.archive.org/web/*/http://www.alexa.com/topsites
prefs:root=General&path=VPN/DNSURIs are difficult to detect when they're embedded in human language text. One can't assume that URIs are delineated by whitespace characters, because a human or software tool may have written a Finder comment without being careful to delimit URIs from the rest of the text. Even worse, URI syntax according toRFC 3986allows for a scheme name followed by an empty path, which means that in the following text,Original source: x-devonthink-item://40C401DB-8A1D-4B1D-032FB186D85A.a strict interpretation requires that the stringsource:is considered a valid URI. (In addition, the trailing period is, strictly speaking, part of the second URI). This is probably not what the author intended.These strict interpretations are usually unhelpful in Urial's domain of application. For this reason,urialtries to be intelligent about recognizing URIs in Finder comments by applying the following rules:it will assume that the following characters are not part of a URI if they come at the end of something that otherwise looks like a URI:.,:;'?!$([it will assume that)and]characters at the end of something that looks like a URI are not part of the URI if there is no opening(or[character in the rest of the URIit will ignore strings that could be URIs with empty path components (e.g.,something:,abc-def:, etc.)To disable this behavior, use the--strictoption; then, the program will assume that URIs are separated from text only by (1) whitespace characters and (2) the characters<>^"`{and}, and it will not ignore potential URIs with empty paths.Options for handling existing Finder commentsThe--modeoption can be used to change the behavior described above. The following are the possible values for this option:append: in this mode, if the URI isnotfound in the Finder comment string,urialwill append the given URI to the end of the comment; otherwise (if the comment string already contains the URI) it will do nothing.prepend: in this mode, if the URI isnotfound in the Finder comment string,urialwill prepend the given URI to the front of the comment; otherwise (if the comment string already contains the URI) it will do nothing.overwrite: the program will overwrite the Finder comment completely with the given URI string, no matter what the Finder comment string contains (even if it already contains the given URI).update: (default) if a URI of the same kind exists in the comment,urialwill replace only the URI portion of the comment string (preserving the rest of the comment string), else (if a URI is NOT found in the comment string) it will do nothing.Note carefully that--mode overwritemakesurialreplace unconditionally the entire Finder comment.  In other words,--mode overwritewill change a Finder comment such asBlah blah blah. URI. More blah blah blah.to justURIassuming thatURIis the URI given tourialon the command line.  If you want to update the URI to a new value and leave rest of the text the same, use--mode updateor simply don't provide a value for--mode(becauseupdateis the default action).Printing the Finder commentInstead of writing a Finder comment,urialcan be used to print an existing comment via the--printoption. The--printoption takes a required argument, which can be eithercommentoruri; the former causesurialto print the entire Finder comment of the file, and the latter just the URI(s) found in the comment. For example, given a file named "somefile.md", the following command will extract and print any URI(s) found anywhere in the Finder comment text:urial--printurisomefile.mdIf more than one URI is found in the Finder comment, they will be printed separately to the terminal, one per line.Additional command-line optionsIf given the--versionoption, this program will print the version and other information, and exit without doing anything else.By default, this program will use macOS dialogs to report errors or other issues.  The option--no-guiwill make it print messages only on the command line, without using GUI dialogs.If given the--debugargument, this program will output a detailed trace of what it is doing. The trace will be sent to the destination given as the value of the option, which can be-(i.e., a dash) to indicate console output, or a file path to send the output to a file.Summary of command-line optionsThe following table summarizes all the command line options available.ShortLong form optMeaningDefault-h--helpDisplay help text and exit-m--modeMApproach for handling existing commentsupdate⚑-p--printPPrint Finder comment or URIs therein, and exit★-s--strictBe strict about URI syntaxDon't be pedantic-U--no-guiPrint errors & warnings to terminalUse GUI dialogs-V--versionDisplay program version info, and exit-@OUT--debugOUTDebugging mode; write trace toOUTNormal mode⬥⚑   Available values areappend,prepend,overwrite, andupdate.★   Available values arecommentanduri.⬥   To write to the console, use the character-as the value ofOUT; otherwise,OUTmust be the name of a file where the output should be written.Getting helpSome notes about how the author uses this program can be found in thewiki.If you find an issue, please submit it inthe GitHub issue trackerfor this repository.ContributingI would be happy to receive your help and participation if you are interested.  Everyone is asked to read and respect thecode of conductwhen participating in this project.LicenseThis software is Copyright © 2024 by Michael Hucka.  This software is freely distributed under the terms of the MIT License.  Please see theLICENSEfile for more information.AcknowledgmentsThe photograph of a sheep from the speciesOvis vigneishown near the top of this page is the work of userFabrice Stoger, who provided it toWikimedia Commonson 2017-03-09 under the terms of aCreative Commons Attribution-Share Alike 4.0 International license. I cropped the original and added a mild drop shadow with the help ofImageMagick(version 7.1.1-23) using the following command on macOS 13.6.3:converturial-cropped.jpg\\(+clone-backgroundblack-shadow10x15+0+10\)\+swap-backgroundtransparent-layersmerge+repageurial.pngThis program makes use of numerous open-source packages, without which Urial could not have been developed.  I want to acknowledge this debt.  In alphabetical order, the packages are:appscript– Apple event bridge for controlling scriptable Mac OS X applicationsflake8– Python code linter and style analyzerjq– JSON data processing toolmarkdownlint-cli2– CLI interface for usingmarkdownlintto lint Markdown filesplac– a command line argument parserpytest-cov– coverage reports for use withpytestpytest-mock– wrapper around themockpackage for use withpytestpytest– testing frameworksetuptools– library forsetup.pyshiv– utility for building fully self-contained Python "zipapps"Sidetrack– simple debug logging/tracing packageTwine– utilities for publishing Python packages onPyPIuritools– functions for parsing, classifying and composing URIs and URI referenceswheel– setuptools extension for building Python wheels