Generate the reference from the runmode

lib/puppet/reference/configuration.rb

@@ -1,15 +1,12 @@
 # frozen_string_literal: true
 
 config = Puppet::Util::Reference.newreference(:configuration, :depth => 1, :doc => "A reference for all settings") do
-  docs = {}
-  Puppet.settings.each do |name, object|
-    docs[name] = object
-  end
+  str = +''
+  unix_runmode_root = Puppet::Util::UnixRunMode.new(:server, true, false)
+  unix_runmode_user = Puppet::Util::UnixRunMode.new(:server, false, false)
+  windows_runmode = Puppet::Util::WindowsRunMode.new(:server, true, false)
 
-  str = ''.dup
-  docs.sort { |a, b|
-    a[0].to_s <=> b[0].to_s
-  }.each do |name, object|
+  Puppet.settings.sort_by { |name, _| name.to_s }.each do |name, object|
     # Make each name an anchor
     header = name.to_s
     str << markdown_header(header, 3)
@@ -23,33 +20,34 @@
     str << "\n\n"
 
     # Now print the data about the item.
-    val = object.default
-    case name.to_s
-    when 'vardir'
-      val = 'Unix/Linux: /opt/puppetlabs/puppet/cache -- Windows: C:\ProgramData\PuppetLabs\puppet\cache -- Non-root user: ~/.puppetlabs/opt/puppet/cache'
-    when 'publicdir'
-      val = 'Unix/Linux: /opt/puppetlabs/puppet/public -- Windows: C:\ProgramData\PuppetLabs\puppet\public -- Non-root user: ~/.puppetlabs/opt/puppet/public'
-    when 'confdir'
-      val = 'Unix/Linux: /etc/puppetlabs/puppet -- Windows: C:\ProgramData\PuppetLabs\puppet\etc -- Non-root user: ~/.puppetlabs/etc/puppet'
-    when 'codedir'
-      val = 'Unix/Linux: /etc/puppetlabs/code -- Windows: C:\ProgramData\PuppetLabs\code -- Non-root user: ~/.puppetlabs/etc/code'
-    when 'rundir'
-      val = 'Unix/Linux: /var/run/puppetlabs -- Windows: C:\ProgramData\PuppetLabs\puppet\var\run -- Non-root user: ~/.puppetlabs/var/run'
-    when 'logdir'
-      val = 'Unix/Linux: /var/log/puppetlabs/puppet -- Windows: C:\ProgramData\PuppetLabs\puppet\var\log -- Non-root user: ~/.puppetlabs/var/log'
-    when 'hiera_config'
-      val = '$confdir/hiera.yaml. However, for backwards compatibility, if a file exists at $codedir/hiera.yaml, Puppet uses that instead.'
-    when 'certname'
-      val = "the Host's fully qualified domain name, as determined by Facter"
-    when 'hostname'
-      val = "(the system's fully qualified hostname)"
-    when 'domain'
-      val = "(the system's own domain)"
-    when 'srv_domain'
-      val = 'example.com'
-    when 'http_user_agent'
-      val = 'Puppet/<version> Ruby/<version> (<architecture>)'
-    end
+    val = case name.to_s
+          when 'vardir'
+            "Unix/Linux: #{unix_runmode_root.var_dir} -- Windows: #{windows_runmode.var_dir} -- Non-root user: #{unix_runmode_user.var_dir}"
+          when 'publicdir'
+            "Unix/Linux: #{unix_runmode_root.public_dir} -- Windows: #{windows_runmode.public_dir} -- Non-root user: #{unix_runmode_user.public_dir}"
+          when 'confdir'
+            "Unix/Linux: #{unix_runmode_root.conf_dir} -- Windows: #{windows_runmode.conf_dir} -- Non-root user: #{unix_runmode_user.conf_dir}"
+          when 'codedir'
+            "Unix/Linux: #{unix_runmode_root.code_dir} -- Windows: #{windows_runmode.code_dir} -- Non-root user: #{unix_runmode_user.code_dir}"
+          when 'rundir'
+            "Unix/Linux: #{unix_runmode_root.run_dir} -- Windows: #{windows_runmode.run_dir} -- Non-root user: #{unix_runmode_user.run_dir}"
+          when 'logdir'
+            "Unix/Linux: #{unix_runmode_root.log_dir} -- Windows: #{windows_runmode.log_dir} -- Non-root user: #{unix_runmode_user.log_dir}"
+          when 'hiera_config'
+            '$confdir/hiera.yaml. However, for backwards compatibility, if a file exists at $codedir/hiera.yaml, Puppet uses that instead.'
+          when 'certname'
+            "the Host's fully qualified domain name, as determined by Facter"
+          when 'hostname'
+            "(the system's fully qualified hostname)"
+          when 'domain'
+            "(the system's own domain)"
+          when 'srv_domain'
+            'example.com'
+          when 'http_user_agent'
+            'Puppet/<version> Ruby/<version> (<architecture>)'
+          else
+            object.default
+          end
 
     # Leave out the section information; it was apparently confusing people.
     # str << "- **Section**: #{object.section}\n"

lib/puppet/util/run_mode.rb

@@ -5,8 +5,10 @@
 module Puppet
   module Util
     class RunMode
-      def initialize(name)
+      def initialize(name, root = nil, expand = true)
         @name = name.to_sym
+        @root = root.nil? ? Puppet.features.root? : root
+        @expand = expand
       end
 
       attr_reader :name
@@ -55,15 +57,83 @@ def log_dir
       # @todo this code duplicates {Puppet::Settings#which\_configuration\_file}
       #   as described in {https://projects.puppetlabs.com/issues/16637 #16637}
       def which_dir(system, user)
-        if Puppet.features.root?
-          File.expand_path(system)
-        else
-          File.expand_path(user)
-        end
+        value = @root ? system : user
+        @expand ? File.expand_path(value) : value
       end
     end
 
     class UnixRunMode < RunMode
+      def conf_dir
+        ENV.fetch('CONFIGURATION_DIRECTORY') do
+          config_home = which_dir("/etc", ENV.fetch("XDG_CONFIG_HOME", "~/.config"))
+          File.join(config_home, packaging_name)
+        end
+      end
+
+      def code_dir
+        File.join(conf_dir, 'code')
+      end
+
+      def var_dir
+        ENV.fetch('STATE_DIRECTORY') do
+          data_home = which_dir("/var/lib", ENV.fetch("XDG_DATA_HOME", "~/.local/share"))
+          File.join(data_home, packaging_name)
+        end
+      end
+
+      def cache_directory
+        ENV.fetch('CACHE_DIRECTORY') do
+          cache_home = which_dir("/var/cache", ENV.fetch("XDG_CACHE_HOME", "~/.cache"))
+          File.join(cache_home, packaging_name)
+        end
+      end
+
+      def public_dir
+        File.join(cache_directory, 'public')
+      end
+
+      def run_dir
+        ENV.fetch('RUNTIME_DIRECTORY') do
+          runtime_dir = which_dir("/run", ENV.fetch("XDG_RUNTIME_DIR") { File.join('/run', 'user', ::Etc.getpwuid.uid) })
+          File.join(runtime_dir, packaging_name)
+        end
+      end
+
+      def log_dir
+        ENV.fetch('LOGS_DIRECTORY') do
+          which_dir(File.join('/var', 'log', packaging_name),
+                    File.join(ENV.fetch("XDG_STATE_HOME", "~/.local/state"), packaging_name, "logs"))
+        end
+      end
+
+      def pkg_config_path
+        # automatically picked up
+      end
+
+      def gem_cmd
+        '/usr/bin/gem'
+      end
+
+      def data_dir
+        File.join('/usr', 'share', packaging_name)
+      end
+
+      def common_module_dir
+        File.join(data_dir, 'modules')
+      end
+
+      def vendor_module_dir
+        File.join(data_dir, 'vendor_modules')
+      end
+
+      private
+
+      def packaging_name
+        'puppet'
+      end
+    end
+
+    class AIORunMode < RunMode
       def conf_dir
         which_dir("/etc/puppetlabs/puppet", "~/.puppetlabs/etc/puppet")
       end
@@ -107,27 +177,27 @@ def vendor_module_dir
 
     class WindowsRunMode < RunMode
       def conf_dir
-        which_dir(File.join(windows_common_base("puppet/etc")), "~/.puppetlabs/etc/puppet")
+        which_dir("puppet/etc", "etc/puppet")
       end
 
       def code_dir
-        which_dir(File.join(windows_common_base("code")), "~/.puppetlabs/etc/code")
+        which_dir("code", "etc/code")
       end
 
       def var_dir
-        which_dir(File.join(windows_common_base("puppet/cache")), "~/.puppetlabs/opt/puppet/cache")
+        which_dir("puppet/cache", "opt/puppet/cache")
       end
 
       def public_dir
-        which_dir(File.join(windows_common_base("puppet/public")), "~/.puppetlabs/opt/puppet/public")
+        which_dir("puppet/public", "opt/puppet/public")
       end
 
       def run_dir
-        which_dir(File.join(windows_common_base("puppet/var/run")), "~/.puppetlabs/var/run")
+        which_dir("puppet/var/run", "var/run")
       end
 
       def log_dir
-        which_dir(File.join(windows_common_base("puppet/var/log")), "~/.puppetlabs/var/log")
+        which_dir("puppet/var/log", "var/log")
       end
 
       def pkg_config_path
@@ -152,12 +222,16 @@ def vendor_module_dir
 
       private
 
+      def which_dir(system, user)
+        super(File.join(windows_common_base(system)), File.join('~/.puppetlabs', user))
+      end
+
       def installdir
         ENV.fetch('FACTER_env_windows_installdir', nil)
       end
 
       def windows_common_base(*extra)
-        [ENV.fetch('ALLUSERSPROFILE', nil), "PuppetLabs"] + extra
+        [ENV.fetch('ALLUSERSPROFILE', 'C:\ProgramData'), "PuppetLabs"] + extra
       end
     end
   end