fountainrb 1.0.0

data/lib/fountainrb/screenplay.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module FountainRB
+  # A character cue together with the parentheticals, dialogue and notes that
+  # belong to it.
+  class DialogueBlock
+    attr_reader :character, :parts
+
+    def initialize(character, parts = [])
+      @character = character
+      @parts = parts
+    end
+
+    def dual?
+      character.dual?
+    end
+
+    def dialogue
+      parts.select { |part| part.is_a?(Dialogue) }
+    end
+
+    def parentheticals
+      parts.select { |part| part.is_a?(Parenthetical) }
+    end
+
+    def notes
+      character.notes + parts.flat_map(&:notes)
+    end
+
+    # All spoken text in the block, separated by newlines.
+    def text
+      dialogue.map(&:text).join("\n")
+    end
+
+    def to_h
+      {
+        "type" => "dialogue_block",
+        "character" => character.to_h,
+        "parts" => parts.map(&:to_h)
+      }
+    end
+  end
+
+  # Two dialogue blocks that are spoken simultaneously.
+  class DualDialogue
+    attr_reader :left, :right
+
+    def initialize(left, right)
+      @left = left
+      @right = right
+    end
+
+    def blocks
+      [left, right]
+    end
+
+    def to_h
+      {
+        "type" => "dual_dialogue",
+        "left" => left.to_h,
+        "right" => right.to_h
+      }
+    end
+  end
+
+  # The result of parsing a Fountain document.
+  #
+  # A screenplay enumerates its elements (in source order) and provides
+  # convenience accessors plus renderers.
+  #
+  #   screenplay = FountainRB.parse(File.read("brick_and_steel.fountain"))
+  #   screenplay.title_page.title       #=> ["BRICK & STEEL", "FULL RETIRED"]
+  #   screenplay.scenes.first.text      #=> "EXT. BRICK'S PATIO - DAY"
+  #   screenplay.character_names        #=> ["STEEL", "BRICK", ...]
+  #   puts screenplay.to_html
+  class Screenplay
+    include Enumerable
+
+    attr_reader :source, :title_page, :elements, :boneyards
+
+    def initialize(source: "", title_page: nil, elements: [], boneyards: [])
+      @source = source
+      @title_page = title_page
+      @elements = elements
+      @boneyards = boneyards
+    end
+
+    def each(&block)
+      elements.each(&block)
+    end
+
+    def [](index)
+      elements[index]
+    end
+
+    def size
+      elements.size
+    end
+    alias_method :length, :size
+
+    def empty?
+      elements.empty?
+    end
+
+    def first
+      elements.first
+    end
+
+    def last
+      elements.last
+    end
+
+    # Elements of a given type symbol, e.g. +:dialogue+.
+    def of_type(type)
+      elements.select { |element| element.type == type }
+    end
+
+    def scenes
+      elements.select { |element| element.is_a?(SceneHeading) }
+    end
+    alias_method :scene_headings, :scenes
+
+    def action
+      elements.select { |element| element.is_a?(Action) }
+    end
+
+    def characters
+      elements.select { |element| element.is_a?(Character) }
+    end
+
+    def dialogues
+      elements.select { |element| element.is_a?(Dialogue) }
+    end
+    alias_method :dialogue, :dialogues
+
+    def parentheticals
+      elements.select { |element| element.is_a?(Parenthetical) }
+    end
+
+    def lyrics
+      elements.select { |element| element.is_a?(Lyrics) }
+    end
+
+    def transitions
+      elements.select { |element| element.is_a?(Transition) }
+    end
+
+    def centered
+      elements.select { |element| element.is_a?(Centered) }
+    end
+
+    def page_breaks
+      elements.select { |element| element.is_a?(PageBreak) }
+    end
+
+    def sections
+      elements.select { |element| element.is_a?(Section) }
+    end
+
+    def synopses
+      elements.select { |element| element.is_a?(Synopsis) }
+    end
+
+    # Every note, both standalone and inline.
+    #
+    # @return [Array<String>]
+    def notes
+      elements.flat_map(&:notes)
+    end
+
+    # Unique character names in order of first appearance.
+    def character_names
+      characters.map(&:name).uniq
+    end
+
+    # Dialogue blocks in source order. Dual-dialogue blocks are returned
+    # individually (use {#units} to get the paired form).
+    def dialogue_blocks
+      units.flat_map do |unit|
+        case unit
+        when DualDialogue then unit.blocks
+        when DialogueBlock then [unit]
+        else []
+        end
+      end
+    end
+
+    # Elements grouped for rendering: plain elements, dialogue blocks and
+    # dual-dialogue pairs.
+    def units
+      @units ||= build_units
+    end
+
+    # @return [Hash] a JSON-friendly representation of the whole screenplay
+    def to_h
+      hash = {
+        "title_page" => title_page&.to_h,
+        "elements" => elements.map(&:to_h)
+      }
+      hash["boneyards"] = boneyards.dup unless boneyards.empty?
+      hash
+    end
+
+    def to_json(*args)
+      require "json"
+      to_h.to_json(*args)
+    end
+
+    # Validation issues for the screenplay's source.
+    #
+    # @see Validator#validate
+    # @return [Array<Issue>]
+    def issues
+      Validator.new(source, screenplay: self).validate
+    end
+
+    # True when the screenplay's source has no validation issues.
+    #
+    # @return [Boolean]
+    def valid?
+      issues.empty?
+    end
+
+    # Render the screenplay as HTML.
+    #
+    # @see HTMLRenderer#initialize
+    def to_html(**options)
+      HTMLRenderer.new(**options).render(self)
+    end
+
+    # Render the screenplay as plain text.
+    #
+    # @see PlainTextRenderer#initialize
+    def to_plain_text(**options)
+      PlainTextRenderer.new(**options).render(self)
+    end
+
+    def ==(other)
+      other.is_a?(Screenplay) &&
+        other.title_page == title_page &&
+        other.elements == elements
+    end
+
+    def inspect
+      "#<FountainRB::Screenplay elements=#{elements.size} title_page=#{!title_page.nil?}>"
+    end
+
+    private
+
+    def build_units
+      result = []
+      index = 0
+
+      while index < elements.size
+        element = elements[index]
+
+        unless element.is_a?(Character)
+          result << element
+          index += 1
+          next
+        end
+
+        parts = []
+        index += 1
+        while index < elements.size && dialogue_part?(elements[index])
+          parts << elements[index]
+          index += 1
+        end
+
+        block = DialogueBlock.new(element, parts)
+        result << if element.dual? && result.last.is_a?(DialogueBlock)
+          DualDialogue.new(result.pop, block)
+        else
+          block
+        end
+      end
+
+      result
+    end
+
+    def dialogue_part?(element)
+      element.is_a?(Parenthetical) || element.is_a?(Dialogue) || element.is_a?(Note)
+    end
+  end
+end

data/lib/fountainrb/title_page.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module FountainRB
+  # The optional title page at the start of a Fountain document.
+  #
+  # Title page data is written as +key: value+ pairs. Values may be inline or
+  # indented on following lines (three or more spaces, or a tab). A single key
+  # may have several values (for example a two-line title or a mailing
+  # address).
+  #
+  #   Title:
+  #       BRICK & STEEL
+  #       FULL RETIRED
+  #   Credit: Written by
+  #   Author: Stu Maschwitz
+  #   Contact:
+  #       Next Level Productions
+  #       Solvang, CA 93463
+  class TitlePage
+    include Enumerable
+
+    # Keys the Fountain spec recommends. Unknown keys are still kept.
+    KNOWN_KEYS = [
+      "title",
+      "credit",
+      "author",
+      "authors",
+      "source",
+      "draft date",
+      "contact",
+      "copyright",
+      "notes",
+      "date",
+      "revision"
+    ].freeze
+
+    # A key starts with a letter, may contain spaces, and ends with a colon.
+    KEY_PATTERN = /\A([A-Za-z][A-Za-z0-9 ._\/'&()\-]*?):[ \t]*(.*)\z/
+
+    # Continuation values are indented by three or more spaces or a tab.
+    INDENTED_PATTERN = /\A(?:[ \t]{3,}|\t)/
+
+    # @return [Hash{String => Array<String>}] normalised key => values
+    attr_reader :entries
+
+    def initialize
+      @entries = {}
+    end
+
+    # Detect a title page starting at +start+ in +lines+.
+    #
+    # A title page is only recognised when the first line looks like a key and
+    # either the key is a known title-page key or a second key line follows
+    # immediately. This keeps scripts that happen to begin with "CUT TO:"
+    # from being mistaken for a title page.
+    def self.detect?(lines, start = 0)
+      line = lines[start]
+      return false unless line
+
+      match = KEY_PATTERN.match(line.lstrip)
+      return false unless match
+
+      key = normalise_key(match[1])
+      following = lines[start + 1]
+
+      KNOWN_KEYS.include?(key) || (following && KEY_PATTERN.match?(following.lstrip))
+    end
+
+    # Parse the title page starting at +start+.
+    #
+    # @return [Array(TitlePage, Integer), nil] the page and the index of the
+    #   first line after it, or nil when no title page is present.
+    def self.parse(lines, start = 0)
+      return nil unless detect?(lines, start)
+
+      page = new
+      key = nil
+      index = start
+
+      while index < lines.size
+        line = lines[index]
+        break if line.strip.empty?
+
+        if key && line.match?(INDENTED_PATTERN)
+          page.add(key, line.strip)
+        elsif (match = KEY_PATTERN.match(line.lstrip))
+          key = normalise_key(match[1])
+          value = match[2].to_s.strip
+          page.add(key, value) unless value.empty?
+        else
+          break
+        end
+
+        index += 1
+      end
+
+      [page, index]
+    end
+
+    def self.normalise_key(key)
+      key.to_s.strip.downcase.gsub(/\s+/, " ")
+    end
+
+    # Add +value+ under +key+.
+    def add(key, value)
+      key = self.class.normalise_key(key)
+      (@entries[key] ||= []) << value.to_s
+      self
+    end
+
+    # Values for a key (case-insensitive).
+    #
+    # @return [Array<String>]
+    def [](key)
+      (@entries[self.class.normalise_key(key)] || []).dup
+    end
+
+    # First value for a key, or nil.
+    def fetch(key)
+      self[key].first
+    end
+
+    def key?(key)
+      @entries.key?(self.class.normalise_key(key))
+    end
+
+    def keys
+      @entries.keys
+    end
+
+    def each(&block)
+      @entries.each(&block)
+    end
+
+    def empty?
+      @entries.empty?
+    end
+
+    # Convenience readers. Each returns an array of values (a title may span
+    # several lines).
+    def title
+      self["title"]
+    end
+
+    def credit
+      self["credit"]
+    end
+
+    # Values for "Author" and "Authors", in that order.
+    def authors
+      self["author"] + self["authors"]
+    end
+
+    def source
+      self["source"]
+    end
+
+    def draft_date
+      self["draft date"] + self["date"]
+    end
+
+    def contact
+      self["contact"]
+    end
+
+    def copyright
+      self["copyright"]
+    end
+
+    def notes
+      self["notes"]
+    end
+
+    def to_h
+      @entries.each_with_object({}) { |(key, values), hash| hash[key] = values.dup }
+    end
+
+    def ==(other)
+      other.is_a?(TitlePage) && other.to_h == to_h
+    end
+
+    def inspect
+      "#<FountainRB::TitlePage #{to_h.inspect}>"
+    end
+  end
+end