Skip to content

Commit d59619d

Browse files
danielparksdanielparks
committed
Use tilde heredocs for readability
This changes most heredocs to use the tilde syntax with variable interpolation off. It indents the contents of the heredoc along with the final symbol. To maintain these changes, it enables `Layout/HeredocIndentation` and `Layout/ClosingHeredocIndentation` in Rubocop. The tilde syntax smartly strips the indentation, and allows for different indention of the closing identifier: ```ruby "test\n" == <<~'END' test END ``` This syntax was introduced in Ruby 2.3.0, so this will not pose compatibility problems. ### Tests that should fail Note that two tests couldn’t be updated to a more common heredoc format to avoid failing. It appears there is a problem with the way YARD parses parameters with defaults with a heredoc ([YARD #779][]). There is a work-around for that issue in `PuppetStrings::Yard::Handlers::Ruby::Base`, but it can’t work in these cases because YARD doesn’t provide enough source to read the whole heredoc content. Given that these are tests of the Puppet 3 style functions, it’s probably not worth pursuing this issue. [YARD #779]: lsegal/yard#779
1 parent 371e37f commit d59619d

26 files changed

+1498
-1711
lines changed

‎.rubocop.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ Layout/ArgumentAlignment:
124124
Layout/BeginEndAlignment:
125125
Enabled: false
126126
Layout/ClosingHeredocIndentation:
127-
Enabled: false
127+
Enabled: true
128128
Layout/EmptyComment:
129129
Enabled: false
130130
Layout/EmptyLineAfterGuardClause:
@@ -140,7 +140,7 @@ Layout/FirstArgumentIndentation:
140140
Layout/HashAlignment:
141141
Enabled: false
142142
Layout/HeredocIndentation:
143-
Enabled: false
143+
Enabled: true
144144
Layout/LeadingEmptyLines:
145145
Enabled: false
146146
Layout/SpaceAroundMethodCallOperator:

‎spec/acceptance/generate_markdown_spec.rb

+15-15
Original file line numberDiff line numberDiff line change
@@ -11,30 +11,30 @@
1111
sut_tmp_path
1212
end
1313

14-
expected = <<-EOF
15-
# Reference
14+
expected = <<~'EOF'
15+
# Reference
1616
17-
## Classes
18-
* [`test`](#test): This class exists to serve as fixture data for testing the puppet strings face
17+
## Classes
18+
* [`test`](#test): This class exists to serve as fixture data for testing the puppet strings face
1919
20-
## Classes
20+
## Classes
2121
22-
### test
22+
### test
2323
24-
#### Examples
25-
```puppet
26-
class { "test": }
27-
```
24+
#### Examples
25+
```puppet
26+
class { "test": }
27+
```
2828
29-
#### Parameters
29+
#### Parameters
3030
31-
##### `package_name`
31+
##### `package_name`
3232
33-
The name of the package
33+
The name of the package
3434
35-
##### `service_name`
35+
##### `service_name`
3636
37-
The name of the service
37+
The name of the service
3838
3939
EOF
4040

‎spec/fixtures/acceptance/modules/test/lib/puppet/datatypes/acceptancedatatype.rb

+2-2
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,13 @@
1010
# @param [Integer] param2 param2 func1 documentation
1111
# @return [Optional[String]]
1212
Puppet::DataTypes.create_type('AcceptanceDataType') do
13-
interface <<-PUPPET
13+
interface <<~'PUPPET'
1414
attributes => {
1515
param1 => Variant[Numeric, String[1,2]],
1616
param2 => { type => Optional[String[1]], value => "param2" }
1717
},
1818
functions => {
1919
func1 => Callable[[String, Integer], Optional[String]]
2020
}
21-
PUPPET
21+
PUPPET
2222
end

‎spec/fixtures/ruby/data_type.rb

+2-2
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@
88
# @param [Integer] param2 param2 documentation
99
# @return [Optional[String]]
1010
Puppet::DataTypes.create_type('UnitDataType') do
11-
interface <<-PUPPET
11+
interface <<~'PUPPET'
1212
attributes => {
1313
param1 => Variant[Numeric, String[1,2]],
1414
param2 => { type => Optional[String[1]], value => "param2" }
1515
},
1616
functions => {
1717
func1 => Callable[[String, Integer], Optional[String]]
1818
}
19-
PUPPET
19+
PUPPET
2020
end

‎spec/fixtures/ruby/func3x.rb

+9-10
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
11
# An example 3.x function
2-
Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC
3-
Documentation for an example 3.x function.
4-
@param param1 [String] The first parameter.
5-
@param param2 [Integer] The second parameter.
6-
@return [Undef]
7-
@example Calling the function.
8-
func3x('hi', 10)
9-
DOC
10-
) do |*args|
11-
#...
2+
Puppet::Parser::Functions.newfunction(:func3x, doc: <<~'DOC') do |*args|
3+
Documentation for an example 3.x function.
4+
@param param1 [String] The first parameter.
5+
@param param2 [Integer] The second parameter.
6+
@return [Undef]
7+
@example Calling the function.
8+
func3x('hi', 10)
9+
DOC
10+
# ...
1211
end

‎spec/fixtures/ruby/resource_api.rb

+13-13
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
Puppet::ResourceApi.register_type(
22
name: 'apt_key',
3-
docs: <<-EOS,
4-
@summary Example resource type using the new API.
5-
@raise SomeError
6-
This type provides Puppet with the capabilities to manage GPG keys needed
7-
by apt to perform package validation. Apt has it's own GPG keyring that can
8-
be manipulated through the `apt-key` command.
9-
@example here's an example
10-
apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
11-
source => 'http://apt.puppetlabs.com/pubkey.gpg'
12-
}
3+
docs: <<~'EOS',
4+
@summary Example resource type using the new API.
5+
@raise SomeError
6+
This type provides Puppet with the capabilities to manage GPG keys needed
7+
by apt to perform package validation. Apt has it's own GPG keyring that can
8+
be manipulated through the `apt-key` command.
9+
@example here's an example
10+
apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
11+
source => 'http://apt.puppetlabs.com/pubkey.gpg'
12+
}
1313
14-
**Autorequires**:
15-
If Puppet is given the location of a key file which looks like an absolute
16-
path this type will autorequire that file.
14+
**Autorequires**:
15+
If Puppet is given the location of a key file which looks like an absolute
16+
path this type will autorequire that file.
1717
EOS
1818
attributes: {
1919
ensure: {

‎spec/fixtures/ruby/resource_type.rb

+11-11
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
Puppet::Type.newtype(:database) do
2-
desc <<-DESC
3-
An example database server type.
4-
@option opts :foo bar
5-
@enum ensure :up Upstate
6-
@enum ensure :down Downstate
7-
@raise SomeError
8-
@example here's an example
9-
database { 'foo':
10-
address => 'qux.baz.bar',
11-
}
12-
DESC
2+
desc <<~'DESC'
3+
An example database server type.
4+
@option opts :foo bar
5+
@enum ensure :up Upstate
6+
@enum ensure :down Downstate
7+
@raise SomeError
8+
@example here's an example
9+
database { 'foo':
10+
address => 'qux.baz.bar',
11+
}
12+
DESC
1313
feature :encryption, 'The provider supports encryption.', methods: [:encrypt]
1414
ensurable do
1515
desc 'What state the database should be in.'

‎spec/unit/puppet-strings/describe_spec.rb

+85-85
Original file line numberDiff line numberDiff line change
@@ -15,125 +15,125 @@
1515
before :each do
1616
# Populate the YARD registry with both Puppet and Ruby source
1717

18-
YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
19-
Puppet::Type.newtype(:database) do
20-
desc 'An example database server resource type.'
21-
end
18+
YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby)
19+
Puppet::Type.newtype(:database) do
20+
desc 'An example database server resource type.'
21+
end
2222
SOURCE
2323

24-
YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
25-
Puppet::ResourceApi.register_type(
26-
name: 'apt_key',
27-
docs: <<-EOS,
28-
@summary Example resource type using the new API.
29-
@raise SomeError
30-
This type provides Puppet with the capabilities to manage GPG keys needed
31-
by apt to perform package validation. Apt has it's own GPG keyring that can
32-
be manipulated through the `apt-key` command.
33-
@example here's an example
34-
apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
35-
source => 'http://apt.puppetlabs.com/pubkey.gpg'
36-
}
37-
38-
**Autorequires**:
39-
If Puppet is given the location of a key file which looks like an absolute
40-
path this type will autorequire that file.
41-
EOS
42-
)
24+
YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby)
25+
Puppet::ResourceApi.register_type(
26+
name: 'apt_key',
27+
docs: <<~'EOS',
28+
@summary Example resource type using the new API.
29+
@raise SomeError
30+
This type provides Puppet with the capabilities to manage GPG keys needed
31+
by apt to perform package validation. Apt has it's own GPG keyring that can
32+
be manipulated through the `apt-key` command.
33+
@example here's an example
34+
apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
35+
source => 'http://apt.puppetlabs.com/pubkey.gpg'
36+
}
37+
38+
**Autorequires**:
39+
If Puppet is given the location of a key file which looks like an absolute
40+
path this type will autorequire that file.
41+
EOS
42+
)
4343
SOURCE
4444

45-
YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
46-
Puppet::Type.type(:file).newproperty(:content) do
47-
include Puppet::Util::Checksums
48-
include Puppet::DataSync
45+
YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby)
46+
Puppet::Type.type(:file).newproperty(:content) do
47+
include Puppet::Util::Checksums
48+
include Puppet::DataSync
4949
50-
attr_reader :actual_content
50+
attr_reader :actual_content
5151
52-
desc <<-'EOT'
53-
The desired contents of a file, as a string. This attribute is mutually
54-
exclusive with `source` and `target`.
55-
EOT
56-
end
52+
desc <<~'EOT'
53+
The desired contents of a file, as a string. This attribute is mutually
54+
exclusive with `source` and `target`.
55+
EOT
56+
end
5757
SOURCE
5858

59-
YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
60-
Puppet::Type.newtype(:file) do
61-
include Puppet::Util::Checksums
62-
include Puppet::Util::Backups
63-
include Puppet::Util::SymbolicFileMode
59+
YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby)
60+
Puppet::Type.newtype(:file) do
61+
include Puppet::Util::Checksums
62+
include Puppet::Util::Backups
63+
include Puppet::Util::SymbolicFileMode
6464
65-
@doc = "Manages files, including their content, ownership, and permissions.
65+
@doc = "Manages files, including their content, ownership, and permissions.
6666
67-
The `file` type can manage normal files, directories, and symlinks; the
68-
type should be specified in the `ensure` attribute."
67+
The `file` type can manage normal files, directories, and symlinks; the
68+
type should be specified in the `ensure` attribute."
6969
70-
newparam(:path) do
71-
desc <<-'EOT'
72-
The path to the file to manage. Must be fully qualified.
70+
newparam(:path) do
71+
desc <<~'EOT'
72+
The path to the file to manage. Must be fully qualified.
7373
74-
On Windows, the path should include the drive letter and should use `/` as
75-
the separator character (rather than `\\`).
76-
EOT
77-
isnamevar
78-
end
74+
On Windows, the path should include the drive letter and should use `/` as
75+
the separator character (rather than `\`).
76+
EOT
77+
isnamevar
78+
end
7979
80-
end
80+
end
8181
SOURCE
8282

83-
YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
84-
Puppet::Type.type(:file).newproperty(:source) do
85-
include Puppet::Util::Checksums
86-
include Puppet::DataSync
83+
YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby)
84+
Puppet::Type.type(:file).newproperty(:source) do
85+
include Puppet::Util::Checksums
86+
include Puppet::DataSync
8787
88-
attr_reader :actual_content
88+
attr_reader :actual_content
8989
90-
desc <<-'EOT'
91-
The desired contents of a file, as a string. This attribute is mutually
92-
exclusive with `source` and `target`.
93-
EOT
94-
end
90+
desc <<-'EOT'
91+
The desired contents of a file, as a string. This attribute is mutually
92+
exclusive with `source` and `target`.
93+
EOT
94+
end
9595
SOURCE
9696
end
9797

9898
describe 'rendering DESCRIBE to stdout' do
9999
it 'outputs the expected describe content for the list of types' do
100-
output = <<-DATA
101-
These are the types known to puppet:
102-
apt_key - This type provides Puppet with the capabiliti ...
103-
database - An example database server resource type.
104-
file - Manages files, including their content, owner ...
100+
output = <<~'DATA'
101+
These are the types known to puppet:
102+
apt_key - This type provides Puppet with the capabiliti ...
103+
database - An example database server resource type.
104+
file - Manages files, including their content, owner ...
105105
DATA
106106
expect { described_class.render(nil, true) }.to output(output).to_stdout
107107
end
108108
it 'outputs the expected describe content for a type' do
109-
output = <<-DATA
109+
output = <<~'DATA'
110110
111-
file
112-
====
113-
Manages files, including their content, ownership, and permissions.
111+
file
112+
====
113+
Manages files, including their content, ownership, and permissions.
114114
115-
The `file` type can manage normal files, directories, and symlinks; the
116-
type should be specified in the `ensure` attribute.
115+
The `file` type can manage normal files, directories, and symlinks; the
116+
type should be specified in the `ensure` attribute.
117117
118-
Parameters
119-
----------
118+
Parameters
119+
----------
120120
121-
- **content**
122-
The desired contents of a file, as a string. This attribute is mutually
123-
exclusive with `source` and `target`.
121+
- **content**
122+
The desired contents of a file, as a string. This attribute is mutually
123+
exclusive with `source` and `target`.
124124
125-
- **path**
126-
The path to the file to manage. Must be fully qualified.
125+
- **path**
126+
The path to the file to manage. Must be fully qualified.
127127
128-
On Windows, the path should include the drive letter and should use `/` as
129-
the separator character (rather than `\\`).
128+
On Windows, the path should include the drive letter and should use `/` as
129+
the separator character (rather than `\`).
130130
131-
- **source**
132-
The desired contents of a file, as a string. This attribute is mutually
133-
exclusive with `source` and `target`.
131+
- **source**
132+
The desired contents of a file, as a string. This attribute is mutually
133+
exclusive with `source` and `target`.
134134
135-
Providers
136-
---------
135+
Providers
136+
---------
137137
DATA
138138
expect { described_class.render(['file']) }.to output(output).to_stdout
139139
end

0 commit comments

Comments
 (0)