Clean up Markd::Options

Add documentation for options
Don't stick multiple vars in the same property instantiation
Enable `Naming/QueryBoolMethods` and fix all infractions
Don't require `gfm` option for tagfilter and autolink extensions

Author: nobodywasishere

.ameba.yml

@@ -8,9 +8,6 @@ Metrics/CyclomaticComplexity:
     - src/markd/parsers/block.cr
     - src/markd/renderer.cr
 
-Naming/QueryBoolMethods:
-  Enabled: false
-
 Naming/BlockParameterName:
   Enabled: false
 

README.md

@@ -56,7 +56,7 @@ Markd.to_html(markdown, options)
 | safe        | `Bool` | false         | if **true**, raw HTML will not be passed through to HTML output (it will be replaced by comments)                                                                               |
 | prettyprint | `Bool` | false         | if **true**, code tags generated by code blocks will have a `prettyprint` class added to them, to be used by [Google code-prettify](https://github.com/google/code-prettify).   |
 | gfm         | `Bool` | false         | **Partial support**                                                                                                                                                         |
-| autolink    | `Bool` | false         | if **true**, more autolinks are detected, like bare email addresses or http links. Requires `gfm` be set to `true`                                  |
+| autolink    | `Bool` | false         | if **true**, more autolinks are detected, like bare email addresses or http links                                             |
 | toc         | `Bool` | false         | **Not supported for now**                                                                                                                                                         |
 | base_url    | `URI?` | nil           | if not **nil**, relative URLs of links are resolved against this `URI`. It act's like HTML's `<base href="base_url">` in the context of a Markdown document.                    |
 

src/markd/options.cr

@@ -3,7 +3,16 @@ require "uri"
 module Markd
   # Markdown rendering options.
   class Options
-    property time, gfm, toc
+    # Render parsing cost time for reading the source, parsing blocks, and parsing inline.
+    property? time : Bool
+
+    # Enables GitHub Flavored Markdown support.
+    #
+    # https://github.github.com/gfm/
+    property? gfm : Bool
+
+    # Not supported for now.
+    property? toc : Bool
 
     # If `true`:
     # - straight quotes will be made curly
@@ -12,41 +21,58 @@ module Markd
     # - `...` will be changed to ellipses
     property? smart : Bool
 
-    @[Deprecated("Use `#smart?` instead.")]
-    getter smart
-
     # If `true`, source position information for block-level elements
     # will be rendered in the `data-sourcepos` attribute (for HTML).
     property? source_pos : Bool
 
-    @[Deprecated("Use `#source_pos?` instead.")]
-    getter source_pos
-
     # If `true`, raw HTML will not be passed through to HTML output
     # (it will be replaced by comments).
     property? safe : Bool
 
-    @[Deprecated("Use `#safe?` instead.")]
-    getter safe
-
     # If `true`, code tags generated by code blocks will have a
     # prettyprint class added to them, to be used by
     # [Google code-prettify](https://github.com/google/code-prettify).
     property? prettyprint : Bool
 
-    @[Deprecated("Use `#prettyprint?` instead.")]
-    getter prettyprint
-
     # If `base_url` is not `nil`, it is used to resolve URLs of relative
     # links. It act's like HTML's `<base href="base_url">` in the context
     # of a Markdown document.
     property base_url : URI?
 
-    property emoji : Bool
+    # Enables GFM emoji support.
+    #
+    # For example:
+    #
+    # ```
+    # @octocat :+1: This PR looks great - it's ready to merge! :ship:
+    # ```
+    #
+    # Becomes:
+    #
+    # ```
+    # @octocat 👍 This PR looks great - it's ready to merge! 🚢
+    # ```
+    # https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#using-emojis
+    property? emoji : Bool
 
-    property tagfilter : Bool
+    # If `true`, the following HTML tags will be filtered when rendering HTML output:
+    #
+    # * `<title>`
+    # * `<textarea>`
+    # * `<style>`
+    # * `<xmp>`
+    # * `<iframe>`
+    # * `<noembed>`
+    # * `<noframes>`
+    # * `<script>`
+    # * `<plaintext>`
+    #
+    # All other HTML tags are left untouched.
+    property? tagfilter : Bool
 
-    property autolink : Bool
+    # If `true`, more autolinks will be detected.
+    # Setting to `false` does not disable autolink support as a whole.
+    property? autolink : Bool
 
     def initialize(
       @time = false,
@@ -62,5 +88,25 @@ module Markd
       @base_url = nil,
     )
     end
+
+    # Deprecated
+
+    @[Deprecated("Use `#time?` instead.")]
+    getter time
+
+    @[Deprecated("Use `#gfm?` instead.")]
+    getter gfm
+
+    @[Deprecated("Use `#smart?` instead.")]
+    getter smart
+
+    @[Deprecated("Use `#source_pos?` instead.")]
+    getter source_pos
+
+    @[Deprecated("Use `#safe?` instead.")]
+    getter safe
+
+    @[Deprecated("Use `#prettyprint?` instead.")]
+    getter prettyprint
   end
 end

src/markd/parsers/block.cr

@@ -26,7 +26,7 @@ module Markd::Parser
     getter line, current_line, blank, inline_lexer,
       indent, indented, next_nonspace, refmap
 
-    delegate gfm, tagfilter, to: @options
+    delegate gfm?, tagfilter?, to: @options
 
     def initialize(@options : Options)
       @inline_lexer = Inline.new(@options)
@@ -55,11 +55,11 @@ module Markd::Parser
     end
 
     def parse(source : String)
-      Utils.timer("block parsing", @options.time) do
+      Utils.timer("block parsing", @options.time?) do
         parse_blocks(source)
       end
 
-      Utils.timer("inline parsing", @options.time) do
+      Utils.timer("inline parsing", @options.time?) do
         process_inlines
       end
 

src/markd/parsers/inline.cr

@@ -43,7 +43,7 @@ module Markd::Parser
             when '*', '_'
               handle_delim(char, node)
             when '~'
-              if @options.gfm
+              if @options.gfm?
                 handle_delim(char, node)
               else
                 string(node)
@@ -61,15 +61,15 @@ module Markd::Parser
             when 'w'
               # Catch www. autolinks for GFM
               # Do not match if it's http://www
-              if @options.gfm && @options.autolink && (@pos == 0 || char_at?(@pos - 1) != '/')
+              if @options.autolink? && (@pos == 0 || char_at?(@pos - 1) != '/')
                 auto_link(node)
               else
                 false
               end
             when 'h'
               # Catch http:// and https:// autolinks for GFM
               # Do not match if it's <http:// ... because that was matched by '<'
-              if @options.gfm && @options.autolink && (
+              if @options.autolink? && (
                    @pos == 0 ||
                    # Do not match if it's <http:// ... because that was matched by '<'
                    char_at?(@pos - 1) != '<' ||
@@ -83,21 +83,21 @@ module Markd::Parser
             when 'f'
               # Catch ftp:// autolinks for GFM
               # Do not match if it's <ftp:// ... because that was matched by '<'
-              if @options.gfm && @options.autolink && (@pos == 0 || char_at?(@pos - 1) != '<')
+              if @options.autolink? && (@pos == 0 || char_at?(@pos - 1) != '<')
                 auto_link(node)
               else
                 false
               end
             when 'x'
               # Catch xmpp: autolinks for GFM
-              if @options.gfm && @options.autolink && (@pos == 0 || char_at?(@pos - 1) != '<')
+              if @options.autolink? && (@pos == 0 || char_at?(@pos - 1) != '<')
                 auto_link(node)
               else
                 false
               end
             when 'm'
               # Catch mailto: autolinks for GFM
-              if @options.gfm && @options.autolink && (@pos == 0 || char_at?(@pos - 1) != '<')
+              if @options.autolink? && (@pos == 0 || char_at?(@pos - 1) != '<')
                 auto_link(node)
               else
                 false
@@ -107,7 +107,7 @@ module Markd::Parser
             when ':'
               emoji(node)
             else
-              if @options.gfm && @options.autolink && node.text.includes? '@'
+              if @options.autolink? && node.text.includes? '@'
                 # Catch email autolinks for GFM
                 auto_link(node)
               else
@@ -356,7 +356,7 @@ module Markd::Parser
           '"'  => delimiter,
         } of Char => Delimiter?
 
-        openers_bottom['~'] = delimiter if @options.gfm
+        openers_bottom['~'] = delimiter if @options.gfm?
 
         # move forward, looking for closers, and handling each
         while closer
@@ -386,7 +386,7 @@ module Markd::Parser
 
           case closer_char
           when '*', '_', '~'
-            if closer_char != '~' || (closer_char == '~' && @options.gfm)
+            if closer_char != '~' || (closer_char == '~' && @options.gfm?)
               if opener
                 # calculate actual number of delimiters used from closer
                 use_delims = (closer.num_delims >= 2 && opener.num_delims >= 2) ? 2 : 1
@@ -458,8 +458,6 @@ module Markd::Parser
               opener.node.text = "\u{201C}"
             end
             closer = closer.next?
-          else
-            nil
           end
 
           if !opener && !odd_match
@@ -482,7 +480,7 @@ module Markd::Parser
       elsif (matched_text = match(Rule::AUTO_LINK))
         node.append_child(link(matched_text, false))
         return true
-      elsif @options.gfm && @options.autolink
+      elsif @options.autolink?
         # These are all the extended autolinks from the
         # autolink extension
 
@@ -535,7 +533,7 @@ module Markd::Parser
       if (text = match(Rule::HTML_TAG))
         child = Node.new(Node::Type::HTMLInline)
 
-        if @options.gfm && @options.tagfilter
+        if @options.tagfilter?
           text = Rule::HTMLBlock.escape_disallowed_html(text)
         end
 
@@ -562,8 +560,6 @@ module Markd::Parser
               break
             when Char::ZERO, nil
               return false
-            else
-              nil
             end
           end
           text = @text.byte_slice((@pos + 1), (pos - 1) - (@pos + 1))
@@ -579,7 +575,7 @@ module Markd::Parser
     end
 
     private def emoji(node : Node)
-      return false unless @options.emoji
+      return false unless @options.emoji?
 
       if char_at?(@pos) == ':'
         pos = @pos + 1
@@ -932,7 +928,7 @@ module Markd::Parser
         #
         # If we are at the beginning of the string, then we return
         # the chunk matched
-        if @options.gfm && @options.autolink
+        if @options.autolink?
           advance = special_string?(@text, @pos)
           if advance > 0
             if @pos > start_pos
@@ -1047,7 +1043,7 @@ module Markd::Parser
       when '\n', '`', '[', ']', '\\', '!', '<', '&', '*', '_', '\'', '"', ':', 'w'
         false
       when '~'
-        !@options.gfm
+        !@options.gfm?
       else
         true
       end
@@ -1076,8 +1072,6 @@ module Markd::Parser
       if byte_index < @text.bytesize
         reader = Char::Reader.new(@text, byte_index)
         reader.current_char
-      else
-        nil
       end
     end
 

src/markd/renderer.cr

@@ -73,7 +73,7 @@ module Markd
     abstract def table_cell(node : Node, entering : Bool) : Nil
 
     def render(document : Node, formatter : T?) forall T
-      Utils.timer("rendering", @options.time) do
+      Utils.timer("rendering", @options.time?) do
         walker = document.walker
         while (event = walker.next)
           node, entering = event

src/markd/renderers/html_renderer.cr

@@ -14,7 +14,7 @@ module Markd
       if entering
         newline
         tag(tag_name, attrs(node))
-        toc(node) if @options.toc
+        toc(node) if @options.toc?
       else
         tag(tag_name, end_tag: true)
         newline
@@ -281,11 +281,11 @@ module Markd
     end
 
     def strong(node : Node, entering : Bool) : Nil
-      @strong_stack -= 1 if @options.gfm && !entering
+      @strong_stack -= 1 if @options.gfm? && !entering
 
       tag("strong", end_tag: !entering) if @strong_stack == 0
 
-      @strong_stack += 1 if @options.gfm && entering
+      @strong_stack += 1 if @options.gfm? && entering
     end
 
     def strikethrough(node : Node, entering : Bool) : Nil
@@ -337,8 +337,6 @@ module Markd
     private def attrs(node : Node)
       if @options.source_pos? && (pos = node.source_pos)
         {"data-source-pos" => "#{pos[0][0]}:#{pos[0][1]}-#{pos[1][0]}:#{pos[1][1]}"}
-      else
-        nil
       end
     end
 
@@ -356,8 +354,6 @@ module Markd
         code_tag_attrs = attrs(node)
         pre_tag_attrs = if @options.prettyprint?
                           {"class" => "prettyprint"}
-                        else
-                          nil
                         end
 
         tag("pre", pre_tag_attrs) do
@@ -375,8 +371,6 @@ module Markd
       code_tag_attrs = attrs(node)
       pre_tag_attrs = if @options.prettyprint?
                         {"class" => "prettyprint"}
-                      else
-                        nil
                       end
 
       lang = code_block_language(languages)

src/markd/rules/block_quote.cr

@@ -6,7 +6,7 @@ module Markd::Rule
       if match?(parser)
         seek(parser)
         parser.close_unmatched_blocks
-        if parser.gfm && (match = parser.line.match(Rule::ADMONITION_START))
+        if parser.gfm? && (match = parser.line.match(Rule::ADMONITION_START))
           node = parser.add_child(Node::Type::Alert, parser.next_nonspace)
           # This is an alert
           node.data["alert"] = match[1]

src/markd/rules/html_block.cr

@@ -31,7 +31,7 @@ module Markd::Rule
     def token(parser : Parser, container : Node) : Nil
       text = container.text.gsub(/(\n *)+$/, "")
 
-      if parser.gfm && parser.tagfilter
+      if parser.tagfilter?
         text = self.class.escape_disallowed_html(text)
       end