Add docs for livecheck stanza. (#97486)

doc/cask_language_reference/all_stanzas.md

@@ -51,6 +51,7 @@ Each Cask must declare one or more *artifacts* (i.e. something to install).
 | `depends_on`           | yes                           | List of dependencies and requirements for this Cask.<br />See [Depends_on Stanza Details](stanzas/depends_on.md) for more information.
 | `conflicts_with`       | yes                           | List of conflicts with this Cask (*not yet functional*).<br />See [Conflicts_with Stanza Details](stanzas/conflicts_with.md) for more information.
 | `caveats`              | yes                           | String or Ruby block providing the user with Cask-specific information at install time.<br />See [Caveats Stanza Details](stanzas/caveats.md) for more information.
+| `livecheck`            | no                            | Ruby block describing how to find updates for this Cask.<br />See [Livecheck Stanza Details](stanzas/livecheck.md) for more information.
 | `preflight`            | yes                           | Ruby block containing preflight install operations (needed only in very rare cases).
 | `postflight`           | yes                           | Ruby block containing postflight install operations.<br />See [Postflight Stanza Details](stanzas/flight.md) for more information.
 | `uninstall_preflight`  | yes                           | Ruby block containing preflight uninstall operations (needed only in very rare cases).

doc/cask_language_reference/livecheck.md

@@ -0,0 +1,60 @@
+# `livecheck`
+
+The `livecheck` stanza is used to automatically fetch the latest version of a cask from changelogs, release notes, appcasts, etc.
+
+Every `livecheck` block must contain a `url`, which can either be a string or a symbol pointing to other URLs in the cask (`:url` or `:homepage`).
+
+Additionally, a `livecheck` should specify which `strategy` should be used to extract the version:
+
+| `strategy`      | Description |
+|-----------------|-----------|
+| `:header_match` | extract version from HTTP headers (e.g. `Location` or `Content-Disposition`) |
+| `:page_match`   | extract version from page contents                                           |
+| `:sparkle`      | extract version from Sparkle appcast contents                                |
+
+Here is a basic example, extracting a simple version from a page:
+
+```ruby
+livecheck do
+  url "https://example.org/my-app/download"
+  strategy :page_match
+  regex(%r{href=.*?/MyApp-(\d+(?:\.\d+)*)\.zip}i)
+end
+```
+
+If the download URL is present on the homepage, we can use a symbol instead of a string:
+
+```ruby
+livecheck do
+  url :homepage
+  strategy :page_match
+  regex(%r{href=.*?/MyApp-(\d+(?:\.\d+)*)\.zip}i)
+end
+```
+
+
+The `header_match` strategy will try parsing a version from the filename (in the `Content-Disposition` header) and the final URL (in the `Location` header). If that doesn't work, a `regex` can be specified, e.g.:
+
+```ruby
+strategy :header_match
+regex(/MyApp-(\d+(?:\.\d+)*)\.zip/i)
+```
+
+If the version depends on multiple header fields, a block can be specified, e.g.
+
+```ruby
+strategy :header_match do |headers|
+  v = headers["content-disposition"][/MyApp-(\d+(?:\.\d+)*)\.zip/i, 1]
+  id = headers["location"][%r{/(\d+)/download$}i, 1]
+  "#{v},#{id}"
+end
+```
+
+Similarly, the `:page_match` strategy can also be used for more complex versions by specifying a block:
+
+```ruby
+strategy :page_match do |page|
+  match = page.match(%r{href=.*?/(\d+)/MyApp-(\d+(?:\.\d+)*)\.zip}i)
+  "#{match[2]},#{match[1]}"
+end
+```

doc/cask_language_reference/stanzas/appcast.md

@@ -2,6 +2,8 @@
 
 The value of the `appcast` stanza is a string, holding the URL for an appcast which provides information on future updates.
 
+Note: The [`livecheck` stanza](livecheck.md) should be preferred in most cases, as it allows casks to be updated automatically.
+
 The main casks repo only accepts submissions for stable versions of software (and [documented exceptions](https://github.com/Homebrew/homebrew-cask/blob/master/doc/development/adding_a_cask.md#but-there-is-no-stable-version)), but it still gets pull requests for unstable versions. By checking the submitted `version` against the contents of an appcast, we can better detect these invalid cases.
 
 Example: [`atom.rb`](https://github.com/Homebrew/homebrew-cask/blob/645dbb8228ec2f1f217ed1431e188687aac13ca5/Casks/atom.rb#L7)