From c31c29276576fdd4affd9643b90e5c0f9a931431 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Mon, 16 Oct 2023 18:00:32 +0000 Subject: [PATCH] ref(sqlpkg): oppa AJ-style --- sqlpkg/README.md | 187 ++++++++++++++++++++++++++++----------------- sqlpkg/install.ps1 | 6 +- sqlpkg/install.sh | 7 +- 3 files changed, 123 insertions(+), 77 deletions(-) diff --git a/sqlpkg/README.md b/sqlpkg/README.md index 4a951b8..59a94cf 100644 --- a/sqlpkg/README.md +++ b/sqlpkg/README.md @@ -7,118 +7,161 @@ description: | sqlpkg manages SQLite extensions --- -To update or switch versions, run `webi sqlpkg@stable` (or `@v1.1`, `@beta`, +To update or switch versions, run `webi sqlpkg@stable` (or `@v0.2.2`, `@beta`, etc). +### Files + +These are the files / directories that are created and/or modified with this +install: + +```text +~/.local/envman/PATH.env +~/.local/bin/sqlpkg +~/.sqlpkg/ +/.sqlpkg/ +``` + ## Cheat Sheet > `sqlpkg` manages SQLite extensions, just like `pip` does with Python packages > or `brew` does with macOS programs. +View and search sqlite extensions at . + +Install via `sqlpkg install`: + ```sh -$ sqlpkg help -┌────────────────────────────────────────────────┐ -│ sqlpkg is an SQLite package manager. │ -│ Use it to install or update SQLite extensions. │ -│ │ -│ Commands: │ -│ help Display help │ -│ info Display package information │ -│ init Init project scope │ -│ install Install packages │ -│ list List installed packages │ -│ uninstall Uninstall package │ -│ update Update installed packages │ -│ version Display version │ -│ which Display path to extension file │ -└────────────────────────────────────────────────┘ +# sqlpkg install +sqlpkg install nalgeon/stats ``` -### Installing packages - -Install a package from the registry: +Verify with `sqlpkg list` ```sh +sqlpkg +``` + +Which then becomes available at `~/.sqlpkg/nalgeon/stats/` + +| Command | Description | +| --------- | ------------------------------ | +| help | Display help | +| info | Display package information | +| init | Init project scope | +| install | Install packages | +| list | List installed packages | +| uninstall | Uninstall package | +| update | Update installed packages | +| version | Display version | +| which | Display path to extension file | + +### How to initialize a Project + +By default, `sqlpkg` installs extensions to `~/.sqlpkg/`. + +However, `sqlpkg init` will create a `.sqlpkg` in the current project folder. \ +(just like _virtual environment_ or `node_modules`) + +```sh +sqlpkg init +``` + +```text +✓ created a project scope +``` + +### How to Install SQLite Extensions + +You can install extensions in various ways: + +- SQL Pkg Registry ([sqlpkg.org](https://sqlpkg.org)) +- Git / GitHub URI +- Spec File URL +- Local Spec File + +#### Registry + +```sh +# sqlpkg install +sqlpkg info nalgeon/stats sqlpkg install nalgeon/stats +sqlpkg list | grep stats ``` `nalgeon/stats` is the ID of the extension as shown in the registry. -Install a package from a GitHub repository (it should have a package spec file): +#### Git / GitHub ```sh -sqlpkg install github.com/nalgeon/sqlean +sqlpkg info github.com/riyaz-ali/dns.sql +sqlpkg install github.com/riyaz-ali/dns.sql +sqlpkg list | grep dns.sql ``` -Install a package from a spec file somewhere on the Internet: +Git repositories must have a package spec file. + +#### Spec URL ```sh -sqlpkg install https://antonz.org/downloads/stats.json +sqlpkg info https://raw.githubusercontent.com/riyaz-ali/dns.sql/main/sqlpkg.json +sqlpkg install https://raw.githubusercontent.com/riyaz-ali/dns.sql/main/sqlpkg.json +sqlpkg list | grep dns.sql ``` -Install a package from a local spec file: +#### Spec File ```sh -sqlpkg install ./stats.json +sqlpkg info ./sqlpkg.json +sqlpkg install ./sqlpkg.json +sqlpkg list | grep dns.sql ``` -### Other commands +### How to Manage Packages -`sqlpkg` provides other basic commands you would expect from a package manager. +`sqlpkg` provides other basic commands you would expect from a package manager: + +- Info +- Install +- Update (one or all) +- Uninstall + +```sh +sqlpkg +``` + +#### `info` + +```sh +sqlpkg info nalgeon/stats +sqlpkg info github.com/riyaz-ali/dns.sql +sqlpkg info https://raw.githubusercontent.com/riyaz-ali/dns.sql/main/sqlpkg.json +sqlpkg info ./sqlpkg.json +``` + +#### `install` + +```sh +sqlpkg install nalgeon/stats +sqlpkg install github.com/riyaz-ali/dns.sql +sqlpkg install https://raw.githubusercontent.com/riyaz-ali/dns.sql/main/sqlpkg.json +sqlpkg install ./sqlpkg.json +``` #### `update` ```sh sqlpkg update +sqlpkg update nalgeon/stats ``` -Updates all installed packages to the latest versions. +**Note**: `update` without a package name will update _ALL_ extensions + +**Note**: `update` installs the _latest_ version, not necessarily a +semver-compatible version #### `uninstall` ```sh sqlpkg uninstall nalgeon/stats ``` - -Uninstalls a previously installed package. - -#### `list` - -```sh -sqlpkg list -``` - -Lists installed packages. - -#### `info` - -```sh -sqlpkg info nalgeon/stats -``` - -Displays package information. Works with both local and remote packages. - -#### `version` - -```sh -sqlpkg version -``` - -Displays `sqlpkg` version number. - -### Project vs. global scope - -By default, `sqlpkg` installs all extensions in the home folder (global scope). -If you are writing a Python (JavaScript, Go, ...) application — you may prefer -to put them in the project folder (project scope, like virtual environment in -Python or `node_modules` in JavaScript). - -To do that, run the `init` command: - -```sh -sqlpkg init -``` - -It will create an `.sqlpkg` folder in the current directory. After that, all -other commands run from the same directory will use it instead of the home -folder. diff --git a/sqlpkg/install.ps1 b/sqlpkg/install.ps1 index 7685776..153956d 100644 --- a/sqlpkg/install.ps1 +++ b/sqlpkg/install.ps1 @@ -1,8 +1,8 @@ #!/usr/bin/env pwsh -#################### +################## # Install sqlpkg # -#################### +################## # Every package should define these variables $pkg_cmd_name = "sqlpkg" @@ -54,4 +54,4 @@ IF (!(Test-Path -Path "$pkg_src_cmd")) echo "Copying into '$pkg_dst_cmd' from '$pkg_src_cmd'" Remove-Item -Path "$pkg_dst_cmd" -Recurse -ErrorAction Ignore | out-null -Copy-Item -Path "$pkg_src" -Destination "$pkg_dst" -Recurse \ No newline at end of file +Copy-Item -Path "$pkg_src" -Destination "$pkg_dst" -Recurse diff --git a/sqlpkg/install.sh b/sqlpkg/install.sh index 56187e6..4c4718c 100644 --- a/sqlpkg/install.sh +++ b/sqlpkg/install.sh @@ -30,9 +30,12 @@ __init_sqlpkg() { } pkg_get_current_version() { - sqlpkg version 2> /dev/null + # 'sqlpkg version' has output in this format: + # 0.2.2 + # This makes it resistant to future added lines or columns + sqlpkg version 2> /dev/null | head -n 1 | cut -f 1 } } -__init_sqlpkg \ No newline at end of file +__init_sqlpkg