Kramdown::Document.new mutates provided :smart_quotes option value

[jeremyevans]

https://github.com/gettalong/kramdown/blob/master/lib/kramdown/options.rb#L415 mutates a :smart_quotes option passed when creating a Kramdown::Document. In general, mutating arguments passed to a method should be avoided unless the purpose of the method is to mutate the arguments. Filing this as a discussion post and not an issue, since it's not technically a bug.

[gettalong]

This is the expected behaviour for option values since it is assumed that the options hash passed in is then owned by kramdown (and the parser/converters that use it). The options hash may also be modified during parsing, e.g. https://github.com/gettalong/kramdown/blob/master/lib/kramdown/parser/kramdown/extensions.rb#L109-L133.

[jeremyevans]

Be aware that this behavior of mutating option values is likely to lead to bugs if any parts of the options are shared, and doing is common. See jeremyevans/tilt@0eba4eb for an issue I fixed in tilt related to this (only discovered because I tried initially to pass a frozen :smart_quotes option value).

Note that options hash passed is not "owned by kramdown", it is merged into the default options (https://github.com/gettalong/kramdown/blob/master/lib/kramdown/document.rb#L97). So passing a frozen option hash works fine, but if you pass a frozen :smart_quotes option value, then it blows up.

If you wish to keep this behavior because it is expected behavior for kramdown, I encourage you to document it, because it is certainly surprising behavior (to me, and I would expect many other Ruby users).

[gettalong]

Yeah, you are right, it should be documented somewhere - thanks!

Btw. passing a frozen options hash will only work fine if the options extension is not used in the document. So it won't work in all cases.