gh-hugoduncan-library-skills-plugins-clojure-libraries/skills/babashka.fs/README.md

Babashka.fs Skill

A comprehensive skill for using the babashka.fs file system utility library in Clojure and Babashka.

Contents

• SKILL.md - Complete documentation and guide for using babashka.fs
• examples.clj - Runnable examples demonstrating key features

What is babashka.fs?

babashka.fs is a cross-platform file system utility library for Clojure that provides:

• Intuitive file and directory operations
• Powerful file searching with glob patterns
• Path manipulation utilities
• File metadata access
• Archive operations (zip/unzip)
• Cross-platform compatibility
• Built-in to Babashka (no dependencies needed)

Quick Start

#!/usr/bin/env bb

(require '[babashka.fs :as fs])

;; Check if a file exists
(fs/exists? "README.md")

;; Find all Clojure files
(fs/glob "." "**/*.clj")

;; Copy a file
(fs/copy "source.txt" "dest.txt")

;; Create directories
(fs/create-dirs "path/to/new/dir")

;; Work with temporary directories
(fs/with-temp-dir [tmp {}]
  (spit (fs/path tmp "test.txt") "data")
  ;; tmp automatically deleted after
  )

Using This Skill

Reading the Documentation

The SKILL.md file contains:

• Complete API reference organized by category
• Detailed examples for each function
• Common patterns and best practices
• Real-world use cases and recipes
• Performance tips and error handling
• Platform-specific considerations

Running the Examples

The examples.clj file is an executable Babashka script:

# Make executable
chmod +x examples.clj

# Run with babashka
bb examples.clj

# Or directly if executable
./examples.clj

The examples demonstrate:

1. Basic file operations
2. Directory listing and filtering
3. Creating directory structures
4. Copy and move operations
5. Path manipulation
6. File metadata
7. Finding executables in PATH
8. Glob pattern matching
9. Recursive directory walking
10. File filtering pipelines
11. XDG base directories
12. Temporary file management

Key Features Covered

File Operations

• Creating, copying, moving, deleting files
• Reading and writing content
• Working with temporary files

Directory Operations

• Listing directory contents
• Creating directory hierarchies
• Recursive tree walking
• Directory streams for efficiency

Searching and Filtering

• Glob patterns for finding files
• Regular expression matching
• Custom filters and predicates
• File metadata queries

Path Manipulation

• Joining path components
• Getting file names, extensions, parents
• Converting between relative and absolute paths
• Cross-platform path handling

Advanced Features

• Archive operations (zip/unzip)
• File permissions (POSIX)
• Timestamps and metadata
• XDG base directories
• Finding executables

Common Use Cases

The skill includes complete recipes for:

• Build tool tasks
• File backup systems
• Log rotation
• File synchronization
• Finding duplicate files
• Cross-platform scripts
• Testing with temporary files

Integration

With Babashka

;; In bb.edn
{:tasks
 {:requires ([babashka.fs :as fs])
  
  clean {:doc "Remove build artifacts"
         :task (fs/delete-tree "target")}
  
  build {:doc "Build project"
         :task (do
                 (fs/create-dirs "target")
                 (println "Building..."))}}}

With Clojure Projects

;; deps.edn
{:deps {babashka/fs {:mvn/version "0.5.27"}}}

;; In your namespace
(ns myproject.core
  (:require [babashka.fs :as fs]))

Why Use This Skill?

• Comprehensive: Covers all major functionality with examples
• Practical: Real-world patterns and recipes included
• Cross-platform: Learn once, works everywhere
• Modern: Uses NIO.2 for good performance
• Battle-tested: babashka.fs is widely used in the Clojure community

Learning Path

1. Start with SKILL.md "Core Concepts" - Understand Path objects and cross-platform support
2. Try the examples - Run examples.clj to see it in action
3. Review "Common Use Cases" - See practical recipes
4. Explore "Advanced Patterns" - Learn best practices
5. Reference as needed - Use Quick Reference for common functions

Additional Resources

• Official GitHub Repository
• API Documentation
• Babashka Book
• cljdoc Documentation

License

This skill documentation is provided as educational material. The babashka.fs library itself is distributed under the EPL License (same as Clojure).

Contributing

This skill is part of the Agent-o-rama skills collection. The examples and documentation are designed to help Claude (and humans!) effectively use the babashka.fs library.

For issues with the library itself, please visit the official repository.