Skip to content

Commit

Permalink
Merge pull request #8 from zdharma-continuum/style/format-md-and-zsh
Browse files Browse the repository at this point in the history
style: format markdown and zsh to zinit convention
  • Loading branch information
vladdoster authored Jul 9, 2022
2 parents f278fad + 14d2c9b commit 0866d85
Show file tree
Hide file tree
Showing 3 changed files with 257 additions and 268 deletions.
197 changes: 96 additions & 101 deletions README.md
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: -->
26 changes: 14 additions & 12 deletions z-a-readurl.plugin.zsh
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# -*- mode: sh; sh-indentation: 4; indent-tabs-mode: nil; sh-basic-offset: 4; -*-

# Copyright (c) 2019-2020 Sebastian Gniazdowski
# License MIT
#!/usr/bin/env zsh
# -*- mode: sh; sh-indentation: 2; indent-tabs-mode: nil; sh-basic-offset: 2; -*-
#
# Copyright (c) 2016-2020 Sebastian Gniazdowski and contributors
# Copyright (c) 2021-2022 zdharma-continuum and contributors

# According to the Zsh Plugin Standard:
# https://zdharma-continuum.github.io/Zsh-100-Commits-Club/Zsh-Plugin-Standard.html

0="${${ZERO:-${0:#$ZSH_ARGZERO}}:-${(%):-%N}}"
0="${${(M)0:#/*}:-$PWD/$0}"

Expand All @@ -14,11 +14,13 @@ autoload -Uz za-readurl-preinit-handler
# An empty stub to fill the help handler fields
→za-readurl-help-null-handler() { :; }

@zinit-register-annex "zinit-annex-readurl" \
hook:preinit-10 \
za-readurl-preinit-handler \
→za-readurl-help-null-handler \
"dlink''|.readurl''" # The ice conflict with dl'' from zinit-annex-patch-dl is being handled
# in the other annex
# The ice conflict with dl'' from zinit-annex-patch-dl is being handled in the
# other annex
@zinit-register-annex \
"zinit-annex-readurl" \
hook:preinit-10 \
za-readurl-preinit-handler \
→za-readurl-help-null-handler \
"dlink''|.readurl''"

# vim:ft=zsh:tw=80:sw=4:sts=4:et
# vim:ft=zsh:sw=2:sts=2:et:foldmarker=[[[,]]]:foldmethod=marker
Loading

0 comments on commit 0866d85

Please sign in to comment.