fountainrb 1.0.0

data/lib/fountainrb/inline.rb

@@ -0,0 +1,356 @@
+# frozen_string_literal: true
+
+module FountainRB
+  # Parses and renders the inline markup that can appear inside Fountain
+  # elements: emphasis, notes and soft line breaks.
+  #
+  # Fountain follows Markdown's emphasis rules with one twist: underscores
+  # mean underline rather than italics.
+  #
+  #   *italics*            -> :italic
+  #   **bold**              -> :bold
+  #   ***bold italics***    -> :bold_italic
+  #   _underline_           -> :underline
+  #   [[a note]]            -> :note
+  #
+  # Delimiters that are not closed on the same line are left as literal text,
+  # and a backslash escapes the following character. Emphasis never spans a
+  # line break.
+  module Inline
+    # A node produced by {Inline.parse}.
+    class Node
+      def ==(other)
+        other.class == self.class && other.state == state
+      end
+      alias_method :eql?, :==
+
+      def hash
+        [self.class, state].hash
+      end
+
+      def to_h
+        raise NotImplementedError, "#{self.class}#to_h"
+      end
+
+      protected
+
+      def state
+        []
+      end
+    end
+
+    # Literal text.
+    class Text < Node
+      attr_reader :text
+
+      def initialize(text)
+        @text = text
+      end
+
+      def to_h
+        {"type" => "text", "text" => text}
+      end
+
+      protected
+
+      def state
+        [text]
+      end
+    end
+
+    # Emphasised text. +style+ is one of +:italic+, +:bold+, +:bold_italic+
+    # or +:underline+; +children+ is a list of nodes.
+    class Emphasis < Node
+      STYLES = %i[italic bold bold_italic underline].freeze
+
+      attr_reader :style, :children
+
+      def initialize(style, children)
+        raise ArgumentError, "unknown emphasis style: #{style.inspect}" unless STYLES.include?(style)
+
+        @style = style
+        @children = children
+      end
+
+      def to_h
+        {"type" => style.to_s, "children" => children.map(&:to_h)}
+      end
+
+      protected
+
+      def state
+        [style, children]
+      end
+    end
+
+    # A note -- text wrapped in double brackets. Notes are normally omitted
+    # from formatted output.
+    class Note < Node
+      attr_reader :text
+
+      def initialize(text)
+        @text = text
+      end
+
+      def to_h
+        {"type" => "note", "text" => text}
+      end
+
+      protected
+
+      def state
+        [text]
+      end
+    end
+
+    # A line break inside an element.
+    class LineBreak < Node
+      def to_h
+        {"type" => "line_break"}
+      end
+    end
+
+    # Marker => { run length => emphasis style }.
+    EMPHASIS_MARKERS = {
+      "*" => {3 => :bold_italic, 2 => :bold, 1 => :italic}.freeze,
+      "_" => {1 => :underline}.freeze
+    }.freeze
+
+    HTML_ESCAPES = {
+      "&" => "&amp;",
+      "<" => "&lt;",
+      ">" => "&gt;",
+      '"' => "&quot;",
+      "'" => "&#39;"
+    }.freeze
+
+    # Characters that a backslash may escape. A backslash before anything
+    # else is kept as literal text (as in Markdown).
+    ESCAPABLE = "\\*_[]<>#!~^=.\""
+
+    class << self
+      # Parse +text+ into a flat list of {Inline} nodes.
+      #
+      # @param text [String, nil]
+      # @param connected_blanks [Boolean] allow a note to span a blank line
+      #   (used for element text, where a blank line can only come from a
+      #   deliberate two-space dialogue line)
+      # @return [Array<Node>]
+      def parse(text, connected_blanks: false)
+        text = text.to_s
+        return [] if text.empty?
+
+        nodes = []
+        position = 0
+
+        while position < text.length
+          open = find_note_open(text, position)
+
+          if open.nil?
+            nodes.concat(parse_emphasis(text[position..]))
+            break
+          end
+
+          close = find_note_close(text, open + 2, connected_blanks: connected_blanks)
+
+          if close.nil?
+            # An unterminated note (or one containing a blank line) is not a
+            # note at all; leave it as literal text.
+            nodes.concat(parse_emphasis(text[position..]))
+            break
+          end
+
+          nodes.concat(parse_emphasis(text[position...open])) if open > position
+          nodes << Note.new(text[(open + 2)...close])
+          position = close + 2
+        end
+
+        nodes
+      end
+
+      # Convert inline markup to HTML.
+      #
+      # @param text [String, nil]
+      # @param notes [Boolean] render notes as spans (default: false)
+      # @param connected_blanks [Boolean] see {#parse}
+      # @return [String]
+      def to_html(text, notes: false, connected_blanks: false)
+        render(parse(text, connected_blanks: connected_blanks), notes: notes)
+      end
+
+      # Strip inline markup from +text+.
+      #
+      # @param text [String, nil]
+      # @param notes [Boolean] keep note contents (default: false)
+      # @param connected_blanks [Boolean] see {#parse}
+      # @return [String]
+      def to_plain_text(text, notes: false, connected_blanks: false)
+        parse(text, connected_blanks: connected_blanks).map { |node| plain_node(node, notes) }.join
+      end
+
+      # Render an already parsed list of nodes.
+      def render(nodes, notes: false)
+        nodes.map { |node| render_node(node, notes) }.join
+      end
+
+      # Escape HTML special characters.
+      def escape_html(text)
+        text.to_s.gsub(/[&<>"']/, HTML_ESCAPES)
+      end
+
+      private
+
+      def parse_emphasis(chunk)
+        return [] if chunk.empty?
+
+        nodes = []
+        chunk.split("\n", -1).each_with_index do |line, index|
+          nodes << LineBreak.new if index.positive?
+          nodes.concat(parse_line(line))
+        end
+        nodes
+      end
+
+      def parse_line(line)
+        nodes = []
+        buffer = +""
+        index = 0
+        length = line.length
+
+        while index < length
+          char = line[index]
+
+          if char == "\\"
+            following = line[index + 1]
+            if following && ESCAPABLE.include?(following)
+              buffer << following
+              index += 2
+            else
+              buffer << char
+              index += 1
+            end
+          elsif char == "*" || char == "_"
+            run = char_run(line, index, char)
+            style = EMPHASIS_MARKERS[char][run]
+            close = style && find_emphasis_close(line, index, char, run)
+
+            if close
+              unless buffer.empty?
+                nodes << Text.new(buffer)
+                buffer = +""
+              end
+              inner = line[(index + run)...close]
+              nodes << Emphasis.new(style, parse_line(inner))
+              index = close + run
+            else
+              buffer << char
+              index += 1
+            end
+          else
+            buffer << char
+            index += 1
+          end
+        end
+
+        nodes << Text.new(buffer) unless buffer.empty?
+        nodes
+      end
+
+      # Length of the run of +char+ starting at +start+.
+      def char_run(line, start, char)
+        run = 0
+        run += 1 while line[start + run] == char
+        run
+      end
+
+      # Find the index of a closing delimiter of exactly +run+ characters.
+      # Escaped characters are skipped and a closing delimiter may not be
+      # preceded by whitespace.
+      def find_emphasis_close(line, start, char, run)
+        content_start = start + run
+        return nil if content_start >= line.length
+        return nil if line[content_start].match?(/\s/)
+
+        index = content_start
+
+        while index < line.length
+          if line[index] == "\\"
+            index += 2
+          elsif line[index] == char
+            length = char_run(line, index, char)
+            if length == run && index.positive? && !line[index - 1].match?(/\s/)
+              return index
+            end
+            index += length
+          else
+            index += 1
+          end
+        end
+
+        nil
+      end
+
+      # Find an unescaped note opener (a "[[" with an even number of
+      # preceding backslashes).
+      def find_note_open(text, from)
+        index = from
+
+        while (open = text.index("[[", index))
+          backslashes = 0
+          cursor = open - 1
+          while cursor >= 0 && text[cursor] == "\\"
+            backslashes += 1
+            cursor -= 1
+          end
+          return open if backslashes.even?
+
+          index = open + 1
+        end
+
+        nil
+      end
+
+      # The end of a note may not cross a blank line unless the caller says
+      # the blank line is a deliberate connected break ("Fountain won't look
+      # past a double line break").
+      def find_note_close(text, from, connected_blanks: false)
+        close = text.index("]]", from)
+        return nil unless close
+        return nil if !connected_blanks && text[from...close].match?(/\n[ \t]*\n/)
+
+        close
+      end
+
+      def render_node(node, notes)
+        case node
+        when Text
+          escape_html(node.text)
+        when LineBreak
+          "<br>"
+        when Note
+          notes ? %(<span class="note">#{escape_html(node.text)}</span>) : ""
+        when Emphasis
+          inner = render(node.children, notes: notes)
+          case node.style
+          when :italic then "<em>#{inner}</em>"
+          when :bold then "<strong>#{inner}</strong>"
+          when :bold_italic then "<strong><em>#{inner}</em></strong>"
+          when :underline then "<u>#{inner}</u>"
+          end
+        else
+          ""
+        end
+      end
+
+      def plain_node(node, notes)
+        case node
+        when Text then node.text
+        when LineBreak then "\n"
+        when Note then notes ? node.text : ""
+        when Emphasis then node.children.map { |child| plain_node(child, notes) }.join
+        else ""
+        end
+      end
+    end
+  end
+end

data/lib/fountainrb/parser.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module FountainRB
+  # Parses Fountain source into a {Screenplay}.
+  #
+  #   screenplay = FountainRB::Parser.new(source).parse
+  #   screenplay.elements.each { |element| puts element.type }
+  #
+  # Parsing never raises on malformed markup: when in doubt, Fountain returns
+  # the text as Action. Unclosed emphasis, notes and boneyards are left as
+  # literal text.
+  class Parser
+    # @return [String] the normalised source being parsed
+    attr_reader :source
+
+    def initialize(source)
+      @source = normalise(source)
+    end
+
+    # @return [Screenplay]
+    def parse
+      lines = source.split("\n", -1)
+      title_page, body_start = split_title_page(lines)
+
+      body = (body_start < lines.size) ? lines[body_start..].join("\n") : ""
+      tokenizer = Tokenizer.new(body, line_offset: body_start)
+
+      Screenplay.new(
+        source: source,
+        title_page: title_page,
+        elements: build_elements(tokenizer.tokens),
+        boneyards: tokenizer.boneyards
+      )
+    end
+
+    private
+
+    def normalise(source)
+      source.to_s.sub(/\A\uFEFF/, "").gsub(/\r\n?/, "\n")
+    end
+
+    def split_title_page(lines)
+      start = 0
+      start += 1 while start < lines.size && lines[start].strip.empty?
+      return [nil, 0] if start >= lines.size
+
+      parsed = TitlePage.parse(lines, start)
+      return [nil, 0] unless parsed
+
+      [parsed[0], parsed[1]]
+    end
+
+    def build_elements(tokens)
+      elements = []
+      pending_blanks = 0
+      can_merge = false
+
+      tokens.each do |token|
+        case token.type
+        when :blank
+          pending_blanks += 1
+          can_merge = false
+        when :hard_break
+          last = elements.last
+          last&.append_line("") if last&.multiline?
+        else
+          element = build_element(token, pending_blanks)
+          pending_blanks = 0
+
+          if can_merge && mergeable?(elements.last, element)
+            elements.last.merge!(element)
+          else
+            elements << element
+            can_merge = true
+          end
+        end
+      end
+
+      elements
+    end
+
+    def mergeable?(last, element)
+      return false if last.nil?
+
+      case element
+      when Action then last.is_a?(Action)
+      when Dialogue then last.is_a?(Dialogue)
+      when Lyrics then last.is_a?(Lyrics)
+      else false
+      end
+    end
+
+    def build_element(token, blank_before)
+      base = {line: token.line, blank_before: blank_before}
+
+      case token.type
+      when :scene_heading
+        SceneHeading.new(
+          text: token.text,
+          scene_number: token[:scene_number],
+          forced: token.forced?,
+          **base
+        )
+      when :action
+        Action.new(text: token.text, forced: token.forced?, **base)
+      when :character
+        Character.new(
+          name: token[:name],
+          extensions: token[:extensions],
+          dual: token[:dual],
+          forced: token.forced?,
+          **base
+        )
+      when :parenthetical
+        Parenthetical.new(text: token.text, **base)
+      when :dialogue
+        Dialogue.new(text: token.text, **base)
+      when :lyrics
+        Lyrics.new(text: token.text, **base)
+      when :transition
+        Transition.new(text: token.text, forced: token.forced?, **base)
+      when :centered
+        Centered.new(text: token.text, **base)
+      when :page_break
+        PageBreak.new(text: token.text, **base)
+      when :section
+        Section.new(text: token.text, level: token[:level], **base)
+      when :synopsis
+        Synopsis.new(text: token.text, **base)
+      when :note
+        Note.new(text: token.text, **base)
+      else
+        Action.new(text: token.text, **base)
+      end
+    end
+  end
+end

data/lib/fountainrb/plain_text_renderer.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module FountainRB
+  # Renders a {Screenplay} as plain text with screenplay-ish indentation.
+  #
+  # This is intentionally simple -- it is useful for quick inspection and for
+  # tests, but it is not a typesetter. Lines are not wrapped.
+  class PlainTextRenderer
+    # Left indentation for each element type.
+    INDENTS = {
+      character: 20,
+      parenthetical: 16,
+      dialogue: 8,
+      lyrics: 8,
+      transition: 0,
+      centered: 20
+    }.freeze
+
+    # @param notes [Boolean] include notes (default: false)
+    # @param sections [Boolean] include sections (default: false)
+    # @param synopses [Boolean] include synopses (default: false)
+    # @param title_page [Boolean] include the title page (default: true)
+    # @param page_breaks [Boolean] include a form feed for page breaks
+    def initialize(notes: false, sections: false, synopses: false,
+      title_page: true, page_breaks: false)
+      @notes = notes
+      @sections = sections
+      @synopses = synopses
+      @title_page = title_page
+      @page_breaks = page_breaks
+    end
+
+    # @param screenplay [Screenplay]
+    # @return [String]
+    def render(screenplay)
+      lines = []
+
+      if @title_page && screenplay.title_page
+        title_lines = render_title_page(screenplay.title_page)
+        lines.concat(title_lines) unless title_lines.empty?
+      end
+
+      previous = nil
+      screenplay.units.each do |unit|
+        rendered = render_unit(unit)
+        next if rendered.nil?
+
+        lines << "" unless lines.empty? || tight?(previous, unit)
+        lines.concat(rendered)
+        previous = unit
+      end
+
+      result = lines.join("\n").rstrip
+      result.empty? ? "" : "#{result}\n"
+    end
+
+    private
+
+    def render_unit(unit)
+      case unit
+      when DialogueBlock then render_dialogue_block(unit)
+      when DualDialogue then render_dual_dialogue(unit)
+      when SceneHeading then text_lines(unit.text)
+      when Action then text_lines(unit.text)
+      when Lyrics then indented(unit.text, INDENTS[:lyrics])
+      when Transition then [unit.text]
+      when Centered then indented(unit.text, INDENTS[:centered])
+      when PageBreak then @page_breaks ? ["\f"] : nil
+      when Section then @sections ? ["#{"#" * unit.level} #{unit.text}".rstrip] : nil
+      when Synopsis then @synopses ? ["= #{unit.text}"] : nil
+      when Note then @notes ? note_lines(unit.text) : nil
+      end
+    end
+
+    def render_title_page(page)
+      lines = []
+
+      page.entries.each do |_key, values|
+        values.each { |value| lines << Inline.to_plain_text(value, notes: @notes) }
+        lines << ""
+      end
+
+      lines.pop if lines.last == ""
+      lines
+    end
+
+    def render_dialogue_block(block)
+      character = block.character
+      cue = character.name
+      character.extensions.each { |extension| cue += " (#{extension})" }
+
+      lines = [indent(cue, INDENTS[:character])]
+
+      block.parts.each do |part|
+        case part
+        when Parenthetical
+          lines << indent(part.text, INDENTS[:parenthetical])
+        when Dialogue
+          lines.concat(indented(part.text, INDENTS[:dialogue]))
+        when Note
+          lines.concat(note_lines(part.text)) if @notes
+        end
+      end
+
+      lines
+    end
+
+    def render_dual_dialogue(dual)
+      left = render_dialogue_block(dual.left)
+      right = render_dialogue_block(dual.right)
+      width = [left.map(&:length).max, right.map(&:length).max].max
+      left.map { |line| line.ljust(width) }
+        .zip(right)
+        .map { |l, r| "#{l}  #{r}".rstrip }
+    end
+
+    def note_lines(text)
+      text.split("\n", -1).map { |line| "[[#{line}]]" }
+    end
+
+    def text_lines(text)
+      text.split("\n", -1).map { |line| Inline.to_plain_text(line, notes: @notes) }
+    end
+
+    def indented(text, count)
+      text.split("\n", -1).map { |line| indent(Inline.to_plain_text(line, notes: @notes), count) }
+    end
+
+    def indent(line, count)
+      line.empty? ? "" : (" " * count) + line
+    end
+
+    def tight?(previous, unit)
+      previous.is_a?(DialogueBlock) && unit.is_a?(DialogueBlock) && unit.dual?
+    end
+  end
+end