Add systemd::escape function

Add a systemd escape function.

```puppet
systemd::escape('/foo/bar')
```
returns `-foo-bar`

while the path escape can be executed as

```puppet
systemd::escape('/foo/bar',true)
```

to return 'foo-bar'

Author: traylenator

README.md

@@ -373,6 +373,20 @@ loginctl_user { 'foo':
 
 or as a hash via the `systemd::loginctl_users` parameter.
 
+### Systemd Escape Function
+Escapes strings as `systemd-escape` command does.
+
+```puppet
+$result = systemd::escape('foo::bar/')
+```
+`$result` would be `foo::bar-`
+
+or path escape as if with `-p` option.
+
+```puppet
+$result = systemd::escape('/mnt/foobar/', true)
+```
+`$result` would be `mnt-foobar`.
 
 ## Transfer Notice
 

REFERENCE.md

@@ -35,6 +35,10 @@
 
 * [`loginctl_user`](#loginctl_user): An arbitrary name used as the identity of the resource.
 
+### Functions
+
+* [`systemd::escape`](#systemdescape): Escape strings as systemd-escape does.
+
 ### Data types
 
 * [`Systemd::Dropin`](#systemddropin): custom datatype that validates filenames/paths for valid systemd dropin files
@@ -1112,6 +1116,60 @@ An arbitrary name used as the identity of the resource.
 The specific backend to use for this `loginctl_user` resource. You will seldom need to specify this --- Puppet will
 usually discover the appropriate provider for your platform.
 
+## Functions
+
+### <a name="systemdescape"></a>`systemd::escape`
+
+Type: Puppet Language
+
+Escape strings as systemd-escape does.
+
+#### Examples
+
+##### Escaping a string
+
+```puppet
+$result = systemd::escape('foo::bar')
+```
+
+##### Escaping a path
+
+```puppet
+$result = systemd::escape('/mnt/foobar',true)
+```
+
+#### `systemd::escape(String[1] $input, Boolean $path = false)`
+
+The systemd::escape function.
+
+Returns: `String` String
+
+##### Examples
+
+###### Escaping a string
+
+```puppet
+$result = systemd::escape('foo::bar')
+```
+
+###### Escaping a path
+
+```puppet
+$result = systemd::escape('/mnt/foobar',true)
+```
+
+##### `input`
+
+Data type: `String[1]`
+
+Input string
+
+##### `path`
+
+Data type: `Boolean`
+
+Use path (-p) ornon-path  style escaping.
+
 ## Data types
 
 ### <a name="systemddropin"></a>`Systemd::Dropin`

functions/escape.pp

@@ -0,0 +1,43 @@
+# @summary Escape strings as systemd-escape does.
+# @param input Input string
+# @param path Use path (-p) ornon-path  style escaping.
+# @return String
+# @example Escaping a string
+#   $result = systemd::escape('foo::bar')
+# @example Escaping a path
+#   $result = systemd::escape('/mnt/foobar',true)
+function systemd::escape(String[1] $input, Boolean $path = false) >> String {
+  # Escape method is defined
+  # https://www.freedesktop.org/software/systemd/man/systemd.unit.html
+
+  # fail path if . on end.
+  if $path and $input[-1] == '.' {
+    fail('A path can not end in a \'.\'')
+  }
+
+  # De-duplicate any `/` and prefix,suffix `/` if file
+  if $path {
+    $_chomped = $input.regsubst('/+$','').regsubst('^/+','').regsubst('//+','/')
+  } else {
+    $_chomped = $input
+  }
+
+  # Docs talk of escaping `:` also but seems not to be the case in reality.
+  #
+  $_output = $_chomped.map |$_i, $_token | {
+    case $_token {
+      '.': {
+        $_escaped = $_i ? {
+          0       => '\x2e',
+          default => $_token,
+        }
+      }
+      '/': { $_escaped = '-' }
+      ',': { $_escaped = '\x2c' }
+      default: { $_escaped = $_token }
+    }
+    $_escaped
+  }.join
+
+  return $_output
+}

spec/functions/escape_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+describe 'systemd::escape' do
+  context 'with path false' do
+    it { is_expected.to run.with_params('foo', false).and_return('foo') }
+    it { is_expected.to run.with_params('foo/bar/.', false).and_return('foo-bar-.') }
+    it { is_expected.to run.with_params('/foo/bar/', false).and_return('-foo-bar-') }
+    it { is_expected.to run.with_params('//foo//bar//', false).and_return('--foo--bar--') }
+    it { is_expected.to run.with_params('//foo:bar,foo_bar.//', false).and_return('--foo:bar\x2cfoo_bar.--') }
+    it { is_expected.to run.with_params('.foo', false).and_return('\x2efoo') }
+  end
+  context 'with path true' do
+    it { is_expected.to run.with_params('foo', true).and_return('foo') }
+    it { is_expected.to run.with_params('foo/bar/.', true).and_raise_error(%r{ path can not end}) }
+    it { is_expected.to run.with_params('/foo/bar/', true).and_return('foo-bar') }
+    it { is_expected.to run.with_params('//foo//bar//', true).and_return('foo-bar') }
+    it { is_expected.to run.with_params('//foo:bar,foo_bar.//', true).and_return('foo:bar\x2cfoo_bar.') }
+    it { is_expected.to run.with_params('.foo', true).and_return('\x2efoo') }
+  end
+end