govspeak 4.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6e737eca62f51b5b954bc37b5fc55d2ba680bb8b
-  data.tar.gz: bf6f399b9badf4708ee7f4f9c6ca50a157493ac5
+  metadata.gz: 726774ba404422dd313e1afb12bbc3d1c2e036fd
+  data.tar.gz: 4f7e5f0f7b4c9e67c33120050f3021048c13dec7
 SHA512:
-  metadata.gz: 9363e23283391abf19861ce9522b7cf30874aeecf37b7274dd19411a7539f1956ba3043218601fbc694acde33f2c062fc71f8bd1f113ce9884ca2e7938f1784f
-  data.tar.gz: efe6a7cda89d313ef06470fa0a5e71acc40d85b16ebe8ab95928865e4f20295e7663a4fa43a1e428a5edd2943a6949a96cbc9ec7c31bac28c2322f3a5ba5f353
+  metadata.gz: a144b4353edd665f01109bd1eae1ff569f22ea6133bf564024e973d7df730e9f318d9eb76e76df5917e130b10dbf9897dcbcd75ccfdb816ba291b16e3e9349a0
+  data.tar.gz: 8370760f5a9929f8c33b001d99fc5409900182d815bbae0059c33360d47ef7ccd560ae4b206bdec7940747b73ce9e544edffd10751a7107070b8a9aa49006e8f

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 5.0.0
+* Update Kramdown version to 1.12.0
+* Add pry-byebug to development dependencies
+* Ability to run Govspeak as a binary from command line [#87](https://github.com/alphagov/govspeak/pull/87)
+* Uses hashes the primary interface for options to commands [#89](https://github.com/alphagov/govspeak/pull/89)
+* Adds the `[embed:attachments:image:%content_id%]` extension [#90](https://github.com/alphagov/govspeak/pull/90)
+* Renders incorrect usages of embedding content as empty strings rather than outputting markdown [91](https://github.com/alphagov/govspeak/pull/91)
+
 ## 4.0.0
 
 * Drop support for Ruby 1.9.3

data/README.md

@@ -18,6 +18,18 @@ then create a new document
     doc = Govspeak::Document.new "^Test^"
     puts doc.to_html
 
+or alternatively, run it from the command line
+
+    $ govspeak "render-me"
+    $ govspeak --file render-me.md
+    $ echo "render-me" | govspeak
+
+options can be passed in through `--options` as a string of JSON or a file
+of JSON can be passed in as `--options-file options.json`.
+
+if installed via bundler prefix commands with bundle exec eg `$ bundle exec govspeak "render-me"`
+
+
 # Extensions
 
 In addition to the [standard Markdown syntax](http://daringfireball.net/projects/markdown/syntax "Markdown syntax"), we have added our own extensions.

data/bin/govspeak

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+lib = File.expand_path("../../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "govspeak/cli"
+
+Govspeak::CLI.new.run

data/lib/govspeak.rb

@@ -1,4 +1,6 @@
 require 'kramdown'
+require 'active_support/core_ext/hash'
+require 'active_support/core_ext/array'
 require 'govspeak/header_extractor'
 require 'govspeak/structured_header_extractor'
 require 'govspeak/html_validator'
@@ -9,6 +11,7 @@ require 'govspeak/post_processor'
 require 'kramdown/parser/kramdown_with_automatic_external_links'
 require 'htmlentities'
 require 'presenters/attachment_presenter'
+require 'presenters/contact_presenter'
 require 'presenters/h_card_presenter'
 require 'erb'
 
@@ -29,11 +32,12 @@ module Govspeak
     end
 
     def initialize(source, options = {})
+      options.deep_symbolize_keys!
       @source = source ? source.dup : ""
       @images = options.delete(:images) || []
-      @attachments = Array(options.delete(:attachments))
-      @links = Array(options.delete(:links))
-      @contacts = Array(options.delete(:contacts))
+      @attachments = Array.wrap(options.delete(:attachments))
+      @links = Array.wrap(options.delete(:links))
+      @contacts = Array.wrap(options.delete(:contacts))
       @locale = options.fetch(:locale, "en")
       @options = {input: PARSER_CLASS_NAME}.merge(options)
       @options[:entity_output] = :symbolic
@@ -185,29 +189,52 @@ module Govspeak
       end
     end
 
-    extension('attachment', /\[embed:attachments:([0-9a-f-]+)\]/) do |content_id, body|
-      attachment = attachments.detect { |a| a.content_id.match(content_id) }
+    extension('attachment', /\[embed:attachments:(?!inline:|image:)\s*(.*?)\s*\]/) do |content_id, body|
+      attachment = attachments.detect { |a| a[:content_id].match(content_id) }
       next "" unless attachment
       attachment = AttachmentPresenter.new(attachment)
-      content = File.read('lib/govspeak/extension/attachment.html.erb')
+      content = File.read(__dir__ + '/templates/attachment.html.erb')
       ERB.new(content).result(binding)
     end
 
-    extension('attachment inline', /\[embed:attachments:inline:([0-9a-f-]+)\]/) do |content_id, body|
-      attachment = attachments.detect { |a| a.content_id.match(content_id) }
+    extension('attachment inline', /\[embed:attachments:inline:\s*(.*?)\s*\]/) do |content_id|
+      attachment = attachments.detect { |a| a[:content_id].match(content_id) }
       next "" unless attachment
       attachment = AttachmentPresenter.new(attachment)
-      content = File.read('lib/govspeak/extension/inline_attachment.html.erb')
-      ERB.new(content).result(binding)
+      span_id = attachment.id ? %{ id="attachment_#{attachment.id}"} : ""
+      # new lines inside our title cause problems with govspeak rendering as this is expected to be on one line.
+      title = (attachment.title || "").tr("\n", " ")
+      link = attachment.link(title, attachment.url)
+      attributes = attachment.attachment_attributes.empty? ? "" : " (#{attachment.attachment_attributes})"
+      %{<span#{span_id} class="attachment-inline">#{link}#{attributes}</span>}
     end
 
-    def render_image(url, alt_text, caption = nil)
+    extension('attachment image', /\[embed:attachments:image:\s*(.*?)\s*\]/) do |content_id|
+      attachment = attachments.detect { |a| a[:content_id].match(content_id) }
+      next "" unless attachment
+      attachment = AttachmentPresenter.new(attachment)
+      title = (attachment.title || "").tr("\n", " ")
+      render_image(attachment.url, title, nil, attachment.id)
+    end
+
+    # As of version 1.12.0 of Kramdown the block elements (div & figcaption)
+    # inside this html block will have it's < > converted into HTML Entities
+    # when ever this code is used inside block level elements.
+    #
+    # To resolve this we have a post-processing task that will convert this
+    # back into HTML (I know - it's ugly). The way we could resolve this
+    # without ugliness would be to output only inline elements which rules
+    # out div and figcaption
+    #
+    # This issue is not considered a bug by kramdown: https://github.com/gettalong/kramdown/issues/191
+    def render_image(url, alt_text, caption = nil, id = nil)
+      id_attr = id ? %{ id="attachment_#{id}"} : ""
       lines = []
-      lines << '<figure class="image embedded">'
-      lines << %Q{  <div class="img"><img alt="#{encode(alt_text)}" src="#{encode(url)}" /></div>}
-      lines << %Q{  <figcaption>#{encode(caption.strip)}</figcaption>} if caption && !caption.strip.empty?
+      lines << %{<figure#{id_attr} class="image embedded">}
+      lines << %Q{<div class="img"><img src="#{encode(url)}" alt="#{encode(alt_text)}"></div>}
+      lines << %Q{<figcaption>#{caption.strip}</figcaption>} if caption && !caption.strip.empty?
       lines << '</figure>'
-      lines.join "\n"
+      lines.join
     end
 
     wrap_with_div('summary', '$!')
@@ -272,13 +299,13 @@ module Govspeak
       end
     end
 
-    extension('embed link', /\[embed:link:([0-9a-f-]+)\]/) do |content_id|
-      link = links.detect { |l| l.content_id.match(content_id) }
+    extension('embed link', /\[embed:link:\s*(.*?)\s*\]/) do |content_id|
+      link = links.detect { |l| l[:content_id].match(content_id) }
       next "" unless link
-      if link.url
-        %Q{<a href="#{encode(link.url)}">#{encode(link.title)}</a>}
+      if link[:url]
+        %Q{<a href="#{encode(link[:url])}">#{link[:title]}</a>}
       else
-        encode(link.title)
+        link[:title]
       end
     end
 
@@ -287,10 +314,11 @@ module Govspeak
     end
     private :render_hcard_address
 
-    extension('Contact', /\[Contact:([0-9a-f-]+)\]/) do |content_id|
-      contact = contacts.detect { |c| c.content_id.match(content_id) }
+    extension('Contact', /\[Contact:\s*(.*?)\s*\]/) do |content_id|
+      contact = contacts.detect { |c| c[:content_id].match(content_id) }
       next "" unless contact
-      @renderer ||= ERB.new(File.read('lib/templates/contact.html.erb'))
+      contact = ContactPresenter.new(contact)
+      @renderer ||= ERB.new(File.read(__dir__ + '/templates/contact.html.erb'))
       @renderer.result(binding)
     end
   end

data/lib/govspeak/cli.rb

@@ -0,0 +1,51 @@
+require 'govspeak/version'
+require 'govspeak'
+require 'commander'
+
+module Govspeak
+  class CLI
+    include Commander::Methods
+
+    def run
+      program(:name, 'Govspeak')
+      program(:version, Govspeak::VERSION)
+      program(:description, "A tool for rendering the GOV.UK dialect of markdown into HTML")
+      default_command(:render)
+      command(:render) do |command|
+        command.syntax = "govspeak render [options] <input>"
+        command.description = "Render Govspeak into HTML, can be sourced from stdin, as an argument or from a file"
+        command.option("--file FILENAME", String, "File to render")
+        command.option("--options JSON", String, "JSON to use as options")
+        command.option("--options-file FILENAME", String, "A file of JSON options")
+        command.action do |args, options|
+          input = get_input($stdin, args, options)
+          raise "Nothing to render. Use --help for assistance" unless input
+          puts Govspeak::Document.new(input, govspeak_options(options)).to_html
+        end
+      end
+      run!
+    end
+
+  private
+
+    def get_input(stdin, args, options)
+      return stdin.read unless stdin.tty?
+      return read_file(options.file) if options.file
+      args.empty? ? nil : args.join(" ")
+    end
+
+    def read_file(file_path)
+      path = Pathname.new(file_path).realpath
+      File.read(path)
+    end
+
+    def govspeak_options(command_options)
+      string = if command_options.options_file
+                read_file(command_options.options_file)
+               else
+                command_options.options
+               end
+      string ? JSON.load(string) : {}
+    end
+  end
+end

data/lib/govspeak/post_processor.rb

@@ -38,5 +38,31 @@ module Govspeak
         el[:class] = "last-child"
       end
     end
+
+    # This "fix" here is tied into the rendering of images as one of the
+    # pre-processor tasks. As images can be created inside block level elements
+    # it's possible that their block level elements can be HTML entity escaped
+    # to produce "valid" HTML.
+    #
+    # This sucks for us as we spit the user out HTML elements.
+    #
+    # This fix reverses this, and of course, totally sucks because it's tightly
+    # coupled to the `render_image` code and it really isn't cool to undo HTML
+    # entity encoding.
+    extension("fix image attachment escaping") do |document|
+      document.css("figure.image").map do |el|
+        xml = el.children.to_s
+        next unless xml =~ /<div class="img">|<figcaption>/
+        el.children = xml
+          .gsub(
+            %r{<(div class="img")>(.*?)<(/div)>},
+            "<\\1>\\2<\\3>"
+          )
+          .gsub(
+            %r{&lt;(figcaption)&gt;(.*?)&lt;(/figcaption&)gt;},
+            "<\\1>\\2<\\3>"
+          )
+      end
+    end
   end
 end

data/lib/govspeak/version.rb

@@ -1,3 +1,3 @@
 module Govspeak
-  VERSION = "4.0.0"
+  VERSION = "5.0.0"
 end

data/lib/presenters/attachment_presenter.rb

@@ -1,77 +1,80 @@
 require "action_view"
 require "money"
+require "htmlentities"
 
 class AttachmentPresenter
   attr_reader :attachment
   include ActionView::Helpers::TagHelper
   include ActionView::Helpers::NumberHelper
   include ActionView::Helpers::AssetTagHelper
+  include ActionView::Helpers::TextHelper
 
   def initialize(attachment)
     @attachment = attachment
   end
 
   def id
-    attachment.id
+    attachment[:id]
   end
 
   def order_url
-    attachment.order_url
+    attachment[:order_url]
   end
 
   def opendocument?
-    attachment.opendocument?
+    attachment[:opendocument?]
   end
 
   def url
-    attachment.url
+    attachment[:url]
   end
 
   def external?
-    attachment.external?
+    attachment[:external?]
   end
 
   def price
-    return unless attachment.price
-    Money.from_amount(attachment.price, 'GBP').format
+    return unless attachment[:price]
+    Money.from_amount(attachment[:price], 'GBP').format
   end
 
   def accessible?
-    attachment.accessible?
+    attachment[:accessible?]
   end
 
   def thumbnail_link
     return if hide_thumbnail?
     return if previewable?
-    link(attachment_thumbnail, url, "aria-hidden=true class=#{attachment_class}")
+    link(attachment_thumbnail, url, "aria-hidden" => "true", "class" => attachment_class)
   end
 
   def help_block_toggle_id
-    "attachment-#{attachment.id}-accessibility-request"
+    "attachment-#{id}-accessibility-request"
   end
 
   def section_class
-    attachment.external? ? "hosted-externally" : "embedded"
+    attachment[:external?] ? "hosted-externally" : "embedded"
   end
 
   def mail_to(email_address, name, options = {})
-    "<a href='mailto:#{email_address}?Subject=#{options[:subject]}&body=#{options[:body]}'>#{name}</a>"
+    query_string = options.slice(:subject, :body).map { |k, v| "#{urlencode(k)}=#{urlencode(v)}" }.join("&")
+    "<a href='mailto:#{encode(email_address)}?#{encode(query_string)}'>#{name}</a>"
   end
 
   def alternative_format_order_link
     attachment_info = []
-    attachment_info << "  Title: #{attachment.title}"
-    attachment_info << "  Original format: #{attachment.file_extension}"
-    attachment_info << "  ISBN: #{attachment.isbn}" if attachment.isbn.present?
-    attachment_info << "  Unique reference: #{attachment.unique_reference}" if attachment.unique_reference.present?
-    attachment_info << "  Command paper number: #{attachment.command_paper_number}" if attachment.command_paper_number.present?
-    if attachment.hoc_paper_number.present?
-      attachment_info << "  House of Commons paper number: #{attachment.hoc_paper_number}"
-      attachment_info << "  Parliamentary session: #{attachment.parliamentary_session}"
+    attachment_info << "  Title: #{title}"
+    attachment_info << "  Original format: #{file_extension}" if file_extension.present?
+    attachment_info << "  ISBN: #{attachment[:isbn]}" if attachment[:isbn].present?
+    attachment_info << "  Unique reference: #{attachment[:unique_reference]}" if attachment[:unique_reference].present?
+    attachment_info << "  Command paper number: #{attachment[:command_paper_number]}" if attachment[:command_paper_number].present?
+    if attachment[:hoc_paper_number].present?
+      attachment_info << "  House of Commons paper number: #{attachment[:hoc_paper_number]}"
+      attachment_info << "  Parliamentary session: #{attachment[:parliamentary_session]}"
     end
 
     options = {
-      subject: "Request for '#{attachment.title}' in an alternative format",
+      subject: "Request for '#{title}' in an alternative format",
       body: body_for_mail(attachment_info)
     }
 
@@ -80,7 +83,7 @@ class AttachmentPresenter
 
   def body_for_mail(attachment_info)
     <<-END
-    Details of document required:
+Details of document required:
 
 #{attachment_info.join("\n")}
 
@@ -95,66 +98,93 @@ Please tell us:
     "govuk-feedback@digital.cabinet-office.gov.uk"
   end
 
+  # FIXME: usage of image_tag will cause these to render at /images/ which seems
+  # very host dependent. I assume this will need links to static urls.
   def attachment_thumbnail
-    if attachment.pdf?
-      image_tag(attachment.file.thumbnail.url)
-    elsif attachment.html?
+    if file_extension == "pdf" && attachment[:thumbnail_url]
+      image_tag(attachment[:thumbnail_url])
+    elsif file_extension == "html"
       image_tag('pub-cover-html.png')
-    elsif %w{doc docx odt}.include? attachment.file_extension
+    elsif %w{doc docx odt}.include?(file_extension)
       image_tag('pub-cover-doc.png')
-    elsif %w{xls xlsx ods csv}.include? attachment.file_extension
+    elsif %w{xls xlsx ods csv}.include?(file_extension)
       image_tag('pub-cover-spreadsheet.png')
     else
       image_tag('pub-cover.png')
     end
   end
 
-  def references
+  def reference
+    ref = []
+    if attachment[:isbn].present?
+      ref << "ISBN " + content_tag(:span, attachment[:isbn], class: "isbn")
+    end
+
+    if attachment[:unique_reference].present?
+      ref << content_tag(:span, attachment[:unique_reference], class: "unique_reference")
+    end
+
+    if attachment[:command_paper_number].present?
+      ref << content_tag(:span, attachment[:command_paper_number], class: "command_paper_number")
+    end
+
+    if attachment[:hoc_paper_number].present?
+      ref << content_tag(:span, "HC #{attachment[:hoc_paper_number]}", class: 'house_of_commons_paper_number') + ' ' +
+        content_tag(:span, attachment[:parliamentary_session], class: 'parliamentary_session')
+    end
+
+    ref.join(', ').html_safe
+  end
+
+  # FIXME this has english in it so will cause problems if the locale is not en
+  def references_for_title
     references = []
-    references << "ISBN: #{attachment.isbn}" if attachment.isbn.present?
-    references << "Unique reference: #{attachment.unique_reference}" if attachment.unique_reference.present?
-    references << "Command paper number: #{attachment.command_paper_number}" if attachment.command_paper_number.present?
-    references << "HC: #{attachment.hoc_paper_number} #{attachment.parliamentary_session}" if attachment.hoc_paper_number.present?
+    references << "ISBN: #{attachment[:isbn]}" if attachment[:isbn].present?
+    references << "Unique reference: #{attachment[:unique_reference]}" if attachment[:unique_reference].present?
+    references << "Command paper number: #{attachment[:command_paper_number]}" if attachment[:command_paper_number].present?
+    references << "HC: #{attachment[:hoc_paper_number]} #{attachment[:parliamentary_session]}" if attachment[:hoc_paper_number].present?
     prefix = references.size == 1 ? "and its reference" : "and its references"
     references.any? ? ", #{prefix} (" + references.join(", ") + ")" : ""
   end
 
   def references?
-    !attachment.isbn.to_s.empty? || !attachment.unique_reference.to_s.empty? || !attachment.command_paper_number.to_s.empty? || !attachment.hoc_paper_number.to_s.empty?
+    !attachment[:isbn].to_s.empty? || !attachment[:unique_reference].to_s.empty? || !attachment[:command_paper_number].to_s.empty? || !attachment[:hoc_paper_number].to_s.empty?
   end
 
   def attachment_class
-    attachment.external? ? "hosted-externally" : "embedded"
+    attachment[:external?] ? "hosted-externally" : "embedded"
   end
 
   def unnumbered_paper?
-    attachment.unnumbered_command_paper? || attachment.unnumbered_hoc_paper?
+    attachment[:unnumbered_command_paper?] || attachment[:unnumbered_hoc_paper?]
   end
 
   def unnumbered_command_paper?
-    attachment.unnumbered_command_paper?
+    attachment[:unnumbered_command_paper?]
   end
 
   def download_link
-    link(attachment.preview_url, "<strong>Download #{attachment.file_extension.upcase}</strong>", number_to_human_size(attachment.file_size))
+    options = {}
+    options[:title] = number_to_human_size(attachment[:file_size]) if attachment[:file_size].present?
+    link("<strong>Download #{file_extension.upcase}</strong>", attachment[:url], options)
   end
 
   def attachment_attributes
     attributes = []
-    if attachment.html?
+    if file_extension == "html"
       attributes << content_tag(:span, 'HTML', class: 'type')
-    elsif attachment.external?
+    elsif attachment[:external?]
       attributes << content_tag(:span, url, class: 'url')
     else
-      attributes << content_tag(:span, humanized_content_type(attachment.file_extension), class: 'type')
-      attributes << content_tag(:span, number_to_human_size(attachment.file_size), class: 'file-size')
-      attributes << content_tag(:span, pluralize(attachment.number_of_pages, "page") , class: 'page-length') if attachment.number_of_pages.present?
+      attributes << content_tag(:span, humanized_content_type(file_extension), class: 'type') if file_extension
+      attributes << content_tag(:span, number_to_human_size(attachment[:file_size]), class: 'file-size') if attachment[:file_size]
+      attributes << content_tag(:span, pluralize(attachment[:number_of_pages], "page"), class: 'page-length') if attachment[:number_of_pages]
     end
     attributes.join(', ').html_safe
   end
 
   def preview_url
-    url << '/preview'
+    url + '/preview'
   end
 
   MS_WORD_DOCUMENT_HUMANIZED_CONTENT_TYPE = "MS Word Document"
@@ -205,37 +235,52 @@ Please tell us:
   end
 
   def previewable?
-    attachment.csv?
+    file_extension == "csv"
   end
 
   def title
-    attachment.title
+    attachment[:title]
+  end
+
+  def file_extension
+    # Note: this is a separate parameter rather than being calculated from the
+    # filename because at the time of writing not all apps were using the effects
+    # of this field.
+    attachment[:file_extension]
   end
 
   def hide_thumbnail?
     defined?(hide_thumbnail) && hide_thumbnail
   end
 
-  def attachement_details
+  def attachment_details
     return if previewable?
-    link(attachment.title, url, title_link_options)
+    link(title, url, title_link_options)
   end
 
   def title_link_options
-    title_link_options = ''
-    title_link_options << "rel=external" if attachment.external?
-    title_link_options << "aria-describedby=#{help_block_id}" unless attachment.accessible?
+    title_link_options = {}
+    title_link_options["rel"] = "external" if attachment[:external?]
+    title_link_options["aria-describedby"] = help_block_id unless attachment[:accessible?]
+    title_link_options
   end
 
   def help_block_id
-    "attachment-#{attachment.id}-accessibility-help"
+    "attachment-#{id}-accessibility-help"
   end
 
-  def link(body, url, options={})
-    <<-END
-      <a href="#{url} #{options}">
-        #{body}
-      </a>
-    END
+  def link(body, url, options = {})
+    options_str = options.map { |k, v| %{#{encode(k)}="#{encode(v)}"} }.join(" ")
+    %{<a href="#{encode(url)}" #{options_str}>#{body}</a>}
+  end
+
+private
+
+  def encode(text)
+    HTMLEntities.new.encode(text)
+  end
+
+  def urlencode(text)
+    ERB::Util.url_encode(text)
   end
 end