This document describes the algorithm implemented in the generate_cask_token script, and covers detailed rules and exceptions which are not needed in most cases.
- Purpose
- Finding the Simplified Name of the Vendor’s Distribution
- Converting the Simplified Name To a Token
- Cask Filenames
- Cask Headers
- Cask Token Examples
- Token Overlap
The purpose of these stringent conventions is to:
- Unambiguously boil down the name of the software into a unique identifier
- Minimize renaming events
- Prevent duplicate submissions
The token itself should be:
- Suitable for use as a filename
- Mnemonic
Details of software names and brands will inevitably be lost in the conversion to a minimal token. To capture the vendor’s full name for a distribution, use the name within a Cask. name accepts an unrestricted UTF-8 string.
-
Start with the exact name of the Application bundle as it appears on disk, such as
Google Chrome.app. -
If the name uses letters outside A-Z, convert it to ASCII as described in Converting to ASCII.
-
Remove
.appfrom the end. -
Remove from the end: the string “app”, if the vendor styles the name like “Software App.app”. Exception: when “app” is an inseparable part of the name, without which the name would be inherently nonsensical, as in rcdefaultapp.rb.
-
Remove from the end: version numbers or incremental release designations such as “alpha”, “beta”, or “release candidate”. Strings which distinguish different capabilities or codebases such as “Community Edition” are currently accepted. Exception: when a number is not an incremental release counter, but a differentiator for a different product from a different vendor, as in pgadmin3.rb.
-
If the version number is arranged to occur in the middle of the App name, it should also be removed. Example: IntelliJ IDEA 13 CE.app.
-
Remove from the end: “Launcher”, “Quick Launcher”.
-
Remove from the end: strings such as “Mac”, “for Mac”, “for OS X”. These terms are generally added to ported software such as “MAME OS X.app”. Exception: when the software is not a port, and “Mac” is an inseparable part of the name, without which the name would be inherently nonsensical, as in PlayOnMac.app.
-
Remove from the end: hardware designations such as “for x86”, “32-bit”, “ppc”.
-
Remove from the end: software framework names such as “Cocoa”, “Qt”, “Gtk”, “Wx”, “Java”, “Oracle JVM”, etc. Exception: the framework is the product being Casked: java.rb.
-
Remove from the end: localization strings such as “en-US”.
-
If the result of that process is a generic term, such as “Macintosh Installer”, try prepending the name of the vendor or developer, followed by a hyphen. If that doesn’t work, then just create the best name you can, based on the vendor’s web page.
-
If the result conflicts with the name of an existing Cask, make yours unique by prepending the name of the vendor or developer, followed by a hyphen. Example: unison.rb and panic-unison.rb.
-
Inevitably, there are a small number of exceptions not covered by the rules. Don’t hesitate to contact the maintainers if you have a problem.
-
If the vendor provides an English localization string, that is preferred. Here are the places it may be found, in order of preference:
CFBundleDisplayNamein the mainInfo.plistfile of the app bundleCFBundleNamein the mainInfo.plistfile of the app bundleCFBundleDisplayNameinInfoPlist.stringsof anen.lprojlocalization directoryCFBundleNameinInfoPlist.stringsof anen.lprojlocalization directoryCFBundleDisplayNameinInfoPlist.stringsof anEnglish.lprojlocalization directoryCFBundleNameinInfoPlist.stringsof anEnglish.lprojlocalization directory
-
When there is no vendor localization string, romanize the name by transliteration or decomposition.
-
As a last resort, translate the name of the app bundle into English.
- The Simplified Name of a
pkgmay be more tricky to determine than that of an App. If apkginstalls an App, then use that App name with the rules above. If not, just create the best name you can, based on the vendor’s web page.
-
Currently, rules for generating a token are not well-defined for Preference Panes, QuickLook plugins, and several other types of software installable by homebrew-cask. Just create the best name you can, based on the filename on disk or the vendor’s web page. Watch out for duplicates.
Non-app tokens should become more standardized in the future.
The token is the primary identifier for a package in our project. It’s the unique string users refer to when operating on the Cask.
To convert the App’s Simplified Name (above) to a token:
- Convert all letters to lower case.
- Expand the
+symbol into a separated English word:-plus-. - Expand the
@symbol into a separated English word:-at-. - Spaces become hyphens.
- Hyphens stay hyphens.
- Digits stay digits.
- Delete any character which is not alphanumeric or a hyphen.
- Collapse a series of multiple hyphens into one hyphen.
- Delete a leading or trailing hyphen.
We avoid defining Cask tokens in the repository which differ only by the placement of hyphens. Prepend the vendor name if needed to disambiguate the token.
Casks are stored in a Ruby file named after the token, with the file extension .rb.
The token is also given in the header line for each Cask.
These illustrate most of the rules for generating a token:
| App Name on Disk | Simplified App Name | Cask Token | Filename |
|---|---|---|---|
Audio Hijack Pro.app |
Audio Hijack Pro | audio-hijack-pro | audio-hijack-pro.rb |
VLC.app |
VLC | vlc | vlc.rb |
BetterTouchTool.app |
BetterTouchTool | bettertouchtool | bettertouchtool.rb |
LPK25 Editor.app |
LPK25 Editor | lpk25-editor | lpk25-editor.rb |
Sublime Text 2.app |
Sublime Text | sublime-text | sublime-text.rb |
When the token for a new Cask would otherwise conflict with the token of an already existing Cask, the nature of that overlap dictates the token (for possibly both Casks). See Finding a Home For Your Cask for information on how to proceed.