Dev (#3)

Add scripts

Author: heckman

.envrc

@@ -0,0 +1,3 @@
+PATH_add .
+PATH_add bin
+PATH_add scripts

.github/workflows/build.yml

@@ -22,9 +22,9 @@ jobs:
 
       - name: Package ZIP
         run: |
-          zip -j macOS-alias-utils.${{ github.ref_name }}.zip \
-          bin/readalias \
-          bin/mkalias \
+          zip macOS-alias-utils.${{ github.ref_name }}.zip \
+          bin/* \
+          scripts/* \
           README.md \
           LICENSE
 

.gitignore

@@ -9,3 +9,4 @@ DerivedData/
 .netrc
 /Sources/**/generated*
 .vscode/launch.json
+/temp

README.md

@@ -18,7 +18,12 @@ on some earlier verions of macOS.
 ## Installation
 
 Download the [latest release](https://github.com/heckman/macOS-alias-utils/releases/latest)
-and put the two universal binaries somewhere on your `PATH`.
+and put the two universal binaries in `bin` somewhere on your `PATH`.
+
+The scripts in `scripts`can be installed the same way,
+or, if using the `Zsh` shell, they can be used as autoloadable functions
+by putting them somewhere on the `fpath`.
+(This is how I use them.)
 
 Alternatively, build the binaries from source.
 You will neet to have Command Line Tools (CLT) installed,
@@ -29,48 +34,106 @@ From there, run `./build`.
 This should produce the `readalias` and `mkalias` binaries
 in a `./bin` directory.
 
-## Features
-
-At the moment, `readalias` simply prints the path to the original item
-and has no options beyond `--help` and `--version`,
-while `mkalias` can be given the `force` ( or `-f`) option
-indicating existing files should be overwritten--by default it
-is non-destructive.
+## Usage
 
-Both respond appropriately to `--version` and `--help` options.
+Both binaries respond appropriately to `--version` and `--help` options.
 The help output includes descriptions their various exit codes.
 
-### Future features
+The help text is also easy to find in their source code.
+
+### readalias
+
+Prints the path to the original file of an alias file.
+It takes no options, and has one required argument:
+
+`readalias <alias-file>`
+
+On error, nothing is printed to stdout,
+an error message is printed to stderr,
+and the exit status is non-zero.
+
+### mkalias
+
+Creates an alias file that points to the path of an original.
+It takes two required positional arguments, and one optional
+flag, which will cause `<alia-file>` to overwrite any existing file.
+Be default, the command will fail if the file already exists.
+
+`mkalias [-f|--force] [--] <path-of-original> <alias-file>`
+
+Never writes to stdout.
+On error, an message is printed to stderr,
+and the exit status is non-zero.
+
+## Scripts
 
-By default `mkalias` will fail
-rather than overwrite and existing file.
-The `force` (or `-f`) option will cause existing
-files to be clobbbered, although a directory
-will still not be overwritten.
+These scripts make use of the `readalias` and `mkalias` binaries.
+The funcionality provided by these scripts
+may eventually be merged into the binaries,
+or be made into new binaries themselves.
+The format of these scripts is such that
+the files can be used as autoloadable functions in Zsh
+by simply placeing them in a directory on the `fpath`.
+This is how I use them, which is why each script
+is a single function called from its body, and why
+the two helper functions have their own scripts.
 
-I indend to offer a third behaviour, which,
-when the specified name for the alias is taken,
-generates a new name in the way the Finder does.
-This might become the default behaviour
-in which case we will need a new a command-line option
-for the fail-on-existing file behaviour.
+### isalias
 
-The renaming strategy is this: Use the same name as the original,
-if avaialbe, otherwise append ` alias` to the name. If that
-is still not unique, then append the smallest integer
-greater than one, separated by a space, sufficient to
-generate a unique name.
+This wraps the `readalias` binary, and produces no output.
+It produces a successful exit status (0) if the file provided
+is an alias file, even if it is broken. It returns a non-zero
+exit status otherwise.
 
-### Edge Cases
+### makealias
+
+This forwards all arguments passed to it to the `mkalias` binary,
+along with one additional argument: a name generated
+using `namealias`, so `<alias-file>` can be unspecified,
+in which case a suitable name will be generated.
+
+### namealias
+
+This is a helper used by `makealias`.
+Given a path, this will print a name
+suitable to be used for an alias file,
+using the the same naming strategy used by the Finder.
+
+### nextname
+
+This is a helper used by `namealias`.
+It prints a path that is guaranteed (at the moment) not to exist.
+It takes the desired path as its only argument.
+It prints the path if it does not exist, otherwise
+it prints the path appended with a space and number, at least 2,
+an only large enough to make the path unique.
+
+## Issues
+
+### Undetermined behaviour
 
 These utilites have only been nominally tested,
-and most edge cases have not been explored:
+and some edge cases have not been explored:
 
 - Broken Aliases
 - Aliases to unmounted external/network volumes
-- Creating and Alias to another Alias
 
-## Props where due
+### Known edge cases
+
+- Creating an Alias to another Alias file makes a new
+  Alias pointing to the original of the other Alias.
+  This is the expected behaviour.
+- Arguments that are empty strings will be treated
+  as `.`, which produces potentially confusing
+  error messages such as "Error: directory exists:".
+
+## Roadmap
+
+- Incorporate scripts into binaries
+- Generate an explicit error when arguments are empty
+- Add formal testing
+
+## Acknowledgements
 
 Prior to writing these two utilites,
 I was using _alisma_, by Howard Oakley,

Sources/config/package-info.swift

@@ -1,6 +1,6 @@
 public let about = """
         (macOS-alias-utils v\(versionNumber))
         Copyright (c) 2026 Erik Ben Heckman
-        SPDX-License-Identifier: MIT
+        MIT License
         <https://github.com/heckman/macOS-alias-utils/>
         """

Sources/mkalias/main.swift

@@ -54,7 +54,7 @@ do {
             exit(2)
         }
     }
-    guard args.count == 2 else {
+    guard args.count >= 2 else {
         fputs(
             "\(usage)\n",
             stderr

scripts/isalias

@@ -0,0 +1,36 @@
+#!/bin/zsh
+# Part of macOS-alias-utils <https://github.com/heckman/macOS-alias-utils>
+# Copyright (c) 2026 Erik Ben Heckman
+# MIT License
+
+#: isalias <alias-file>
+
+# Return 0 if <alias-file> is an alias file,
+# even if it cannot be resolved.
+# Otherwise, return 1.
+#
+# Produces no output.
+#
+# This relies on the exit status of `readalias <alias-file>`:
+#   0: <alias-file> is an alias file and can be resolved.
+#   1: <alias-file> is an alias file but cannot be resolved.
+#   2: <alias-file> is not an alias file, does not exist,
+#      or was not specified.
+#
+# Requires: [readalias](https://github.com/heckman/macOS-alias-utils).
+#;
+
+if (( $+commands[readalias] ))
+then
+isalias() {
+	readalias $@ &>/dev/null || ((?==1))
+}
+else
+isalias(){
+	print -u2 'Error: the `isalias` function requires the `readalias` command'
+	print -u2 'Get it here: <https://github.com/heckman/macOS-alias-utils>'
+	return 69 # EX_UNAVAILABLE
+}
+fi
+
+isalias $@

scripts/makealias

@@ -0,0 +1,32 @@
+#!/bin/zsh
+# Part of macOS-alias-utils <https://github.com/heckman/macOS-alias-utils>
+# Copyright (c) 2026 Erik Ben Heckman
+# MIT License
+
+#: makealias [options] <original> [<alias-file>]
+
+# All arguments (and options) are passed to the `mkalias` command,
+# along with one additional argument: an alias name derived
+# from the last argument. This means that, unlike the `mkalias`
+# command, <alias-file> is optional. I <alias-file> is specified,
+# this script will still produce an additional argument, but
+# it will be ignored by the `mkalias` command.
+#
+# This script relies on the fact that the `mkalias` command
+# will silently ignore extra arguments.
+#;
+
+if (( $+commands[mkalias] ))
+then
+makealias() {
+	mkalias $@ "$(namealias ${@[-1]})"
+}
+else
+makealias(){
+	print -u2 'Error: the `makealias` function requires the `mkalias` command'
+	print -u2 'Get it here: <https://github.com/heckman/macOS-alias-utils>'
+	return 69 # EX_UNAVAILABLE
+}
+fi
+
+makealias $@

scripts/namealias

@@ -0,0 +1,30 @@
+#!/bin/zsh
+# Part of macOS-alias-utils <https://github.com/heckman/macOS-alias-utils>
+# Copyright (c) 2026 Erik Ben Heckman
+# MIT License
+
+#: namealias <original>
+
+if (( $+commands[readalias] ))
+then
+namealias() {
+	local ideal f
+	# If original is an alias, use _its_ original
+	# otherwise, use the original.
+	# Then strip the directory from the name.
+	ideal="${"$(readalias $1 2>/dev/null || echo $1)":t}"
+
+	if [[ -e $ideal ]]
+	then nextname "$ideal alias"
+	else print -- $ideal
+	fi
+}
+else
+namealias(){
+	print -u2 'Error: the `namealias` function requires the `readalias` command'
+	print -u2 'Get it here: <https://github.com/heckman/macOS-alias-utils>'
+	return 69 # EX_UNAVAILABLE
+}
+fi
+
+namealias $@

scripts/nextname

@@ -0,0 +1,38 @@
+#!/bin/zsh
+# Part of macOS-alias-utils <https://github.com/heckman/macOS-alias-utils>
+# Copyright (c) 2026 Erik Ben Heckman
+# MIT License
+
+#: nextname <desired-name>
+
+# If <desired-name> does not exist, print it.
+# Otherwise append 2 to the name, and check again.
+# Increment the number until an available name is found.
+#;
+
+nextname() {
+	# nothing to do if the name is available
+	[[ -e $1 ]] || {
+		print -- $1
+		return
+	}
+
+	# This limits the number of alternate names that will be checked.
+	# The loop is quite fast--file existence is not checked within it.
+	local loop_limit=99999
+
+	# populate an set of potentially-conflicting names
+	local base="$1 "
+	local -A extant=()
+	local f
+	for f ( $base*(N) ) extant[$f]=1
+	local counter=1
+
+	# increment counter until the name is not in the set
+	while (( ${+extant[$base$((++counter))]} )) {
+		(( counter > loop_limit )) && return 1
+	}
+	print -- $base$counter
+}
+
+nextname $@