launch 1.2.6d1 [unreleased]
==============

A command-line launcher for macOS in the spirit of open(1).

Written by Nicholas Riley <mailto:launchsw@sabi.net>.
Obtain updates from <https://sabi.net/nriley/software/>.

WHAT IS IT?
-----------

Apple provides a simple command-line launching program called 'open'
with macOS.  'launch' offers several options that 'open' doesn't.  It:

- opens "slack" URLs (e.g. apple.com) and email addresses (-l)
- lets you specify applications by their four-character creator
  (e.g. 'ToyS') or Java-style bundle ID (e.g. com.apple.ScriptEditor2),
  both of which allow you to move or rename an application without
  changing references to it
- lets you find applications rather than opening them (-n)
- asks applications to print documents (-p)
- allows you to pipe output to any GUI application (not just TextEdit)
- displays extensive file, folder and volume information including type,
  creator, bundle ID, sizes, dates and versions (-f)
- reports errors intelligibly
- and much more!

'launch' is useful by itself, but is even better when used in scripts.
Assign a shell command to your favorite macOS text or graphics editor.
Go to your favorite Web site with a few keystrokes.

Like 'open', 'launch' provides one half of the round-trip between
Terminal and the Finder.  You can drag and drop icons or proxy icons
onto a Terminal window to insert their paths into command lines.  To
go in the other direction, type 'launch .' (or 'open .') to open a
Finder window showing the current directory.

INSTALLATION
------------

The commands below install the 'launch' tool in /usr/local/bin, which
is in the default path.  You should subsequently be able to use
'launch' by typing its name.  If you wish to install it somewhere
else, modify the install lines as appropriate.

% sudo /usr/bin/install -d -m 755 /usr/local /usr/local/bin
% sudo /usr/bin/install -d -m 755 /usr/local/share /usr/local/share/man
% sudo /usr/bin/install -d -m 755 /usr/local/share/man/man1
% sudo chmod 755 /usr/local/bin /usr/local/share/man /usr/local/share/man/man1
% sudo /usr/bin/install launch /usr/local/bin
% sudo /usr/bin/install -m 644 launch.1 /usr/local/share/man/man1
% rehash				# if necessary

Uninstallation:

% sudo rm -f /usr/local/bin/launch /usr/local/share/man/man1/launch.1

COMPILATION
-----------

An Xcode project, 'launch.xcodeproj', is included.  A precompiled
binary is also provided.  'launch' was developed and tested under macOS
10.15.7 with Xcode 12.4.

USAGE
-----

Just type 'launch' by itself to receive usage information.  See the
manual page (man launch) for more information.

Some examples:

% launch -c 'R*ch'
[BBEdit opens]
                                
% launch -pbc 'R*ch' test.txt
[BBEdit starts printing test.txt in the background]

% ls -l | launch -c '!Rch' -
[TextWrangler opens with an untitled document containing the file list]

% launch -i org.mozilla.firefox https://www.apple.com/
[Firefox opens Apple's Web site]

% launch -l launchsw@sabi.net
[Your preferred email client opens a new message to comment on launch]

% launch -f /Applications/Preview.app
/Applications/Preview.app: scriptable macOS application package
	type: 'APPL'	creator: 'prvw'
	display name: Preview
	architecture: Intel x86-64
	bundle ID: com.apple.Preview
	version: 10.0
	kind: Application
	attributes: extension hidden
	content type ID: com.apple.application-bundle
	contents: 1 item
[...]

A scripting example: a zsh function which provides an macOS wrapper
around emacsclient and the Mac port of GNU Emacs, using launch and
appswitch (another one of my command-line tools).

    e() {
      ( emacsclient -n $@ >&/dev/null && \
        appswitch -a Emacs ) || \
      ( launch -ba Emacs && \
  	until { emacsclient -n $@ >&/dev/null } do sleep 1; done;
        appswitch -a Emacs )
      export EDITOR=emacsclient
    }

FREQUENTLY ASKED QUESTIONS
--------------------------

Q. How do I discover bundle IDs for applications?

A. The -f option to launch can help.  Say you have Messages in your
/Applications folder, and want to find out its bundle ID.  Type
'launch -f', and drop the Messages icon on the Terminal window:

% launch -f /Applications/Messages.app
/Applications/Messages.app: scriptable macOS application package
	type: 'APPL'	creator: 'fez!'
	display name: Messages
	architecture: Intel x86-64
	bundle ID: com.apple.iChat
[...]

Note that bundle IDs are not case-sensitive: com.barebones.BBEdit is
the same as com.barebones.bbedit.


Q. Why does application X open a file with a name beginning with 
'launch-stationery-'?  

A. Application X does not support stationery.  When you open a
stationery pad in an application which supports it, the application
creates a new untitled document with the contents of the stationery.
Most Cocoa applications, such as TextEdit, do not support stationery.
(Omni Group applications are a notable exception.)  If you're looking
for a text editor which supports stationery, try BBEdit.

For the curious: launch processes input by simultaneously reading it
and writing to a temporary stationery pad file.  Once reading is
complete, launch opens the stationery with your selected application,
then deletes the stationery after one minute (as a conservative
measure, since it is not possible to accurately gauge how long it will
take for the application to open the stationery).


Q. Why doesn't launch support opening items as root?

A. Apple eliminated this capability with the Mac OS X 10.1 Security
Update.  If at some point Apple restores this capability, 'launch'
will be ready to support it.


Q. Why do I get an error -600?

A. A typical occurrence of this would be:

% launch -n .
launch: can't open items: unable to connect to system service.
Are you logged in? (-600)

In order to perform certain operations, launch needs to talk to
various system services owned by the currently logged-on user.  If you
aren't using 'launch' from a terminal currently logged into the macOS GUI,
certain operations may not work.  Try opening Terminal, creating
a new terminal window, and trying again.

Another possibility is to create your own interprocess messaging.
For example, place this script in a file:

#!/bin/sh
PIPE=/tmp/.launchpipe
[ -e $PIPE ] || mkfifo $PIPE
while true; do
    read opts < $PIPE
    eval "/path/to/launch $opts" & # change this to launch's path
done

Then, define a function or alias.  For zsh:

rlaunch() { echo $@ > /tmp/.launchpipe }

Or for tcsh:

alias rlaunch 'echo \!* > /tmp/.launchpipe'

Start the shell script above from the console, then you can use
'rlaunch' in place of 'launch' logged in from anywhere else.

Thanks to robert <robert@allyourbass.org> for this suggestion.

COMMENTS, SUGGESTIONS, BUG REPORTS, ETC.
----------------------------------------

Please send to the author, Nicholas Riley, at <launchsw@sabi.net>.

VERSION HISTORY
---------------

1.2.6 - unreleased
 - signed Universal 2 binary, built for macOS/OS X 10.9 and later
1.2.5 - 2 April 2018
 - no longer unnecessarily restrict -s, -b, -m, -h with -l (should
   have been done with changes in 1.2)
1.2.4 - 1 October 2017
 - code changes (no functionality changes) to compile with the macOS
   10.13 SDK
 - install man pages in /usr/local/share/man instead of /usr/local/man
 - 64-bit Intel binary, built for macOS/OS X 10.8 and later (tested on
   10.8.5, 10.9.5, 10.10.5, 10.11.6, 10.12.6 and 10.13)
1.2.3 - 28 July 2015
 - display display names for bundles
 - display localized file sizes which match Mac OS X 10.6 and later
   (base 10) also now uses EB for larger-than-TB units
 - display localized numbers (with grouping separators if applicable)
 - 64-bit Intel binary, built for OS X 10.8 and later (tested on 10.8.5,
   10.9.5 and 10.10.4)
1.2.2 - 15 March 2014
 - use non-deprecated API for marking files as stationery
 - display type and creator codes containing null bytes
 - display ProDOS types if encoded as HFS types
 - display AppleWorks mixed-case filenames by decoding ProDOS
   auxiliary types if present
1.2.1 - 25 January 2014
 - better work around a bug in OS X 10.8 and 10.9, causing crashes
   using -f with a relative path to an item inside a package
   (r. 15772932)
 - work around an OS X bug in order to display "excluded from backup"
   in more cases when an item is excluded from Time Machine.  Use
   `tmutil isexcluded` if you want a correct answer in all cases
   (r. 15909530)
1.2 - 12 January 2014
 - -l: no longer use Internet Config; can specify application
 - allow getting information (-f) on an application located by
   name, URL, bundle ID or creator
 - display alias targets, where available, with -f
 - display detailed volume information with -f
 - display information on special files and named pipes with -f
 - display total file size (including all forks and metadata)
   instead of resource fork size with -f
 - display hard link count (if > 1) with -f
 - display label (or tags, on 10.9+) with -f
 - display file attributes with -f (e.g., extension hidden)
 - restore -o: pass command-line arguments, fixed as of Mac OS X 10.5
 - read Info.plists embedded in Mach-O binaries
 - fix incorrect error messages with -u
 - fix symbolic links being identified as aliases everywhere
   (and display their targets)
 - fix incorrect size display for items over 4 GB
 - fix display of [can't access package contents] for non-packages
 - update error codes
 - remove support for Classic
 - remove support for resource fork versions
 - remove display of backup date (no supported way to retrieve it)
 - remove display of "in use" status (no supported way to retrieve it)
 - eliminate use of most API deprecated as of OS X 10.8
 - 32-bit/64-bit Intel binary, built for OS X 10.8 and later
   (tested on 10.8.5 and 10.9.1)
1.1 - 30 October 2006
 - -L: send "launch" (ascr/noop) event to app - bypasses automatic
   opening of untitled document, etc.
 - -o: pass command-line arguments (broken, r. 4474993)
 - display content type ID (UTI)
 - display architecture of Mach-O files
 - switch to new LSOpen APIs (now requires Mac OS X 10.4 or later)
 - switch to new date formatting APIs (the old ones are deprecated)
 - for compatibility with open(1), take app path as argument to -a
 - Universal Binary, compatible with Intel Macs [Peter Hosey]
1.0.1 - 3 April 2005
 - prefer files to URLs; added -U for old behavior
 - don't display extraneous leading './' on file paths
 - display 'zero items', not '0 items', for consistency
 - display versions of non-applications
 - read Info.plists embedded in unbundled Mach-O applications
 - non-ASCII arguments are now handled with the filesystem, rather
   than the system encoding [Derrick Bass]
 - explicitly use UTF-8 everywhere else to properly interpret and
   display non-ASCII filenames and URLs
 - reading OSTypes and 'vers' resources, and opening URLs with
   Internet Config still uses the system encoding, converting as
   necessary for display
 - should be buildable on 10.2 again
1.0 - 23 October 2003
 - work around CFBundle bug to report bundle identifiers and versions
   from resource forks of unpackaged Carbon applications and Classic
   applications [Lloyd Dupont]
 - add descriptions for more error codes and clarified error
   reporting
 - output all errors to stderr
 - provide better errors for -X option
 - restore -m: OS X bug is fixed in Panther
 - fix a couple of tiny memory leaks
 - add man page [Hisashi T Fujinaka]
 - work around bug in LSOpenFromURLSpec opening multiple items in
   Mac OS X 10.3
1.0b2 - 9 March 2003
 - fix install instructions to create /usr/local/bin if needed
 - show bundle version with text, hex and integer representations
1.0b1 - 14 December 2002
 - accept "slack" (default http) URLs and email addresses with -l
 - accept input from stdin with '-'
 - open URLs with arbitrary applications when specified without -l
 - build without compiler warnings
1.0a9 - 2 April 2002
 - license, comments changes
1.0a8 - 29 March 2002
 - errors with -l (from ICeCoffEE), added rlaunch script
1.0a7 - 3 March 2002
 - print dates, sizes, folder valence, locked status for -f
 - don't abort on failure to obtain bundle information
1.0a6 - 30 November 2001
 - fixed incorrect messages, broken -u and crash on -nu
1.0a5 - 28 November 2001
 - print kind string for -f, still no new installer
1.0a4 - 20 November 2001
 - [try to] use Installer VISE instead of InstallAnywhere
1.0a3 - 15 November 2001
 - fixed package identification in -f, updated examples
1.0a2 - 15 November 2001
 - -f, removed broken -m
1.0a1 - 14 November 2001
 - renamed from "FindApp", launch by default, -u
1.0d5 - 7 November 2001
 - option -s for launching as root [nonfunctional]
1.0d4 - 6 November 2001
 - URL launching and Internet Config support
1.0d3 - 4 November 2001
 - more robust, support for docs without app
1.0d2 - 4 November 2001
 - options -opsbmhCX, -cin, documents
1.0d1 - 26 August 2001
 - returns path of application identified by creator