fountainrb 1.0.0

data/lib/fountainrb/elements.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module FountainRB
+  # Base class for every screenplay element.
+  #
+  # Every element knows:
+  #
+  # * +text+          -- the element's content with markup removed from the
+  #                      element prefix (a leading ".", "!", "@", ">", "~",
+  #                      "#" or "=") but with inline emphasis left intact.
+  # * +line+          -- the 1-based line number in the source where the
+  #                      element begins.
+  # * +blank_before+  -- the number of blank source lines immediately before
+  #                      the element.
+  # * +forced?+       -- whether the writer used an explicit prefix to force
+  #                      the element type.
+  class Element
+    attr_reader :text, :line, :blank_before
+
+    def initialize(text: "", line: nil, blank_before: 0, forced: false)
+      @text = text.to_s
+      @line = line
+      @blank_before = blank_before
+      @forced = forced
+    end
+
+    # Symbol identifying the element type. Subclasses override.
+    def type
+      :element
+    end
+
+    def forced?
+      @forced
+    end
+
+    # True for elements that may contain several source lines (and therefore
+    # may be merged or extended by the parser).
+    def multiline?
+      false
+    end
+
+    # Append a line of text. Used for line breaks inside multi-line elements.
+    def append_line(line)
+      @text = "#{@text}\n#{line}"
+      self
+    end
+
+    # Merge another element of the same type into this one.
+    def merge!(other)
+      append_line(other.text)
+      @forced ||= other.forced?
+      self
+    end
+
+    # Inline notes contained in this element's text.
+    #
+    # @return [Array<String>]
+    def notes
+      Inline.parse(text, connected_blanks: true)
+        .select { |node| node.is_a?(Inline::Note) }
+        .map(&:text)
+    end
+
+    # @return [Hash] a JSON-friendly representation
+    def to_h
+      hash = {"type" => type.to_s, "text" => text}
+      hash["line"] = line if line
+      hash["blank_before"] = blank_before if blank_before.to_i.positive?
+      hash["forced"] = true if forced?
+      hash
+    end
+
+    def ==(other)
+      other.class == self.class && other.to_h == to_h
+    end
+    alias_method :eql?, :==
+
+    def hash
+      to_h.hash
+    end
+
+    def inspect
+      attributes = to_h.slice(*(to_h.keys - ["type"]))
+      "#<#{self.class.name.split("::").last} #{attributes.inspect}>"
+    end
+  end
+
+  # A scene heading, e.g. "INT. BRICK'S PATIO - DAY" or ".OPENING TITLES".
+  class SceneHeading < Element
+    attr_reader :scene_number
+
+    def initialize(scene_number: nil, **kwargs)
+      super(**kwargs)
+      @scene_number = scene_number
+    end
+
+    def type
+      :scene_heading
+    end
+
+    def to_h
+      hash = super
+      hash["scene_number"] = scene_number if scene_number
+      hash
+    end
+  end
+
+  # Scene description. May contain several lines and intentional whitespace.
+  class Action < Element
+    def type
+      :action
+    end
+
+    def multiline?
+      true
+    end
+
+    # The action broken into its individual lines.
+    def lines
+      text.split("\n", -1)
+    end
+  end
+
+  # A character cue, e.g. "STEEL", "MOM (O. S.)" or "@McCLANE".
+  class Character < Element
+    attr_reader :name, :extensions
+
+    def initialize(name:, extensions: [], dual: false, **kwargs)
+      @name = name.to_s
+      @extensions = Array(extensions).map(&:to_s)
+      @dual = dual
+      super(text: build_text, **kwargs)
+    end
+
+    def type
+      :character
+    end
+
+    # True when the cue ends with a caret, meaning this block is simultaneous
+    # with the preceding dialogue block (dual dialogue).
+    def dual?
+      @dual
+    end
+
+    def extension
+      extensions.join(" ")
+    end
+
+    def to_h
+      hash = super
+      hash["name"] = name
+      hash["extensions"] = extensions unless extensions.empty?
+      hash["dual"] = true if dual?
+      hash
+    end
+
+    private
+
+    def build_text
+      [name, *extensions.map { |extension| "(#{extension})" }].join(" ")
+    end
+  end
+
+  # A line of dialogue.
+  class Dialogue < Element
+    def type
+      :dialogue
+    end
+
+    def multiline?
+      true
+    end
+
+    def lines
+      text.split("\n", -1)
+    end
+  end
+
+  # A parenthetical direction, e.g. "(starting the engine)".
+  class Parenthetical < Element
+    def type
+      :parenthetical
+    end
+
+    # The text without the surrounding parentheses.
+    def content
+      if text.start_with?("(") && text.end_with?(")") && text.length >= 2
+        text[1...-1]
+      else
+        text
+      end
+    end
+
+    def to_h
+      hash = super
+      hash["content"] = content
+      hash
+    end
+  end
+
+  # A lyric line, introduced by "~".
+  class Lyrics < Element
+    def type
+      :lyrics
+    end
+
+    def multiline?
+      true
+    end
+  end
+
+  # A transition, e.g. "CUT TO:" or ">Burn to White.".
+  class Transition < Element
+    def type
+      :transition
+    end
+  end
+
+  # Centered text, e.g. "> THE END <". Fountain treats this as a special
+  # form of Action.
+  class Centered < Element
+    def type
+      :centered
+    end
+  end
+
+  # A page break: a line of three or more equals signs.
+  class PageBreak < Element
+    def type
+      :page_break
+    end
+  end
+
+  # An outline section, e.g. "# Act One" or "## Sequence".
+  class Section < Element
+    attr_reader :level
+
+    def initialize(level:, **kwargs)
+      super(**kwargs)
+      @level = level
+    end
+
+    def type
+      :section
+    end
+
+    def to_h
+      hash = super
+      hash["level"] = level
+      hash
+    end
+  end
+
+  # A single-line synopsis, e.g. "= Set up the characters.".
+  class Synopsis < Element
+    def type
+      :synopsis
+    end
+  end
+
+  # A note on its own line.
+  class Note < Element
+    def type
+      :note
+    end
+
+    def notes
+      [text]
+    end
+  end
+end

data/lib/fountainrb/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module FountainRB
+  # Base class for every error raised by fountainrb.
+  class Error < StandardError; end
+
+  # Raised when source text cannot be read or parsed.
+  class ParseError < Error; end
+end

data/lib/fountainrb/html_renderer.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module FountainRB
+  # Renders a {Screenplay} as HTML.
+  #
+  # The output uses semantic class names rather than inline styles so that the
+  # caller can supply whatever screenplay stylesheet they like. Sections,
+  # synopses and notes are omitted by default because Fountain ignores them in
+  # formatted output, but they can be enabled for editing/debug views.
+  #
+  #   puts screenplay.to_html(notes: true, sections: true)
+  class HTMLRenderer
+    # @param notes [Boolean] render notes (default: false)
+    # @param sections [Boolean] render sections (default: false)
+    # @param synopses [Boolean] render synopses (default: false)
+    # @param title_page [Boolean] render the title page (default: true)
+    # @param page_breaks [Boolean] render page breaks (default: true)
+    def initialize(notes: false, sections: false, synopses: false,
+      title_page: true, page_breaks: true)
+      @notes = notes
+      @sections = sections
+      @synopses = synopses
+      @title_page = title_page
+      @page_breaks = page_breaks
+    end
+
+    # @param screenplay [Screenplay]
+    # @return [String]
+    def render(screenplay)
+      parts = []
+
+      if @title_page && screenplay.title_page
+        parts << render_title_page(screenplay.title_page)
+      end
+
+      screenplay.units.each do |unit|
+        html = render_unit(unit)
+        parts << html unless html.nil? || html.empty?
+      end
+
+      %(<div class="fountain">\n#{parts.join("\n")}\n</div>)
+    end
+
+    private
+
+    def html(text)
+      Inline.to_html(text, notes: @notes, connected_blanks: true)
+    end
+
+    def escape(text)
+      Inline.escape_html(text)
+    end
+
+    def render_unit(unit)
+      case unit
+      when DialogueBlock then render_dialogue_block(unit)
+      when DualDialogue then render_dual_dialogue(unit)
+      when SceneHeading then render_scene_heading(unit)
+      when Action then render_action(unit)
+      when Lyrics then render_lyrics(unit)
+      when Transition then render_transition(unit)
+      when Centered then render_centered(unit)
+      when PageBreak then @page_breaks ? render_page_break : nil
+      when Section then @sections ? render_section(unit) : nil
+      when Synopsis then @synopses ? render_synopsis(unit) : nil
+      when Note then @notes ? render_note(unit) : nil
+      end
+    end
+
+    def render_title_page(page)
+      lines = ['<section class="title-page">']
+
+      page.entries.each do |key, values|
+        class_name = key.gsub(/[^a-z0-9]+/, "-")
+        lines << %(  <div class="#{class_name}">)
+        values.each { |value| lines << %(    <p>#{html(value)}</p>) }
+        lines << "  </div>"
+      end
+
+      lines << "</section>"
+      lines.join("\n")
+    end
+
+    def render_scene_heading(element)
+      attributes = +%(class="scene-heading")
+      if element.scene_number
+        attributes << %( data-scene-number="#{escape(element.scene_number)}")
+      end
+      %(<h2 #{attributes}>#{html(element.text)}</h2>)
+    end
+
+    def render_action(element)
+      %(<p class="action">#{html(element.text)}</p>)
+    end
+
+    def render_lyrics(element)
+      %(<p class="lyrics">#{html(element.text)}</p>)
+    end
+
+    def render_transition(element)
+      %(<p class="transition">#{html(element.text)}</p>)
+    end
+
+    def render_centered(element)
+      %(<p class="centered">#{html(element.text)}</p>)
+    end
+
+    def render_page_break
+      %(<div class="page-break"></div>)
+    end
+
+    def render_section(element)
+      %(<div class="section" data-level="#{element.level}">#{html(element.text)}</div>)
+    end
+
+    def render_synopsis(element)
+      %(<div class="synopsis">#{html(element.text)}</div>)
+    end
+
+    def render_note(element)
+      %(<div class="note">#{html(element.text)}</div>)
+    end
+
+    def render_dialogue_block(block)
+      lines = ['<div class="dialogue-block">']
+      lines << %(  <p class="character">#{render_character(block.character)}</p>)
+
+      block.parts.each do |part|
+        case part
+        when Parenthetical
+          lines << %(  <p class="parenthetical">#{html(part.text)}</p>)
+        when Dialogue
+          lines << %(  <p class="dialogue">#{html(part.text)}</p>)
+        when Note
+          lines << %(  <p class="note">#{html(part.text)}</p>) if @notes
+        end
+      end
+
+      lines << "</div>"
+      lines.join("\n")
+    end
+
+    def render_dual_dialogue(dual)
+      lines = ['<div class="dual-dialogue">']
+      lines << render_dialogue_block(dual.left)
+      lines << render_dialogue_block(dual.right)
+      lines << "</div>"
+      lines.join("\n")
+    end
+
+    def render_character(character)
+      parts = [%(<span class="character-name">#{html(character.name)}</span>)]
+      character.extensions.each do |extension|
+        parts << %( <span class="extension">(#{html(extension)})</span>)
+      end
+      parts.join
+    end
+  end
+end