Equivocal Puppet Class Parameters

While working with Puppet recently I have noticed that there is some funny business going on with the rules of parameter naming. The Puppet’s documentation states:

Parameter names begin with a dollar sign prefix ($). The parameter name after the prefix:

Must begin with a lowercase letter.

Can include lowercase letters.

Can include digits.

Can include underscores.

Let’s see if this is true. Tried applying this manifest with Puppet 5.5.10 which is available on Ubuntu Focal Fossa (20.04):

class test(
  String $_content
){
  file {'/tmp/helloworld':
    content =>  "${_content}\n",
  }
}


class { 'test':
  _content => "123"
}

And it does not work as expected:

$ puppet apply hello.pp
Error: Could not parse for environment production: Syntax error at '_content' (file: /home/gstatkevicius/dev/puppet_testing/manifest/hellofile.pp, line: 11, column: 3) on node gstatkevicius-desktop

Now, let’s try creating a simple hiera configuration:

---
:backends:
  - yaml
:yaml:
  :datadir: /home/gstatkevicius/dev/puppet_testing/hieradata
:hierarchy:
  - test
:logger: console

$ cat hieradata/test.yaml 
test::_a: "Hello World!"

It looks like the hiera part works:

hiera -c ./hiera.yaml -d test::_a
DEBUG: 2020-11-03 23:39:00 +0200: Hiera YAML backend starting
DEBUG: 2020-11-03 23:39:00 +0200: Looking up test::_a in YAML backend
DEBUG: 2020-11-03 23:39:00 +0200: Looking for data source test
DEBUG: 2020-11-03 23:39:00 +0200: Found test::_a in test
Hello World!

Now let’s see if applying the manifest with Puppet works:

$ puppet apply --hiera_config=hiera.yaml manifest/hellofile.pp
Notice: Applied catalog in 0.01 seconds
$ cat /tmp/helloworld
Hello World!

Oh, so now everything is OK? It seems that for APL – automatic parameter look-up – the rules are a bit different. My guess at this point would be that they are treated as regular variables instead. I personally haven’t found a way to instantiate a class where one parameter starts with an underscore. Thus, I think we can formulate one lesson:

To prevent your class from ever being instantiated by other classes in Puppet with explicit arguments, start at least one class parameter with an underscore.

But, one question remains – why is it actually considered a syntax error? What makes the underscore character forbidden in names of class parameters whereas it works for regular variables?

Now, I’m not an expert in how Puppet parsing but let’s take a short trip down Puppet’s code-base and see what’s happening.

A quick grep of Syntax error at shows that there is some kind of function SYNTAX_ERROR that gets used whenever there is a need to print a message that a syntax error has occurred.

Digging a bit deeper, it seems that there is some kind of parser being generated from a grammar. Other Puppet developers have kindly documented this process for us in docs/parser_work.md. We are finally able to find the grammar in lib/puppet/pops/parser/egrammar.ra.

Valid name of a variable seems to be expressed here in lexer2.rb:

PATTERN_DOLLAR_VAR     = %r{\$(::)?(\w+::)*\w+}

I believe that what is a valid argument passed to a class is defined here:

#---ATTRIBUTE OPERATIONS (Not an expression)
#
attribute_operations
  :                                                { result = [] }
  | attribute_operation                            { result = [val[0]] }
  | attribute_operations COMMA attribute_operation { result = val[0].push(val[2]) }

  # Produces String
  # QUESTION: Why is BOOLEAN valid as an attribute name?
  #
  attribute_name
    : NAME
    | keyword

A valid NAME is defined here in lib/puppet/pops/patterns.rb:

NAME = %r{\A((::)?[a-z]\w*)(::[a-z]\w*)*\z}

So, it seems like the argument’s name is rejected because it does not follow this regular expression even though it is accepted by the lexer. To be fair, Puppet’s documentation also states:

CAUTION: In some cases, names containing unsupported characters might still work. Such cases are bugs and could cease to work at any time. Removal of these bug cases is not limited to major releases.

All in all, it’s probably best to follow the letter of the law laid out in Puppet’s documentation as it says here but if you want to forbid the users of your class to pass arguments explicitly, start one of them with an underscore 🙃.