what_weve_got_here_is_an_error_to_communicate 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6d8b74cd9d659e3218cc9ecad4a0fdbba80b6d07
+  data.tar.gz: eadb2da5ec5d00795c54b93bf8efd7e0304b017d
+SHA512:
+  metadata.gz: e060fb388519b4492109c8e31d1f723b6b3cdb939650b6a709348778cbf771f0cbd5f75ec7a866945d140308c58330c5436d464cd01254fea9c4272f4b87c126
+  data.tar.gz: 2df113222792975b9e4bdc07dbdb2190e1f4f67b1ef5b5daa6b13d2fbfaa675755abc92818e873c00e737efdacd84dd38f8790cb49ccac72d72ef23f12fefaa9

data/.gitignore

@@ -0,0 +1,11 @@
+# Where our acceptance tests render
+proving_grounds
+
+# Libs shouldn't lock down deps
+Gemfile.lock
+
+# Thoughts and shit
+notes
+
+# the rubygems we compile and distribute
+*.gem

data/.rspec

@@ -0,0 +1,4 @@
+--colour
+--fail-fast
+--require error_to_communicate/rspec_formatter
+--format WhatWeveGotHereIsAnErrorToCommunicate::RSpecFormatter

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.0
+  - 2.1
+  - 2.2
+matrix:
+  fast_finish: true

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/Rakefile

@@ -0,0 +1,6 @@
+#!/usr/bin/env rake
+require File.join('rspec', 'core', 'rake_task')
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/Readme.md

@@ -0,0 +1,34 @@
+[![Build Status](https://travis-ci.org/JoshCheek/what-we-ve-got-here-is-an-error-to-communicate.svg?branch=master)](https://travis-ci.org/JoshCheek/what-we-ve-got-here-is-an-error-to-communicate)
+
+What if error messages were compelling to read?
+-----------------------------------------------
+
+Blog explaining the code is [here](http://blog.turing.io/2015/01/18/what-we-ve-got-here-is-an-error-to-communicate/).
+(or will be once it's merged).
+
+A screenshot of the code rendering an `ArgumentError`.
+
+![screenshot](https://s3.amazonaws.com/josh.cheek/images/scratch/better-reuby-commandline-errors.png)
+
+This is a proof of concept
+--------------------------
+
+This isn't fit for real-world use.
+If there is resonance in the community, I'll probably try to make it a real gem.
+I'll have some time to do that during my next braeak in late march 2015.
+
+Inspirations:
+-------------
+
+* I think initially this was inspired by Sarah Gray's talk at Software Craftsmanship North America:
+  [Visualizing Enumerable: Own Abstract Concepts Through Physicalization](https://vimeo.com/54860297)
+* Got to thinking about it again with Kerri Miller, conversing at DCamp,
+  and then at Ruby Conf, she created [chatty_exceptions](https://github.com/kerrizor/chatty_exceptions)
+  which is in this same domain.
+* Charlie Sommerville's [better_errors](https://rubygems.org/gems/better_errors)
+  gem gives you a nice interface like this for Rails.
+
+License
+--------
+
+[<img src="http://www.wtfpl.net/wp-content/uploads/2012/12/wtfpl.svg" width="15" height="15" alt="WTFPL" /> Do what the fuck you want to.](http://www.wtfpl.net/)

data/acceptance

@@ -0,0 +1,29 @@
+No error:
+  Given a file that doesn't error
+  No exception is printed
+  It exits with 0
+
+Argument Error:
+  Given a file with three lines in the backtrace that explodes on the third
+  displaying the error:
+    It prints the exception class
+    It prints the message (reworded to be more obvious)
+  heuristic:
+    It displays the most recent line of code and the next 5
+    It displays the second most recent of the backtrace, and 5 lines of code before / after
+  backtrace:
+    It displays each line of the backtrace
+    It includes the code from that line
+
+NoMethod Error:
+  Given a file with three lines in the backtrace that explodes on the third
+  displaying the error:
+    It prints the exception class
+    It prints the message (reworded to be more obvious) #<Object> has no method called #<method name>
+  heuristic:
+    It displays the line of the backtrace with the NoMethodError, and 5 lines of code before / after #This is where it blew up
+    It displays the second most recent of the backtrace, and 5 lines of code before / after #This is where the called started
+  backtrace:
+    It displays each line of the backtrace
+    It includes the code from that line
+

data/experiments/formatting/5_potential_structure_dsls.rb

@@ -0,0 +1,88 @@
+# a bunch of different options for what the DSL could look like
+
+def display_location(attributes)
+  formatter      = attributes.fetch :formatter
+  location       = attributes.fetch :location
+  path           = Pathname.new location.path
+  line_index     = location.linenum - 1
+  highlight      = attributes.fetch :highlight, location.label # currently ignoring this, b/c we can't highlight into the middle of the syntax highlighted output
+  end_index      = bound_num min: 0, num: line_index+attributes.fetch(:context).end
+  start_index    = bound_num min: 0, num: line_index+attributes.fetch(:context).begin
+  annotation     = attributes.fetch :annotation, ''
+  message_offset = line_index - start_index
+  emphasize_path = attributes.fetch(:emphasisis) == :path
+  raw_code       = path.exist? && File.read(path).lines[start_index..end_index].join("")
+
+  # explicitly call begin to make the next call a node, call .end to leave
+  formatter
+    .begin.group(:path_with_code)
+      .begin.group(:path, emphasize_path&&:emphasize)
+        .text(:dir,         path_to_dir(@cwd, path, '/'))
+        .text(:filename,    path.basename)
+        .text(:separator,   ":")
+        .text(:line_number, location.linenum)
+      .end
+      .begin.code(raw_code || "Can't find code")
+        .strip_indentation(true)
+        .language(:ruby)
+        .starting_linenum(start_index.next)
+        .if(raw_code).annotate(:error, annotate, line: message_offset)
+      .end
+    .end
+
+  # leaves get !, use .end to end a node
+  formatter
+    .group(:path_with_code)
+      .group(:path, emphasize_path&&:emphasize)
+        .text!(:dir,         path_to_dir(@cwd, path, '/'))
+        .text!(:filename,    path.basename)
+        .text!(:separator,   ":")
+        .text!(:line_number, location.linenum)
+      .end
+      .code(raw_code || "Can't find code")
+        .strip_indentation!
+        .language!(:ruby)
+        .starting_linenum!(start_index.next)
+        .if(raw_code)
+          .annotate!(:error, annotate, line: message_offset)
+        .end
+      .end
+    .end
+
+  # nodes get !
+  formatter
+    .group!(:path_with_code)
+      .group!(:path, emphasize_path&&:emphasize)
+        .text(:dir,         path_to_dir(@cwd, path, '/'))
+        .text(:filename,    path.basename)
+        .text(:separator,   ":")
+        .text(:line_number, location.linenum)
+      .end
+      .code!(raw_code || "Can't find code")
+        .strip_indentation
+        .language(:ruby)
+        .starting_linenum(start_index.next)
+        .if!(raw_code)
+          .annotate(:error, annotate, line: message_offset)
+        .end
+      .end
+    .end
+
+  # swapping self
+  formatter.eval prototype: self do
+    group :path_with_code do
+      group :path, emphasize_path&&:emphasize do
+        text :dir,         path_to_dir(@cwd, path, '/')
+        text :filename,    path.basename
+        text :separator,   ":"
+        text :line_number, location.linenum
+      end
+      code raw_code||"Can't find code" do
+        language :ruby
+        strip_indentation
+        starting_linenum start_index.next
+        annotate :error, annotate, line: message_offset if raw_code
+      end
+    end
+  end
+end

data/experiments/formatting/half_thoughtout_dsl_for_toplevel_structure_of_argument_error.rb

@@ -0,0 +1,43 @@
+SemanticStructure
+  .dsl
+  .partition
+    .header
+      .title!(@info.classname)
+      .subtext(:error)
+        .text!(@info.explanation)
+        .deemphasize
+          .text!(:context,    '(expected ')
+          .text!(:stands_out, @info.num_expected)
+          .text!(:context,    ', sent ')
+          .text!(:stands_out, @info.num_received)
+          .text!(:context,    ')')
+        .end
+      .end
+    .end
+  }
+  .partition { |heuristic|
+    heuristic = display_location formatter:  heuristic,
+                                 annotation: "expected #{@info.num_expected}",
+                                 location:   @info.backtrace[0],
+                                 highlight:  @info.backtrace[0].label,
+                                 context:    0..5,
+                                 emphasisis: :code
+
+    heuristic = display_location formatter:  heuristic
+                                 annotation: "SENT #{info.num_received}",
+                                 location:   info.backtrace[1],
+                                 highlight:  info.backtrace[0].label,
+                                 context:    -5..5,
+                                 emphasisis: :code
+    heuristic
+  }
+  .partition { |fmt|
+    info.backtrace.reduce(fmt) do |formatter, location|
+      display_location formatter:  formatter,
+                       location:   location,
+                       highlight:  location.succ.label,
+                       context:    0..0,
+                       emphasisis: :path
+    end
+  }
+end

data/experiments/formatting/haml_like_structure.rb

@@ -0,0 +1,139 @@
+# hypothetical way to render http://blog.turing.io/images/article_images/error_to_communicate/proof_of_concept-e2d4c91d.png
+# Seems like it would take a lot of work, though, and I'm not totally sure how to map it to HTML/CSS
+
+# =====  KEY  =====
+  defn:      - a tree definition named "defn"
+  defn:<     - a tree definition named "defn" with one child, a node named "defn"
+  node       - a node named "node"
+               if a leaf, then its children may be provided as text
+               or zero or more of any kind of node
+  *node      - zero or more nodes named "node"
+  $ref       - node named "ref" whose children come from a structure definition named "ref"
+  ?node      - zero or one nodes named "node"
+  .class     - a boolean attribute on the containing node (ie a css class)
+  node.class - node has the boolean attribute "attr"
+
+# =====  TEMPLATE  =====
+main:
+  error_type
+    class
+    explanation
+  heuristic
+  backtrace
+    *$codeview
+
+wrong_number_of_arguments:
+  $codeview
+  $codeview
+
+codeview:
+  path
+    ?.emphasize
+    dir
+    file
+    ?line_num
+  code
+    *codeline
+      ?.emphasize
+      ?linenum
+      line
+      ?annotation
+
+message:<
+details:<
+standout:<
+
+# =====  STYLE  =====
+
+error_type {
+  display:       block;
+  border-top:    2px solid white;
+  border-bottom: 2px solid white;
+}
+error_type class {
+  color: #fff;
+  border-right: 1px solid white;
+}
+error_type explanation message  { color: #F00 }
+error_type explanation details  { color: #A00 }
+error_type explanation standout { color: #FFF }
+
+path            { display: block; }
+path.emphasize  { text-decoration: underline; }
+path dir        { color: #088; }
+path file       { color: #08C; }
+path line_num   { color: #04C; }
+
+# should be grayed out if not emphasize
+code            { display: block; }
+code codeline   { display: block; }
+code linenum    { linenum: #04C; }
+code line       { }
+code annotation {
+  background-color: #F00;
+  color:            #FFF;
+  text-transform:   uppercase;
+}
+
+
+# =====  DATA  =====
+bt0 = backtrace[0]
+bt2 = backtrace[1]
+main: {
+  error_type: {
+    class: 'ArgumentError',
+    explanation: [
+      {message: 'wrong number of arguments'},
+      {details: [
+        '(sent ',
+        {standout: 3},
+        ' expected ',
+        {standout: 2},
+        ')',
+      ]}
+    ]
+  },
+  heuristic: [
+    {codeview: {
+      path: {
+        dir:     File.dirname(bt0.path),
+        file:    File.basename(bt0.path),
+        linenum: bt0.linenum,
+      },
+      code: File.read(bt0.path)[bt0.linenum, 5].map.with_index(bt0.linenum) { |line, linenum|
+        { emphasize:  true,
+          linenum:    linenum,
+          line:       line,
+          annotation: ('Expected 2' if linenum == bt0.linenum),
+        }
+      },
+    }},
+    {codeview: {
+      path: {
+        dir:     File.dirname(bt1.path),
+        file:    File.basename(bt1.path),
+        linenum: bt1.linenum,
+      },
+      code: File.read(bt1.path)[bt1.linenum, 5].map.with_index(bt1.linenum) { |line, linenum|
+        { emphasize:  true,
+          linenum:    linenum,
+          line:       line,
+          annotation: ('Sent 3' if linenum == bt1.linenum)
+        }
+      },
+    }},
+  ],
+  backtrace: backtrace.map { |location|
+    { path: {
+        emphasize: true,
+        dir:       File.dirname(location.path),
+        file:      File.basename(location.path),
+        linenum:   location.linenum,
+      },
+      code: {
+        linenum:   location.linenum,
+        line:      File.read(location.path).lines[location.linenum-1],
+      }
+    }
+  }
+}

data/experiments/formatting/other_structures

@@ -0,0 +1,156 @@
+Hypothesis: Everything can be made from the following elements and styling
+  stack (vertical   list)
+  flow  (horizontal list)
+  grid  (basically a table -- overlaid stacks and flows?)
+  text  (an element containing only text)
+
+Shoes:
+  (I'm omitting the methods that seem like they manipulate styles)
+  http://shoesrb.com/manual/Hello.html
+  layout
+    stack
+    flow
+    window
+  generic
+    image
+    video
+    background
+    banner
+    caption
+    code
+    dialog
+    inscription
+  form
+    list_box
+    button
+    check
+    edit_box
+    edit_line
+    radio
+  shapes
+    arc
+    arrow
+    cap
+    line
+    oval
+    rect
+    shape
+    star
+  text
+    para
+    strong
+    title
+    em
+    link
+    ins
+    span
+    sub
+    subtitle
+    sup
+    del
+
+HTML:
+  http://www.w3.org/wiki/HTML/Elements
+  limited to just the ones I was already aware of, or seem useful
+  I've rearranged them a little bit
+  metadata
+    head
+    title
+    link
+    meta
+  sections
+    body
+    section
+    nav
+    article
+    aside
+    h1 - h6
+    header
+    footer
+  grouping
+    hr
+    pre
+    blockquote
+    ol/ul/dl/li/dt/dd
+    figure
+    figcaption
+    div
+    main
+  text
+    p
+    center
+    a
+    acronym
+    abbr
+    br
+    cite
+    code
+    em
+    mark
+    q
+    span
+    small
+    spacer
+    strike
+    strong
+    sub/sup
+    time
+    wbr <-- line break opportunity (who knew!)
+    ins
+    del
+  embedded content
+    img
+    iframe
+    embed
+    object
+    param
+    video
+    audio
+    source
+    track
+    canvas
+    map
+    area
+    math
+    svg
+    applet
+    frame
+    frameset
+    noframes
+    bgsound
+    noembed
+    plaintext
+  tables
+    table
+    caption
+    colgroup
+    col
+    tbody
+    thead
+    tfoot
+    tr
+    td
+    th
+  forms
+    form
+    fieldset
+    legend
+    label
+    input
+    button
+    select
+    datalist
+    optgroup
+    option
+    textarea
+    keygen
+    output
+    progress
+    meter
+  interactive
+    details
+    summary
+    command
+    menu
+  other
+    script