summaryrefslogtreecommitdiff
path: root/src/Propellor/Property/Cmd.hs
diff options
context:
space:
mode:
authorJoey Hess2015-12-06 13:30:00 -0400
committerJoey Hess2015-12-06 13:30:00 -0400
commitf404f5ed9a79449c620fde5bd669ab41fcb8d0fb (patch)
tree91a28c85887b66378b6c7ae99a2c2d9e4f5d28b3 /src/Propellor/Property/Cmd.hs
parenta8a6c0593a2a55f37b6a24ac7a007616f4a8f876 (diff)
improve docs
Diffstat (limited to 'src/Propellor/Property/Cmd.hs')
-rw-r--r--src/Propellor/Property/Cmd.hs33
1 files changed, 27 insertions, 6 deletions
diff --git a/src/Propellor/Property/Cmd.hs b/src/Propellor/Property/Cmd.hs
index b02376a3..3db00bc1 100644
--- a/src/Propellor/Property/Cmd.hs
+++ b/src/Propellor/Property/Cmd.hs
@@ -1,7 +1,33 @@
{-# LANGUAGE PackageImports #-}
+-- | This module lets you construct Properties by running commands and
+-- scripts. To get from an `UncheckedProperty` to a `Property`, it's
+-- up to the user to check if the command made a change to the system.
+--
+-- The best approach is to `check` a property, so that the command is only
+-- run when it needs to be. With this method, you avoid running the
+-- `cmdProperty` unnecessarily, and you know that whenever it runs, a
+-- change was made.
+--
+-- > check (not <$> userExists "bob")
+-- > (cmdProperty "useradd" ["bob"] `assume` MadeChange)
+--
+-- Sometimes it's just as expensive to check a property as it would be to
+-- run the command that ensures the property. So you can let the command
+-- run every time, and use `changesFile` or `checkResult` to determine if
+-- anything changed:
+--
+-- > cmdProperty "chmod" ["600", "/etc/secret"]
+-- > `changesFile` "/etc/secret"
+--
+-- Or you can punt and `assume` a change was made, but then propellor will
+-- always say it make a change, and `onChange` will always fire.
+--
+-- > cmdProperty "service" ["foo", "reload"]
+-- > `assume` MadeChange
+
module Propellor.Property.Cmd (
- -- * Properties for running commands and scripts
+ -- * Constricting properties running commands and scripts
cmdProperty,
cmdProperty',
cmdPropertyEnv,
@@ -32,11 +58,6 @@ import Utility.Process (createProcess, CreateProcess, waitForProcess)
-- | A property that can be satisfied by running a command.
--
-- The command must exit 0 on success.
---
--- This and other properties in this module are `UncheckedProperty`,
--- and return `NoChange`. It's up to the user to check if the command
--- made a change to the system, perhaps by using `checkResult` or
--- `changesFile`, or you can use @cmdProperty "foo" ["bar"] `assume` MadeChange@
cmdProperty :: String -> [String] -> UncheckedProperty NoInfo
cmdProperty cmd params = cmdProperty' cmd params id