Hawk

https://github.com/wkf/hawk
Admin
Hawk is a Clojure library that provides a file and directory watcher, wrapping the JDK 7...
Tokens:34,617
Snippets:467
Trust Score:8.2
Update:3 months ago
Show doc for...
Tokens:
Raw
### Configuration Example

Source: https://github.com/wkf/hawk/blob/master/_autodocs/README.md

An example demonstrating how to configure the watcher, such as using polling for virtual environments.

```clojure
;; Use polling for virtual environments
(hawk/watch! {:watcher :polling :sensitivity :medium}
             [{:paths ["data"]
               :handler (fn [ctx e] ctx)}])
```

--------------------------------

### Basic Stop Example

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/stop-api.md

Demonstrates how to start a watch using `hawk/watch!` and then stop it using `hawk/stop!` after a delay. This is a common pattern for simple watch management.

```clojure
(require '[hawk.core :as hawk])

(let [watch (hawk/watch! [{:paths ["src"]
                           :handler (fn [ctx event] 
                                      (println event)
                                      ctx)}])] 
  (Thread/sleep 5000)
  (hawk/stop! watch))
```

--------------------------------

### watch! - Create and start file system watchers

Source: https://github.com/wkf/hawk/blob/master/_autodocs/README.md

The `watch!` function is used to create and start file system watchers. It accepts options for configuration and a list of watch specifications.

```APIDOC
## watch!(opts & groups)

### Description
Create and start file system watchers.

### Parameters
- **opts** (map) - Optional configuration options for the watcher.
- **groups** (list of maps) - A list of watch specifications, each containing paths, handlers, and filters.
```

--------------------------------

### Watch Specification Map Example

Source: https://github.com/wkf/hawk/blob/master/_autodocs/types.md

An example of a watch specification map used to monitor specific directories, apply a file type filter, initialize context, and update a counter based on event kind.

```clojure
{:paths ["src/main" "src/test"]
 :filter hawk/file?
 :context (constantly {})
 :handler (fn [ctx event] 
            (update ctx (:kind event) inc))}
```

--------------------------------

### Basic Watcher Setup

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watch-api.md

Sets up a watcher to monitor a specific file for changes and logs events. Requires the :paths and :handler keys in the watch specification.

```clojure
(watch! {:watcher :java}
  [(watch-file "/tmp/file.txt")
   {:handler (fn [ctx evt] (println evt))}
   {:filter (fn [ctx evt] (not= (:change evt) :delete))}
   {:context (fn [ctx] (assoc ctx :start-time (System/currentTimeMillis)))})]
```

--------------------------------

### PollingWatchKey Constructor Example

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/abstract-watch-key.md

Example of a subclass constructor (PollingWatchKey) that extends AbstractWatchKey, demonstrating how the superclass constructor is called.

```java
PollingWatchKey(Path dir, PollingWatchService watcher, Object fileKey)
    throws IOException {
    super(dir, watcher);
    this.fileKey = fileKey;
    // ... initialization
}
```

--------------------------------

### Simple File System Watch

Source: https://github.com/wkf/hawk/blob/master/_autodocs/README.md

Creates and starts a file system watcher for the 'src' directory. Events are printed to the console. The handler returns the context.

```clojure
(require '[hawk.core :as hawk])

(hawk/watch! [{:paths ["src"]
               :handler (fn [ctx event]
                          (println "Event:" event)
                          ctx)}])
```

--------------------------------

### Start a Simple File Watch

Source: https://github.com/wkf/hawk/blob/master/hawk_www/resources/public/index.html

Initiate a basic file watch on specified paths. The handler function processes events and manages context.

```clojure
(hawk/watch! [{:paths ["src/main/hawk"]
                   :handler (fn [ctx e]
                              (println "event: " e)
                              (println "context: " ctx)
                              ctx)}])
```

--------------------------------

### Watching a non-existent path in Hawk

Source: https://github.com/wkf/hawk/blob/master/_autodocs/errors.md

This example shows how calling `hawk/watch!` with a path that does not exist will trigger a FileSystemException during path canonicalization.

```clojure
(hawk/watch! [{:paths ["/non/existent/path"]
               :handler (fn [ctx e] ctx)}])
; Throws during path canonicalization
```

--------------------------------

### Watch Options Map Usage Example

Source: https://github.com/wkf/hawk/blob/master/_autodocs/types.md

Demonstrates how to use the watch options map to configure a low-sensitivity polling watcher when initiating a Hawk watch with multiple specifications.

```clojure
(hawk/watch! {:watcher :polling :sensitivity :low} [spec1 spec2])
```

--------------------------------

### Filtered Watch Example

Source: https://github.com/wkf/hawk/blob/master/_autodocs/README.md

An example showing how to use a filter to only process file events.

```clojure
(hawk/watch! [{:paths ["src"]
               :filter hawk/file?
               :handler (fn [ctx event]
                          (println "File:" (:file event))
                          ctx)}])
```

--------------------------------

### Recursive Directory Registration in Clojure

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Provides an example of recursively registering directories in Clojure, enabling the system to catch subdirectory creation events automatically.

```clojure
(doseq [^java.io.File dir (-> path .toFile .listFiles)]
  (when (.isDirectory dir)
    (register! this (.toPath dir) events)))
```

--------------------------------

### Start a Simple File Watch

Source: https://github.com/wkf/hawk/blob/master/README.md

Initiates a watch on specified paths. The handler function processes events and updates the context. The event structure includes the event kind and the affected file.

```clojure
(hawk/watch! [{:paths ["src/main/hawk"]
                   :handler (fn [ctx e] 
                              (println "event: " e)
                              (println "context: " ctx)
                              ctx)}])
```

--------------------------------

### Event Deduplication Example

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Illustrates event deduplication at the WatchKey level, where multiple MODIFY events are consolidated into a single event with a count.

```java
// Multiple MODIFY events → single event with count=N
```

--------------------------------

### Example IOException Scenario

Source: https://github.com/wkf/hawk/blob/master/_autodocs/errors.md

Illustrates a scenario where an IOException might be thrown, such as during a close operation or if a directory becomes inaccessible. Recovery involves graceful handling or retrying access.

```java
// Example of a potential IOException trigger (conceptual)
// This code is illustrative and not directly executable without context.
// For instance, an error during implClose() or file attribute reads.
// Recovery: Graceful close, retry directory access, or propagate.
```

--------------------------------

### Verify Paths Before Watching

Source: https://github.com/wkf/hawk/blob/master/_autodocs/errors.md

A function to safely initiate a Hawk watch by first verifying that all specified paths exist. If any path does not exist, the watch is not started.

```clojure
(defn safe-watch [paths handler]
  (when (every? #(.exists (clojure.java.io/file %)) paths)
    (hawk/watch! [{:paths paths
                   :handler handler}])))
```

--------------------------------

### Deduplication Examples for signalEvent

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/abstract-watch-key.md

Illustrates how the signalEvent method handles event deduplication and overflow scenarios.

```plaintext
Incoming:  CREATE(a), CREATE(a), CREATE(a)
Result:    [ Event(CREATE, a, count=3) ]
```

```plaintext
Incoming:  MODIFY(b), MODIFY(b)
Result:    [ Event(MODIFY, b, count=2) ]
```

```plaintext
Incoming:  CREATE(c), MODIFY(c), MODIFY(c)
Result:    [ Event(CREATE, c, count=1), Event(MODIFY, c, count=2) ]
```

```plaintext
Incoming:  (512 events accumulated), CREATE(new)
Result:    [ Event(OVERFLOW, null, count=1) ]  <- all previous events discarded
```

--------------------------------

### Start a Filtered File Watch

Source: https://github.com/wkf/hawk/blob/master/README.md

Starts a watch that only processes events matching a specific filter. Hawk provides built-in filters like `hawk/file?`, or you can define your own predicate functions.

```clojure
(hawk/watch! [{:paths ["src/main/hawk"]
                   :filter hawk/file?
                   :handler (fn [_ _] 
                              (println "look ma, just files!"))}])
```

--------------------------------

### Get JVM System Property

Source: https://github.com/wkf/hawk/blob/master/_autodocs/configuration.md

Access the JVM system property 'os.name' to determine the platform. This is used by Hawk to select the appropriate watcher.

```clojure
(println (System/getProperty "os.name"))
; Output: "Linux"
```

--------------------------------

### Start a Stateful File Watch

Source: https://github.com/wkf/hawk/blob/master/README.md

Enables stateful watching by initializing context with `:context` and updating it within the `:handler`. The handler function receives the current context and returns the updated context.

```clojure
(hawk/watch! [{:paths ["src/main/hawk"]
                   :context (constantly 1)
                   :handler (fn [ctx _] (inc ctx))}])
```

--------------------------------

### Start a Polling Watch

Source: https://github.com/wkf/hawk/blob/master/hawk_www/resources/public/index.html

Utilize the polling watcher as a fallback when native event monitoring is unavailable. Sensitivity can be adjusted from :high to :low.

```clojure
(hawk/watch! {:watcher :polling}
                 [{:paths ["src/main/hawk"]
                   :handler (fn [ctx e]
                              (println "event: " e)
                              (println "context: " ctx)
                              ctx)}])
```

--------------------------------

### Start a Polling Watch

Source: https://github.com/wkf/hawk/blob/master/README.md

Utilizes a polling watcher as a fallback when native OS events are unreliable, such as in virtual environments. The `:sensitivity` option controls the polling frequency.

```clojure
(hawk/watch! {:watcher :polling} 
                 [{:paths ["src/main/hawk"]
                   :handler (fn [ctx e] 
                              (println "event: " e)
                              (println "context: " ctx)
                              ctx)}])
```

--------------------------------

### Configure Hawk with Minimal Options

Source: https://github.com/wkf/hawk/blob/master/_autodocs/configuration.md

Demonstrates the basic usage of `hawk/watch!` with only the required path and a simple handler. This will apply default options for watcher type, sensitivity, and context.

```clojure
(hawk/watch! [{:paths ["src"]
               :handler (fn [ctx e] ctx)}])
```

--------------------------------

### Multiple Watch Groups

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watch-api.md

Demonstrates setting up multiple watch groups, each with its own paths, handler, and filter. The first group watches a directory, and the second watches a specific file.

```clojure
(watch! {:sensitivity :medium}
  [(watch-dir "/tmp/dir")
   {:handler (fn [ctx evt] (println "Dir event:" evt))}]

  [(watch-file "/tmp/file.txt")
   {:handler (fn [ctx evt] (println "File event:" evt))}
   {:filter (fn [ctx evt] (= (:change evt) :create))}
   {:context (fn [ctx] (assoc ctx :file-count 0))})]
```

--------------------------------

### Simple Hawk Watch

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watch-api.md

Sets up a basic file watch on the 'src' directory. The handler prints the event kind and file.

```clojure
(require '[hawk.core :as hawk])

(hawk/watch! [{:paths ["src"]
               :handler (fn [ctx event] 
                          (println "File event:" (:kind event) (:file event))
                          ctx)}])
```

--------------------------------

### Watch Configuration with Context Initialization

Source: https://github.com/wkf/hawk/blob/master/_autodocs/configuration.md

Sets up a watch with a custom context initialization function. The context is initialized to 0 and incremented on each event.

```clojure
{:paths ["src"]
 :context (constantly 0)
 :handler (fn [ctx event] 
            (inc ctx))}
```

--------------------------------

### Get Watched Path

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/abstract-watch-key.md

Retrieves the Path that was registered with the WatchService. This is the original directory passed to the constructor.

```java
public Path watchable()

```

```java
Path watched = key.watchable();

```

--------------------------------

### Basic Watch Configuration with Paths

Source: https://github.com/wkf/hawk/blob/master/_autodocs/configuration.md

A minimal watch configuration specifying the paths to monitor. The handler function is a placeholder.

```clojure
{:paths ["src"] :handler (fn [ctx e] ctx)}
```

--------------------------------

### Polling Wait Interrupted (Java)

Source: https://github.com/wkf/hawk/blob/master/_autodocs/errors.md

Example of catching an InterruptedException when a polling wait on a WatchService is interrupted. This is a common scenario during thread interruption.

```java
try {
    WatchKey key = watchService.poll(5, TimeUnit.SECONDS);
} catch (InterruptedException e) {
    // Thread interrupted during wait
}
```

--------------------------------

### Hawk Watch Initialization Data Flow

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Illustrates the sequence of operations when the hawk/watch! function is called, from parsing options to returning the watcher service and thread.

```text
hawk/watch! called with specs
    │
    ├─► Parse options (watcher type, sensitivity)
    │
    ├─► Extract and canonicalize paths
    │
    ├─► Create watcher instance (new-watcher dispatch)
    │
    ├─► Register all paths with underlying WatchService
    │
    ├─► Create thread for event processing loop
    │
    └─► Return {:thread watcher-thread :watcher service}
```

--------------------------------

### Example of Handler Error

Source: https://github.com/wkf/hawk/blob/master/_autodocs/errors.md

Demonstrates an error occurring within a Hawk watch handler. The exception is caught and printed, and the watch continues processing.

```clojure
(hawk/watch! [{:paths ["src"]
               :handler (fn [ctx e]
                          (throw (Exception. "Handler error"))
                          ctx)}])

```

--------------------------------

### Simple File Watcher

Source: https://github.com/wkf/hawk/blob/master/_autodocs/INDEX.md

Watch files in a specified directory and print event details. Requires importing the hawk.core namespace.

```clojure
(require '[hawk.core :as hawk])

(hawk/watch! [{:paths ["src"]
               :handler (fn [ctx event] 
                          (println "Event:" (:kind event) (:file event))
                          ctx)}])
```

--------------------------------

### Watch Configuration with Event Handler

Source: https://github.com/wkf/hawk/blob/master/_autodocs/configuration.md

Configures a watch to execute a handler function for each file system event. The handler logs the event and returns the context.

```clojure
{:paths ["src"]
 :handler (fn [ctx event] 
            (println "Event: " event)
            ctx)}
```

--------------------------------

### take! Method

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watcher-protocol.md

Blocks until a file system event is available and returns all pending events for the signaled key. It handles interruptions and closed watch services, returning a sequence of event maps or nil if interrupted.

```APIDOC
## take! 

### Description
Blocks until a file system event is available and returns all pending events for the signaled key.

### Method
(take! [watcher])

### Parameters
#### Path Parameters
- **watcher** (Watcher implementation) - Required - The watch service instance

### Return Type
Sequence of event maps, or nil if interrupted

### Event Map Structure
```clojure
{:kind keyword    ; :create, :modify, or :delete
 :file File}      ; java.io.File, canonicalized
```

### Behavior
- Blocks indefinitely until an event occurs or the thread is interrupted
- Returns immediately with pending events once a WatchKey is signaled
- Resets the WatchKey after retrieving events
- Catches `InterruptedException` and returns `nil`
- Handles `ClosedWatchServiceException` for closed watch services
- May synthesize additional events (e.g., for files created before parent directory event is processed)

### Threading
- Safe to call from multiple threads
- Typically called by a single event processing thread in a loop
```

--------------------------------

### Path Processing Steps

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Illustrates the sequence of operations applied to user-provided paths to canonicalize and prepare them for event watching. This includes resolving symlinks, separating files from directories, and removing redundant entries.

```text
User paths (":paths ["src" "file.txt"]")
    │
    ├─► Canonicalize (absolute, resolve symlinks)
    ├─► Separate into files and directories
    ├─► Convert files to parent directories
    ├─► Remove duplicates
    └─► Remove child paths (only register parents)
```

--------------------------------

### Get Sensitivity Value in Seconds

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/sensitivity-watch-event-modifier.md

Retrieves the polling interval in milliseconds for a given sensitivity level. HIGH returns 500ms, MEDIUM 5000ms, and LOW 30000ms.

```java
public int sensitivityValueInSeconds()
```

```java
SensitivityWatchEventModifier mod = SensitivityWatchEventModifier.HIGH;
int intervalMs = mod.sensitivityValueInSeconds(); // returns 500
```

--------------------------------

### Create Watcher Instance

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watcher-protocol.md

Use the `new-watcher` function to create a watcher instance. Options can specify the implementation (e.g., `:polling`) or let the system auto-select based on the OS.

```clojure
(new-watcher {:watcher :polling :sensitivity :medium})
```

--------------------------------

### Hawk Key Lifecycle States

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Illustrates the state transitions for a watch key, showing the flow from READY to SIGNALLED and back, including the reset operation.

```clojure
READY ──► (events signaled) ──► SIGNALLED ──► (pollEvents called) ──► READY
                                    ▲                                    │
                                    │                                    │
                                    └────────── reset() ─────────────────┘
                                                (if more events pending)
```

--------------------------------

### Default Watcher Usage

Source: https://github.com/wkf/hawk/blob/master/_autodocs/configuration.md

When no watcher is explicitly specified, Hawk defaults to the optimal implementation for the current platform. This example shows how to invoke watch! without specifying a watcher.

```clojure
(hawk/watch! [{:paths ["src"] :handler (fn [ctx e] ctx)}])
```

--------------------------------

### Custom Context Initialization

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watch-api.md

Illustrates using a custom context initialization function to set an initial state for the watcher. The context is updated by the handler.

```clojure
(watch! (watch-file "/tmp/data.csv")
  {:handler (fn [ctx evt] (println (:data ctx)))
   :context (fn [ctx] (assoc ctx :data "initial data"))})
```

--------------------------------

### Hawk Directory Recursion Data Flow

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Outlines the process when a new directory is detected, including registration, walking the tree, and emitting synthetic create events.

```text
Directory creation detected
    │
    ├─► Register new directory with watcher
    │
    ├─► Walk directory tree to find existing files
    │
    └─► Emit synthetic :create events for all files
        (prevents missing events for files created before
         directory creation event processed)
```

--------------------------------

### Graceful Degradation with Watcher Fallback

Source: https://github.com/wkf/hawk/blob/master/_autodocs/errors.md

This pattern demonstrates graceful degradation by attempting to start a preferred watcher type (e.g., :java) and falling back to another type (e.g., :polling) if the first one fails.

```clojure
(let [watcher (or (try
                    (hawk/watch! {:watcher :java} spec)
                    (catch Exception _))
                  (hawk/watch! {:watcher :polling} spec))] 
  watcher)

```

--------------------------------

### Hawk Context State Initialization and Handling

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Defines how to initialize the context state and how the handler function updates the context based on events. State flows sequentially through agents for thread-safe updates.

```clojure
;; Initialization
(context-fn)  ;; Returns initial context

;; Per-event
(handler context event)  ;; Returns updated context
```

```clojure
Event 1 → handler → agent receives update (ctx1)
Event 2 → handler → agent receives update (ctx2)
Event 3 → handler → agent receives update (ctx3)
```

--------------------------------

### Hawk Project Directory Structure

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Illustrates the organization of source files, tests, and build configuration within the Hawk project.

```text
hawk/
├── src/main/clojure/hawk/
│   ├── core.clj          # Main public API
│   └── watcher.clj       # Internal watcher protocol and factory
├── src/main/java/hawk/
│   ├── AbstractWatchService.java      # Base WatchService implementation
│   ├── AbstractWatchKey.java          # Base WatchKey implementation
│   ├── PollingWatchService.java       # Polling-based WatchService
│   └── SensitivityWatchEventModifier.java  # Polling sensitivity enum
├── src/test/clojure/hawk/
│   ├── core_test.clj     # Integration tests
│   └── test_helper.clj   # Test utilities
├── README.md             # Usage documentation
└── project.clj           # Build configuration
```

--------------------------------

### Define Main Clojure Source Path

Source: https://github.com/wkf/hawk/blob/master/_autodocs/configuration.md

Specify the directory for main Clojure source files in project.clj. These are the entry points for watch operations.

```clojure
:source-paths ["src/main/clojure"]
```

--------------------------------

### register! Method

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watcher-protocol.md

Registers a file system path with the watcher for notification of specified events. It supports recursive registration for directories and automatically resolves platform-specific event kinds.

```APIDOC
## register! 

### Description
Registers a file system path with the watcher for notification of specified events.

### Method
(register! [watcher path events])

### Parameters
#### Path Parameters
- **watcher** (Watcher implementation) - Required - The watch service instance
- **path** (java.nio.file.Path) - Required - Path to register (directory or file parent)
- **events** (vector) - Required - Event kinds to watch: `[:create :modify :delete]` or subset

### Behavior
- For directories, performs recursive registration of all subdirectories
- Automatically resolves internal event kind names (`:create`, `:modify`, `:delete`) to platform-specific WatchEvent.Kind constants
- Returns the WatchKey for the registered path (implementation-dependent)

### Exceptions
- `java.nio.file.ClosedWatchServiceException` — if watcher is closed
- `java.io.IOException` — if path cannot be accessed or is invalid
```

--------------------------------

### Stateful Hawk Watch with Context

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watch-api.md

Demonstrates a watch with a stateful context. The context is initialized to 0 and incremented with each event.

```clojure
(hawk/watch! [{:paths ["src"]
               :context (constantly 0)
               :handler (fn [ctx event] 
                          (inc ctx))}])
```

--------------------------------

### Watch Lifecycle Stages

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Illustrates the stages of the watch lifecycle: creation, registration, processing, and shutdown. Each stage details the key operations involved.

```text
Creation:
    new-watcher()
        └─► WatchService instance created

Registration:
    register! for each path
        └─► WatchKey created

Processing:
    take! loops fetching events

Shutdown:
    stop!
        ├─► Thread.interrupt()
        ├─► Thread.join() (blocks until thread exits)
        └─► watcher.close()
            └─► All resources released
```

--------------------------------

### Watch for Created Events

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/filter-functions.md

Sets up a watch to process only file creation events. The handler is invoked when a new file or directory is created.

```clojure
(hawk/watch! [{:paths ["src"]
               :filter hawk/created?
               :handler (fn [ctx event]
                          (println "New file created: " (:file event))
                          ctx)}])
```

--------------------------------

### new-watcher

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watcher-protocol.md

Creates an appropriate Watcher implementation based on provided options and the operating system. It supports forcing specific watcher implementations or auto-selecting based on the OS.

```APIDOC
## new-watcher

### Description
Creates an appropriate Watcher implementation based on options and platform.

### Signature
`(new-watcher [opts])`

### Options
- `:watcher :java` — forces Java NIO implementation
- `:watcher :barbary` — forces Barbary implementation (macOS only)
- `:watcher :polling` — forces Polling implementation with optional `:sensitivity`
- `:watcher :default` (or omitted) — auto-selects based on OS (`:barbary` on macOS, `:java` elsewhere)

### Example
```clojure
(new-watcher {:watcher :polling :sensitivity :medium})
; Returns: hawk.PollingWatchService instance
```
```

--------------------------------

### take

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/polling-watch-service.md

Retrieves and removes the next WatchKey with pending events, blocking indefinitely until an event occurs or the thread is interrupted.

```APIDOC
## take()

### Description
Retrieves and removes the next WatchKey with pending events. This method blocks until an event occurs or the thread is interrupted.

### Method
```java
public final WatchKey take()
    throws InterruptedException
```

### Parameters
None

### Returns
- **WatchKey** — first available key with pending events

### Behavior
- Blocks until an event occurs or thread is interrupted.

### Exceptions
- `InterruptedException` — if the thread is interrupted while waiting
```

--------------------------------

### Watch Options Map

Source: https://github.com/wkf/hawk/blob/master/_autodocs/types.md

Configuration passed as the first argument to `hawk/watch!`, specifying the watcher implementation and sensitivity.

```APIDOC
## Watch Options Map

### Description
Configuration passed as first argument to `hawk/watch!`.

### Structure
```clojure
{:watcher keyword
 :sensitivity keyword}
```

### Parameters
#### Watcher
- **:watcher** (keyword) - Optional - Values: `:java`, `:barbary`, `:polling`, `:default`. Default: `:default`. Watch service implementation. `:default` selects `:barbary` on macOS, `:java` otherwise.

#### Sensitivity
- **:sensitivity** (keyword) - Optional - Values: `:high`, `:medium`, `:low`. Default: `:high`. Polling interval (ms) when using `:polling` watcher. `:high` = 500ms, `:medium` = 5s, `:low` = 30s

### Usage
Optional first parameter to `hawk/watch!`

### Notes
- `:sensitivity` only applies when `:watcher` is `:polling`
- On non-macOS systems, `:barbary` watcher is not available
- `:java` watcher uses OS-native file system events but may not work in all virtual environments
- `:polling` watcher works everywhere but consumes more CPU

### Example
```clojure
(hawk/watch! {:watcher :polling :sensitivity :low} [spec1 spec2])
```
```

--------------------------------

### hawk/watch!

Source: https://github.com/wkf/hawk/blob/master/_autodocs/MANIFEST.txt

Creates and manages a file watcher. This is the primary function for initiating file system monitoring.

```APIDOC
## hawk/watch!

### Description
Creates and manages a file watcher. This function allows users to define paths to monitor, specify a handler for events, and configure filtering and context.

### Method
(Not specified, likely a function call in a Clojure context)

### Endpoint
(Not applicable, this is an SDK function)

### Parameters
#### Path Parameters
(Not applicable)

#### Query Parameters
(Not applicable)

#### Request Body
(Not applicable)

### Request Example
(Not provided in source)

### Response
#### Success Response (200)
(Not specified, likely returns a watch handle)

#### Response Example
(Not provided in source)

### Exceptions/Error Conditions
- ClosedWatchServiceException
- InterruptedException
- NotDirectoryException
- FileSystemException
- IllegalArgumentException
- NullPointerException
- UnsupportedOperationException
```

--------------------------------

### Safe Cleanup with try/finally

Source: https://github.com/wkf/hawk/blob/master/_autodocs/INDEX.md

Demonstrates how to ensure a watcher is stopped even if errors occur during its operation using a try/finally block.

```clojure
;; Safe cleanup with try/finally
(let [watch (hawk/watch! specs)]
  (try
    (do-something)
    (finally
      (hawk/stop! watch))))
```

--------------------------------

### Watching a path with insufficient permissions in Hawk

Source: https://github.com/wkf/hawk/blob/master/_autodocs/errors.md

This snippet demonstrates attempting to watch a directory for which the current user lacks read permissions, resulting in a FileSystemException.

```clojure
(hawk/watch! [{:paths ["/root/.ssh"] ; No read permission for user
               :handler (fn [ctx e] ctx)})

```

--------------------------------

### Create then Modify Deduplication

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/abstract-watch-key.md

Demonstrates how a CREATE event followed by multiple MODIFY events are handled.

```text
Raw Events:   CREATE, MODIFY, MODIFY, MODIFY
Delivered:    CREATE (count=1), MODIFY (count=3)
```

--------------------------------

### Watch for File System Events

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/filter-functions.md

Sets up a watch on specified paths. The filter function determines which events are processed by the handler.

```clojure
(hawk/watch! [{:paths ["src"]
               :filter hawk/file?
               :handler (fn [ctx event]
                          (println "Only files: " (:file event))
                          ctx)}])
```

--------------------------------

### Configure Java Watcher

Source: https://github.com/wkf/hawk/blob/master/_autodocs/configuration.md

Use the :java watcher for high-performance, native file system event monitoring. This is suitable for most platforms including Linux, macOS, and Windows.

```clojure
(hawk/watch! {:watcher :java}
             [{:paths ["src"] :handler (fn [ctx e] ctx)}])
```

--------------------------------

### AbstractWatchService

Source: https://github.com/wkf/hawk/blob/master/_autodocs/INDEX.md

Provides the base implementation for watch services, offering methods for polling and managing watch keys.

```APIDOC
## AbstractWatchService (Base Implementation)

### Description
Provides the base implementation for watch services, offering methods for polling and managing watch keys.

### Methods
- `poll()`: Non-blocking check for watch key.
- `poll(timeout, unit)`: Check with timeout.
- `take()`: Block until watch key available.
- `close()`: Shutdown service.
- `register(path, events, modifiers)`: Abstract method for subclasses.
```

--------------------------------

### Internal Watcher Registration and Event Loop

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watcher-protocol.md

This snippet demonstrates the internal usage of the Watcher protocol within `hawk.core/watch!`. It shows how to create a new watcher, register multiple paths for specific events (create, modify, delete), and then enter a loop to process incoming events.

```clojure
;; Internal usage in watch!
(let [watcher (new-watcher opts)]
  (doseq [path paths]
    (watcher/register! watcher path [:create :modify :delete]))
  (loop []
    (when-let [events (watcher/take! watcher)]
      ; process events
      (recur))))
```

--------------------------------

### Watcher Selection Logic: Dispatch Chain

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Explains how Hawk selects the appropriate Watcher implementation based on user-provided options or platform defaults. It prioritizes explicit `:watcher` options before falling back to OS-specific choices.

```text
new-watcher called with opts
    │
    ├─► :watcher specified?
    │   ├─ :java    → java.nio.file.WatchService
    │   ├─ :barbary → com.barbarysoftware.watchservice.WatchService
    │   ├─ :polling → hawk.PollingWatchService (with sensitivity)
    │   └─ :default → check OS
    │
    └─► Platform auto-selection
        ├─ macOS ("Mac OS X") → :barbary
        └─ Other → :java
```

--------------------------------

### implClose

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/abstract-watch-service.md

Cleans up implementation-specific resources. This is an abstract method that must be implemented by subclasses.

```APIDOC
## implClose (abstract)

```java
abstract void implClose() throws IOException;
```

### Description
Cleans up implementation-specific resources. This method must be implemented by subclasses.

### Throws
- **IOException** - If an I/O error occurs during cleanup.
```

--------------------------------

### Abstract register Method Signature

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/abstract-watch-service.md

This abstract method must be implemented by subclasses to convert platform-specific file system APIs into WatchKey objects. It takes the path to watch, the event types to monitor, and optional modifiers.

```java
abstract WatchKey register(Path path,
                           WatchEvent.Kind<?>[] events,
                           WatchEvent.Modifier... modifers)
    throws IOException;

```

--------------------------------

### register

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/abstract-watch-service.md

Registers a path for watching specific file system events. This is an abstract method that must be implemented by subclasses.

```APIDOC
## register (abstract)

```java
abstract WatchKey register(Path path,
                           WatchEvent.Kind<?>[] events,
                           WatchEvent.Modifier... modifers)
    throws IOException;
```

### Description
Registers a path for watching specific file system events. This method must be implemented by subclasses.

### Parameters

#### Path Parameters
- **path** (Path) - Required - The file or directory to watch.
- **events** (WatchEvent.Kind<?>[]) - Required - The event types to watch for (e.g., ENTRY_CREATE, ENTRY_MODIFY, ENTRY_DELETE).
- **modifers** (WatchEvent.Modifier...) - Optional - Modifiers for the watch registration, such as sensitivity.

### Returns
- **WatchKey** - A WatchKey representing the registration.
```

--------------------------------

### Hawk Watch with Multiple Groups (Parallel Processing)

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watch-api.md

Sets up two independent watch groups that process events in parallel. Group 1 monitors 'src/main' and Group 2 monitors 'src/test'.

```clojure
(hawk/watch! 
  ;; Group 1 - monitors source files
  [{:paths ["src/main"]
    :context (constantly 1)
    :handler (fn [ctx event] 
              (println "Source event:" event)
              (inc ctx))}]
  ;; Group 2 - monitors test files (runs in parallel)
  [{:paths ["src/test"]
    :context (constantly 0)
    :handler (fn [ctx event] 
              (println "Test event:" event)
              (inc ctx))}])
```

--------------------------------

### Graceful Degradation Across Watcher Types

Source: https://github.com/wkf/hawk/blob/master/_autodocs/INDEX.md

Shows how to fall back to a different watcher implementation if the preferred one fails to initialize, ensuring service continuity.

```clojure
;; Graceful degradation across watcher types
(let [watch (or (try (hawk/watch! {:watcher :java} specs) 
                     (catch Exception _))
                (hawk/watch! {:watcher :polling} specs))]
  watch)
```

--------------------------------

### Determine Supported Watcher Implementations by OS

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Selects the appropriate watcher implementations based on the operating system. This is used to configure tests for specific platforms.

```clojure
(def supported-watcher-implementations
  (if (= "Mac OS X" (System/getProperty "os.name"))
    [:barbary :java :polling]
    [:java :polling]))
```

--------------------------------

### Define Java Source Path

Source: https://github.com/wkf/hawk/blob/master/_autodocs/configuration.md

Specify the directory for supporting Java source files in project.clj. This includes implementations like AbstractWatchService.

```clojure
:java-source-paths ["src/main/java"]
```

--------------------------------

### AbstractWatchKey Constructor

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/abstract-watch-key.md

Protected constructor for AbstractWatchKey. Initializes the directory, watcher, state, events list, and lastModifyEvents map. Not directly instantiated.

```java
protected AbstractWatchKey(Path dir, AbstractWatchService watcher)
```

--------------------------------

### Stateful File Watcher

Source: https://github.com/wkf/hawk/blob/master/_autodocs/INDEX.md

Perform stateful operations during file watching. Initializes context to 0 and increments it for each event. The watch is stopped after 10 seconds.

```clojure
(let [watch (hawk/watch! [{:paths ["src"]
                           :context (constantly 0)
                           :handler (fn [ctx _] 
                                      (inc ctx))}])] 
  (Thread/sleep 10000)
  (hawk/stop! watch))
```

--------------------------------

### Watch for Directory Events

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/filter-functions.md

Sets up a watch to process only directory events. The handler is called only when a directory is affected.

```clojure
(hawk/watch! [{:paths ["src"]
               :filter hawk/directory?
               :handler (fn [ctx event]
                          (println "Only directories: " (:file event))
                          ctx)}])
```

--------------------------------

### Hawk Module Dependencies

Source: https://github.com/wkf/hawk/blob/master/_autodocs/architecture.md

Details the module dependencies within Hawk, showing how the public API relies on internal modules and external services.

```text
hawk.core (public API)
    │
    └── requires ──► hawk.watcher (internal)
                        │
                        ├── imports JDK 7+ WatchService
                        ├── imports Barbary WatchService
                        └── imports hawk.PollingWatchService
                                    │
                                    └── extends hawk.AbstractWatchService
                                            │
                                            └── implements java.nio.file.WatchService
```

--------------------------------

### Custom Watch Service Implementation

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/abstract-watch-service.md

Extend AbstractWatchService to create a custom watch service. Override the register method to implement custom registration logic and ensure thread safety by synchronizing on the closeLock. The isOpen check prevents registration on a closed service.

```java
public class CustomWatchService extends AbstractWatchService {
    
    @Override
    WatchKey register(Path path, WatchEvent.Kind<?>[] events,
                      WatchEvent.Modifier... modifiers) throws IOException {
        synchronized (closeLock()) {
            if (!isOpen()) {
                throw new ClosedWatchServiceException();
            }
            // custom registration logic
            return watchKey;
        }
    }
    
    @Override
    void implClose() throws IOException {
        // cleanup
    }
}
```

--------------------------------

### PollingWatchService

Source: https://github.com/wkf/hawk/blob/master/_autodocs/INDEX.md

A concrete implementation of AbstractWatchService that uses periodic directory polling to detect file system changes.

```APIDOC
## PollingWatchService (Polling Implementation)

### Description
A concrete implementation of AbstractWatchService that uses periodic directory polling to detect file system changes. It features configurable sensitivity and event deduplication.

### Constructor
```java
public PollingWatchService(SensitivityWatchEventModifier sensitivity)
```

### Features
- Periodic directory polling
- File state tracking via last-modified time
- Configurable sensitivity via SensitivityWatchEventModifier
- Event deduplication via AbstractWatchKey
```

--------------------------------

### Configure Ahead-of-Time Compilation

Source: https://github.com/wkf/hawk/blob/master/_autodocs/configuration.md

Configure ahead-of-time (AOT) compilation and set Java compatibility to version 1.7 in project.clj.

```clojure
:aot [hawk.watcher]
:javac-options ["-target" "1.7" "-source" "1.7"]
```

--------------------------------

### Polling Watcher for Virtual Environments

Source: https://github.com/wkf/hawk/blob/master/_autodocs/INDEX.md

Use a polling-based watcher suitable for virtual environments or when native file system events are unreliable. Configurable sensitivity.

```clojure
(hawk/watch! {:watcher :polling :sensitivity :medium}
             [{:paths ["data"]
               :handler (fn [ctx e] 
                          (process-file (:file e)) 
                          ctx)}])
```

--------------------------------

### Converting files to parent directories in Clojure

Source: https://github.com/wkf/hawk/blob/master/_autodocs/errors.md

This Clojure code snippet shows how Hawk processes paths, converting file paths to their parent directories to ensure compatibility with directory-based watch services.

```clojure
(defn process-paths [{:keys [files directories] :as spec}]
  (assoc spec :paths
         (concat
           (map #(-> % .toPath) directories)
           (map #(-> % .getParentFile .toPath) files)))) ; Convert files to parent dirs
```

--------------------------------

### AbstractWatchKey

Source: https://github.com/wkf/hawk/blob/master/_autodocs/INDEX.md

Manages pending events for a specific watchable directory and provides methods to interact with the watch key state.

```APIDOC
## AbstractWatchKey (Event Management)

### Description
Manages pending events for a specific watchable directory and provides methods to interact with the watch key state.

### Key Methods
- `watchable()`: Return watched directory.
- `pollEvents()`: Get all pending events.
- `reset()`: Reset key state.
- `isValid()`: Check if key is still valid.
- `cancel()`: Stop watching.
```

--------------------------------

### watch! Function

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/watch-api.md

Creates one or more watch groups that monitor specified paths for file system events. This is the primary API for setting up file system watchers in Hawk.

```APIDOC
## watch! Function

### Description
Creates one or more watch groups that monitor specified paths for file system events.

### Function Signature
```clojure
(watch! [opts & groups])
```

### Parameters
#### `opts` (map) - Optional
Watch service configuration options.

#### `groups` (var-args) - Required
One or more vectors, each containing watch specification maps.

### Options Object (`opts`)
- **`:watcher`** (keyword) - Optional - Default: `:default` - Watch service implementation: `:java`, `:barbary`, `:polling`, or `:default`.
- **`:sensitivity`** (keyword) - Optional - Default: `:high` - Polling sensitivity level: `:high` (500ms), `:medium` (5s), `:low` (30s) - only applies with `:polling` watcher.

### Watch Specification Object
Each element in a watch group is a specification map with the following structure:
- **`:paths`** (vector of strings) - Required - Paths to watch (files or directories). Can be canonicalized automatically. Directories are watched recursively.
- **`:handler`** (function) - Required - Function called for each event: `(fn [context event] new-context)`. Must return the updated context.
- **`:filter`** (function) - Optional - Predicate function: `(fn [context event] boolean)`. If provided, handler is only called for events that pass the filter.
- **`:context`** (function) - Optional - Initialization function: `(fn [context] new-context)`. Called once at watch startup. If omitted, context defaults to identity.
```

--------------------------------

### Configure Polling Watcher with Low Sensitivity

Source: https://github.com/wkf/hawk/blob/master/_autodocs/configuration.md

Use the :polling watcher with :low sensitivity for minimal CPU impact (30000ms interval). Recommended for background operations or resource-constrained systems.

```clojure
(hawk/watch! {:watcher :polling :sensitivity :low}
             [{:paths ["src"] :handler (fn [ctx e] ctx)}])
```

--------------------------------

### Registering Path After Watch Stop (Clojure)

Source: https://github.com/wkf/hawk/blob/master/_autodocs/errors.md

Demonstrates an attempt to register a new path after a watch service has been stopped. This scenario would lead to a ClosedWatchServiceException if the operation were exposed.

```clojure
(let [watch (hawk/watch! [{:paths ["src"] :handler (fn [ctx e] ctx)}])]
  (hawk/stop! watch)
  ; Attempting to register a new path now would fail if exposed
)
```

--------------------------------

### Multiple Watch Groups for Parallel Processing

Source: https://github.com/wkf/hawk/blob/master/_autodocs/INDEX.md

Set up multiple independent watch groups to process different directories or tasks in parallel. Each group has its own path and handler.

```clojure
(hawk/watch! 
  [{:paths ["src/main"]
    :handler (fn [ctx e] 
              (compile-source (:file e)) 
              ctx)}] 
  [{:paths ["src/test"]
    :handler (fn [ctx e] 
              (run-tests (:file e)) 
              ctx)}])
```

--------------------------------

### AbstractWatchService Protected Constructor

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/abstract-watch-service.md

Initializes the state for subclasses. The pendingKeys queue is set to a LinkedBlockingDeque, and the closed flag is initialized to false.

```java
protected AbstractWatchService()

```

--------------------------------

### Filtered File System Watch

Source: https://github.com/wkf/hawk/blob/master/_autodocs/README.md

Creates a file system watcher for the 'src' directory that only triggers for file events. It prints the file name associated with the event. The handler returns the context.

```clojure
(hawk/watch! [{:paths ["src"]
               :filter hawk/file?
               :handler (fn [ctx event]
                          (println "File:" (:file event))
                          ctx)})
```

--------------------------------

### Registering a file path with PollingWatchService

Source: https://github.com/wkf/hawk/blob/master/_autodocs/errors.md

This snippet demonstrates attempting to register a regular file with the PollingWatchService, which expects a directory. This will result in a NotDirectoryException.

```java
Path file = Paths.get("/path/to/regular/file.txt");
WatchKey key = pollingWatcher.register(
    file,
    new WatchEvent.Kind<?>[]{StandardWatchEventKinds.ENTRY_CREATE},
    new WatchEvent.Modifier[]{});
// Throws: java.nio.file.NotDirectoryException: /path/to/regular/file.txt
```

--------------------------------

### PollingWatchService Constructor

Source: https://github.com/wkf/hawk/blob/master/_autodocs/api-reference/polling-watch-service.md

Initializes a new PollingWatchService. This constructor allows setting the polling sensitivity, which determines the interval at which directories are checked for changes.

```APIDOC
## PollingWatchService(SensitivityWatchEventModifier sensitivity)

### Description
Constructs a new PollingWatchService with a specified polling sensitivity.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```java
public PollingWatchService(SensitivityWatchEventModifier sensitivity)
```

### Parameters
- **sensitivity** (SensitivityWatchEventModifier) - Required - Polling interval modifier: HIGH (500ms), MEDIUM (5s), or LOW (30s)

### Behavior
- Creates a single-thread ScheduledExecutorService for polling tasks (daemon thread).
- Initializes the directory cache map for tracking file state.
- Sets the global sensitivity for all subsequently registered paths.

### Example
```java
PollingWatchService watcher = new PollingWatchService(SensitivityWatchEventModifier.HIGH);
```
```

--------------------------------

### Require Hawk Core Library

Source: https://github.com/wkf/hawk/blob/master/README.md

To use Hawk, you need to require the core library in your Clojure project. This sets up the necessary functions for watching files.

```clojure
(ns hawk.sample
    (:require [hawk.core :as hawk]))
```
Tokens:
Raw