feat: added zsh completion

Author: arthur-debert

.markdownlint.json

@@ -0,0 +1 @@
+{ "MD013": false, "MD029": false, "MD014": false }

README.md

@@ -35,10 +35,24 @@ Access deeply **nested values** using intuitive dot-separated paths (e.g., **`pe
 
 Dotcat is a good **unix citizen** with well structured **exit codes** so it can take part of your command pipeline like cat or grep would.
 
+Includes **ZSH autocompletion** for both file paths and dotted paths, making it even easier to navigate complex data structures.
+
 ## Installation
 
 If you have a global pip install, this will install dotcat globally:
 
 ```bash
 pip install dotcat
 ```
+
+## ZSH Completion
+
+Dotcat comes with ZSH completion support. After installing the package, you can set up the completion by:
+
+```bash
+# Copy the completion script to your ZSH completions directory
+mkdir -p ~/.zsh/completions
+cp /path/to/installed/package/zsh/_dotcat ~/.zsh/completions/
+```
+
+See the [ZSH completion README](zsh/README.md) for detailed instructions.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 packages = [{ include = "dotcat", from = "src" }]
-include = ["templates", "template/**", "LICENSE", "README.md"]
+include = ["templates", "template/**", "LICENSE", "README.md", "zsh/**"]
 exclude = ["tests"]
 
 [project]

zsh/README.md

@@ -0,0 +1,185 @@
+# Dotcat ZSH Completion
+
+This directory contains ZSH completion scripts for the `dotcat` command.
+
+These completion files are included when you install the dotcat package.
+
+## Files
+
+- `_dotcat` - ZSH completion script (uses the Python helper)
+- `dotcat-completion.py` - Python helper script for extracting dotted paths
+- `test-completion.zsh` - Script for testing the completion locally
+
+## Quick Installation
+
+1. Copy the completion script to a directory in your $fpath:
+
+```bash
+# Create completion directory if it doesn't exist
+mkdir -p ~/.zsh/completions
+
+# Copy the completion script
+cp zsh/_dotcat ~/.zsh/completions/_dotcat
+
+# Make sure the directory is in your fpath
+echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
+```
+
+2. Install the Python helper script:
+
+```bash
+# Copy to a directory in your PATH
+mkdir -p ~/bin
+cp zsh/dotcat-completion.py ~/bin/
+chmod +x ~/bin/dotcat-completion.py
+
+# Make sure the directory is in your PATH
+echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
+```
+
+3. Reload your ZSH configuration:
+
+```bash
+source ~/.zshrc
+```
+
+## Testing
+
+You can test the completion by typing:
+
+```bash
+# Test file completion
+dotcat [TAB]
+
+# Test dotted path completion
+dotcat path/to/file.json [TAB]
+
+# Test nested path completion
+dotcat path/to/file.json python[TAB]
+```
+
+For local testing without installation, use the test script:
+
+```bash
+./zsh/test-completion.zsh
+```
+
+## Detailed Installation Guide
+
+### Step 1: Choose a directory in your $fpath
+
+First, check your current $fpath directories:
+
+```bash
+echo $fpath
+```
+
+Choose one of the directories from the output (e.g.,
+`/usr/local/share/zsh/site-functions/` or `~/.zsh/completions/`).
+
+If you want to use `~/.zsh/completions/`, make sure it exists:
+
+```bash
+mkdir -p ~/.zsh/completions
+```
+
+And add it to your $fpath in your `~/.zshrc`:
+
+```bash
+fpath=(~/.zsh/completions $fpath)
+```
+
+### Step 2: Install the completion files
+
+Copy the completion script to your chosen directory:
+
+```bash
+cp zsh/_dotcat /path/to/your/chosen/directory/_dotcat
+```
+
+Install the Python helper script to a directory in your PATH:
+
+```bash
+# System-wide installation
+cp zsh/dotcat-completion.py /usr/local/bin/
+chmod +x /usr/local/bin/dotcat-completion.py
+
+# Or to a local bin directory
+mkdir -p $HOME/bin
+cp zsh/dotcat-completion.py $HOME/bin/
+chmod +x $HOME/bin/dotcat-completion.py
+```
+
+Make sure the directory is in your PATH:
+
+```bash
+echo 'export PATH="$HOME/bin:$PATH"' >> $HOME/.zshrc
+```
+
+### Step 3: Reload your ZSH configuration
+
+```bash
+source ~/.zshrc
+```
+
+Or restart your terminal.
+
+## Troubleshooting
+
+If completion doesn't work:
+
+1. Make sure the file is in a directory in your $fpath
+2. Check that the file has the correct permissions:
+
+```bash
+chmod 755 /path/to/_dotcat
+```
+
+3. If using the Python helper, make sure it's in your PATH and executable:
+
+```bash
+which dotcat-completion.py
+chmod +x /path/to/dotcat-completion.py
+```
+
+4. Run `compinit` to rebuild the completion system:
+
+```bash
+autoload -Uz compinit && compinit
+```
+
+5. Check for any error messages when sourcing your `.zshrc`
+
+## Manual Testing
+
+If you want to test the Python helper script directly:
+
+```bash
+# Get top-level paths from a file
+dotcat-completion.py path/to/file.json
+
+# Get nested paths
+dotcat-completion.py path/to/file.json python
+dotcat-completion.py path/to/file.json python.editor
+```
+
+You can also use the included test script to try the completion in a temporary
+environment:
+
+```bash
+# Run the test script
+./zsh/test-completion.zsh
+```
+
+## How It Works
+
+The completion system works in two parts:
+
+1. The ZSH completion script (`_dotcat`) handles the command-line argument
+   completion.
+2. The Python helper script (`dotcat-completion.py`) parses the structured data
+   files and extracts the dotted paths.
+
+When you type `dotcat file.json` and press TAB, the completion script calls the
+Python helper to extract the possible paths from the file and presents them as
+completion options.

zsh/_dotcat

@@ -0,0 +1,91 @@
+#!/usr/bin/env zsh
+# shellcheck disable=SC1071  # ShellCheck only supports sh/bash/dash/ksh scripts, not zsh
+#compdef dotcat
+
+# zsh completion for dotcat command
+# Uses the dotcat-completion.py helper script for dotted path suggestions
+
+_dotcat() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
+
+  _arguments -C \
+    '1:file:_files' \
+    '2:dotted path:_dotcat_dotted_path' \
+    '--output=[Output format]:format:(raw formatted json yaml toml ini)' \
+    '--check-install[Check if required packages are installed]' \
+    '--version[Show version information]' \
+    '--help[Show help message]'
+}
+
+# Function to suggest dotted paths based on file content using the Python helper
+_dotcat_dotted_path() {
+  local file=${words[2]}
+  local current=${words[3]}
+  local prefix="" suggestions=()
+
+  # If we already have part of a dotted path, extract the prefix
+  if [[ "$current" == *.* ]]; then
+    prefix=$(echo "$current" | sed 's/\.[^.]*$//')
+  fi
+
+  # Check if we have a file argument and it exists
+  if [[ -n "$file" && -f "$file" ]]; then
+    # Get the path to the helper script
+    local script_dir=${0:A:h}  # Directory containing this completion script
+    local helper_script="${script_dir}/dotcat-completion.py"
+
+    # If the helper script doesn't exist in the same directory, try to find it
+    if [[ ! -f "$helper_script" ]]; then
+      # Try common locations
+      for dir in "/usr/local/bin" "/usr/bin" "$HOME/.local/bin" "$HOME/bin"; do
+        if [[ -f "${dir}/dotcat-completion.py" ]]; then
+          helper_script="${dir}/dotcat-completion.py"
+          break
+        fi
+      done
+    fi
+
+    # If we found the helper script, use it to get suggestions
+    if [[ -f "$helper_script" ]]; then
+      # Make sure the script is executable
+      [[ -x "$helper_script" ]] || chmod +x "$helper_script"
+
+      # Call the helper script with the file and prefix (if any)
+      if [[ -n "$prefix" ]]; then
+        # Get suggestions for the given prefix
+        while IFS= read -r line; do
+          [[ -n "$line" ]] && suggestions+=("$line")
+        done < <(python3 "$helper_script" "$file" "$prefix" 2>/dev/null)
+      else
+        # Get top-level suggestions
+        while IFS= read -r line; do
+          [[ -n "$line" ]] && suggestions+=("$line")
+        done < <(python3 "$helper_script" "$file" 2>/dev/null)
+      fi
+
+      # If we have suggestions, offer them as completions
+      if (( ${#suggestions} > 0 )); then
+        _describe -t dotted-paths 'dotted path' suggestions
+        return 0
+      fi
+    else
+      # If we couldn't find the helper script, show a message
+      _message "dotted path (helper script not found)"
+      return 1
+    fi
+  fi
+
+  # If we couldn't parse the file or there are no suggestions,
+  # just complete without suggestions
+  _message 'dotted path'
+  return 1
+}
+
+_dotcat "$@"
+
+# Installation instructions:
+# 1. Place this file in a directory in your $fpath (e.g., /usr/local/share/zsh/site-functions/)
+# 2. Rename it to _dotcat
+# 3. Make sure dotcat-completion.py is in your PATH or in the same directory
+# 4. Run `compinit` or restart your shell