Export CommandParam, boolSystem, safeSystem and shellEscape from Propellor.Property.Cmd, so they are available for use in constricting your own Properties when using propellor as a library.

Several imports of Utility.SafeCommand now redundant.

debian/changelog

@@ -4,6 +4,9 @@ propellor (2.5.0) UNRELEASED; urgency=medium
     more generic cmdProperty' (API change)
   * Add docker image related properties.
     Thanks, Antoine Eiche.
+  * Export CommandParam, boolSystem, safeSystem and shellEscape from
+    Propellor.Property.Cmd, so they are available for use in constricting
+    your own Properties when using propellor as a library.
 
  -- Joey Hess <id@joeyh.name>  Thu, 07 May 2015 12:08:34 -0400
 

src/Propellor/Bootstrap.hs

@@ -6,7 +6,6 @@ module Propellor.Bootstrap (
 ) where
 
 import Propellor
-import Utility.SafeCommand
 
 import System.Posix.Files
 import Data.List

src/Propellor/CmdLine.hs

@@ -18,7 +18,6 @@ import Propellor.Types.CmdLine
 import qualified Propellor.Property.Docker as Docker
 import qualified Propellor.Property.Chroot as Chroot
 import qualified Propellor.Shim as Shim
-import Utility.SafeCommand
 
 usage :: Handle -> IO ()
 usage h = hPutStrLn h $ unlines 

src/Propellor/Git.hs

@@ -3,7 +3,6 @@ module Propellor.Git where
 import Propellor
 import Propellor.PrivData.Paths
 import Propellor.Gpg
-import Utility.SafeCommand
 import Utility.FileMode
 
 getCurrentBranch :: IO String

src/Propellor/Property/Apache.hs

@@ -4,7 +4,6 @@ import Propellor
 import qualified Propellor.Property.File as File
 import qualified Propellor.Property.Apt as Apt
 import qualified Propellor.Property.Service as Service
-import Utility.SafeCommand
 
 type ConfigFile = [String]
 

src/Propellor/Property/Chroot.hs

@@ -19,7 +19,6 @@ import Propellor.Property.Chroot.Util
 import qualified Propellor.Property.Debootstrap as Debootstrap
 import qualified Propellor.Property.Systemd.Core as Systemd
 import qualified Propellor.Shim as Shim
-import Utility.SafeCommand
 
 import qualified Data.Map as M
 import Data.List.Utils

src/Propellor/Property/Cmd.hs

@@ -1,11 +1,20 @@
 {-# LANGUAGE PackageImports #-}
 
 module Propellor.Property.Cmd (
+	-- * Properties for running commands and scripts
 	cmdProperty,
 	cmdProperty',
 	cmdPropertyEnv,
+	Script,
 	scriptProperty,
 	userScriptProperty,
+	-- * Lower-level interface for running commands
+	CommandParam(..),
+	boolSystem,
+	boolSystemEnv,
+	safeSystem,
+	safeSystemEnv,
+	shellEscape
 ) where
 
 import Control.Applicative
@@ -40,15 +49,18 @@ cmdPropertyEnv cmd params env = property desc $ liftIO $ do
   where
 	desc = unwords $ cmd : params
 
--- | A property that can be satisfied by running a series of shell commands.
-scriptProperty :: [String] -> Property NoInfo
+-- | A series of shell commands. (Without a leading hashbang.)
+type Script = [String]
+
+-- | A property that can be satisfied by running a script.
+scriptProperty :: Script -> Property NoInfo
 scriptProperty script = cmdProperty "sh" ["-c", shellcmd]
   where
 	shellcmd = intercalate " ; " ("set -e" : script)
 
--- | A property that can satisfied by running a series of shell commands,
+-- | A property that can satisfied by running a script
 -- as user (cd'd to their home directory).
-userScriptProperty :: User -> [String] -> Property NoInfo
+userScriptProperty :: User -> Script -> Property NoInfo
 userScriptProperty (User user) script = cmdProperty "su" ["--shell", "/bin/sh", "-c", shellcmd, user]
   where
 	shellcmd = intercalate " ; " ("set -e" : "cd" : script)

src/Propellor/Property/Cron.hs

@@ -4,7 +4,6 @@ import Propellor
 import qualified Propellor.Property.File as File
 import qualified Propellor.Property.Apt as Apt
 import Propellor.Bootstrap
-import Utility.SafeCommand
 import Utility.FileMode
 
 import Data.Char

src/Propellor/Property/Debootstrap.hs

@@ -15,7 +15,6 @@ import qualified Propellor.Property.Apt as Apt
 import Propellor.Property.Chroot.Util
 import Propellor.Property.Mount
 import Utility.Path
-import Utility.SafeCommand
 import Utility.FileMode
 
 import Data.List

src/Propellor/Property/Docker.hs

@@ -48,7 +48,6 @@ import qualified Propellor.Property.File as File
 import qualified Propellor.Property.Apt as Apt
 import qualified Propellor.Property.Cmd as Cmd
 import qualified Propellor.Shim as Shim
-import Utility.SafeCommand
 import Utility.Path
 import Utility.ThreadScheduler
 

src/Propellor/Property/Firewall.hs

@@ -18,7 +18,6 @@ import Data.Char
 import Data.List
 
 import Propellor
-import Utility.SafeCommand
 import qualified Propellor.Property.Apt as Apt
 import qualified Propellor.Property.Network as Network
 

src/Propellor/Property/Git.hs

@@ -4,7 +4,6 @@ import Propellor
 import Propellor.Property.File
 import qualified Propellor.Property.Apt as Apt
 import qualified Propellor.Property.Service as Service
-import Utility.SafeCommand
 
 import Data.List
 

src/Propellor/Property/Mount.hs

@@ -1,7 +1,6 @@
 module Propellor.Property.Mount where
 
 import Propellor
-import Utility.SafeCommand
 
 type FsType = String
 type Source = String

src/Propellor/Property/OS.hs

@@ -16,7 +16,6 @@ import qualified Propellor.Property.File as File
 import qualified Propellor.Property.Reboot as Reboot
 import Propellor.Property.Mount
 import Propellor.Property.Chroot.Util (stdPATH)
-import Utility.SafeCommand
 
 import System.Posix.Files (rename, fileExist)
 import Control.Exception (throw)

src/Propellor/Property/Obnam.hs

@@ -4,7 +4,6 @@ import Propellor
 import qualified Propellor.Property.Apt as Apt
 import qualified Propellor.Property.Cron as Cron
 import qualified Propellor.Property.Gpg as Gpg
-import Utility.SafeCommand
 
 import Data.List
 

src/Propellor/Property/Reboot.hs

@@ -1,7 +1,6 @@
 module Propellor.Property.Reboot where
 
 import Propellor
-import Utility.SafeCommand
 
 now :: Property NoInfo
 now = cmdProperty "reboot" []

src/Propellor/Property/Service.hs

@@ -1,7 +1,6 @@
 module Propellor.Property.Service where
 
 import Propellor
-import Utility.SafeCommand
 
 type ServiceName = String
 

src/Propellor/Property/SiteSpecific/GitHome.hs

@@ -3,7 +3,6 @@ module Propellor.Property.SiteSpecific.GitHome where
 import Propellor
 import qualified Propellor.Property.Apt as Apt
 import Propellor.Property.User
-import Utility.SafeCommand
 
 -- | Clones Joey Hess's git home directory, and runs its fixups script.
 installedFor :: User -> Property NoInfo

src/Propellor/Property/SiteSpecific/JoeySites.hs

@@ -15,7 +15,6 @@ import qualified Propellor.Property.User as User
 import qualified Propellor.Property.Obnam as Obnam
 import qualified Propellor.Property.Apache as Apache
 import qualified Propellor.Property.Postfix as Postfix
-import Utility.SafeCommand
 import Utility.FileMode
 
 import Data.List

src/Propellor/Property/Ssh.hs

@@ -24,7 +24,6 @@ import Propellor
 import qualified Propellor.Property.File as File
 import qualified Propellor.Property.Service as Service
 import Propellor.Property.User
-import Utility.SafeCommand
 import Utility.FileMode
 
 import System.PosixCompat

src/Propellor/Property/Systemd.hs

@@ -25,7 +25,6 @@ import qualified Propellor.Property.Chroot as Chroot
 import qualified Propellor.Property.Apt as Apt
 import qualified Propellor.Property.File as File
 import Propellor.Property.Systemd.Core
-import Utility.SafeCommand
 import Utility.FileMode
 
 import Data.List

src/Propellor/Shim.hs

@@ -8,7 +8,6 @@ module Propellor.Shim (setup, cleanEnv, file) where
 
 import Propellor
 import Utility.LinuxMkLibs
-import Utility.SafeCommand
 import Utility.FileMode
 import Utility.FileSystemEncoding
 

src/Propellor/Ssh.hs

@@ -1,7 +1,6 @@
 module Propellor.Ssh where
 
 import Propellor
-import Utility.SafeCommand
 import Utility.UserInfo
 
 import System.PosixCompat

src/Utility/SafeCommand.hs

@@ -17,16 +17,15 @@ import Data.Char
 import Control.Applicative
 import Prelude
 
-{- A type for parameters passed to a shell command. A command can
- - be passed either some Params (multiple parameters can be included,
- - whitespace-separated, or a single Param (for when parameters contain
- - whitespace), or a File.
- -}
-data CommandParam = Params String | Param String | File FilePath
+-- | Parameters that can be passed to a shell command.
+data CommandParam
+	= Params String -- ^ Contains multiple parameters, separated by whitespace
+	| Param String -- ^ A single parameter
+	| File FilePath -- ^ The name of a file
 	deriving (Eq, Show, Ord)
 
-{- Used to pass a list of CommandParams to a function that runs
- - a command and expects Strings. -}
+-- | Used to pass a list of CommandParams to a function that runs
+-- a command and expects Strings. -}
 toCommand :: [CommandParam] -> [String]
 toCommand = concatMap unwrap
   where
@@ -43,9 +42,10 @@ toCommand = concatMap unwrap
 	-- path separator on Windows.
 	pathseps = pathSeparator:"./"
 
-{- Run a system command, and returns True or False
- - if it succeeded or failed.
- -}
+-- | Run a system command, and returns True or False if it succeeded or failed.
+--
+-- This and other command running functions in this module log the commands
+-- run at debug level, using System.Log.Logger.
 boolSystem :: FilePath -> [CommandParam] -> IO Bool
 boolSystem command params = boolSystem' command params id
 
@@ -59,7 +59,7 @@ boolSystemEnv :: FilePath -> [CommandParam] -> Maybe [(String, String)] -> IO Bo
 boolSystemEnv command params environ = boolSystem' command params $
 	\p -> p { env = environ }
 
-{- Runs a system command, returning the exit status. -}
+-- | Runs a system command, returning the exit status.
 safeSystem :: FilePath -> [CommandParam] -> IO ExitCode
 safeSystem command params = safeSystem' command params id
 
@@ -74,23 +74,22 @@ safeSystemEnv :: FilePath -> [CommandParam] -> Maybe [(String, String)] -> IO Ex
 safeSystemEnv command params environ = safeSystem' command params $ 
 	\p -> p { env = environ }
 
-{- Wraps a shell command line inside sh -c, allowing it to be run in a
- - login shell that may not support POSIX shell, eg csh. -}
+-- | Wraps a shell command line inside sh -c, allowing it to be run in a
+-- login shell that may not support POSIX shell, eg csh.
 shellWrap :: String -> String
 shellWrap cmdline = "sh -c " ++ shellEscape cmdline
 
-{- Escapes a filename or other parameter to be safely able to be exposed to
- - the shell.
- -
- - This method works for POSIX shells, as well as other shells like csh.
- -}
+-- | Escapes a filename or other parameter to be safely able to be exposed to
+-- the shell.
+--
+-- This method works for POSIX shells, as well as other shells like csh.
 shellEscape :: String -> String
 shellEscape f = "'" ++ escaped ++ "'"
   where
 	-- replace ' with '"'"'
 	escaped = join "'\"'\"'" $ split "'" f
 
-{- Unescapes a set of shellEscaped words or filenames. -}
+-- | Unescapes a set of shellEscaped words or filenames.
 shellUnEscape :: String -> [String]
 shellUnEscape [] = []
 shellUnEscape s = word : shellUnEscape rest
@@ -107,19 +106,19 @@ shellUnEscape s = word : shellUnEscape rest
 		| c == q = findword w cs
 		| otherwise = inquote q (w++[c]) cs
 
-{- For quickcheck. -}
+-- | For quickcheck.
 prop_idempotent_shellEscape :: String -> Bool
 prop_idempotent_shellEscape s = [s] == (shellUnEscape . shellEscape) s
 prop_idempotent_shellEscape_multiword :: [String] -> Bool
 prop_idempotent_shellEscape_multiword s = s == (shellUnEscape . unwords . map shellEscape) s
 
-{- Segments a list of filenames into groups that are all below the maximum
- - command-line length limit. -}
+-- | Segments a list of filenames into groups that are all below the maximum
+--  command-line length limit.
 segmentXargsOrdered :: [FilePath] -> [[FilePath]]
 segmentXargsOrdered = reverse . map reverse . segmentXargsUnordered
 
-{- Not preserving data is a little faster, and streams better when
- - there are a great many filesnames. -}
+-- | Not preserving order is a little faster, and streams better when
+-- there are a great many filenames.
 segmentXargsUnordered :: [FilePath] -> [[FilePath]]
 segmentXargsUnordered l = go l [] 0 []
   where