mustermann-visualizer 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d028b3c70fb1171e8ffd5afe880b163866e972bf
+  data.tar.gz: edea773ff5a6c259e378b4156c1e5c4566d50a57
+SHA512:
+  metadata.gz: 8adb6e5e73eea9f6bf5b1550b28f74242b349e7a8400f7f5c4cb9346edeb69de6a9e540aaf1e385ad2936c01f54b8f0b23444dd814523f9a870a72b8402afa48
+  data.tar.gz: bbfba32e4b53c7e581de1958b30eda063faa4fc076fa31ece683f13cc5a1d84ec866ddb0ae402f8398e2b2deb0e5868e41550f5af6aa68c37433b53671b91e25

data/README.md

@@ -0,0 +1,196 @@
+# Mustermann Pattern Visualizer
+
+With this gem, you can visualize the internal structure of a Mustermann pattern:
+
+* You can generate a **syntax highlighted** version of a pattern object. Both HTML/CSS based highlighting and ANSI color code based highlighting is supported.
+* You can turn a pattern object into a **tree** (with ANSI color codes) representing the internal AST. This of course only works for AST based patterns.
+
+## Syntax Highlighting
+
+![](highlighting.png)
+
+Loading `mustermann/visualizer` will automatically add `to_html` and `to_ansi` to pattern objects.
+
+``` ruby
+require 'mustermann/visualizer'
+puts Mustermann.new('/:name').to_ansi
+puts Mustermann.new('/:name').to_html
+```
+
+Alternatively, you can also create a separate `highlight` object, which allows finer grained control and more formats:
+
+``` ruby
+require 'mustermann/visualizer'
+
+pattern   = Mustermann.new('/:name')
+highlight = Mustermann::Visualizer.highlight(pattern)
+
+puts highlight.to_ansi
+```
+### `inspect` mode
+
+By default, the highlighted string will be a colored version of `to_s`. It is also possible to produce a colored version of `inspect`
+
+``` ruby
+require 'mustermann/visualizer'
+
+pattern = Mustermann.new('/:name')
+
+# directly from the pattern
+puts pattern.to_ansi(inspect: true)
+
+# via the highlighter
+highlight = Mustermann::Visualizer.highlight(pattern, inspect: true)
+puts highlight.to_ansi
+```
+
+### Themes
+
+![](theme.png)
+
+element      | inherits style from | default theme | note
+-------------|---------------------|---------------|-------------------------
+default      |                     | #839496       | ANSI `\e[10m` if not set
+special      | default             | #268bd2       |
+capture      | special             | #cb4b16       |
+name         |                     | #b58900       | always inside `capture`
+char         | default             |               |
+expression   | capture             |               | only exists in URI templates
+composition  | special             |               | meta style, does not exist directly
+group        | composition         |               |
+union        | composition         |               |
+optional     | special             |               |
+root         | default             |               | wraps the whole pattern
+separator    | char                | #93a1a1       |
+splat        | capture             |               |
+named_splat  | splat               |               |
+variable     | capture             |               | always inside `expression`
+escaped      | char                | #93a1a1       |
+escaped_char |                     |               | always inside `escaped`
+quote        | special             |               |
+illegal      | special             | #8b0000       |
+
+You can set theme any of the above elements. The default theme will only be applied if no custom theming is used.
+
+``` ruby
+# custom theme with highlight object
+highlight = Mustermann::Visualizer.highlight(pattern, special: "#08f")
+puts highlight.to_ansi
+```
+
+Themes apply both to ANSI and to HTML/CSS output. The exact ANSI code used depends on the terminal and its capabilities.
+
+### HTML and CSS
+
+By default, the syntax elements will be translated into `span` tags with `style` attributes.
+
+``` ruby
+Mustermann.new('/:name').to_html
+```
+
+``` html
+<span style="color: #839496;"><span style="color: #93a1a1;">/</span><span style="color: #cb4b16;">:<span style="color: #b58900;">name</span></span></span></span>
+```
+
+You can also set the `css` option to `true` to make it include a stylesheet instead.
+
+``` ruby
+Mustermann.new('/:name').to_html(css: true)
+```
+
+``` html
+<span class="mustermann_pattern"><style type="text/css">
+.mustermann_pattern .mustermann_name {
+  color: #b58900;
+}
+/* ... etc ... */
+</style><span class="mustermann_root"><span class="mustermann_separator">/</span><span class="mustermann_capture">:<span class="mustermann_name">name</span></span></span></span>
+```
+
+Or you can set it to `false`, which will omit `style` attributes, but include `class` attributes.
+
+``` html
+<span class="mustermann_pattern"><span class="mustermann_root"><span class="mustermann_separator">/</span><span class="mustermann_capture">:<span class="mustermann_name">name</span></span></span></span>
+```
+
+It is possible to change the class prefix and the tag used.
+
+``` ruby
+Mustermann.new('/:name').to_html(css: false, class_prefix: "mm_", tag: "tt")
+```
+
+``` html
+<tt class="mm_pattern"><tt class="mm_root"><tt class="mm_separator">/</tt><tt class="mm_capture">:<tt class="mm_name">name</tt></tt></tt></tt>
+```
+
+If you create a highlight object, you can ask it for its `stylesheet`.
+
+``` erb
+<% highlight = Mustermann::Visualizer.highlight("/:name") %>
+
+<html>
+  <head>
+    <style type="text/css">
+      <%= highlight.stylesheet %>
+    </style>
+  </head>
+  <body>
+    <%= highlight.to_html(css: false) %>
+  </body>
+</html>
+```
+
+
+### Other formats
+
+If you create a highlight object, you have two other formats available: Hansi template strings and s-expression like strings. These might be useful if you want to check how a theme will be applied or as intermediate format for highlighting by other means.
+
+``` ruby
+require 'mustermann/visualizer'
+highlight = Mustermann::Visualizer.highlight("/:page")
+puts highlight.to_hansi_template
+puts highlight.to_sexp
+```
+
+**Hansi template strings** wrap elements in tags that are similar to XML tags (though they are not, entity encoding and attributes are not supported, escaping works with a slash, so an escaped `>` would be `\>`, not `&gt;`).
+
+``` xml
+<pattern><root><separator>/</separator><capture>:<name>page</name></capture></root></pattern>
+```
+
+The **s-expression like syntax** looks as follows:
+
+```
+(root (separator /) (capture : (name page)))
+```
+
+* An expression is enclosed by parens and contains elements separated by spaces. The first element in the expression type (corresponding to themeable elements). These are simple strings. The other elements are either expressions, simple strings or full strings.
+* Simple strings do not contain spaces, parens, single or double quotes or any character that needs to be escaped.
+* Full strings are Ruby strings enclosed by double quotes.
+* Spaces before or after parens are optional.
+
+### IRB/Pry integration
+
+When `mustermann` is being loaded from within an IRB or Pry session, it will automatically load `mustermann/visualizer` too, if possible.
+When displayed as result, it will be highlighted.
+
+![](irb.png)
+
+In Pry, this will even work when nested inside other objects (like as element on an array).
+
+## Tree Rendering
+
+![](tree.png)
+
+Loading `mustermann/visualizer` will automatically add `to_tree` to pattern objects.
+
+``` ruby
+require 'mustermann/visualizer'
+puts Mustermann.new("/:page(.:ext)?/*action").to_tree
+```
+
+For patterns not based on an AST (shell, simple, regexp), it will print out a single line:
+
+    pattern (not AST based)  "/example"
+
+It will display a tree for identity patterns. While these are not based on an AST internally, Mustermann supports generating an AST for these patterns.

data/examples/highlighting.rb

@@ -0,0 +1,27 @@
+require 'bundler/setup'
+require 'mustermann/visualizer'
+
+def self.example(type, *patterns)
+  print Hansi.render(:bold, "  #{type}: ".ljust(14))
+  patterns.each do |pattern|
+    pattern     = Mustermann.new(pattern, type: type)
+    space_after = pattern.to_s.size > 24 ? " " : " " * (25 - pattern.to_s.size)
+    highlight   = Mustermann::Visualizer.highlight(pattern)
+    print highlight.to_ansi + space_after
+  end
+  puts
+end
+
+puts
+example(:cake,     '/:prefix/**')
+example(:express,  '/:prefix+/:id(\d+)', '/:page/:slug+')
+example(:flask,    '/<prefix>/<int:id>', '/user/<int(min=0):id>')
+example(:identity, '/image.png')
+example(:pyramid,  '/{prefix:.*}/{id}',  '/{page}/*slug')
+example(:rails,    '/:slug(.:ext)')
+example(:regexp,   '/(?<slug>[^/]+)',    '/(?:page|user)/(\d+)')
+example(:shell,    '/**/*',              '/\{a,b\}/{a,b}')
+example(:simple,   '/:page/*slug')
+example(:sinatra,  '/:page/*slug',         '/users/{id}?')
+example(:template, '/{+pre}/{page}{?q,p}', '/users/{id}?')
+puts

data/lib/mustermann/visualizer.rb

@@ -0,0 +1,38 @@
+require 'mustermann'
+require 'mustermann/visualizer/highlight'
+require 'mustermann/visualizer/tree_renderer'
+require 'mustermann/visualizer/pattern_extension'
+
+module Mustermann
+  # Namespace for Mustermann visualization logic.
+  module Visualizer
+    extend self
+
+    # @example creating a highlight object
+    #   require 'mustermann/visualizer'
+    #   
+    #   pattern   = Mustermann.new('/:name')
+    #   highlight = Mustermann::Visualizer.highlight(pattern)
+    #   
+    #   puts highlight.to_ansi
+    #
+    # @return [Mustermann::Visualizer::Highlight] highlight object for given pattern
+    # @param (see Mustermann::Visualizer::Highlight#initialize)
+    def highlight(pattern, **options)
+      Highlight.new(pattern, **options)
+    end
+
+    # @example creating a tree object
+    #   require 'mustermann/visualizer'
+    #   
+    #   pattern = Mustermann.new('/:name')
+    #   tree    = Mustermann::Visualizer.tree(pattern)
+    #   
+    #   puts highlight.to_s
+    #
+    # @return [Mustermann::Visualizer::Tree] tree object for given pattern
+    def tree(pattern, **options)
+      TreeRenderer.render(pattern, **options)
+    end
+  end
+end

data/lib/mustermann/visualizer/highlight.rb

@@ -0,0 +1,136 @@
+require 'hansi'
+require 'mustermann'
+require 'mustermann/visualizer/highlighter'
+require 'mustermann/visualizer/renderer/ansi'
+require 'mustermann/visualizer/renderer/hansi_template'
+require 'mustermann/visualizer/renderer/html'
+require 'mustermann/visualizer/renderer/sexp'
+
+module Mustermann
+  module Visualizer
+    # Meta class for highlight objects.
+    # @see Mustermann::Visualizer#highlight
+    class Highlight
+      # @!visibility private
+      attr_reader :pattern, :theme
+
+      # @!visibility private
+      DEFAULT_THEME = Hansi::Theme.new(:solarized, {
+        default:   :base0,
+        separator: :base1,
+        escaped:   :base1,
+        capture:   :orange,
+        name:      :yellow,
+        special:   :blue,
+        quote:     :char,
+        illegal:   :darkred
+      })
+
+      # @!visibility private
+      BASE_THEME = Hansi::Theme.new({
+        special:     :default,
+        capture:     :special,
+        char:        :default,
+        expression:  :capture,
+        composition: :special,
+        group:       :composition,
+        union:       :composition,
+        optional:    :special,
+        root:        :default,
+        separator:   :char,
+        splat:       :capture,
+        named_splat: :splat,
+        variable:    :capture,
+        escaped:     :char,
+        quote:       :special,
+        illegal:     :special
+      })
+
+      # @!visibility private
+      def initialize(pattern, type: nil, inspect: false, **theme)
+        @pattern = Mustermann.new(pattern, type: type)
+        @inspect = inspect
+        theme    = theme.any? ? Hansi::Theme.new(theme) : DEFAULT_THEME
+        @theme   = BASE_THEME.merge(theme)
+      end
+
+      # @example
+      #   require 'mustermann/visualizer'
+      #   
+      #   pattern   = Mustermann.new('/:name')
+      #   highlight = Mustermann::Visualizer.highlight(pattern)
+      #   
+      #   puts highlight.to_hansi_template
+      #
+      # @return [String] Hansi template representation of the pattern
+      def to_hansi_template(**options)
+        render_with(Renderer::HansiTemplate, **options)
+      end
+
+      # @example
+      #   require 'mustermann/visualizer'
+      #   
+      #   pattern   = Mustermann.new('/:name')
+      #   highlight = Mustermann::Visualizer.highlight(pattern)
+      #   
+      #   puts highlight.to_ansi
+      #
+      # @return [String] ANSI colorized version of the pattern
+      def to_ansi(**options)
+        render_with(Renderer::ANSI, **options)
+      end
+
+      # @example
+      #   require 'mustermann/visualizer'
+      #   
+      #   pattern   = Mustermann.new('/:name')
+      #   highlight = Mustermann::Visualizer.highlight(pattern)
+      #   
+      #   puts highlight.to_html
+      #
+      # @return [String] HTML rendering of the pattern
+      def to_html(**options)
+        render_with(Renderer::HTML, **options)
+      end
+
+      # @example
+      #   require 'mustermann/visualizer'
+      #   
+      #   pattern   = Mustermann.new('/:name')
+      #   highlight = Mustermann::Visualizer.highlight(pattern)
+      #   
+      #   puts highlight.to_sexp
+      #
+      # @return [String] s-expression like representation of the pattern
+      def to_sexp(**options)
+        render_with(Renderer::Sexp, **options)
+      end
+
+      # @return [Mustermann::Pattern] the pattern used to create the highlight object
+      def to_pattern
+        pattern
+      end
+
+      # @return [String] string representation of the pattern
+      def to_s
+        pattern.to_s
+      end
+
+      # @return [String] stylesheet for HTML output from the pattern
+      def stylesheet(**options)
+        Renderer::HTML.new(self, **options).stylesheet
+      end
+
+      # @!visibility private
+      def render_with(renderer, **options)
+        options[:inspect] = @inspect if options[:inspect].nil?
+        renderer.new(self, **options).render
+      end
+
+      # @!visibility private
+      def render(renderer)
+        Highlighter.highlight(pattern, renderer)
+      end
+    end
+  end
+end

data/lib/mustermann/visualizer/highlighter.rb

@@ -0,0 +1,36 @@
+require 'mustermann/visualizer/highlighter/ast'
+require 'mustermann/visualizer/highlighter/ad_hoc'
+require 'mustermann/visualizer/highlighter/dummy'
+require 'mustermann/visualizer/highlighter/regular'
+
+module Mustermann
+  module Visualizer
+    # @!visibility private
+    module Highlighter
+      extend self
+
+      # @return [String] highlighted string
+      # @!visibility private
+      def highlight(pattern, renderer)
+        highlighter_for(pattern).highlight(pattern, renderer)
+      end
+
+      # @return [#highlight] Highlighter for given pattern
+      # @!visibility private
+      def highlighter_for(pattern)
+        return pattern.highlighter if pattern.respond_to? :highlighter and pattern.highlighter
+        consts      = constants.map { |name| const_get(name) }
+        highlighter = consts.detect { |c| c.respond_to? :highlight? and c.highlight? pattern }
+        highlighter || Dummy
+      end
+
+      # Used to generate highlighting rules on the fly.
+      # @see {Mustermann::Shell#highlighter}
+      # @see {Mustermann::Simple#highlighter}
+      # @!visibility private
+      def create(&block)
+        Class.new(AdHoc, &block)
+      end
+    end
+  end
+end