slideck 0.1.0

data/lib/slideck/renderer.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+module Slideck
+  # Responsible for rendering slides
+  #
+  # @api private
+  class Renderer
+    # The terminal cursor
+    #
+    # @example
+    #   renderer.cursor
+    #
+    # @return [TTY::Cursor]
+    #
+    # @api public
+    attr_reader :cursor
+
+    # Create a Renderer instance
+    #
+    # @param [Slideck::Converter] converter
+    #   the markdown to terminal output converter
+    # @param [Strings::ANSI] ansi
+    #   the ansi codes handler
+    # @param [TTY::Cursor] cursor
+    #   the cursor navigation
+    # @param [Integer] width
+    #   the screen width
+    # @param [Integer] height
+    #   the screen height
+    #
+    # @api public
+    def initialize(converter, ansi, cursor, width: nil, height: nil)
+      @converter = converter
+      @ansi = ansi
+      @cursor = cursor
+      @width = width
+      @height = height
+
+      freeze
+    end
+
+    # Create a Renderer with a new screen size
+    #
+    # @example
+    #   renderer.resize(200, 50)
+    #
+    # @param [Integer] width
+    #   the screen width
+    # @param [Integer] height
+    #   the screen height
+    #
+    # @return [Slideck::Renderer]
+    #
+    # @api public
+    def resize(width, height)
+      self.class.new(@converter, @ansi, @cursor, width: width, height: height)
+    end
+
+    # Render a slide
+    #
+    # @example
+    #   renderer.render(metadata, slide, 1, 5)
+    #
+    # @param [Slideck::Metadata] metadata
+    #   the global metadata
+    # @param [Hash{Symbol => Hash, String}, nil] slide
+    #   the current slide to render
+    # @param [Integer] current_num
+    #   the current slide number
+    # @param [Integer] num_of_slides
+    #   the number of slides
+    #
+    # @return [String]
+    #
+    # @api public
+    def render(metadata, slide, current_num, num_of_slides)
+      slide_metadata = slide && slide[:metadata]
+      [].tap do |out|
+        out << render_content(metadata, slide) if slide
+        out << render_footer(metadata, slide_metadata)
+        out << render_pager(metadata, slide_metadata,
+                            current_num, num_of_slides)
+      end.join
+    end
+
+    # Clear terminal screen
+    #
+    # @example
+    #   renderer.clear
+    #
+    # @return [String]
+    #
+    # @api public
+    def clear
+      cursor.clear_screen + cursor.move_to(0, 0)
+    end
+
+    private
+
+    # Render slide content
+    #
+    # @param [Slideck::Metadata] metadata
+    #   the global metadata
+    # @param [Hash{Symbol => Hash, String}] slide
+    #   the slide to render
+    #
+    # @return [String]
+    #
+    # @api private
+    def render_content(metadata, slide)
+      alignment, margin, symbols, theme =
+        *select_metadata(metadata, slide[:metadata], :align, :margin,
+                         :symbols, :theme)
+      converted = convert_markdown(slide[:content], margin, symbols, theme)
+
+      render_section(converted.lines, alignment, margin)
+    end
+
+    # Render footer
+    #
+    # @param [Slideck::Metadata] metadata
+    #   the global metadata
+    # @param [Slideck::Metadata] slide_metadata
+    #   the slide metadata
+    #
+    # @return [String]
+    #
+    # @api private
+    def render_footer(metadata, slide_metadata)
+      footer_metadata = pick_metadata(metadata, slide_metadata, :footer)
+      return if (text = footer_metadata[:text]).empty?
+
+      alignment = footer_metadata[:align] || metadata.footer[:align]
+      margin, symbols, theme =
+        *select_metadata(metadata, slide_metadata, :margin, :symbols, :theme)
+      converted = convert_markdown(text, margin, symbols, theme).chomp
+
+      render_section(converted.lines, alignment, margin)
+    end
+
+    # Render pager
+    #
+    # @param [Slideck::Metadata] metadata
+    #   the global metadata
+    # @param [Slideck::Metadata] slide_metadata
+    #   the slide metadata
+    # @param [Integer] current_num
+    #   the current slide number
+    # @param [Integer] num_of_slides
+    #   the number of slides
+    #
+    # @return [String]
+    #
+    # @api private
+    def render_pager(metadata, slide_metadata, current_num, num_of_slides)
+      pager_metadata = pick_metadata(metadata, slide_metadata, :pager)
+      return if (text = pager_metadata[:text]).empty?
+
+      alignment = pager_metadata[:align] || metadata.pager[:align]
+      margin, symbols, theme =
+        *select_metadata(metadata, slide_metadata, :margin, :symbols, :theme)
+      formatted_text = format(text, page: current_num, total: num_of_slides)
+      converted = convert_markdown(formatted_text, margin, symbols, theme).chomp
+
+      render_section(converted.lines, alignment, margin)
+    end
+
+    # Select configuration(s) by name(s) from metadata
+    #
+    # @param [Slideck::Metadata] metadata
+    #   the global metadata
+    # @param [Slideck::Metadata] slide_metadata
+    #   the slide metadata
+    # @param [Array<Symbol>] names
+    #   the configuration names
+    #
+    # @return [Array<Object>]
+    #
+    # @api private
+    def select_metadata(metadata, slide_metadata, *names)
+      names.each_with_object([]) do |name, selected|
+        selected << pick_metadata(metadata, slide_metadata, name)
+      end
+    end
+
+    # Pick configuration by name from metadata
+    #
+    # @param [Slideck::Metadata] metadata
+    #   the global metadata
+    # @param [Slideck::Metadata] slide_metadata
+    #   the slide metadata
+    # @param [Symbol] name
+    #   the configuration name
+    #
+    # @return [Hash, Slideck::Alignment, Slideck::Margin, String, Symbol]
+    #
+    # @api private
+    def pick_metadata(metadata, slide_metadata, name)
+      slide_metadata_item = slide_metadata && slide_metadata.send(name)
+      slide_metadata_item || metadata.send(name)
+    end
+
+    # Render section with aligned lines
+    #
+    # @param [Array<String>] lines
+    #   the lines to align
+    # @param [Slideck::Alignment] alignment
+    #   the section alignment
+    # @param [Slideck::Margin] margin
+    #   the slide margin
+    #
+    # @return [String]
+    #
+    # @api private
+    def render_section(lines, alignment, margin)
+      max_line = max_line_length(lines)
+      left = find_left_column(alignment.horizontal, margin, max_line)
+      top = find_top_row(alignment.vertical, margin, lines.size)
+
+      lines.map.with_index do |line, i|
+        cursor.move_to(left, top + i) + line
+      end.join
+    end
+
+    # Find a left column
+    #
+    # @param [String] alignment
+    #   the horizontal alignment
+    # @param [Slideck::Margin] margin
+    #   the slide margin
+    # @param [Integer] content_length
+    #   the maximum content length
+    #
+    # @return [Integer]
+    #
+    # @api private
+    def find_left_column(alignment, margin, content_length)
+      case alignment
+      when "left"
+        margin.left
+      when "center"
+        margin.left + ((slide_width(margin) - content_length) / 2)
+      when "right"
+        margin.left + (slide_width(margin) - content_length)
+      end
+    end
+
+    # Find a top row
+    #
+    # @param [String] alignment
+    #   the vertical alignment
+    # @param [Slideck::Margin] margin
+    #   the slide margin
+    # @param [Integer] num_of_lines
+    #   the number of content lines
+    #
+    # @return [Integer]
+    #
+    # @api private
+    def find_top_row(alignment, margin, num_of_lines)
+      case alignment
+      when "top"
+        margin.top
+      when "center"
+        margin.top + ((slide_height(margin) - num_of_lines) / 2)
+      when "bottom"
+        margin.top + (slide_height(margin) - num_of_lines)
+      end
+    end
+
+    # Convert markdown content to terminal output
+    #
+    # @param [String] content
+    #   the content to convert to terminal output
+    # @param [Slideck::Margin] margin
+    #   the slide margin
+    # @param [Hash, String, Symbol] symbols
+    #   the converted content symbols
+    # @param [Hash{Symbol => Array, String, Symbol}] theme
+    #   the converted content theme
+    #
+    # @return [String]
+    #
+    # @api private
+    def convert_markdown(content, margin, symbols, theme)
+      @converter.convert(
+        content, symbols: symbols, theme: theme, width: slide_width(margin))
+    end
+
+    # Find maximum line length
+    #
+    # @param [Array<String>] lines
+    #   the lines to search through
+    #
+    # @return [Integer]
+    #
+    # @api private
+    def max_line_length(lines)
+      lines.map { |line| @ansi.sanitize(line).size }.max
+    end
+
+    # Calculate slide height
+    #
+    # @param [Slideck::Margin] margin
+    #   the slide margin
+    #
+    # @return [Integer]
+    #
+    # @api private
+    def slide_height(margin)
+      @height - margin.top - margin.bottom
+    end
+
+    # Calculate slide width
+    #
+    # @param [Slideck::Margin] margin
+    #   the slide margin
+    #
+    # @return [Integer]
+    #
+    # @api private
+    def slide_width(margin)
+      @width - margin.left - margin.right
+    end
+  end # Renderer
+end # Slideck

data/lib/slideck/runner.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "listen"
+require "strings-ansi"
+require "strscan"
+require "tty-cursor"
+require "tty-markdown"
+require "tty-reader"
+require "yaml"
+
+require_relative "alignment"
+require_relative "converter"
+require_relative "loader"
+require_relative "margin"
+require_relative "metadata"
+require_relative "metadata_converter"
+require_relative "metadata_defaults"
+require_relative "metadata_parser"
+require_relative "metadata_wrapper"
+require_relative "parser"
+require_relative "presenter"
+require_relative "renderer"
+require_relative "tracker"
+require_relative "transformer"
+
+module Slideck
+  # Parse and display slides
+  #
+  # @api private
+  class Runner
+    # Create a Runner instance
+    #
+    # @example
+    #   Slideck::Runner.new(TTY::Screen, $stdin, $stdout, {})
+    #
+    # @param [TTY::Screen] screen
+    #   the terminal screen size
+    # @param [IO] input
+    #   the input stream
+    # @param [IO] output
+    #   the output stream
+    # @param [Hash] env
+    #   the environment variables
+    #
+    # @api public
+    def initialize(screen, input, output, env)
+      @screen = screen
+      @input = input
+      @output = output
+      @env = env
+    end
+
+    # Run the slides in a terminal
+    #
+    # @example
+    #   runner.run("slides.md", color: :always, watch: true)
+    #
+    # @param [String] filename
+    #   the filename with slides
+    # @param [String, Symbol] color
+    #   the color display out of always, auto or never
+    # @param [Boolean] watch
+    #   whether to watch for changes in a filename
+    #
+    # @return [void]
+    #
+    # @api public
+    def run(filename, color: nil, watch: nil)
+      transformer = build_transformer
+      presenter = build_presenter(color) { transformer.read(filename) }
+
+      if watch
+        listener = build_listener(filename) { presenter.reload.render }
+        listener.start
+      end
+
+      presenter.start
+    ensure
+      listener && listener.stop
+    end
+
+    private
+
+    # Build transformer
+    #
+    # @return [Slideck::Transformer]
+    #
+    # @api private
+    def build_transformer
+      loader = Loader.new(::File)
+      Transformer.new(loader, build_parser, build_metadata_wrapper)
+    end
+
+    # Build parser
+    #
+    # @return [Slideck::Parser]
+    #
+    # @api private
+    def build_parser
+      metadata_parser = MetadataParser.new(
+        ::YAML, permitted_classes: [Symbol], symbolize_names: true)
+      Parser.new(::StringScanner, metadata_parser)
+    end
+
+    # Build metadata wrapper
+    #
+    # @return [Slideck::MetadataWrapper]
+    #
+    # @api private
+    def build_metadata_wrapper
+      metadata_converter = MetadataConverter.new(Alignment, Margin)
+      metadata_defaults = MetadataDefaults.new(Alignment, Margin)
+      MetadataWrapper.new(Metadata, metadata_converter, metadata_defaults)
+    end
+
+    # Build presenter
+    #
+    # @param [String, Symbol] color
+    #   the color display out of always, auto or never
+    # @param [Proc] reloader
+    #   the metadata and slides reloader
+    #
+    # @return [Slideck::Presenter]
+    #
+    # @api private
+    def build_presenter(color, &reloader)
+      reader = TTY::Reader.new(input: @input, output: @output, env: @env,
+                               interrupt: :exit)
+      converter = Converter.new(TTY::Markdown, color: color)
+      renderer = Renderer.new(converter, Strings::ANSI, TTY::Cursor,
+                              width: @screen.width, height: @screen.height)
+      tracker = Tracker.for(0)
+      Presenter.new(reader, renderer, tracker, @screen, @output, &reloader)
+    end
+
+    # Build a listener for changes in a filename
+    #
+    # @param [String] filename
+    #   the filename with slides
+    #
+    # @return [Listen::Listener]
+    #
+    # @api private
+    def build_listener(filename)
+      watched_dir = File.expand_path(File.dirname(filename))
+      watched_file = File.expand_path(filename)
+      Listen.to(watched_dir) do |changed_files, _, _|
+        yield if changed_files.include?(watched_file)
+      end
+    end
+  end # Runner
+end # Slideck

data/lib/slideck/tracker.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Slideck
+  # Responsible for tracking current slide number
+  #
+  # @api private
+  class Tracker
+    # Create a Tracker instance with the current slide set to zero
+    #
+    # @example
+    #   Slideck::Tracker.for(11)
+    #
+    # @param [Integer] total
+    #   the total number of slides
+    #
+    # @return [Slideck::Tracker]
+    #
+    # @api public
+    def self.for(total)
+      new(0, total)
+    end
+
+    # The current slide number
+    #
+    # @example
+    #   tracker.current
+    #
+    # @return [Integer]
+    #
+    # @api public
+    attr_reader :current
+
+    # The total number of slides
+    #
+    # @example
+    #   tracker.total
+    #
+    # @return [Integer]
+    #
+    # @api public
+    attr_reader :total
+
+    # Create a Tracker instance
+    #
+    # @example
+    #   Slideck::Tracker.new(0, 11)
+    #
+    # @param [Integer] current
+    #   the current slide number
+    # @param [Integer] total
+    #   the total number of slides
+    #
+    # @api public
+    def initialize(current, total)
+      @current = current
+      @total = total
+
+      freeze
+    end
+
+    # Move to the next slide
+    #
+    # @example
+    #   tracker = tracker.next
+    #
+    # @return [Slideck::Tracker]
+    #
+    # @api public
+    def next
+      return self if current >= total - 1
+
+      self.class.new(current + 1, total)
+    end
+
+    # Move to the previous slide
+    #
+    # @example
+    #   tracker = tracker.previous
+    #
+    # @return [Slideck::Tracker]
+    #
+    # @api public
+    def previous
+      return self if current.zero?
+
+      self.class.new(current - 1, total)
+    end
+
+    # Move to the first slide
+    #
+    # @example
+    #   tracker = tracker.first
+    #
+    # @return [Slideck::Tracker]
+    #
+    # @api public
+    def first
+      self.class.new(0, total)
+    end
+
+    # Move to the last slide
+    #
+    # @example
+    #   tracker = tracker.last
+    #
+    # @return [Slideck::Tracker]
+    #
+    # @api public
+    def last
+      self.class.new(total - 1, total)
+    end
+
+    # Go to a specific slide number
+    #
+    # @example
+    #   tracker = tracker.go_to(5)
+    #
+    # @param [Integer] slide_no
+    #   the slide number
+    #
+    # @return [Slideck::Tracker]
+    #
+    # @api public
+    def go_to(slide_no)
+      return self if slide_no < 0 || total - 1 < slide_no
+
+      self.class.new(slide_no, total)
+    end
+
+    # Resize to the new total
+    #
+    # @example
+    #   tracker = tracker.resize(10)
+    #
+    # @param [Integer] new_total
+    #   the new total
+    #
+    # @return [Slideck::Tracker]
+    #
+    # @api public
+    def resize(new_total)
+      return self if new_total < 0 || total == new_total
+
+      self.class.new(reset_current(new_total), new_total)
+    end
+
+    private
+
+    # Reset current
+    #
+    # @param [Integer] new_total
+    #   the new total
+    #
+    # @return [Integer]
+    #
+    # @api private
+    def reset_current(new_total)
+      if current < new_total
+        current
+      elsif new_total.zero?
+        0
+      else
+        new_total - 1
+      end
+    end
+  end # Tracker
+end # Slideck

data/lib/slideck/transformer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Slideck
+  # Responsible for transforming file content into metadata and slides
+  #
+  # @api private
+  class Transformer
+    # Create a Transformer instance
+    #
+    # @example
+    #   Transformer.new(loader, parser, metadata_wrapper)
+    #
+    # @param [Slideck::Loader] loader
+    #   the file loader
+    # @param [Slideck::Parser] parser
+    #   the file content parser
+    # @param [Slideck::MetadataWrapper] metadata_wrapper
+    #   the metadata wrapper
+    #
+    # @api public
+    def initialize(loader, parser, metadata_wrapper)
+      @loader = loader
+      @parser = parser
+      @metadata_wrapper = metadata_wrapper
+    end
+
+    # Read metadata and slides from a file
+    #
+    # @example
+    #   transformer.read("slides.md")
+    #
+    # @param [String] filename
+    #   the filename to read metadata and slides from
+    #
+    # @return [Array<Slideck::Metadata, Array<Hash>>]
+    #
+    # @api public
+    def read(filename)
+      @metadata_wrapper.wrap(@parser.parse(@loader.load(filename)))
+    end
+  end # Transformer
+end # Slideck

data/lib/slideck/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Slideck
+  VERSION = "0.1.0"
+end # Slideck

data/lib/slideck.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "tty-screen"
+
+require_relative "slideck/cli"
+require_relative "slideck/errors"
+require_relative "slideck/runner"
+require_relative "slideck/version"
+
+# Present Markdown-powered slide decks in a terminal
+module Slideck
+  # Run slides deck
+  #
+  # @example
+  #   Slideck.run
+  #
+  # @param [Array<String>] cmd_args
+  #   the command arguments
+  # @param [Hash{String => String}] env
+  #   the environment variables
+  #
+  # @return [void]
+  #
+  # @api public
+  def self.run(cmd_args = ARGV, env = ENV)
+    runner = Runner.new(TTY::Screen, $stdin, $stdout, env)
+    cli = CLI.new(runner, $stdout, $stderr)
+    cli.start(cmd_args, env)
+  end
+end # Slideck