(GH-141) Modify the Puppet Function loading to use all of the new Puppet 4 API features

[glennsarti]

Builds on #140

Fixes #141

• Remove all TODOs
• What about puppet language functions?

---

Previously the Sidecar Protocol had the serialisation methods on the
BasePuppetObject however this meant anything that wanted to use the
serialisation methods also inherited the parameters like key and calling_source.

This commit:

• Moves the serialisation methods (to_json, from_json!) to BaseClass which
  BasePuppetObject now inherits from
• Adds equality methods on the BaseClass to make it possible to compare
  Sidecar objects correctly. This is mainly required in spec tests to test for
  equality (either == or eql?)
• Adds a hash method to generate the hash number required when Sidecar objects
  are put into hashtables

---

Previously the Puppet Function information retrieved over the Sidecar Protocol
only supported the older V3 Function API. This commit updates the Protocol to
now be able to transmit V4 function information. V3 information is expected to
be adapted into its equivalent in V4.

This commit:

• Removes the deprecated arity and type methods and adds function_version and
  signatures. Where signatures are the function method signatures expressed as
  a PuppetFunctionSignatureList object
• Adds a PuppetFunctionSignature and PuppetFunctionSignatureList object which
  captures all of the properties of Puppet Function V4 API method signature.
  The PuppetFunctionSignatureList object is a "typed" array of
  PuppetFunctionSignature objects
• Adds a PuppetFunctionSignatureParameter and
  PuppetFunctionSignatureParameterList object which captures all of the
  properties of Puppet Function V4 API method signature parameter. The
  PuppetFunctionSignatureParameterList object is a "typed" array of
  PuppetFunctionSignatureParameter objects
• Updates the spec_helper to be able to create mock objects for functions,
  function signatures and function signature parameters
• Updates the sidecar protocol tests for the modified parameters and newly added
  classes
• Updates the in-memory cache object tests for the modified parameters of a
  Function.

---

Previously a Puppet Strings Helper was added however there no tests for the
metadata extraction. This commit:

• Adds tests to ensure that YARD/Puppet Strings extracts the metadata correctly
• Converts the Strings Helper module into a class to make it easier to test
• Updates the Puppet 4 function fixture to be a more complete example

---

When Puppet Strings extracts the parameter name it differs from how it appears
in the signature key. This makes it hard for clients to determine where in the
signature, the parameter actually is. This commit:

• Updates the Sidecar Protocol and adds two new methods for the
  PuppetFunctionSignatureParameter class; signature_key_offset and
  signature_key_length. These values will store where in the signature key
  a parameter exists
• Updates the protocol tests and spec helper for the new methods
• Updates the Puppet Strings Helper to detect and populate the offset and length
  values for each parameter in a signature
• Updates the Puppet Strings Helper tests to assert these values are correct for
  bare parameter names, blocks and splattable arguments.

---

Previously the Sidecar could only emit information in function V3 API format.
Now that the Sidecar Protocol has been changed to emit V4 information, this
commit updates the Sidecar to extact the V4 information.

This commit:

• Updates the sidecar_protocol_extensions for the Puppet Function object to
  adapt the V3 function information into the V4 version
• Updates the tests for the sidecar_protocol_extensions for the new parameters
  for the V4 API functions
• Updates the Puppet Strings Helper to extract the required information from
  YARN in order to populate the V4 API function metadata. In particular the
  concepts of function type and arity no longer apply, and have been replaced
  using Function Signatures.

---

Now that the Sidecar and the Sidecar Protocol have been modified to emit V4
API function metadata the completion and hover providers need to be modified
to use it. This commit:

• Because the concept of Function Type no longer exists (rvalue vs statement)
  all functions need to be returned when in the root of a document. Therefore
  the all_statement_functions method is changed into all_functions
• The completion resolver is modified to only emit completion information if the
  function actually has a signature (all functions should have at least one
  sig). The resulting resolution now returns the function documentation and
  function signatures in separate fields in the response
• The insertion text for the completion item now just emits the function with
  empty parentheses. This should trigger the Signature Helper, which will be
  implemented in later commits
• The hover provider is modified to remove a todo item because arity no longer
  exists

[glennsarti]

Found some bugs. Back to WIP

[jpogran]

I'm good to merge this, but feel like I haven't really 'used' it as I don't have examples of these advanced functions and stuff you've exposed. Do you have some examples to use?

[glennsarti]

Stdlib is my goto module as it basically has everything and it's used a lot

4.x
https://github.com/puppetlabs/puppetlabs-stdlib/tree/master/lib/puppet/functions

3.x
https://github.com/puppetlabs/puppetlabs-stdlib/tree/master/lib/puppet/parser/functions

[jpogran]