fix(tofs): prepend the config-based source_files to the default

* https://github.com/saltstack-formulas/nginx-formula/pull/247#issuecomment-514262549
  - The main issue is that the `nginx-formula` has dynamic values being
    used as the default `source_files` -- there is no way to provide
    this from the pillar/config in a sensible fashion
  - Prepending to this default (rather than overriding it) resolves this
    problem entirely, without adding excessive entries to the `source`
* Closes #151

docs/TOFS_pattern.rst

@@ -325,6 +325,7 @@ We can simplify the ``conf.sls`` with the new ``files_switch`` macro to use in t
 
 
 * This uses ``config.get``, searching for ``ntp:tofs:source_files:Configure NTP`` to determine the list of template files to use.
+* If this returns a result, the default of ``['/etc/ntp.conf.jinja']`` will be appended to it.
 * If this does not yield any results, the default of ``['/etc/ntp.conf.jinja']`` will be used.
 
 In ``libtofs.jinja``, we define this new macro ``files_switch``.
@@ -426,7 +427,6 @@ The list of ``source_files`` can be given:
      tofs:
        source_files:
          Configure NTP:
-           - '/etc/ntp.conf.jinja'
            - '/etc/ntp.conf_alt.jinja'
 
 Resulting in:
@@ -434,10 +434,13 @@ Resulting in:
 .. code-block:: sls
 
          - source:
-           - salt://ntp/files/theminion/etc/ntp.conf.jinja
            - salt://ntp/files/theminion/etc/ntp.conf_alt.jinja
-           - salt://ntp/files/Debian/etc/ntp.conf.jinja
+           - salt://ntp/files/theminion/etc/ntp.conf.jinja
            - salt://ntp/files/Debian/etc/ntp.conf_alt.jinja
-           - salt://ntp/files/default/etc/ntp.conf.jinja
+           - salt://ntp/files/Debian/etc/ntp.conf.jinja
            - salt://ntp/files/default/etc/ntp.conf_alt.jinja
+           - salt://ntp/files/default/etc/ntp.conf.jinja
+
+Note: This does *not* override the default value.
+Rather, the value from the pillar/config is prepended to the default.
 

pillar.example

@@ -43,6 +43,8 @@ template:
     # dirs:
     #   files: files_alt
     #   default: default_alt
+    # The entries under `source_files` are prepended to the default source files
+    # given for the state
     # source_files:
     #   template-config-file-file-managed:
     #     - 'example_alt.tmpl'

template/config/file.sls

@@ -13,7 +13,7 @@ include:
 template-config-file-file-managed:
   file.managed:
     - name: {{ template.config }}
-    - source: {{ files_switch(['example.tmpl', 'example.tmpl.jinja'],
+    - source: {{ files_switch(['example.tmpl'],
                               lookup='template-config-file-file-managed'
                  )
               }}

template/libtofs.jinja

@@ -10,7 +10,7 @@
 
     Params:
       * source_files: ordered list of files to look for
-      * lookup: key under '<tplroot>:tofs:source_files' to override
+      * lookup: key under '<tplroot>:tofs:source_files' to prepend to the
         list of source files
       * default_files_switch: if there's no config (e.g. pillar)
         '<tplroot>:tofs:files_switch' this is the ordered list of grains to
@@ -55,14 +55,13 @@
       tplroot ~ ':tofs:files_switch',
       default_files_switch
   ) %}
-  {#- Lookup source_files (v2), files (v1), or fallback to source_files parameter #}
+  {#- Lookup source_files (v2), files (v1), or fallback to an empty list #}
   {%- set src_files = salt['config.get'](
       tplroot ~ ':tofs:source_files:' ~ lookup,
-      salt['config.get'](
-          tplroot ~ ':tofs:files:' ~ lookup,
-          source_files
-      )
+      salt['config.get'](tplroot ~ ':tofs:files:' ~ lookup, [])
   ) %}
+  {#- Append the default source_files #}
+  {%- set src_files = src_files + source_files %}
   {#- Only add to [''] when supporting older TOFS implementations #}
   {%- set path_prefix_exts = [''] %}
   {%- if v1_path_prefix != '' %}