[ch5::Variables] Variable names can begin with an underscore and letters include not only the ASCII range

[kolewu]

It is not correct that names may only begin with a letter and that letters include only the ASCII range.

The current documentation (v2.9) is very vague on this:

Variable names should be letters, numbers, and underscores. Variables should always start with a letter.

but should is not must and the term letter is not defined (maybe it is in the code), so it's unclear from the words whether it's really [A-Za-z] like you wrote or contains also letters outside the ASCII range (that's always a problem with english speaking developers: they can't think of any letters outside ASCII).

After testing with --syntax-check Ansible understands all UTF-8 letters (tested with only some, of course) like Python does for it's names and not only [A-Za-z].

The forthcoming documentation states more clearly:

A variable name can only include letters, numbers, and underscores. Python keywords and playbook keywords are not valid variable names. A variable name cannot begin with a number.
Variable names can begin with an underscore.

I do use variable names starting with underscore to mark them as private and not redefinable (defined in the roles vars/ directory) – though the new version of the documentation clearly states, that this is not how ansible sees the variable:

In many programming languages, variables that begin with an underscore are private. This is not true in Ansible. Variables that begin with an underscore are treated exactly the same as any other variable. Do not rely on this convention for privacy or security.

So I only use this as syntactic sugar and a note to the reader: This variable is defined in the roles vars directory and cannot be changed by the user.

[geerlingguy]

@kolewu - Thanks for the note, and you're correct. The text in the book is currently a little inaccurate. Instead, I've updated that section of chapter 5 to the following:

Variables

Variables in Ansible work just like variables in most other systems. Variables usually begin with a letter ([A-Za-z]), but can also start with an underscore (_). Variables can include any number of letters, underscores, or numbers.

Valid variable names include foo, foo_bar, foo_bar_5, _foo, and fooBar, though the standard is to use all lowercase letters, and typically avoid numbers in variable names (no camelCase or UpperCamelCase).

Invalid variable names include foo-bar, 12, foo.bar and foo bar.

In an ini-style inventory file, a variable's value is assigned using an equals sign, like so:

foo=bar

In a playbook or variables include file, a variable's value is assigned using a colon, like so:

foo: bar

While it's not explictly stated in Ansible's documentation, starting a variable with an underscore (e.g. _my_variable) is uncommon, but sometimes is used as a way of indicating a 'private' or 'internal use only' variable. For example, many of the geerlingguy Ansible roles I maintain prefix variables with an underscore if they're meant for internal role use only, and should not be overridden by playbooks using the role.

[geerlingguy]

This will be in the next revision of the book.