propellor-5.17: property-based host configuration management in haskell

Safe Haskell | Safe-Inferred
Language | Haskell2010

Propellor.Property.File

Synopsis

- type Line = String
- hasContent :: FilePath -> [Line] -> Property UnixLike
- containsLine :: FilePath -> Line -> Property UnixLike
- containsLines :: FilePath -> [Line] -> Property UnixLike
- containsBlock :: FilePath -> [Line] -> RevertableProperty UnixLike UnixLike
- lacksLine :: FilePath -> Line -> Property UnixLike
- lacksLines :: FilePath -> [Line] -> Property UnixLike
- hasContentProtected :: FilePath -> [Line] -> Property UnixLike
- hasPrivContent :: IsContext c => FilePath -> c -> Property (HasInfo + UnixLike)
- hasPrivContentFrom :: (IsContext c, IsPrivDataSource s) => s -> FilePath -> c -> Property (HasInfo + UnixLike)
- hasPrivContentExposed :: IsContext c => FilePath -> c -> Property (HasInfo + UnixLike)
- hasPrivContentExposedFrom :: (IsContext c, IsPrivDataSource s) => s -> FilePath -> c -> Property (HasInfo + UnixLike)
- hasPrivContent' :: (IsContext c, IsPrivDataSource s) => FileWriteMode -> s -> FilePath -> c -> Property (HasInfo + UnixLike)
- basedOn :: FilePath -> (FilePath, [Line] -> [Line]) -> Property UnixLike
- notPresent :: FilePath -> Property UnixLike
- dirExists :: FilePath -> Property UnixLike
- newtype LinkTarget = LinkTarget FilePath
- isSymlinkedTo :: FilePath -> LinkTarget -> RevertableProperty UnixLike UnixLike
- isCopyOf :: FilePath -> FilePath -> Property UnixLike
- ownerGroup :: FilePath -> User -> Group -> Property UnixLike
- applyPath :: Monoid (Property metatypes) => FilePath -> FilePath -> (FilePath -> Property metatypes) -> Property metatypes
- mode :: FilePath -> FileMode -> Property UnixLike
- class FileContent c where
  - emptyFileContent :: c
  - readFileContent :: FilePath -> IO c
  - writeFileContent :: FileWriteMode -> FilePath -> c -> IO ()
- data FileWriteMode
  - = NormalWrite
  - | ProtectedWrite
- fileProperty :: (FileContent c, Eq c) => Desc -> (c -> c) -> FilePath -> Property UnixLike
- fileProperty' :: (FileContent c, Eq c) => FileWriteMode -> Desc -> (c -> c) -> FilePath -> Property UnixLike
- stableTmpFor :: FilePath -> FilePath
- viaStableTmp :: (MonadMask m, MonadIO m) => (FilePath -> m ()) -> FilePath -> m ()
- configFileName :: String -> FilePath
- showConfigFileName :: Show v => v -> FilePath
- readConfigFileName :: Read v => FilePath -> Maybe v
- data Overwrite
  - = OverwriteExisting
  - | PreserveExisting
- checkOverwrite :: Overwrite -> FilePath -> (FilePath -> Property i) -> Property i

# Documentation

type Line = String Source #

hasContent :: FilePath -> [Line] -> Property UnixLike Source #

Replaces all the content of a file.

containsLine :: FilePath -> Line -> Property UnixLike Source #

Ensures that a line is present in a file, adding it to the end if not.

For example:

    	& "/etc/default/daemon.conf" `File.containsLine` ("cachesize = " ++ val 1024)

The above example uses `val` to serialize a `ConfigurableValue`

containsLines :: FilePath -> [Line] -> Property UnixLike Source #

Ensures that a list of lines are present in a file, adding any that are not to the end of the file.

Note that this property does not guarantee that the lines will appear consecutively, nor in the order specified. If you need either of these, use `containsBlock`.

containsBlock :: FilePath -> [Line] -> RevertableProperty UnixLike UnixLike Source #

Ensures that a block of consecutive lines is present in a file, adding it to the end if not. Revert to ensure that the block is not present (though the lines it contains could be present, non-consecutively).

lacksLine :: FilePath -> Line -> Property UnixLike Source #

Ensures that a line is not present in a file. Note that the file is ensured to exist, so if it doesn't, an empty file will be written.

lacksLines :: FilePath -> [Line] -> Property UnixLike Source #

hasContentProtected :: FilePath -> [Line] -> Property UnixLike Source #

Replaces all the content of a file, ensuring that its modes do not allow it to be read or written by anyone other than the current user

hasPrivContent :: IsContext c => FilePath -> c -> Property (HasInfo + UnixLike) Source #

Ensures a file has contents that comes from PrivData.

The file's permissions are preserved if the file already existed. Otherwise, they're set to 600.

hasPrivContentFrom :: (IsContext c, IsPrivDataSource s) => s -> FilePath -> c -> Property (HasInfo + UnixLike) Source #

Like hasPrivContent, but allows specifying a source for PrivData, rather than using `PrivDataSourceFile`.

hasPrivContentExposed :: IsContext c => FilePath -> c -> Property (HasInfo + UnixLike) Source #

Leaves the file at its default or current mode, allowing "private" data to be read.

Use with caution!

hasPrivContentExposedFrom :: (IsContext c, IsPrivDataSource s) => s -> FilePath -> c -> Property (HasInfo + UnixLike) Source #

hasPrivContent' :: (IsContext c, IsPrivDataSource s) => FileWriteMode -> s -> FilePath -> c -> Property (HasInfo + UnixLike) Source #

basedOn :: FilePath -> (FilePath, [Line] -> [Line]) -> Property UnixLike Source #

Replaces the content of a file with the transformed content of another file

notPresent :: FilePath -> Property UnixLike Source #

Removes a file. Does not remove symlinks or non-plain-files.

dirExists :: FilePath -> Property UnixLike Source #

Ensures a directory exists.

newtype LinkTarget Source #

The location that a symbolic link points to.

Constructors

LinkTarget FilePath |

isSymlinkedTo :: FilePath -> LinkTarget -> RevertableProperty UnixLike UnixLike Source #

Creates or atomically updates a symbolic link.

Revert to ensure no symlink is present.

Does not overwrite or delete regular files or directories.

isCopyOf :: FilePath -> FilePath -> Property UnixLike Source #

Ensures that a file is a copy of another (regular) file.

ownerGroup :: FilePath -> User -> Group -> Property UnixLike Source #

Ensures that a file/dir has the specified owner and group.

applyPath :: Monoid (Property metatypes) => FilePath -> FilePath -> (FilePath -> Property metatypes) -> Property metatypes Source #

Given a base directory, and a relative path under that directory, applies a property to each component of the path in turn, starting with the base directory.

For example, to make a file owned by a user, making sure their home directory and the subdirectories to it are also owned by them:

    "/home/user/program/file" `hasContent` ["foo"]
    	`before` applyPath "/home/user" ".config/program/file"
    		(\f -> ownerGroup f (User "user") (Group "user"))

mode :: FilePath -> FileMode -> Property UnixLike Source #

Ensures that a file/dir has the specfied mode.

class FileContent c where Source #

Methods

emptyFileContent :: c Source #

readFileContent :: FilePath -> IO c Source #

writeFileContent :: FileWriteMode -> FilePath -> c -> IO () Source #

#### Instances

Instances details

FileContent ByteString Source # |
Instance details Defined in Propellor.Property.File Methods emptyFileContent :: ByteString Source # readFileContent :: FilePath -> IO ByteString Source # writeFileContent :: FileWriteMode -> FilePath -> ByteString -> IO () Source #
FileContent [Line] Source # |
Instance details Defined in Propellor.Property.File Methods emptyFileContent :: [Line] Source # readFileContent :: FilePath -> IO [Line] Source # writeFileContent :: FileWriteMode -> FilePath -> [Line] -> IO () Source #

data FileWriteMode Source #

Constructors

NormalWrite |
ProtectedWrite |

fileProperty :: (FileContent c, Eq c) => Desc -> (c -> c) -> FilePath -> Property UnixLike Source #

A property that applies a pure function to the content of a file.

fileProperty' :: (FileContent c, Eq c) => FileWriteMode -> Desc -> (c -> c) -> FilePath -> Property UnixLike Source #

stableTmpFor :: FilePath -> FilePath Source #

A temp file to use when writing new content for a file.

This is a stable name so it can be removed idempotently.

It ends with "~" so that programs that read many config files from a directory will treat it as an editor backup file, and not read it.

viaStableTmp :: (MonadMask m, MonadIO m) => (FilePath -> m ()) -> FilePath -> m () Source #

Creates/updates a file atomically, running the action to create the stable tmp file, and then renaming it into place.

configFileName :: String -> FilePath Source #

Generates a base configuration file name from a String, which can be put in a configuration directory, such as /etc/apt/sources.list.d/

The generated file name is limited to using ASCII alphanumerics, '_' and '.' , so that programs that only accept a limited set of characters will accept it. Any other characters will be encoded in escaped form.

Some file extensions, such as ".old" may be filtered out by programs that use configuration directories. To avoid such problems, it's a good idea to add an static prefix and extension to the result of this function. For example:

    aptConf foo = "/etc/apt/apt.conf.d" </> "propellor_" ++ configFileName foo <.> ".conf"

showConfigFileName :: Show v => v -> FilePath Source #

Applies configFileName to any value that can be shown.

readConfigFileName :: Read v => FilePath -> Maybe v Source #

Inverse of showConfigFileName.

data Overwrite Source #

Constructors

OverwriteExisting |
PreserveExisting |

checkOverwrite :: Overwrite -> FilePath -> (FilePath -> Property i) -> Property i Source #

When passed PreserveExisting, only ensures the property when the file does not exist.