fsnotify-0.4.4.0: Cross platform library for file change notification.

Safe Haskell | None
Language | Haskell2010

System.FSNotify

Contents

- Events
- Starting/Stopping
- Configuration
- Lower level
- Watching

Description

This library does not currently report changes made to directories, only files within watched directories.

Minimal example:

    {-# LANGUAGE OverloadedStrings #-} -- for FilePath literals

    import System.FSNotify
    import Control.Concurrent (threadDelay)
    import Control.Monad (forever)

    main =
      withManager $ \mgr -> do
        -- start a watching job (in the background)
        watchDir
          mgr          -- manager
          "."          -- directory to watch
          (const True) -- predicate
          print        -- action

        -- sleep forever (until interrupted)
        forever $ threadDelay 1000000

Synopsis

- data Event
  - = Added {
    - eventPath :: FilePath
    - eventTime :: UTCTime
    - eventIsDirectory :: EventIsDirectory
    }
  - | Modified {
    - eventPath :: FilePath
    - eventTime :: UTCTime
    - eventIsDirectory :: EventIsDirectory
    }
  - | ModifiedAttributes {
    - eventPath :: FilePath
    - eventTime :: UTCTime
    - eventIsDirectory :: EventIsDirectory
    }
  - | Removed {
    - eventPath :: FilePath
    - eventTime :: UTCTime
    - eventIsDirectory :: EventIsDirectory
    }
  - | WatchedDirectoryRemoved {
    - eventPath :: FilePath
    - eventTime :: UTCTime
    - eventIsDirectory :: EventIsDirectory
    }
  - | CloseWrite {
    - eventPath :: FilePath
    - eventTime :: UTCTime
    - eventIsDirectory :: EventIsDirectory
    }
  - | Unknown {
    - eventPath :: FilePath
    - eventTime :: UTCTime
    - eventIsDirectory :: EventIsDirectory
    - eventString :: String
    }
- data EventIsDirectory
  - = IsFile
  - | IsDirectory
- type EventChannel = Chan Event
- type Action = Event -> IO ()
- type ActionPredicate = Event -> Bool
- data WatchManager
- withManager :: (WatchManager -> IO a) -> IO a
- startManager :: IO WatchManager
- stopManager :: WatchManager -> IO ()
- defaultConfig :: WatchConfig
- data WatchConfig
- confWatchMode :: WatchConfig -> WatchMode
- confThreadingMode :: WatchConfig -> ThreadingMode
- confOnHandlerException :: WatchConfig -> SomeException -> IO ()
- data WatchMode
  - = WatchModePoll {
    - watchModePollInterval :: Int
    }
  - | WatchModeOS
- data ThreadingMode
  - = SingleThread
  - | ThreadPerWatch
  - | ThreadPerEvent
- withManagerConf :: WatchConfig -> (WatchManager -> IO a) -> IO a
- startManagerConf :: WatchConfig -> IO WatchManager
- type StopListening = IO ()
- watchDir :: WatchManager -> FilePath -> ActionPredicate -> Action -> IO StopListening
- watchDirChan :: WatchManager -> FilePath -> ActionPredicate -> EventChannel -> IO StopListening
- watchTree :: WatchManager -> FilePath -> ActionPredicate -> Action -> IO StopListening
- watchTreeChan :: WatchManager -> FilePath -> ActionPredicate -> EventChannel -> IO StopListening

# Events

data Event Source #

A file event reported by a file watcher. Each event contains the canonical path for the file and a timestamp guaranteed to be after the event occurred (timestamps represent current time when FSEvents receives it from the OS and/or platform-specific Haskell modules).

Constructors

Added |

Fields

- eventPath :: FilePath
- eventTime :: UTCTime
- eventIsDirectory :: EventIsDirectory

Modified |

Fields

- eventPath :: FilePath
- eventTime :: UTCTime
- eventIsDirectory :: EventIsDirectory

ModifiedAttributes |

Fields

- eventPath :: FilePath
- eventTime :: UTCTime
- eventIsDirectory :: EventIsDirectory

Removed |

Fields

- eventPath :: FilePath
- eventTime :: UTCTime
- eventIsDirectory :: EventIsDirectory

WatchedDirectoryRemoved | Note: Linux-only

Fields

- eventPath :: FilePath
- eventTime :: UTCTime
- eventIsDirectory :: EventIsDirectory

CloseWrite | Note: Linux-only

Fields

- eventPath :: FilePath
- eventTime :: UTCTime
- eventIsDirectory :: EventIsDirectory

Unknown | Note: Linux-only

Fields

- eventPath :: FilePath
- eventTime :: UTCTime
- eventIsDirectory :: EventIsDirectory
- eventString :: String

#### Instances

Instances details

Show Event Source # |
Instance details Defined in System.FSNotify.Types Methods showsPrec :: Int -> Event -> ShowS Source # show :: Event -> String Source # showList :: [Event] -> ShowS Source #
Eq Event Source # |
Instance details Defined in System.FSNotify.Types Methods (==) :: Event -> Event -> Bool Source # (/=) :: Event -> Event -> Bool Source #

data EventIsDirectory Source #

Constructors

IsFile |
IsDirectory |

#### Instances

Instances details

Show EventIsDirectory Source # |
Instance details Defined in System.FSNotify.Types Methods showsPrec :: Int -> EventIsDirectory -> ShowS Source # show :: EventIsDirectory -> String Source # showList :: [EventIsDirectory] -> ShowS Source #
Eq EventIsDirectory Source # |
Instance details Defined in System.FSNotify.Types Methods (==) :: EventIsDirectory -> EventIsDirectory -> Bool Source # (/=) :: EventIsDirectory -> EventIsDirectory -> Bool Source #

type EventChannel = Chan Event Source #

type Action = Event -> IO () Source #

An action to be performed in response to an event.

type ActionPredicate = Event -> Bool Source #

A predicate used to determine whether to act on an event.

# Starting/Stopping

data WatchManager Source #

Watch manager. You need one in order to create watching jobs.

withManager :: (WatchManager -> IO a) -> IO a Source #

Perform an IO action with a WatchManager in place. Tear down the WatchManager after the action is complete.

startManager :: IO WatchManager Source #

Start a file watch manager. Directories can only be watched when they are managed by a started watch manager. When finished watching. you must release resources via `stopManager`. It is preferrable if possible to use `withManager` to handle this automatically.

stopManager :: WatchManager -> IO () Source #

Stop a file watch manager. Stopping a watch manager will immediately stop watching for files and free resources.

# Configuration

defaultConfig :: WatchConfig Source #

Default configuration

- Uses OS watch mode (if possible) and single thread.

data WatchConfig Source #

Watch configuration.

confWatchMode :: WatchConfig -> WatchMode Source #

Watch mode to use.

confThreadingMode :: WatchConfig -> ThreadingMode Source #

Threading mode to use.

confOnHandlerException :: WatchConfig -> SomeException -> IO () Source #

Called when a handler throws an exception.

data WatchMode Source #

Method of watching for changes.

Constructors

WatchModePoll |

Fields

- watchModePollInterval :: Int

  Polling interval in microseconds.

WatchModeOS | Use OS-specific mechanisms to be notified of changes (inotify on Linux, FSEvents on OSX, etc.). Not currently available on e.g. *BSD and Wasm/WASI.

data ThreadingMode Source #

Constructors

SingleThread | Use a single thread for the entire `Manager`. Event handler callbacks will run sequentially.
ThreadPerWatch | Use a single thread for each watch (i.e. each call to `watchDir`, `watchTree`, etc.). Callbacks within a watch will run sequentially but callbacks from different watches may be interleaved.
ThreadPerEvent | Launch a separate thread for every event handler.

# Lower level

withManagerConf :: WatchConfig -> (WatchManager -> IO a) -> IO a Source #

Like `withManager`, but configurable.

startManagerConf :: WatchConfig -> IO WatchManager Source #

Like `startManager`, but configurable.

type StopListening = IO () Source #

An action that cancels a watching/listening job.

# Watching

watchDir :: WatchManager -> FilePath -> ActionPredicate -> Action -> IO StopListening Source #

Watch the immediate contents of a directory by committing an Action for each event. Watching the immediate contents of a directory will only report events associated with files within the specified directory, and not files within its subdirectories.

watchDirChan :: WatchManager -> FilePath -> ActionPredicate -> EventChannel -> IO StopListening Source #

Watch the immediate contents of a directory by streaming events to a Chan. Watching the immediate contents of a directory will only report events associated with files within the specified directory, and not files within its subdirectories.

watchTree :: WatchManager -> FilePath -> ActionPredicate -> Action -> IO StopListening Source #

Watch all the contents of a directory by committing an Action for each event. Watching all the contents of a directory will report events associated with files within the specified directory and its subdirectories.

watchTreeChan :: WatchManager -> FilePath -> ActionPredicate -> EventChannel -> IO StopListening Source #

Watch all the contents of a directory by streaming events to a Chan. Watching all the contents of a directory will report events associated with files within the specified directory and its subdirectories.