System.FSNotify

fsnotify-0.4.1.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 #

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

data EventIsDirectory #

Constructors

IsFile |
IsDirectory |

#### Instances

Instances details

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

type EventChannel = Chan Event #

type Action = Event -> IO () #

An action to be performed in response to an event.

type ActionPredicate = Event -> Bool #

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

# Starting/Stopping

data WatchManager #

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

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

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

startManager :: IO WatchManager #

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 () #

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

# Configuration

defaultConfig :: WatchConfig #

Default configuration

- Uses OS watch mode and single thread.

data WatchConfig #

Watch configuration.

confWatchMode :: WatchConfig -> WatchMode #

Watch mode to use.

confThreadingMode :: WatchConfig -> ThreadingMode #

Threading mode to use.

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

Called when a handler throws an exception.

data WatchMode #

Method of watching for changes.

Constructors

WatchModePoll | Detect changes by polling the filesystem. Less efficient and may miss fast changes. Not recommended unless you're experiencing problems with `WatchModeOS` (or `WatchModeOS` is not supported on your platform).
Fields watchModePollInterval :: Int
WatchModeOS | Use OS-specific mechanisms to be notified of changes (inotify on Linux, FSEvents on OSX, etc.). Not currently available on *BSD.

data ThreadingMode #

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 #

Like `withManager`, but configurable.

startManagerConf :: WatchConfig -> IO WatchManager #

Like `startManager`, but configurable.

type StopListening = IO () #

An action that cancels a watching/listening job.

# Watching

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

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 #

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 #

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 #

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.