Allow attributes argument of render/load APIs to be a string or array

[mojavelinux]

Currently, attributes must be passed as a Hash to the render and load APIs. There are times when this makes the argument list feel too heavy. As an alternative, these APIs should accept the attributes as a string or array.

For instance, consider a user of the API wants to pass the attribute that enables the table of contents (toc) and auto-numbering (numbered).

result = Asciidoctor.render_file('master.ad',
    :attributes => {'toc' => '', 'numbered' => ''})

The toc attribute does not require a value. An empty string value is the convention in AsciiDoc/Asciidoctor to enable an attribute of this type (a flag attribute).

This invocation could be simplified if the API accepted the attribute keys as an array.

result = Asciidoctor.render_file('master.ad',
    :attributes => ['toc', 'numbered'])

It can be further simplified using the array-from-string shorthand in Ruby:

result = Asciidoctor.render_file('master.ad',
    :attributes => %w(toc numbered))

That leads us into attributes specified as a string:

result = Asciidoctor.render_file('master.ad',
    :attributes => 'toc numbered')

That's quite an improvement over the original call.

To handle attributes that accept values, we can recognize the key=value form:

result = Asciidoctor.render_file('master.ad',
    :attributes => 'toc numbered source-highlighter=coderay')

This parallels the commandline argument form, encouraging consistency:

asciidoctor -a toc -a numbered -a source-highlighter=coderay master.adoc

I think this enhancement will be particularly useful in the integrations, such as the Gradle plugin.