Skip to content

Latest commit

 

History

History
109 lines (83 loc) · 5.33 KB

CASK_NAMING_REFERENCE.md

File metadata and controls

109 lines (83 loc) · 5.33 KB
Raw

Cask Naming Reference

This document describes the algorithm implemented in the cask_namer script, and covers detailed rules and exceptions which are not needed in most cases.

Find the Canonical Name of the Developer's Distribution

Canonical Names of Apps

  • Start with the exact name of the Application bundle as it appears on disk, such as Google Chrome.app
  • Translate the name into English if necessary
  • Remove .app from the end
  • Remove the term "app" from the end, if the developer styles the name like "Software App.app". Exception: if the term "app" describes functionality, 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: 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: "mac", "for mac", "for OS X". These terms are generally added to ports such as "MAME OS X.app". Exception: when the software is not a port, but "Mac" is an inseparable part of the name or branding, as in 'PlayForMac.app'
  • Remove from the end: hardware designations such as "for x86", "32-bit", "ppc".
  • Remove from the end: software framework names such as "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"
  • Pay attention to details, for example: "Git Hub" != "git_hub" != "GitHub"
  • If the result of that process is something unhelpful, such as Macintosh Installer, then just create the best name you can, based on the developer'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 separator. 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.

Canonical Names of pkg-based Installers

  • The Canonical Name of a pkg may be more tricky to determine than that of an App. If a pkg installs an App, then use that App name with the rules above. If not, just create the best name you can, based on the developer's web page.

Canonical Names of non-App Software

  • Currently, naming rules are not well-defined for Preference Panes, QuickLook plugins, and other types of software installable by homebrew-cask. Just create the best name you can, based on the filename on disk or the developer's web page. Watch out for duplicates.

Cask Name

The "Cask name" is the primary identifier for a package in our project. It's the string people will use to interact with the Cask on their system.

To get from the App's canonical name to the Cask name:

  • convert all letters to lower case
  • expand the + symbol into a separated English word: -plus-
  • hyphens stay hyphens
  • spaces become hyphens
  • digits stay digits
  • delete any character which is not alphanumeric or hyphen
  • collapse a series of multiple hyphens into one hyphen
  • delete a leading hyphen
  • a leading digit gets spelled out into English: 1password becomes onepassword

Casks are stored in a Ruby file matching their name. If possible, avoid creating Cask files which differ only by the placement of hyphens.

Cask Class

Casks are implemented as Ruby classes, so a Cask's "class" needs to be a valid Ruby class name.

When converting a Cask name to its corresponding class name:

  • convert to UpperCamelCase
  • wherever a hyphen occurs in the Cask name, remove the hyphen and create a case change in the class name

Cask Naming Examples

These illustrate most of the naming rules:

App Name on Disk Canonical App Name Cask Name Cask File Cask Class
Audio Hijack Pro.app Audio Hijack Pro audio-hijack-pro audio-hijack-pro.rb AudioHijackPro
VLC.app VLC vlc vlc.rb Vlc
BetterTouchTool.app BetterTouchTool bettertouchtool bettertouchtool.rb Bettertouchtool
LPK25 Editor.app LPK25 Editor lpk25-editor lpk25-editor.rb Lpk25Editor
Sublime Text 2.app Sublime Text sublime-text sublime-text.rb SublimeText
1Password.app 1Password onepassword onepassword.rb Onepassword

<3 THANK YOU TO ALL CONTRIBUTORS! <3