(#17994) Generate a new file and dir each time

Previously, the test would reuse the same file and dir each time,
assuming that the chmod would set the initial mode correctly at the
start of each test using a numeric mode. However, on debian (at
least):

    SETUID AND SETGID BITS
    ...
    You can set or clear the bits with symbolic modes like
    u+s and g-s, and you can set (but not clear) the bits with
    a numeric mode.

Since we can't reliably set the initial mode using chmod, this commit
modifies the test to delete the file/dir at the start of every
test. This ensures that state from one test doesn't leak across.

Also, modifies the assert_match to account that the file path may
contain special regexp characters that need to be escaped.
(#17994) Handle setgid bit on Solaris specially

From the Solaris chmod man page, "For directories, the set-gid bit can
only be set or cleared by using symbolic mode." As a result, the test
that attempted to chmod the start_mode for a directory to 2744, and then
verify puppet could apply `g-s` fails, because the start_mode was never
set correctly.

We could use puppet to set the start_mode, as it correctly applies 2744
to a directory. But that breaks other tests that aren't expecting puppet
to magically make readable directories executable.

We could express start_mode as a symbol, `u=rwx,go=4,+s`, but that
requires reworking whether we expect a mode change or not.

So for now, we just skip the test on Solaris.

It also adds tests for u+s, g+s, u+t when modifying an existing
file/dir.

Another thing to keep in mind is that Solaris supports a mandatory
locking flag 'l'. When mode 2750 is applied to a file (so the permission
for the group class is executable), then the setgid bit is set as
expected: -rwxr-sr--

However, if the permission for the group class is not executable (2644),
then the bit corresponds to mandatory file locking: -rw-r-lr--
Merge branch 'ticket/master/17994-wrong-mode-not-octal'

* ticket/master/17994-wrong-mode-not-octal:
  (#17994) Handle setgid bit on Solaris specially
  (#17994) Generate a new file and dir each time
Get YARD for the Puppet module to show up correctly.
Fix Puppet::Parser::Functions.arity

This method was untested and used two methods that no longer exist.
Flesh out documentation for Puppet::Parser::Functions

This documents several previously undocumented methods in
Puppet::Parser::Functions and marks everything that is considered public api
Add docs for lookupvar
Begin exposing Puppet::Type as public API.
(#18023) Document user facing classes using yardoc and show api.

This adds yardoc to user facing classes Type, Parameter, Property,
Provider, Report, as well as classes used by these via inclusion or
delegation and where documetation was most relevant to add at the source.

This also includes puppet specific tags (@comment, and @dsl), puppet
specific templates (shows DSL for elements marked with @dsl), as well
as some general improvements to the default yard templates.

As this is the first stab at providing more comprehensive code
documentation, there are many unanswered questions in the documentation
that are marked with @todo, or ??? to indicate uncertainty.
More investigation is required to update these.

Many methods are marked as being non api. As this documentation is not final,
and only covers a portion of the puppet code base, the lack of a "private"
tag being displayed should not yet be taken as authoritiative indication
that it is api.
Merge pull request #1370 from hlindberg/yard2

(#18023) Document user facing classes using yardoc and show api. 
(maint) Skip IPv6 examples that cannot pass on MRI 1.9.3-p327

Without this patch applied the following examples fail on MRI
1.9.3-p327, but not other versions.

Failures:

  1) Puppet::Network::AuthStore::Declaration when the pattern is a valid IP such as ::2:3:4:5:6:7:8 should match the specified IP
     Failure/Error: @declaration = Puppet::Network::AuthStore::Declaration.new(:allow_ip,ip)
     ArgumentError:
       invalid address
     # ./lib/puppet/network/authstore.rb:252:in `new'
     # ./lib/puppet/network/authstore.rb:252:in `parse_ip'
     # ./lib/puppet/network/authstore.rb:171:in `pattern='
     # ./lib/puppet/network/authstore.rb:151:in `initialize'
     # ./spec/unit/network/authstore_spec.rb:304:in `new'
     # ./spec/unit/network/authstore_spec.rb:304:in `block (4 levels) in <top (required)>'

  2) Puppet::Network::AuthStore::Declaration when the pattern is a valid IP such as ::2:3:4:5:6:7:8 should not match other IPs
     Failure/Error: @declaration = Puppet::Network::AuthStore::Declaration.new(:allow_ip,ip)
     ArgumentError:
       invalid address
     # ./lib/puppet/network/authstore.rb:252:in `new'
     # ./lib/puppet/network/authstore.rb:252:in `parse_ip'
     # ./lib/puppet/network/authstore.rb:171:in `pattern='
     # ./lib/puppet/network/authstore.rb:151:in `initialize'
     # ./spec/unit/network/authstore_spec.rb:304:in `new'
     # ./spec/unit/network/authstore_spec.rb:304:in `block (4 levels) in <top (required)>'

These failures are a result of Bug https://bugs.ruby-lang.org/issues/7477 in MRI itself.

This patch addresses the problem by explicitly excluding the examples that will
fail because of the bugged Ruby interpreter.  The patch targets very specific
patch level versions of MRI so that future and past MRI versions will
explicitly fail, notifying us when the root cause of the issue is resolved.
(maint) Use conditional pending mechanism for ruby issue 7477

Without this patch Daniel's concern isn't being addressed, "It seems
like this would be much better handled with the "conditional pending"
mechanism that rspec provides." [1]

This patch switches over to conditional pending messages to disable the
examples.

[1]: http://goo.gl/5VzBa
Merge pull request #1367 from jeffmccune/fix/master/ipaddress_specs

(maint) Skip IPv6 examples that cannot pass on MRI 1.9.3-p327
Fixup use of conditional pending

Without this patch the tests aren't actually getting marked as pending
because exceptions are being raised in the before blocks.  This patch
addresses the problem by switching the declaration references to a lazy
evaluated let method rather than a preemptive before block.  This
prevents the exception and allows the pending methods to execute.
(maint) Add Travis CI Support

This patch adds Travis support.  It also makes sure that `bundle install
--path vendor` works with `bundle exec rake spec`.

This patch should coincide with enabling Travis CI support for pull requests.
A build status image is also included in the project README.
Future proof authstore ruby issue 7477

Without this patch once a new patch level version of MRI comes out,
Travis CI will start failing because the test that fails on
`IPAddr.new('::2:3:4:5:6:7:8')` because of ruby issue 7477 [1].  This
patch fixes the problem by raising an exception if the bugged code is
still bugged.  When the issue is fixed the blocks of code that cause the
examples to be marked as pending will pass without exception.

[1]: http://goo.gl/Bb1LU
Merge pull request #1373 from jeffmccune/feature/master/travis_ci

(maint) Add Travis CI Support
Merge remote-tracking branch 'upstream/master'