diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Revision history for microlens-process -## 0.1.0.0 -- YYYY-mm-dd + +## 0.1.0.0 + +Expose a new module called `System.Process.Microlens.CommandSpec`, exposing +traversals into the arguments of a raw command. + +Added doctests + +Improved docs + +## 0.0.2.0 + +Widen bounds, improve docs + +## 0.0.1.1 + +* Correct and widen version bounds + +## 0.0.1.0 * First version. Released on an unsuspecting world. diff --git a/Setup.hs b/Setup.hs --- a/Setup.hs +++ b/Setup.hs @@ -1,2 +1,6 @@ -import Distribution.Simple -main = defaultMain +module Main where + +import Distribution.Extra.Doctest (defaultMainWithDoctests) + +main :: IO () +main = defaultMainWithDoctests "doctests" diff --git a/microlens-process.cabal b/microlens-process.cabal --- a/microlens-process.cabal +++ b/microlens-process.cabal @@ -1,10 +1,10 @@ -cabal-version: >=1.10 +cabal-version: >= 1.18 -- Initial package description 'microlens-process.cabal' generated by -- 'cabal init'. For further documentation, see -- http://haskell.org/cabal/users-guide/ name: microlens-process -version: 0.0.2.0 +version: 0.1.0.0 synopsis: Micro-optics for the process library description: 'microlens-process' is a set of multi-purpose optics and convenience @@ -18,7 +18,7 @@ maintainer: emilypi@cohomolo.gy copyright: (c) 2019 Emily Pillmore category: System -build-type: Simple +build-type: Custom extra-source-files: CHANGELOG.md, README.md tested-with: GHC == 8.0.2 , GHC == 8.4.3 @@ -30,14 +30,36 @@ type: git location: https://github.com/emilypi/lens-process.git +custom-setup + setup-depends: base >= 4.0 && < 5 + , Cabal + , cabal-doctest >= 1 && < 1.1 + library exposed-modules: System.Process.Microlens , System.Process.Microlens.CreateProcess + , System.Process.Microlens.CommandSpec build-depends: base >= 4.0 && < 5 , filepath >= 1.0 && < 1.5 - , microlens >= 0.4.11 && < 4.12 - , process >= 1.4 && < 1.7 + , microlens >= 0.4.11 && < 0.4.12 + , process >= 1.5 && < 1.7 hs-source-dirs: src default-language: Haskell2010 + +test-suite doctests + + main-is: doctests.hs + type: exitcode-stdio-1.0 + + build-depends: base >= 4.0 && < 5 + , doctest >= 0.16 && < 0.17 + , microlens >= 0.4.11 && < 0.4.12 + , microlens-process + , process >= 1.5 && < 1.7 + + hs-source-dirs: test + default-language: Haskell2010 + ghc-options: -Wall -threaded + x-doctest-options: --fast diff --git a/src/System/Process/Microlens.hs b/src/System/Process/Microlens.hs --- a/src/System/Process/Microlens.hs +++ b/src/System/Process/Microlens.hs @@ -1,22 +1,28 @@ +{-# LANGUAGE Rank2Types #-} -- | --- Module : Sysetem.Process.Lens.Optics -- Copyright : 2019 Emily Pillmore -- License : BSD -- -- Maintainer : Emily Pillmore -- Stability : Experimental --- Portability : TypeFamilies, Rank2Types +-- Portability : TypeFamilies, RankNTypes -- --- Just the (classy) optics +-- This module provides all of the optical exports, as well ask any associated +-- combinators. For just the optics, see 'System.Process.Lens.Optics', or +-- if you are in need of something lighter weight, just for working with a +-- 'CreateProcess' in terms of getters and setters, see -- +-- For more information on usage and how to work with lenses, see and the tests for example uses. You can also ask questions on Freenode +-- in the #haskell-lens channel. +-- module System.Process.Microlens ( -- * Lenses cmdspec_ , cwd_ , env_ -, stdin -, stdout -, stderr +, stdin_ +, stdout_ +, stderr_ , closefds , creategroup , delegatectlc @@ -25,10 +31,15 @@ , childgroup , childuser , useprocessjobs + -- * Traversals +, arguments -- * Classy Lenses , HasStdin(..) , HasStdout(..) , HasStderr(..) + -- * Combinators +, arguing ) where +import System.Process.Microlens.CommandSpec import System.Process.Microlens.CreateProcess diff --git a/src/System/Process/Microlens/CommandSpec.hs b/src/System/Process/Microlens/CommandSpec.hs new file mode 100644 --- /dev/null +++ b/src/System/Process/Microlens/CommandSpec.hs @@ -0,0 +1,62 @@ +{-# LANGUAGE TypeFamilies #-} +-- | +-- Module : System.Process.Lens.CommandSpec +-- Copyright : 2019 Emily Pillmore +-- License : BSD +-- +-- Maintainer : Emily Pillmore +-- Stability : Experimental +-- Portability : TypeFamilies +-- +-- This module provides the associated optics and combinators +-- for working with 'CommandSpec' objects. 'CommandSpec' consists of two +-- cases: a Shell command, which is a command to execute naively in the shell, +-- and a Raw command which is a command path together with its arguments. +-- +-- 'CommandSpec' has two cases, and therefore a prism into those two cases. +-- There is also a convenient 'Traversal' available for working with the arglist +-- of a Raw command, as well as associated 'Review's for each prism, and combinators +-- for working with arguments monoidally. +-- +-- We provide classy variants for all useful prisms +-- +module System.Process.Microlens.CommandSpec +( -- * Traversals + arguments + -- * Combinators +, arguing +) where + +import Lens.Micro +import System.Process + + +-- $setup +-- >>> import Lens.Micro +-- >>> import System.Process +-- >>> :set -XTypeApplications +-- >>> :set -XRank2Types + +-- | 'Traversal'' into the arguments of a command +-- +-- Examples: +-- +-- >>> RawCommand "/bin/ls" ["-l"] ^. arguments +-- ["-l"] +-- +arguments :: Traversal' CmdSpec [String] +arguments f c = case c of + RawCommand fp args -> RawCommand fp <$> f args + t -> pure t +-- | Append an argument to the argument list of a 'RawCommand' +-- +-- Examples: +-- +-- >>> arguing "-h" $ RawCommand "/bin/ls" ["-l"] +-- RawCommand "/bin/ls" ["-l","-h"] +-- +-- >>> arguing "-h" (RawCommand "/bin/ls" ["-l"]) ^. arguments +-- ["-l","-h"] +-- +arguing :: String -> CmdSpec -> CmdSpec +arguing s = arguments <>~ [s] diff --git a/src/System/Process/Microlens/CreateProcess.hs b/src/System/Process/Microlens/CreateProcess.hs --- a/src/System/Process/Microlens/CreateProcess.hs +++ b/src/System/Process/Microlens/CreateProcess.hs @@ -1,7 +1,6 @@ -{-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE Rank2Types #-} -- | --- Module : Sysetem.Process.Microlens.CreateProcess +-- Module : Sysetem.Process.Lens.CreateProcess -- Copyright : 2019 Emily Pillmore -- License : BSD -- @@ -9,16 +8,28 @@ -- Stability : Experimental -- Portability : TypeFamilies, Rank2Types -- --- 'CreateProcess' lenses and combinators +-- This module provides the associated optics and combinators +-- for working with 'CreateProcess' objects. -- +-- Because 'CreateProcess' was created before the `_` prefix record +-- name convention, some record accessors don't have an apparently +-- "good" name for their corresponding lens. Those that do not are +-- post-fixed with `_` i order to denote their lens status. Thankfully, +-- there are 6 that meet the criteria: 'cmdspec_', 'env_', 'cwd_', 'stdin_', +-- 'stdout_', and 'stderr_'. +-- +-- We provide classy variants of what we consider the significant portions +-- of 'CreateProcess' - namely, the `std_in`, `std_out`, and `std_err` entries. +-- +-- module System.Process.Microlens.CreateProcess ( -- * Lenses cmdspec_ , cwd_ , env_ -, stdin -, stdout -, stderr +, stdin_ +, stdout_ +, stderr_ , closefds , creategroup , createnewconsole @@ -62,18 +73,18 @@ -- | Lens into the 'std_in' entry of the 'CreateProcess' record -- -stdin :: Lens' CreateProcess StdStream -stdin = lens std_in (\t b -> t { std_in = b }) +stdin_ :: Lens' CreateProcess StdStream +stdin_ = lens std_in (\t b -> t { std_in = b }) -- | Lens into the 'std_out' entry of the 'CreateProcess' record -- -stdout :: Lens' CreateProcess StdStream -stdout = lens std_out (\t b -> t { std_out = b }) +stdout_ :: Lens' CreateProcess StdStream +stdout_ = lens std_out (\t b -> t { std_out = b }) -- | Lens into the 'std_err' entry of the 'CreateProcess' record -- -stderr :: Lens' CreateProcess StdStream -stderr = lens std_err (\t b -> t { std_err = b }) +stderr_ :: Lens' CreateProcess StdStream +stderr_ = lens std_err (\t b -> t { std_err = b }) -- | Lens into the 'close_fds' entry of the 'CreateProcess' record -- @@ -132,7 +143,7 @@ _Stdin = id instance HasStdin CreateProcess where - _Stdin = stdin + _Stdin = stdin_ -- | Classy lens for types with a stdout -- @@ -143,7 +154,7 @@ _Stdout = id instance HasStdout CreateProcess where - _Stdout = stdout + _Stdout = stdout_ -- | Classy lens for types with a stderr -- @@ -154,4 +165,4 @@ _Stderr = id instance HasStderr CreateProcess where - _Stderr = stderr + _Stderr = stderr_ diff --git a/test/doctests.hs b/test/doctests.hs new file mode 100644 --- /dev/null +++ b/test/doctests.hs @@ -0,0 +1,7 @@ +module Main where + +import Build_doctests (flags, pkgs, module_sources) +import Test.DocTest (doctest) + +main :: IO () +main = doctest $ flags ++ pkgs ++ module_sources