readme: add api usage example

.github/workflows/deno.yml

@@ -0,0 +1,41 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# This workflow will install Deno then run `deno lint` and `deno test`.
+# For more information see: https://github.com/denoland/setup-deno
+
+name: Deno
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Setup repo
+        uses: actions/checkout@v3
+
+      - name: Setup Deno
+        # uses: denoland/setup-deno@v1
+        uses: denoland/setup-deno@9db7f66e8e16b5699a514448ce994936c63f0d54
+        with:
+          deno-version: v1.x
+          
+      - name: Verify formatting
+        run: deno fmt --check
+
+      - name: Run linter
+        run: deno lint
+
+      - name: Run tests
+        run: deno test -A

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Anton Nesterov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mod.ts

@@ -69,14 +69,14 @@ function asReadable$(entry: ConfigEntry): ReadableEntry {
         break;
       }
       case "github": {
-        const [repo, version] = entry.source.split("@");
+        const [repo, ...version] = entry.source.split("@");
         if (!version) {
           throw new Error(
-            `Invalid source format: ${entry.source} 
+            `Invalid source format: ${entry.source}
             Expected: <repo>@<version>`,
           );
         }
-        read = () => githubPick({ repo, version, pick });
+        read = () => githubPick({ repo, version: version.join("@"), pick });
         break;
       }
       default: {

pickit.ts

@@ -8,6 +8,8 @@ import { cleanFetchCache, write } from "./mod.ts";
 if (Deno.args.length == 1) {
   if (Deno.args[0] == "clean") {
     await cleanFetchCache();
+  } else if (Deno.args[0] == "help") {
+    printHelp();
   } else {
     const config = await import(Deno.args[0]);
     await write(config.default);
@@ -16,16 +18,28 @@ if (Deno.args.length == 1) {
   const [source, output, ...pick] = Deno.args;
   await write([{ source, output, pick }]);
 } else {
+  printHelp();
+}
+
+function printHelp() {
   console.log(
     `
   %cPickIt
   `,
     "font-size: 1.5em; font-weight: bold",
   );
-  console.log(`
+  console.log(
+    `
         This utility helps you to extract files from tarballs and github repos using glob syntax or regular expressions.
         You can use either a config file or command line arguments.
-    `);
+
+          pickit %cclean - cleans the cache of fetched files.
+          %cpickit %chelp - prints this help message.
+    `,
+    "color: #ccb;",
+    "",
+    "color: #ccb;",
+  );
   console.log(
     `
   %cUsage:
@@ -74,7 +88,7 @@ if (Deno.args.length == 1) {
             },
         ] as PickConfig;
 
-        
+
     `,
     "color: #aab;",
   );

readme.md

@@ -1,3 +1,117 @@
-# Pick [WIP]
+# Pickit
 
-Pick files from remote sources
+This utility helps you to extract files from tarballs and github repos using
+glob syntax or regular expressions. You can use either a config file or command
+line arguments.
+
+## Examples
+
+> Pick files from a github repo to directory `scripts`:
+
+```bash
+pickit nesterow/pickit@v0.0.1a scripts **/tests/*.ts
+```
+
+> Pick files from a tarball to directory `logs`:
+
+```bash
+pickit server_logs.tar.gz logs **/error.log
+```
+
+## Installation
+
+```bash
+deno install -A https://deno.land/x/pickit/pickit.ts
+```
+
+## Using without installation
+
+```bash
+deno run -A https://deno.land/x/pickit/pickit.ts [args]...
+```
+
+## Using config file
+
+If you need to pick files from multiple sources, you can use a config file. The
+config file should export an array of `PickConfig` objects.
+
+```typescript
+import type { PickConfig } from "https://deno.land/x/pickit/mod.d.ts";
+export default [
+    {
+        source: "username/repo@version",
+        output: "./outputDir",
+        pick: [
+            /^.*/base/.*.css$/, // can be a regular expression
+            "/src/index.js",
+            "/src/**/*.yaml"
+        ],
+    },
+] as PickConfig;
+```
+
+See the complete example
+[here](https://github.com/nesterow/pickit/blob/main/tests/config_mock.ts).
+
+> Usage:
+
+```bash
+pickit ./config.ts
+```
+
+## API
+
+Most methods are exported from `mod.ts` and can be used within your code. Read
+the [API documentation](https://deno.land/x/pickit/mod.ts)
+
+> All functions are using RegExp to match files. So you need to convert globs
+> explicitly. Example:
+
+```typescript
+import { githubPick } from "https://deno.land/x/pickit@v0.0.3/mod.ts";
+import { globToRegExp, join } from "$std/path/mod.ts";
+import { readAll } from "$std/streams/conversion.ts";
+
+for await (
+  const cssFile of githubPick({
+    repo: "saadeghi/daisyui",
+    version: "v2.47.0",
+    pick: [
+      globToRegExp("**/src/components/**/*.css"),
+    ],
+  })
+) {
+  const css = new TextDecoder("utf-8").decode(await readAll(cssFile));
+  // do something with css
+}
+```
+
+## License
+
+```text
+MIT License
+
+Copyright (c) 2023 Pick it contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## Contributors
+
+[@nesterow](https://github.com/nesterow)

tests/mod_test.ts

@@ -74,7 +74,7 @@ test("mod", async (t) => {
   });
 });
 
-test("pickit: cmd line interface", async () => {
+test("cmd line interface", async () => {
   const p = await Deno.run({
     cmd: [
       "deno",
@@ -90,4 +90,5 @@ test("pickit: cmd line interface", async () => {
   const status = await p.status();
   assert(status.success);
   await Deno.remove("daisyui", { recursive: true });
+  await p.close();
 });