Puppet Heredoc (ARM-4) Submitted

[Henrik Lindberg]

Hi,
I have now finished the work on Puppet Heredoc ARM-4.
The proposal is updated and can be read here:
https://github.com/puppetlabs/armatures/blob/master/arm-4.heredoc/heredoc.md

There is now also a full implementation of this available from my branch
here:
https://github.com/hlindberg/puppet/tree/feature/master/heredoc

In short, puppet heredoc allows you to write text blocks in puppet
manifests with control over the left margin and escapes. Here are some
examples:

afunc(@(END))
This is the text that goes into the heredoc
it ends when a line with the end-token is seen.
END

afunc(@(END))
This is the text that goes into the heredoc
it ends when a line with the end-token is seen.
You can control the left margin by using a pipe
on the end line to denote where the margin is.
| END

afunc(@(END/tn))
This turns on escapes for tabs and newlines.
Here is a tab: \t
Here is a newline: \n
END

afunc(@(END:json))
This is supposed to be text in JSON.
If there is a validator for json available
errors will be generated if it is not valid.
END

For further examples and details, see the ARM text. (In the examples
above I am just sending of the value to some function, the @(TAG)
produces a value, so you can use this at any place in the logic where
you can place a string).

You can comment on this ARM here, do a pull request to the armatures
repo, or comment directly on a commit.

If you want to try out the implementation, you need to pull it from my
branch (shown above) and then run with the setting --parser future

Regards
- henrik

[Luke Kanies]

Hi Henrik,

I'm confused by the 'afunc' in the above examples - its pervasiveness in your examples implies it's required, but it doesn't actually appear to be based on the ARM. What am I missing?

--
Luke Kanies | http://about.me/lak | http://puppetlabs.com/ | +1-615-594-8199
Join us at PuppetConf 2013, August 22-23 in San Francisco - http://bit.ly/pupconf13

[Henrik Lindberg]

On 2013-23-04 23:54, Luke Kanies wrote:
> On Apr 23, 2013, at 7:13 AM, Henrik Lindberg <henrik....@cloudsmith.com> wrote:

>
> I'm confused by the 'afunc' in the above examples - its pervasiveness in your examples implies it's required, but it doesn't actually appear to be based on the ARM. What am I missing?
>

"afunc" simply a fictive name of a function, any function - should
perhaps have called it "foo" to make it more apparent :)

@(END)
text
END

produces a rvalue. Not so interesting to show it with
$a = @(END)
text
END

since you can do almost the same with just a string (no margin and no
detailed control of escapes though).

so - showing it with a function (here also passing additional parameters)

foo(@(END), 1, 2)
some text
END

Hope that clarifies what "afunc" is/was...

Regards
- henrik

[Luke Kanies]

> Hope that clarifies what "afunc" is/was…

Yep, that helps.

I'm curious at the chosen syntax here -- is @() a common syntax for heredocs? I'm more used to things like:

$foo = <<END
…
END

Was that more common syntax not a possibility for us?

[Henrik Lindberg]

On 2013-24-04 1:28, Luke Kanies wrote:

> I'm curious at the chosen syntax here -- is @() a common syntax for heredocs? I'm more used to things like:
>
> $foo = <<END

> �

> END
>
> Was that more common syntax not a possibility for us?
>

There is a note about that in the ARM (i.e. the issues with the Ruby
Heredoc).

Basically, it is difficult to use << which is also left shift.

Ruby heredoc also lacks several features that I implemented in the
Puppet Heredoc. In Ruby you typically have to do post processing to
remove the left margin (and other similar cleanups). (I hate doing that
in Ruby every time as it is brittle (indent the source text and it
breaks, etc).

So, I wanted a heredoc that was more feature rich and that was
unambiguous at the lexical level and at the same time supporting the
features I wanted to see (setting syntax and controlling escapes).

Example with whitespaces

@( This is the end : json /nrt )
text with a tab: \t and newline \n embedded as single chars
This is the end

With the @() notation, there is an unambiguous end to search for.

It is naturally possible to change it to any other non ambiguous tokens,
but I would like it to have an end character (if not I fear some other
features in the ARM proposal may have to be dropped).

Regards
- henrik

[Luke Kanies]

On Apr 23, 2013, at 6:17 PM, Henrik Lindberg

<henrik....@cloudsmith.com> wrote:

> On 2013-24-04 1:28, Luke Kanies wrote:
>
>> I'm curious at the chosen syntax here -- is @() a common syntax for heredocs? I'm more used to things like:
>>
>> $foo = <<END

>> …

>> END
>>
>> Was that more common syntax not a possibility for us?
> There is a note about that in the ARM (i.e. the issues with the Ruby Heredoc).
>
> Basically, it is difficult to use << which is also left shift.
>
> Ruby heredoc also lacks several features that I implemented in the Puppet Heredoc. In Ruby you typically have to do post processing to remove the left margin (and other similar cleanups). (I hate doing that in Ruby every time as it is brittle (indent the source text and it breaks, etc).
>
> So, I wanted a heredoc that was more feature rich and that was unambiguous at the lexical level and at the same time supporting the features I wanted to see (setting syntax and controlling escapes).
>
> Example with whitespaces
>
> @( This is the end : json /nrt )
> text with a tab: \t and newline \n embedded as single chars
> This is the end
>
> With the @() notation, there is an unambiguous end to search for.
>
> It is naturally possible to change it to any other non ambiguous tokens, but I would like it to have an end character (if not I fear some other features in the ARM proposal may have to be dropped).

Excellent, that's very helpful; thanks.