From faf8cc228293414542ddc3f88ea50a4a1a59df52 Mon Sep 17 00:00:00 2001 From: Alexis Mousset Date: Tue, 17 Jan 2017 15:59:51 +0100 Subject: [PATCH] Fixes #10020: Document usage of \"file ensure keys->values present\" --- .../file_ensure_keys_values.cf | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/tree/30_generic_methods/file_ensure_keys_values.cf b/tree/30_generic_methods/file_ensure_keys_values.cf index f9cf10bb0..821059681 100644 --- a/tree/30_generic_methods/file_ensure_keys_values.cf +++ b/tree/30_generic_methods/file_ensure_keys_values.cf @@ -18,6 +18,57 @@ # @name File ensure keys -> values present # @description Ensure that the file contains all pairs of "key separator value", with arbitrary separator between each key and its value +# @documentation This method ensures key-value pairs are present in a file. +# +# #### Usage +# +# This method will iterate over the key-value pairs in the dict, and: +# +# * If the key is not defined in the destination, add the *key + separator + value* line. +# * If the key is already present in the file, replace the *key + separator +* anything by *key + separator + value* +# +# Keys are considered unique (to allow replacing the value), so you should use [file_ensure_lines_present](#file_ensure_lines_present) +# if you want to have multiple lines with the same key. +# +# #### Example +# +# If you have an initial file (`/etc/myfile.conf`) containing: +# +# ``` +# key1 = something +# key3 = value3 +# ``` +# +# To define key-value pairs, use the [variable_dict](#variable_dict) or +# [variable_dict_from_file](#variable_dict_from_file) methods. +# +# For example, if you use the following content (stored in `/tmp/data.json`): +# +# ```json +# { +# "key1": "value1", +# "key2": "value2" +# } +# ``` +# +# With the following policy: +# +# ``` +# # Define the `content` variable in the `configuration` prefix from the json file +# variable_dict_from_file("configuration", "content", "/tmp/data.json") +# # Enforce the presence of the key-value pairs +# file_ensure_keys_values("/etc/myfile.conf", "configuration.content", " = ") +# +# ``` +# +# The destination file (`/etc/myfile.conf`) will contain: +# +# ``` +# key1 = value1 +# key3 = value3 +# key2 = value2 +# ``` +# # # @parameter file File name to edit # @parameter keys Dict structure containing the keys (keys of the dict), and values to define (values of the dict)