diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -0,0 +1,66 @@ +Twitch is monadic DSL and library for file watching. +It conveniently utilizes 'do' notation in the style of +[Shake](https://hackage.haskell.org/package/shake) and +[clay](https://hackage.haskell.org/package/clay) to expose the functionality of the +[fsnotify](http://hackage.haskell.org/package/fsnotify) cross-platform file system +watcher. + +Here is an example that converts Markdown files to Html and reloads Safari +whenever the input files change. + +```haskell +{-# LANGUAGE OverloadedStrings #-} +import Twitch +import Filesystem.Path.CurrentOS + +main = defaultMain $ do + "*.md" |> \filePath -> system $ "pandoc -t html " ++ encodeString filePath + "*.html" |> \_ -> system $ "osascript refreshSafari.AppleScript" +``` + +Rules are specified in the `Dep` (for Dependency) monad. The library takes advantage +of the *OverloadedStrings* extension to create a Dep value from a glob pattern. + +After creating a `Dep` value using a glob, event callbacks are added using prefix +or infix API. + +There are three types of events, *add*, *modify* and *delete*. In many cases, +the *add* and *modify* responses are the same, so an 'add and modify' API +is provided + +In the example above an 'add and modify' callback was added to both the "*.md" +and "*.html" globs using the `|>` operator. + +All this is the common case, differing callbacks can be added with `|+` (or `add`) +and `|%` (or `modify`) functions. Finally, delete callbacks are added with +`|-` (of `delete`). + +Here is a more complex usage example, handling all three events seperately. + +```haskell +handleHaskellFiles :: Dep +handleHaskellFiles = "src/**/*.hs" |+ addToCabalFile |% reloadFile |- removeFromCabalFile +``` + +The glob above is also more complicated and incorporates a recursive wildcard. For +complete documentation on the glob syntax, consult the +[Glob](https://hackage.haskell.org/package/Glob-0.7.5/docs/System-FilePath-Glob.html#v:compile) +library's documentation. + +Since a command pattern is calling system commands with a file path, a useful addition +to twitch is the [file-command-qq](https://hackage.haskell.org/package/file-command-qq-0.1.0.4) quasiquoter, +which is the package of the same name. + +Here is a slightly more complicated version the example from earlier, using the +[file-command-qq](https://hackage.haskell.org/package/file-command-qq-0.1.0.4) quasiquoter. + +```haskell +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE QuasiQuotes #-} +import Twitch +import FileCommand + +main = defaultMain $ do + "*.md" |> [s|pandoc -t html -o$directory$basename-test.html $path|] + "*.html" |> [s|osascript refreshSafari.AppleScript|] +``` diff --git a/src/Twitch.hs b/src/Twitch.hs --- a/src/Twitch.hs +++ b/src/Twitch.hs @@ -1,11 +1,11 @@ --- | Twitch is monadic DSL and library for file watching. +-- | Twitch is a monadic DSL and library for file watching. -- It conveniently utilizes 'do' notation in the style of -- and -- to expose the functionality of the -- cross-platform file system -- watcher. -- --- Here is an example that converts Markdown files to Html and reloads Safari +-- Here is an example that converts Markdown files to HTML and reloads Safari -- whenever the input files change. -- -- > {-# LANGUAGE OverloadedStrings #-} @@ -17,23 +17,23 @@ -- > "*.html" |> \_ -> system $ "osascript refreshSafari.AppleScript" -- -- Rules are specified in the 'Dep' (for Dependency) monad. The library takes advantage --- of the OverloadedStrings extension to create a Dep value from a glob pattern. +-- of the OverloadedStrings extension to create a 'Dep' value from a glob pattern. -- -- After creating a 'Dep' value using a glob, event callbacks are added using prefix -- or infix API. -- --- There are three types of events, \'add\', \'modify\' and \'delete\'. In many cases, --- the add and modify responses are the same, so an \'add and modify\' API +-- There are three types of events: \'add\', \'modify\' and \'delete\'. In many cases, +-- the \'add\' and \'modify\' responses are the same, so an \'add and modify\' API -- is provided -- --- In the example above an \'add and modify\' callback was added to both the \"*.md\" +-- In the example above, an \'add and modify\' callback was added to both the \"*.md\" -- and \"*.html\" globs using the '|>' operator. -- --- All this is the common case, differing callbacks can be added with '|+' (or 'add') +-- Although this is the common case, differing callbacks can be added with '|+' (or 'add') -- and '|%' (or 'modify') functions. Finally, delete callbacks are added with -- '|-' (of 'delete'). -- --- Here is a more complex usage example, handling all three events seperately. +-- Here is a more complex usage example, handling all three events separately. -- -- > handleHaskellFiles :: Dep -- > handleHaskellFiles = "src/**/*.hs" |+ addToCabalFile |% reloadFile |- removeFromCabalFile @@ -44,8 +44,7 @@ -- library's documentation. -- -- Since a command pattern is calling system commands with a file path, a useful addition --- to twitch is the quasiquoter, --- which is the package of the same name. +-- to twitch is the quasiquoter. -- -- Here is a slightly more complicated version the example from earlier, using the -- FileCommand quasiquoter. diff --git a/twitch.cabal b/twitch.cabal --- a/twitch.cabal +++ b/twitch.cabal @@ -2,15 +2,15 @@ -- documentation, see http://haskell.org/cabal/users-guide/ name: twitch -version: 0.1.2.1 +version: 0.1.2.2 synopsis: A high level file watcher DSL description: - Twitch is monadic DSL and library for file watching. + Twitch is a monadic DSL and library for file watching. It conveniently utilizes 'do' notation in the style of Shake and clay to expose the functionality of the fsnotify cross-platform file system watcher. . - Here is an example that converts Markdown files to Html and reloads Safari + Here is an example that converts Markdown files to HTML and reloads Safari whenever the input files change. .