(#19886) Add heredoc to Puppet DSL

This adds heredoc support to puppet.
(#19886) Add evaluation of Heredoc and syntax checking.

This adds Heredoc to the Puppet::Parser::AST and implements
transformation from the Pops model. It includes validation of the
heredoc syntax and implements the syntax validation as described in the
Heredoc ARM.
(#19886) Add a function that performs heredoc syntax checking for JSON

By using a Heredoc syntax string of "json", or that ends with "...+json"
the function added in this commit will perform a test parse and report
the failure.

The function can also be called directly from a manifest to syntax check
an aribtrary string - e.g. check_json_syntax("am I valid", "json").

When used in a heredoc the same is triggered by specifying the syntax in
the heredoc tag e.g. $a = @(END:json) ...
(#19886) Add ability to specify escapes for dq strings

It was a nuisance to not be able to control the escapes in a dq string.
This adds the ability to specify the escapes for a dq string the same
was as for a sq string.

In addition, the notation '/' turns on all escapes. The default for a dq
strings is not also to not use any escapes e.g. @(END) means escapes are
verbatim.
(maint) Remove commented code.
(maint) Fix tests that compensated for an error in model tree dumper

Two tests compared result from tree dumper compensating for a
(now fixed) dumper formatting error.
(#19886) Fix issues from review

This fixes a number of stylistic issues and adds comments for some
otherwise hard to understand logic.
(#19886) Change syntax check feature to use extensions/injector

This changes the heredoc feature to perform syntax checking to
lookup available syntax checkers via Puppet Bindings instead of
via special purpose parser functions.

This is good because the functions were not intended to be used from user
logic as one function per "syntax" was required. If a function is wanted
it should be a generic function that looks up the syntax.
(#19886) Correct issues from review (yardoc, use of '::')

- This corrects the calling a class method using CLASS::method instead
of CLASS.method.
- Yardoc corrected (check method does not return a value)
- Error message formatting improved.
(maint) Remove dead code from IssueReporter and improve summary message.

There was dead/bad code at the end of the assert_and_report method that
would make the method fail if called when there were no errors.

The emitted message is improved when there is one warning (it used the
plural form when there was one warning).
(#19886) Refactor AST::Heredoc to use injection of checker

- This changes the AST::Heredoc implementation to use the Puppet binder
  and inject syntax checkers instead of calling them as functions.
- This also alters the implementation to use the common error/warning
  reporting behavior in Puppet::Pops::IssueReporter.
- Tests added
- Yardoc updated
(yardoc) Remove faulty yardoc that implementation is abstract
(#19886) Add a Yaml syntax checker

This adds a yaml syntax checker and binds it as 'yaml'
(maint) Move & refactor test specific be_like for match of lexer tokens

Many tests define the same matcher (not all identical). This commit adds
a shared matcher 'match_tokens' that is used by the lexer tests under
pops.
(maint) Refactor requirement on rspec helpers for pops

The helper classes for rspec testing of pops related functionality was
included using __FILE__ relative paths instead of being placed in a
directory on the riby load path.

This commit moves the helpers (factory_rspec_helper,
parser_rspec_helper, and transformer_rspec_helper) and changes the
require statements to use a location under 'puppet_spec' in the test
that makes use of these helpers.
(maint) Cleanup empty lines
(#19886) Fix test with yaml issue not being triggered for ruby 1.8.7

The YAML parser in Ruby 1.8.7 is very permissive. The bad YAML used
to test that raised errors from the YAML parser gets processed did not
get an exception as expected. This commit replaces the problem with one
that triggers YAML parser in 1.8.7, and later rubies.
(maint) Fix lexing of heredoc after merge of master

Changes to the lexer's handling of braces and interpolation stack
required additional changes to handling of dqstring based heredoc.