-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #8 from zdharma-continuum/style/format-md-and-zsh
style: format markdown and zsh to zinit convention
- Loading branch information
Showing
3 changed files
with
257 additions
and
268 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,152 +1,147 @@ | ||
# zinit-annex-readurl | ||
# zinit-annex-readurl<a name="zinit-annex-readurl"></a> | ||
|
||
<!-- START doctoc generated TOC please keep comment here to allow auto update --> | ||
<!-- mdformat-toc start --slug=github --maxlevel=6 --minlevel=1 --> | ||
|
||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> | ||
- [zinit-annex-readurl](#zinit-annex-readurl) | ||
- [Skipping `dlink''` Ice](#skipping-dlink-ice) | ||
- [Summary](#summary) | ||
- [Sorting The Matched URLs / Package Versions](#sorting-the-matched-urls--package-versions) | ||
- [Filtering The Matched URLs](#filtering-the-matched-urls) | ||
- [Other Examples](#other-examples) | ||
|
||
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* | ||
<!-- mdformat-toc end --> | ||
|
||
- [Introduction](#introduction) | ||
- [Intermediate Download Page](#intermediate-download-page) | ||
- [Skipping `dlink''` Ice](#skipping-dlink-ice) | ||
- [Summary](#summary) | ||
- [Installation](#installation) | ||
- [Other Examples](#other-examples) | ||
- [Sorting The Matched URLs / Package Versions](#sorting-the-matched-urls--package-versions) | ||
- [Filtering The Matched URLs](#filtering-the-matched-urls) | ||
This Zinit extension allows to automatically download the newest version of a file to which the URL | ||
is hosted on a webpage. | ||
|
||
<!-- END doctoc generated TOC please keep comment here to allow auto update --> | ||
It works as follows: | ||
|
||
## Introduction | ||
- invoke `snippet` (or pass the `http://…` address using the `for` syntax) on the web-page that | ||
hosts the URL to the file to download, | ||
- provide `dlink''` ice with the expected file-download URL, replacing the version with the | ||
`%VERSION%` keyword, | ||
- also, provide `as''` ice with one of the following values: `readurl`, `readurl|command`, | ||
`readurl|completion`, `readurl|null`; the part after the `|` has the same meaning as in the normal | ||
`as''` ice. | ||
|
||
This Zinit extension allows to automatically download the newest version of | ||
a file to which URL is hosted on a webpage. | ||
So, for example: | ||
|
||
It works as follows: | ||
````zsh | ||
zinit for \ | ||
as'readurl|command' \ | ||
dlink'/junegunn/fzf-bin/releases/download/%VERSION%/fzf-%VERSION%-linux_amd64.tgz' | ||
extract \ | ||
id-as'fzf' | ||
https://github.com/junegunn/fzf-bin/releases/ | ||
``` | ||
The snippet is just an example. The same effect is obtained by loading as `junegunn/fzf-bin` plugin | ||
with `from'gh-r'` ice. | ||
|
||
- invoke `snippet` (or simply pass the `http://…` address using the `for` | ||
syntax) on the web-page that hosts the URL to the file to download, | ||
- provide `dlink''` ice with the expected file-download URL replacing the version | ||
with the `%VERSION%` keyword, | ||
- also provide `as''` ice with one of the following values: `readurl`, | ||
`readurl|command`, `readurl|completion`, `readurl|null`; the part after the `|` has | ||
the same meaning as in the normal `as''` ice. | ||
As demonstrated, the `dlink''` can be a relative or an absolute path and also a full URL (i.e.: | ||
beginning with the `http://…` prefix). | ||
|
||
So, for example: | ||
|
||
## Installation<a name="installation"></a> | ||
|
||
Load as a regular plugin via: | ||
|
||
```zsh | ||
zinit id-as=fzf as='readurl|command' extract \ | ||
dlink='/junegunn/fzf-bin/releases/download/%VERSION%/fzf-%VERSION%-linux_amd64.tgz' \ | ||
for https://github.com/junegunn/fzf-bin/releases/ | ||
zinit light zdharma-continuum/z-a-readurl | ||
``` | ||
|
||
The snippet is just an example. The same effect is obtained by loading as | ||
`junegunn/fzf-bin` plugin with `from'gh-r'` ice. | ||
|
||
As it can be seen, the `dlink''` can be a relative or an absolute path and also | ||
a full URL (i.e.: beginning with the `http://…` prefix). | ||
After executing the above command (possibly via `zshrc`), it's then possible to use the `dlink''` and | ||
`dlink0''` ices and the special `as'readurl|…'` value of the `as''` ice. | ||
## Intermediate Download Page | ||
Sometimes, like it is in case of | ||
[terraform](http://releases.hashicorp.com/terraform) command, the final download | ||
link isn't at the download page, but on a page that's listed on it. In such case | ||
use the `dlink0''` ice to provide the pattern for the additional, intermediate | ||
download page. For example, in case of `terraform`, the Zinit command is: | ||
Sometimes, like in the case of the [terraform](http://releases.hashicorp.com/terraform) command, the download link isn't on the download page but on a page listed on it. In such cases utilize | ||
the `dlink0''` ice and provide the pattern for the additional, intermediate download page. For | ||
For example, in the case of `terraform`, the Zinit command is: | ||
|
||
```zsh | ||
zinit id-as=terraform as='readurl|command' extract \ | ||
dlink0='/terraform/%VERSION%/' \ | ||
dlink='/terraform/%VERSION%/terraform_%VERSION%_linux_386.zip' \ | ||
for \ | ||
http://releases.hashicorp.com/terraform/ | ||
``` | ||
zinit for \ | ||
as'readurl|command' \ | ||
dlink0'/terraform/%VERSION%/' \ | ||
dlink'/terraform/%VERSION%/terraform_%VERSION%_linux_386.zip' \ | ||
extract \ | ||
id-as'terraform' \ | ||
http://releases.hashicorp.com/terraform/ | ||
```` | ||
## Skipping `dlink''` Ice | ||
## Skipping `dlink''` Ice<a name="skipping-dlink-ice"></a> | ||
Sometimes the URL of the download page differs from the URL of the archive in | ||
just a few `/`-sections. In such case, it is possible to skip the `dlink''` ice | ||
by appending a `++`-separated fragment of the archive URL, like so: | ||
Sometimes the URL of the download page differs from the URL of the archive in just a few | ||
`/`-sections. In such a case, it is possible to skip the `dlink''` ice by appending a `++`-separated | ||
fragment of the archive URL, like so: | ||
```zsh | ||
zinit as'readurl|command' extract for \ | ||
http://domain.com/download-page++/archive.zip | ||
zinit for \ | ||
as'readurl|command' \ | ||
extract \ | ||
http://domain.com/download-page++/archive.zip | ||
``` | ||
If the archive URL has some different `/`-sections, then it's possible to strip | ||
the conflicting ones from the download URL by using `+++`, `++++`, etc. – the | ||
number of the `/`-section that'll be stripped equals to the number of the `+` | ||
minus | ||
2\. So, for example: | ||
If the archive URL has some different `/`-sections, then it's possible to strip the conflicting ones | ||
from the download URL by using `+++`, `++++`, etc. – the number of the `/`-section that'll be | ||
stripped equals the number of the `+` minus 2. So, for example: | ||
```zsh | ||
zinit as'readurl|command' extract for \ | ||
http://domain.com/download-page/removed-section+++/archive.zip | ||
zinit for \ | ||
as'readurl|command' \ | ||
extract \ | ||
http://domain.com/download-page/removed-section+++/archive.zip | ||
``` | ||
## Summary | ||
## Summary<a name="summary"></a> | ||
The annex provides: | ||
1. Two new ices: `dlink''` and `dlink0''`. | ||
1. A handling of the special values of the `as''` ice, i.e.: of `as'readurl'`, | ||
2. A handling of the special values of the `as''` ice, i.e.: of `as'readurl'`, | ||
`as'readurl|command'`, etc. | ||
The annex works only with snippets, not plugins. | ||
## Installation | ||
|
||
Simply load like a regular plugin, i.e.: | ||
## Sorting The Matched URLs / Package Versions<a name="sorting-the-matched-urls--package-versions"></a> | ||
```zsh | ||
zinit light zdharma-continuum/z-a-readurl | ||
``` | ||
Sometimes the download page doesn't list the package versions from newest to the oldest, but in some | ||
other order. In such case, it's possible to sort the URLs / package versions by prepending the | ||
chosen `dlink` ice (`dlink0''` or `dlink''`) with the exclamation mark (`dlink'!…'`, etc.). See the | ||
next section for an example: | ||
After executing the above command (possibly via `zshrc`) it's then possible to | ||
use the `dlink''` and `dlink0''` ices and also the special `as'readurl|…'` value | ||
of the `as''` ice. | ||
## Filtering The Matched URLs<a name="filtering-the-matched-urls"></a> | ||
## Sorting The Matched URLs / Package Versions | ||
|
||
Sometimes the download page doesn't list the package versions from newest to the | ||
oldest, but in some other order. In such case it's possible to sort the URLs | ||
/ package versions by prepending the chosen `dlink` ice (`dlink0''` or | ||
`dlink''`) with the exclamation mark (`dlink'!…'`, etc.). See the next section | ||
for an example: | ||
|
||
## Filtering The Matched URLs | ||
|
||
Sometimes there are some unwanted URLs that match the `dlink''`/`dlink0''` | ||
regex / pattern. In such case it's possible to filter them out by appending | ||
a filtering regex to the `dlink''` ice as: | ||
`dlink='the-main-regex~%the-unwanted-URLs-regex%'` (or the same for `dlink0''`). | ||
An example package that can benefit from this is the [Open | ||
Shift](https://www.openshift.com/) client, which doesn't sort the URLs from | ||
latest to the oldest – hence the exclamation mark (`!`) prepend – and it has | ||
special URLs like `stable-4.4` or `candidate-4.5` together with the regular | ||
version URLs (like `4.5.0-rc.1`): | ||
Sometimes some unwanted URLs match the `dlink''`/`dlink0''` regex/pattern. In such case it's | ||
possible to filter them out by appending a filtering regex to the `dlink''` ice as: | ||
`dlink='the-main-regex~%the-unwanted-URLs-regex%'` (or the same for `dlink0''`). An example package | ||
that can benefit from this is the [Open Shift](https://www.openshift.com/) client, which doesn't | ||
sort the URLs from latest to the oldest – hence the exclamation mark (`!`) prepend – and it has | ||
special URLs like `stable-4.4` or `candidate-4.5` together with the regular version URLs (like | ||
`4.5.0-rc.1`): | ||
```zsh | ||
zinit id-as"ocp" as"readurl|command" \ | ||
zinit for \ | ||
as'readurl|command' \ | ||
dlink'openshift-client-windows-%VERSION%.zip' \ | ||
dlink0'!%VERSION%~%(stable|latest|fast|candidate).*%' \ | ||
dlink"openshift-client-windows-%VERSION%.zip" for \ | ||
https://mirror.openshift.com/pub/openshift-v4/clients/ocp/ | ||
id-as'ocp' \ | ||
https://mirror.openshift.com/pub/openshift-v4/clients/ocp/ | ||
``` | ||
The above snippet of Zsh code / Zinit invocation will sort the URLs | ||
(`dlink0'!…'`) and then filter out the special ones from the results (via | ||
`…~%(stable|latest|fast|candidate).*%`), this way selecting the latest version | ||
of the Open Shift client. | ||
The above snippet of Zsh code / Zinit invocation will sort the URLs (`dlink0'!…'`) and then filter | ||
out the special ones from the results (via `…~%(stable|latest|fast|candidate).*%`), this way | ||
selecting the latest version of the Open Shift client. | ||
## Other Examples | ||
## Other Examples<a name="other-examples"></a> | ||
[**Pulumi**](https://www.pulumi.com/), a tool to create, deploy, and manage modern cloud software. | ||
```zsh | ||
zi id-as'pulumi' as'readurl|null' extract'!' \ | ||
dlink='https://get.pulumi.com/releases/sdk/pulumi-%VERSION%-linux-x64.tar.gz' \ | ||
sbin'pulumi*' for \ | ||
https://www.pulumi.com/docs/get-started/install/versions/ | ||
zi for \ | ||
as'readurl|null' \ | ||
dlink'https://get.pulumi.com/releases/sdk/pulumi-%VERSION%-linux-x64.tar.gz' \ | ||
extract'!' \ | ||
id-as'pulumi' \ | ||
sbin'pulumi*' \ | ||
https://www.pulumi.com/docs/get-started/install/versions/ | ||
``` | ||
|
||
<!-- vim:set ft=markdown tw=80 fo+=a1n autoindent: --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.