DscResources/Carbon_IniFile/Carbon_IniFile.psm1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

& (Join-Path -Path $PSScriptRoot -ChildPath '..\Initialize-CarbonDscResource.ps1' -Resolve)

function Get-TargetResource
{
    [CmdletBinding()]
    [OutputType([Collections.Hashtable])]
    param
    (
        [Parameter(Mandatory=$true)]
        [string]
        # The path to the file to update.
        $Path,

        [string]
        # The section of the INI file where the setting can be found.
        $Section,

        [Parameter(Mandatory=$true)]
        [string]
        # The name of the INI setting.
        $Name,

        [string]
        # The value of the INI setting.
        $Value,

        [Switch]
        # The INI file being modified is case-sensitive.
        $CaseSensitive,

        [Switch]
        # If `$true`, creates the INI file if it doesn't exist.
        $Force,

        [ValidateSet("Present","Absent")]
        [string]
        # Create or delete the INI setting?
        $Ensure = 'Present'
    )
    
    Set-StrictMode -Version 'Latest'

    $ini = @{ }
    if( (Test-Path -Path $Path -PathType Leaf) )
    {
        $ini = Split-Ini -Path $Path -AsHashtable -CaseSensitive:$CaseSensitive
    }
    else
    {
        if( -not $Force )
        {
            Write-Error ('INI file ''{0}'' not found. Set the `Force` property to `true` to create this INI file when it doesn''t exist.' -f $Path)
            return
        }
    }
    
    $key = $Name
    if( $Section )
    {
        $key = '{0}.{1}' -f $Section,$Name
    }
    
    $currentValue = $null
    $Ensure = 'Absent'
    if( $ini.ContainsKey( $key ) )
    {
        $currentValue = $ini[$key].Value
        $Ensure = 'Present';
    }
    
    @{
        Path = $Path;
        Section = $Section;
        Name = $Name;
        Value = $currentValue;
        CaseSensitive = [bool]$CaseSensitive;
        Force = [bool]$Force
        Ensure = $Ensure;
    }
}

function Set-TargetResource
{
    <#
    .SYNOPSIS
    DSC resource for managing settings in INI files.
 
    .DESCRIPTION
    The `Carbon_IniFile` resource sets or removes settings from INI files.
 
    `Carbon_IniFile` is new in Carbon 2.0.
 
    .LINK
    Remove-IniEntry
 
    .LINK
    Set-IniEntry
 
    .LINK
    Split-Ini
 
    .EXAMPLE
    >
    Demonstrates how to create/set a setting in sectionless INI file.
 
        Carbon_IniFile SetNpmPrefix
        {
            Path = 'C:\Program Files\nodejs\node_modules\npm\npmrc'
            Name = 'prefix';
            Value = 'C:\node-global-modules';
            CaseSensitive = $true;
        }
 
    In this case, we're setting the `prefix` NPM setting to `C:\node-global-modules` in the `C:\Program Files\nodejs\node_modules\npm\npmrc` file. It is expected this file exists and you'll get an error if it doesn't. NPM configuration files are case-sensitive, so the `CaseSensitive` property is set to `$true`.
 
    This line will be added to the INI file:
 
        prefix = C:\node-global-modules
 
    .EXAMPLE
    >
    Demonstrates how to create/set a setting in an INI file with sections.
 
        Carbon_IniFile SetBuildUserMercurialUsername
        {
            Path = 'C:\Users\BuildUser\mercurial.ini'
            Section = 'ui';
            Name = 'username';
            Force = $true;
            Value = 'Build User <builduser@example.com>';
        }
 
    In this case, we're setting the 'username' setting in the 'ui' section of the `C:\Users\BuildUser\mercurial.ini` file to `Build User <builduser@example.com>`. Since the `$Force` property is `$true`, if the file doesn't exist, it will be created. These lines will be added to the ini file:
 
        [ui]
        username = Build User <builduser@example.com>
 
    .EXAMPLE
    >
    Demonstrates how to remove a setting from a case-sensitive INI file.
 
        Carbon_IniFile RemoveNpmPrefix
        {
            Path = 'C:\Program Files\nodejs\node_modules\npm\npmrc'
            Name = 'prefix';
            CaseSensitive = $true;
            Ensure = 'Absent';
        }
 
    .EXAMPLE
    >
    Demonstrates how to remove a setting from an INI file that organizes settings into sections.
 
        Carbon_IniFile RemoveBuildUserMercurialUsername
        {
            Path = 'C:\Users\BuildUser\mercurial.ini'
            Section = 'ui';
            Name = 'username';
            Ensure = 'Absent';
        }
    #>

    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory=$true)]
        [string]
        # The path to the file to update.
        $Path,

        [string]
        # The section of the INI file where the setting can be found.
        $Section,

        [Parameter(Mandatory=$true)]
        [string]
        # The name of the INI setting.
        $Name,

        [string]
        # The value of the INI setting.
        $Value,

        [Switch]
        # The INI file being modified is case-sensitive.
        $CaseSensitive,

        [Switch]
        # If `$true`, creates the INI file if it doesn't exist.
        $Force,

        [ValidateSet("Present","Absent")]
        [string]
        # Create or delete the INI setting?
        $Ensure = 'Present'
    )
    
    Set-StrictMode -Version 'Latest'

    $resource = Get-TargetResource -Path $Path -Section $Section -Name $Name -Force:$Force -CaseSensitive:$CaseSensitive
    if( -not $resource )
    {
        return
    }

    if( -not (Test-Path -Path $Path -PathType Leaf) -and $Force )
    {
        New-Item -Path $Path -ItemType 'File' -Force | Out-Null
    }

    $fullName = $Name
    if( $Section )
    {
        $fullName = '{0}.{1}' -f $Section,$Name
    }

    if( $resource.Ensure -eq 'Present' -and $Ensure -eq 'Absent' )
    {
        Write-Verbose ('{0}: {1}: removing' -f $Path,$fullName)
        Remove-IniEntry -Path $Path -Section $Section -Name $Name -CaseSensitive:$CaseSensitive
        return
    }

    if( $Ensure -eq 'Present' )
    {
        Write-Verbose ('{0}: {1}: setting' -f $Path,$fullName)
        Set-IniEntry -Path $Path -Section $Section -Name $Name -Value $Value -CaseSensitive:$CaseSensitive
    }
}

function Test-TargetResource
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [Parameter(Mandatory=$true)]
        [string]
        # The path to the file to update.
        $Path,

        [string]
        # The section of the INI file where the setting can be found.
        $Section,

        [Parameter(Mandatory=$true)]
        [string]
        # The name of the INI setting.
        $Name,

        [string]
        # The value of the INI setting.
        $Value,

        [Switch]
        # The INI file being modified is case-sensitive.
        $CaseSensitive,

        [Switch]
        # If `$true`, creates the INI file if it doesn't exist.
        $Force,

        [ValidateSet("Present","Absent")]
        [string]
        # Create or delete the INI setting?
        $Ensure = 'Present'
    )
    
    Set-StrictMode -Version 'Latest'

    $resource = Get-TargetResource -Path $Path -Section $Section -Name $Name -Force:$Force
    if( -not $resource )
    {
        return $false
    }

    $fullName = $Name
    if( $Section )
    {
        $fullName = '{0}.{1}' -f $Section,$Name
    }

    if( $Ensure -eq 'Present' )
    {
        $result = ($resource.Value -eq $Value)
        if( $CaseSensitive )
        {
            $result = ($resource.Value -ceq $Value)
        }

        if( $result )
        {
            Write-Verbose ('{0}: {1}: current value unchanged' -f $Path,$fullName)
        }
        else
        {
            Write-Verbose ('{0}: {1}: current value differs' -f $Path,$fullName)
        }
    }
    else
    {
        $result = ($resource.Ensure -eq 'Absent')
        if( $result )
        {
            Write-Verbose ('{0}: {1}: not found' -f $Path,$fullName) 
        }
        else
        {
            Write-Verbose ('{0}: {1}: found' -f $Path,$fullName)
        }
    }
    return $result
}

Export-ModuleMember -Function '*-TargetResource'