Numeric file/directory modes in Rex

The documentation for Rex::Commands::File and Rex::Commands::Fs show unquoted numeric file/directory "mode" strings for commands that interact with files. Examples:

Rex::Commands::File: file("/path/to/file", mode => 400)
Rex::Commands::Fs: chmod(755, "/path/to/file")

It looks like Rex is using the native system chmod binary to change file/directory modes when a Rexfile creates a new file or runs the chmod() DSL from Rex::Commands::Fs.

This will cause issues whenever someone uses a mode string that starts with a zero. In Perl, an unquoted mode string of 0777 will be interpreted by Perl as an octal number, and Perl will print the decimal value for this number when Perl stringifies it in order to run the chmod command in exec().

perl -e "print 077 . qq(\n);"
63
perl -e "print 0777 . qq(\n);"
511
perl -e "print 0644 . qq(\n);"
420

Note that string mode arguments (u+rwx) generally won't have any issues under Rex, as they would need to be quoted from Perl to prevent strictness checks from causing the script to exit. (People do use 'use strict;', right?)

The Perl built-in chmod() is the opposite, it wants octal numbers, string modes will cause incorrect modes to be set (http://perldoc.perl.org/functions/chmod.html)

The purpose of this ticket is to document this issue, as well as come up with suggestions for changes.

First suggestion would be to quote all octal file/directory modes in Rex documentation, and make a note about how Perl handles unquoted numbers with a leading '0', (i.e. the conversion to an octal number), and that Rex is needs the mode arguments to be strings when it calls the system's chmod command for setting file/directory modes.

Another suggestion is that it may be possible to "round trip" a file/directory mode argument for the chmod DSL function using either oct or sprintf, to see if the mode argument passed in to the function will have an issue with it when it's run on the remote system.

Locate the documentation for Rex::Commands::File and Rex::Commands::Fs; start by checking the mode examples and the chmod DSL behavior. Update the examples and explain Perl's leading-zero octal conversion and Rex's string-mode requirement, while recording any confirmed suggestions for changes.