From f404f5ed9a79449c620fde5bd669ab41fcb8d0fb Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Sun, 6 Dec 2015 13:30:00 -0400 Subject: improve docs --- src/Propellor/Property/Cmd.hs | 33 +++++++++++++++++++++++++++------ 1 file 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 -- cgit v1.2.3