The rewritten Puppet 2.7 language reference is live

[Nick Fagerlund]

Hi all,

I've finished the all new Puppet 2.7 language reference. EXCITING! Well, exciting to me, at least. Table of contents:

http://docs.puppetlabs.com/puppet/2.7/reference/

Visual index (for when you know what you're looking for but you don't know what it's called):

http://docs.puppetlabs.com/puppet/2.7/reference/lang_visual_index.html

And of course, use the navigation in the left sidebar to jump between pages.

Our goal here is to nail down every detail of how the Puppet language works, then cut new versions along with major Puppet releases. We'll eventually be expanding this versioned document with non-language details -- we've been referring to this plan as the "Puppet reference manual." Its purpose isn't to replace any of the guides or how-tos, but to lay down a "just the facts" baseline that lets you get in and out fast.

Anyway, we hope you find it useful. Thanks for using Puppet.

[wen1023 wu]

it's very useful,i think it's better than puppet guide,

2012/8/22 Nick Fagerlund <nick.fa...@puppetlabs.com>

--
You received this message because you are subscribed to the Google Groups "Puppet Users" group.
To view this discussion on the web visit https://groups.google.com/d/msg/puppet-users/-/bDBvT082CjQJ.
To post to this group, send email to puppet...@googlegroups.com.
To unsubscribe from this group, send email to puppet-users...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.

[Erik Dalén]

Very nice!

But I'm wondering about the section on "Reserved Variable Names" that
says that reusing fact names as variables in a local scope may cause
malfunctions. This is something I've done quite a lot without any
problem, is it considered unsupported and might break in future
versions?
The only issue is of course that you hide the fact in the local scope
so you get for example $::ipaddress and $ipaddress with different
values.

But with a defined type that has a ipaddress parameter it doesn't
really make much sense to name it anything else. And besides you can
never know what facts a system might have installed.

> --
> You received this message because you are subscribed to the Google Groups
> "Puppet Users" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/puppet-users/-/bDBvT082CjQJ.
> To post to this group, send email to puppet...@googlegroups.com.
> To unsubscribe from this group, send email to
> puppet-users...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/puppet-users?hl=en.

--
Erik Dalén

[Nick Fagerlund]

On Thursday, August 23, 2012 1:55:15 AM UTC-7, Erik Dalén wrote:

But I'm wondering about the section on "Reserved Variable Names" that
says that reusing fact names as variables in a local scope may cause
malfunctions. This is something I've done quite a lot without any
problem, is it considered unsupported and might break in future
versions?

No no -- it's just that if you're declaring a class from someone else's module and they didn't use the $::fact idiom, overriding a fact might change the class's environment enough to break it. If you know what's going on in your classes you're fine, and if you're overriding a fact in a scope that doesn't beget any other scopes you're fine. I should rewrite that to be more clear!

[Aaron Grewell]

Hi Nick, I have a suggestion. In
http://docs.puppetlabs.com/puppet/2.7/reference/lang_datatypes.html#hashes
it would be helpful to have a hash example that contains multiple keys
each with multiple subkeys. The way the commas are distributed in
that scenario is different from how commas are handled in resources
and properties which can be confusing. After reading the hash
section I ended up having to google for a more complete example and
I'm sure I'm not the only one.

Thanks again for your work, I really like the new layout.

-Aaron

[Nick Fagerlund]

On Thursday, August 23, 2012 12:47:16 PM UTC-7, Aaron Grewell wrote:

In http://docs.puppetlabs.com/puppet/2.7/reference/lang_datatypes.html#hashes
it would be helpful to have a hash example that contains multiple keys
each with multiple subkeys.

You're right, I'll put one in. (Although since sometime before 2.7, you can actually use trailing commas in hashes the same way you do in resource declarations. I'll add that to the docs too!)

[Henrik Lindberg]

EXCELLENT GUIDE !!!
I which that had been available when I started on Geppetto :)

Here are some things that I would like the documentation to clarify:

- How do I create strings that span multiple lines? (Since there is no
string concatenation operator 'x' + 'y' does not work). Can I write a
string that continues on the next line? If so, is the newline included
or not? Can I tell it to not include the newline? How is the line-break
encoded - if it is CR-LF in the pp-file, does the string contain that at
runtime?

- Can I write more complex expressions in an interpolation? Can I do
something like "The sum is ${$a + $b}", and if that is the case, is it
possible to have any expression interpolated (including nested strings
with interpolation)?

- The compiler allows ${a} without double quotes - which is a string
interpolation of $a. Which IIRC is slightly different than using $a
directly (getting an empty string if $a is undefined). I don't recall
seeing that in the documentation on the first read through.

- IIRC, Use of numerical variables $0 - $9 as a result of regular
expression matching was not mentioned. When talking about variables I
think it is worth noting that you should not use $0 - $9 for anything
else (or you may be surprised as the regexp match creates an inner scope
where these variables refer to match results). (IMO use of $0-$9 should
be reserved for that purpose and they should not be assignable).

- Arrays and Hashes are mutable; which is either an bug or a language
feature. While it is not allowed to directly change a variable, it can
be indirectly modified if it refers to an array or hash. Great if the
documentation can clarify if this is a supported feature or should be
avoided. i.e. $a = [1,2,3] $a[0] = 10. (IMO, this is problematic as any
logic can refer to the variable and assign to an entry - at least last I
tried).


Again, an excellent language reference!
Regards
- henrik

[Aaron Grewell]

That looks really good. After reviewing my code, I suspect that my
issue was not that Puppet's approach was inconsistent but rather that
I never use this kind of nesting in my resource declarations. It's
common for hashes though, so the new examples are a definite plus.

[Nick Fagerlund]

Err, I think google groups may have eaten my response. But THANK YOU, and I'm adjusting the guide to patch all these holes as we speak.

[Nick Fagerlund]

Yeah that reply isn't coming back. Anyway, I was totally hoping you'd chime in with some holes you found. :)

On Friday, August 24, 2012 6:33:01 AM UTC-7, Henrik Lindberg wrote:

- How do I create strings that span multiple lines? (Since there is no
string concatenation operator 'x' + 'y' does not work). Can I write a
string that continues on the next line? If so, is the newline included
or not? Can I tell it to not include the newline? How is the line-break
encoded - if it is CR-LF in the pp-file, does the string contain that at
runtime?

Added this! Line breaks are preserved, line break format is preserved (so whatever you used in the file, that's what you get in your strings, I don't like it either), you can use \n to get literal Unix line breaks, but you can't use \r\n to get Windows ones because \r doesn't exist. There isn't an ignore-whitespace option for strings.

- Can I write more complex expressions in an interpolation? Can I do
something like "The sum is ${$a + $b}", and if that is the case, is it
possible to have any expression interpolated (including nested strings
with interpolation)?

Nope! Thanks for reminding me about this, I remember trying to make Puppet do this and being disappointed.
 

- The compiler allows ${a} without double quotes - which is a string
interpolation of $a. Which IIRC is slightly different than using $a
directly (getting an empty string if $a is undefined). I don't recall
seeing that in the documentation on the first read through.

If the parser allows this, it's getting blocked elsewhere in the system, because Puppet definitely fails compilation hard if you try to use ${var} outside a double-quoted string.
 

- IIRC, Use of numerical variables $0 - $9 as a result of regular
expression matching was not mentioned. When talking about variables I
think it is worth noting that you should not use $0 - $9 for anything
else (or you may be surprised as the regexp match creates an inner scope
where these variables refer to match results). (IMO use of $0-$9 should
be reserved for that purpose and they should not be assignable).

Ahhh good call. Actually, I just tested and it looks like assigning directly to $\d is a no-op??? That's pretty wild. Anyway, putting them in as reserved variable names. 

- Arrays and Hashes are mutable; which is either an bug or a language
feature. While it is not allowed to directly change a variable, it can
be indirectly modified if it refers to an array or hash. Great if the
documentation can clarify if this is a supported feature or should be
avoided. i.e. $a = [1,2,3] $a[0] = 10. (IMO, this is problematic as any
logic can refer to the variable and assign to an entry - at least last I
tried).

D:< EWW. "Problematic" is putting it mildly, especially since behavior is inconsistent between arrays and hashes. (Both can add, only arrays can reassign to existing indexes.) But I'd better document it anyhow.

[Henrik Lindberg]

Hi,

On 2012-25-08 1:02, Nick Fagerlund wrote:
> Yeah that reply isn't coming back. Anyway, I was totally hoping you'd
> chime in with some holes you found. :)
>

Comments below...

> On Friday, August 24, 2012 6:33:01 AM UTC-7, Henrik Lindberg wrote:
>
> - How do I create strings that span multiple lines? (Since there is no
> string concatenation operator 'x' + 'y' does not work). Can I write a
> string that continues on the next line? If so, is the newline included
> or not? Can I tell it to not include the newline? How is the line-break
> encoded - if it is CR-LF in the pp-file, does the string contain
> that at
> runtime?
>
> Added this! Line breaks are preserved, line break format is preserved
> (so whatever you used in the file, that's what you get in your strings,
> I don't like it either), you can use \n to get literal Unix line breaks,
> but you can't use \r\n to get Windows ones because \r doesn't exist.
> There isn't an ignore-whitespace option for strings.>
>

So, I guess you really have to use a template file instead if you want
something long and/or need more control over whitepsace.

> - Can I write more complex expressions in an interpolation? Can I do
> something like "The sum is ${$a + $b}", and if that is the case, is it
> possible to have any expression interpolated (including nested strings
> with interpolation)?
>
>
> Nope! Thanks for reminding me about this, I remember trying to make
> Puppet do this and being disappointed.
>

The thing is that it is supported in the parser (at least IIRC, but I
have not checked the last couple of months if anything changed). So the
question is if it is supposed to be in the language or not even if not
implemented correctly (i.e. language bug, or runtime bug?).

>
> - The compiler allows ${a} without double quotes - which is a string
> interpolation of $a. Which IIRC is slightly different than using $a
> directly (getting an empty string if $a is undefined). I don't recall
> seeing that in the documentation on the first read through.
>
>
> If the parser allows this, it's getting blocked elsewhere in the system,
> because Puppet definitely fails compilation hard if you try to use
> ${var} outside a double-quoted string.
>

Makes sense, and I should adjust Geppetto validation. It now accepts
${var} to have the same meaning as "${var}". One wonders why it is in
the grammar in the first place - maybe just a bug, or to give an
opportunity to say "${var} must be placed in a double quoted string?

> - IIRC, Use of numerical variables $0 - $9 as a result of regular
> expression matching was not mentioned. When talking about variables I
> think it is worth noting that you should not use $0 - $9 for anything
> else (or you may be surprised as the regexp match creates an inner
> scope
> where these variables refer to match results). (IMO use of $0-$9 should
> be reserved for that purpose and they should not be assignable).
>
>
> Ahhh good call. Actually, I just tested and it looks like assigning
> directly to $\d is a no-op??? That's pretty wild. Anyway, putting them
> in as reserved variable names.
>
>
> - Arrays and Hashes are mutable; which is either an bug or a language
> feature. While it is not allowed to directly change a variable, it can
> be indirectly modified if it refers to an array or hash. Great if the
> documentation can clarify if this is a supported feature or should be
> avoided. i.e. $a = [1,2,3] $a[0] = 10. (IMO, this is problematic as any
> logic can refer to the variable and assign to an entry - at least
> last I
> tried).
>
>
> D:< EWW. "Problematic" is putting it mildly, especially since behavior
> is inconsistent between arrays and hashes. (Both can add, only arrays
> can reassign to existing indexes.) But I'd better document it anyhow.
>

The thing is, if arrays and hashes are immutable (as they should be),
there is no meaning to have [] operator produce a Lvalue at all - i.e.
can't assign something to the result. The only possible interpretation
of say $a[3]= 10 when they are immutable is to create a new variable $a
with an array assigned where 0-2 are undefined and 3 is assigned to 10.
Seems like a completely useless construct.

Passing arrays and hashes to functions is naturally a potential danger.

- henrik

[Henrik Lindberg]

On 2012-25-08 1:02, Nick Fagerlund wrote:

> - Can I write more complex expressions in an interpolation? Can I do
> something like "The sum is ${$a + $b}", and if that is the case, is it
> possible to have any expression interpolated (including nested strings
> with interpolation)?
>
>
> Nope! Thanks for reminding me about this, I remember trying to make
> Puppet do this and being disappointed.

I just tested on puppet 2.7.14...

puppet apply -e '$x = 1 $y =2 $b="x${$x+$y}x" notice($b)'
notice: Scope(Class[main]): x3x
notice: Finished catalog run in 0.01 seconds

And

puppet apply -e '$x = 1 $y =2 $b="x${"abc${$x+$y}abc"}x" notice($b)'
notice: Scope(Class[main]): xabc3abcx
notice: Finished catalog run in 0.01 seconds

So - seems to work just fine - at least simple, complex things :)

- henrik

[Trevor Vaughan]

Just to make this extra fun....

You CAN change variables after they've been assigned.

If you assign a new value to the variable in a template, it will pick
up the new value.

Note that this should NOT be used as a feature but I'm sure it'll bite
someone like it did me at some point since it lovely and random but,
once set, is set for that variable as long as it's memory resident.

Note: I haven't checked that this still happens in a while but I would
bet that it does.

Trevor

On Fri, Aug 24, 2012 at 7:02 PM, Nick Fagerlund
<nick.fa...@puppetlabs.com> wrote:
>> - Arrays and Hashes are mutable; which is either an bug or a language
>> feature. While it is not allowed to directly change a variable, it can
>> be indirectly modified if it refers to an array or hash. Great if the
>> documentation can clarify if this is a supported feature or should be
>> avoided. i.e. $a = [1,2,3] $a[0] = 10. (IMO, this is problematic as any
>> logic can refer to the variable and assign to an entry - at least last I
>> tried).
>
>
> D:< EWW. "Problematic" is putting it mildly, especially since behavior is
> inconsistent between arrays and hashes. (Both can add, only arrays can
> reassign to existing indexes.) But I'd better document it anyhow.
>

--
Trevor Vaughan
Vice President, Onyx Point, Inc
(410) 541-6699
tvau...@onyxpoint.com

-- This account not approved for unencrypted proprietary information --

[Nick Fagerlund]

On Sunday, August 26, 2012 6:44:25 PM UTC-7, Henrik Lindberg wrote:

I just tested on puppet 2.7.14...

puppet apply -e '$x = 1 $y =2 $b="x${$x+$y}x" notice($b)'
notice: Scope(Class[main]): x3x
notice: Finished catalog run in 0.01 seconds

And

puppet apply -e '$x = 1 $y =2 $b="x${"abc${$x+$y}abc"}x" notice($b)'
notice: Scope(Class[main]): xabc3abcx
notice: Finished catalog run in 0.01 seconds

So - seems to work just fine - at least simple, complex things :)

- henrik

 

WAT.

Oh wow, this gets kind of weird. https://gist.github.com/f870b2c33ffa466c8f18

I could have sworn that didn't used to work, but I just tested it back to 2.6.3, and it's solid. Weird.

[Nick Fagerlund]

On Monday, August 27, 2012 7:09:39 AM UTC-7, Trevor Vaughan wrote:

Just to make this extra fun....

You CAN change variables after they've been assigned.

If you assign a new value to the variable in a template, it will pick
up the new value.

Ah ha, but templates are not part of the puppet language's grammar. :)

(In seriousness, I think we consider that a bug.)

[Trevor Vaughan]

I get it, but it would be nice to explicitly tell people to be careful
about this when talking about variables and pitfalls.

Trevor

> --
> You received this message because you are subscribed to the Google Groups
> "Puppet Users" group.
> To view this discussion on the web visit

> https://groups.google.com/d/msg/puppet-users/-/0LcYJ96UjkEJ.

>
> To post to this group, send email to puppet...@googlegroups.com.
> To unsubscribe from this group, send email to
> puppet-users...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/puppet-users?hl=en.

[Nick Fagerlund]

On Monday, August 27, 2012 11:55:23 AM UTC-7, Trevor Vaughan wrote:

I get it, but it would be nice to explicitly tell people to be careful
about this when talking about variables and pitfalls.

Okay, fair point. I'll put a note.

[jcbollinger]

Good grief, don't do that!  If it actually gets published in an official PL document then it may be Puppet 4 before it can be removed!


John

[Nick Fagerlund]

On Monday, August 27, 2012 1:20:53 PM UTC-7, jcbollinger wrote:

D:< EWW. "Problematic" is putting it mildly, especially since behavior is inconsistent between arrays and hashes. (Both can add, only arrays can reassign to existing indexes.) But I'd better document it anyhow.

Good grief, don't do that!  If it actually gets published in an official PL document then it may be Puppet 4 before it can be removed!

Well, this runs up against the blurry boundary between the docs and the ticket tracker. Obviously I'm not writing every outstanding bug into the language reference, but it IS meant to be a record of everything we know about the Puppet language as she is actually played, so there are a few bugs like this that deserve a mention in it (along with a big fat DON'T DO THIS sign).

For the time being, I'm putting notes by a few things saying that they're considered bugs and may be removed without a deprecation period. My approach may change a bit over time?

[Henrik Lindberg]

On 2012-28-08 24:34, Nick Fagerlund wrote:

> ...blurry...
> ...ticket tracker ... outstanding bug
>...DON'T DO THIS...

Ah,
which reminded me about the fun and games that can be played with node
inheritance and regular expressions. There is a bug logged for that.

Problem being that a node can inherit from another by referencing it via
its "name". The "name" can be a regular expression (which is reasonable
to match against hostnames). What is not reasonable is to have complex
RHS expression that inherits based on a regexp.

A regexp may also match the special "default" node as well - see:

http://projects.puppetlabs.com/issues/7433
http://projects.puppetlabs.com/issues/7423

What - that issue (7423) was closed because 2.6 version was deleted? The
problem still exists because nodeparent uses rule hostname
https://github.com/puppetlabs/puppet/blob/3.x/lib/puppet/parser/grammar.ra#L708

and hostname allows regexp

https://github.com/puppetlabs/puppet/blob/3.x/lib/puppet/parser/grammar.ra#L677

I re-opened the issue 7423.

Anyway, I agree with the approach to document how it *should be*, and
when the reality happens to allow something completely different it
should be noted.

Language design and implementation is tricky -
https://www.destroyallsoftware.com/talks/wat
NaNaNaNa - Batman ! (around 3:50 in if you are impatient).


Regards
- henrik

[Henrik Lindberg]

https://github.com/puppetlabs/puppet/commit/193e19eb14ff640a68f2a21fd525ef6c8825dbf2

Don't think that was in the language guide.

And the new 'unless' statement in 3.0.

- henrik

[Daniel Johnson]

> And of course, use the navigation in the left sidebar to jump between pages.

Next/Back links at the top, and bottom of each page would be nice for
reading through the whole manual. Would save a little bit of effort
over scrolling back up to the contents after finishing reading a page.