diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,12 @@ +Change log +========== + +teardown uses [Semantic Versioning][1]. +The change log is available [on GitHub][2]. + +[1]: http://semver.org/spec/v2.0.0.html +[2]: https://github.com/roman/Haskell-teardown/libraries/teardown/CHANGELOG.md + +## v0.0.0.2 + +* First release of this library diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,13 @@ +Copyright (c) 2017, Roman Gonzalez + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +# componentm-devel + +> A library that enhances componentm to work nicely with GHCi and ghcid + +## Table Of Contents + +* [Installation](#installation) +* [Purpose](#purpose) + * [Differences with ResourceT](#differences-with-resourcet) +* [Development](#development) +* [Documentation](#documentation) +* [License](#license) + +## Installation + +[![Hackage](https://img.shields.io/hackage/v/componentm.svg)](https://img.shields.io/hackage/v/componentm.svg) +[![Stackage LTS](http://stackage.org/package/componentm/badge/lts)](http://stackage.org/lts/package/componentm) +[![Stackage Nightly](http://stackage.org/package/componentm/badge/nightly)](http://stackage.org/nightly/package/componentm) + +Make sure you include the following entry on your [cabal file's +dependecies](https://www.haskell.org/cabal/users-guide/developing-packages.html#build-information) +section. + +```cabal +library: + build-depends: + componentm + , componentm-devel +``` + +Or on your `package.yaml` + +``` +dependencies: +- componentm +- componentm-devel +``` + +## Purpose + +This library enhances the +[componentm](https://github.com/Haskell-componentm/componentm) library to +dispose and re-allocate an application on a REPL environment. + +## Development +[![Build Status](https://travis-ci.org/roman/Haskell-componentm.svg?branch=master)](https://travis-ci.org/roman/Haskell-componentm) +[![Hackage Dependencies](https://img.shields.io/hackage-deps/v/componentm-devel.svg)](http://packdeps.haskellers.com/feed?needle=componentm-devel) +[![Github](https://img.shields.io/github/commits-since/roman/haskell-componentm/v0.0.0.2.svg)](https://img.shields.io/github/commits-since/roman/haskell-componentm/v0.0.0.2.svg) + +This library is intended to be minimal, providing a few functions that work +reliably among many different kind of projects. If you want to contribute, Pull +Request are very welcome! Please try to follow these simple rules: + +* Please create a topic branch for every separate change you make. +* Update the README.md file if necessary. +* Please _do not_ change the version number on your Pull Request. + +### Open Commit Bit + +This project has an open commit bit policy: Anyone with an accepted pull request +gets added as a repository collaborator. Please try to follow these simple +rules: + +* Commit directly onto the master branch only for typos, improvements to the + README and documentation. +* Create a feature branch and open a pull-request early for any new features to + get feedback. +* Make sure you adhere to the general pull request rules above. + +## License + +Copyright (c) 2017-current Roman Gonzalez + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,2 @@ +import Distribution.Simple +main = defaultMain diff --git a/componentm-devel.cabal b/componentm-devel.cabal new file mode 100644 --- /dev/null +++ b/componentm-devel.cabal @@ -0,0 +1,43 @@ +cabal-version: >=1.10 +name: componentm-devel +version: 0.0.0.2 +license: MIT +license-file: LICENSE +copyright: © 2017-current Roman Gonzalez +maintainer: open-source@roman-gonzalez.info +author: Roman Gonzalez +stability: alpha (experimental) +tested-with: ghc ==8.0.1 ghc ==8.0.2 ghc ==8.2.1 +homepage: https://github.com/roman/Haskell-componentm#readme +bug-reports: https://github.com/roman/Haskell-componentm/issues +synopsis: Easy REPL driven development using ComponentM +description: + This library enhances the componentm with auto-reloading + capabilites for your application, allowing to ensure cleanup + of resources when doing REPL driven development, or when using + ghcid +category: System +build-type: Simple +extra-source-files: + CHANGELOG.md + README.md + +source-repository head + type: git + location: https://github.com/roman/Haskell-componentm + +library + exposed-modules: + Control.Monad.Component.Development + hs-source-dirs: src + other-modules: + Paths_componentm_devel + default-language: Haskell2010 + ghc-options: -Wall -Wincomplete-uni-patterns + -Wincomplete-record-updates + build-depends: + base >=4.8 && <5, + componentm >=0.0.0.2, + foreign-store >=0.2, + rio >=0.0.3, + teardown >=0.3 diff --git a/src/Control/Monad/Component/Development.hs b/src/Control/Monad/Component/Development.hs new file mode 100644 --- /dev/null +++ b/src/Control/Monad/Component/Development.hs @@ -0,0 +1,97 @@ +{-# LANGUAGE BangPatterns #-} +{-# LANGUAGE NamedFieldPuns #-} +{-# LANGUAGE NoImplicitPrelude #-} +{-# LANGUAGE OverloadedStrings #-} +module Control.Monad.Component.Development + ( + -- * Making 'ComponentM' values useful + ComponentM + , runComponentDevel + + -- * Error Records + , ComponentError (..) + , ComponentBuildError (..) + + -- * 'ComponentM' tracing accessors + , ComponentEvent (..) + , Build + , buildElapsedTime + , buildFailure + , BuildResult + , toBuildList + ) + where + +import RIO + +import Control.Monad.Component.Internal.Types +import Control.Teardown (Teardown, + emptyTeardown, + newTeardown, + runTeardown) +import Foreign.Store + +devTeardownStoreNum :: Word32 +devTeardownStoreNum = 0 + +runComponentDevel_ + :: (ComponentEvent -> IO ()) -- ^ Callback function to trace 'ComponentEvent' records + -> Text -- ^ Name of your application (used for tracing purposes) + -> ComponentM a -- ^ Builder of your application environment + -> (a -> IO b) -- ^ Function where your main application will live + -> IO Teardown +runComponentDevel_ !logFn !appName (ComponentM buildFn) !appFn = + mask $ \restore -> do + result <- restore buildFn + case result of + Left (errList, buildTable) -> do + appTeardown <- buildTableToTeardown appName buildTable + teardownResult <- runTeardown appTeardown + restore $ logFn $ ComponentErrorDetected + (ComponentBuildFailed errList teardownResult) + return $ emptyTeardown "development" + + Right (resource, buildTable) -> do + let buildList = buildTableToOrderedList buildTable + restore $ logFn $ ComponentBuilt $ BuildResult $ reverse buildList + + appTeardown <- buildTableToTeardown appName buildTable + appAsync <- asyncWithUnmask $ \unmask -> unmask $ appFn resource + + appAsyncTeardown <- newTeardown "application async" + (cancel appAsync :: IO ()) + newTeardown "development" [appTeardown, appAsyncTeardown] + +-- | Similar to 'runComponentM1', when running for the first time, it creates an +-- application in the REPL environment, subsequent invocations will teardown the +-- and build up the application again. +-- +-- All 'ComponentM' characteristics are driven by this particular use-case given: +-- +-- * It will print out the time spent on initialization and teardown +-- * It guarantees that teardown operations are as robust as possible +-- * It documents your application components to pin-point quickly errors in your +-- reloading logic +-- +runComponentDevel + :: (ComponentEvent -> IO ()) -- ^ Callback function to trace 'ComponentEvent' records + -> Text -- ^ Name of your application (used for tracing purposes) + -> ComponentM a -- ^ Builder of your application environment + -> (a -> IO b) -- ^ Function where your main application will + -- live, note this function must block the thread + -- as how the normal main would + -> IO () +runComponentDevel !logFn !appName !builder !appFn = do + mdevTeardownStore <- lookupStore devTeardownStoreNum + case mdevTeardownStore of + Nothing -> do + devTeardown <- runComponentDevel_ logFn appName builder appFn + writeStore (Store devTeardownStoreNum) devTeardown + + Just devTeardownStore -> do + devTeardown0 <- readStore devTeardownStore + teardownResult <- runTeardown (devTeardown0 :: Teardown) + logFn $ ComponentReleased teardownResult + + devTeardown <- runComponentDevel_ logFn appName builder appFn + writeStore (Store devTeardownStoreNum) devTeardown