slideck 0.1.0

data/lib/slideck/cli.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require "tty-option"
+
+module Slideck
+  # Responsible for parsing command line inputs
+  #
+  # @api private
+  class CLI
+    include TTY::Option
+
+    usage do
+      no_command
+
+      desc "Present Markdown-powered slide decks in the terminal"
+
+      desc "Controls:",
+           "  First   f, ^",
+           "  Go to   1..n+g",
+           "  Last    t, $",
+           "  Next    n, l, Right, Spacebar",
+           "  Prev    p, h, Left, Backspace",
+           "  Reload  r, Ctrl+l",
+           "  Quit    q, Esc"
+
+      example "Start presentation",
+              "$ #{program} slides.md"
+    end
+
+    argument :file
+
+    option :color do
+      long "--color WHEN"
+      default "auto"
+      permit %w[always auto never]
+      desc "When to color output"
+    end
+
+    flag :debug do
+      short "-d"
+      long "--debug"
+      desc "Run in debug mode"
+    end
+
+    flag :help do
+      short "-h"
+      long "--help"
+      desc "Print usage"
+    end
+
+    flag :no_color do
+      long "--no-color"
+      desc "Do not color output. Identical to --color=never"
+    end
+
+    flag :version do
+      short "-v"
+      long "--version"
+      desc "Print version"
+    end
+
+    flag :watch do
+      short "-w"
+      long "--watch"
+      desc "Watch for changes in the file with slides"
+    end
+
+    # The error exit code
+    #
+    # @return [Integer]
+    #
+    # @api private
+    CODE_ERROR = 1
+    private_constant :CODE_ERROR
+
+    # The success exit code
+    #
+    # @return [Integer]
+    #
+    # @api private
+    CODE_SUCCESS = 0
+    private_constant :CODE_SUCCESS
+
+    # The pattern to detect color option
+    #
+    # @return [Regexp]
+    #
+    # @api private
+    COLOR_OPTION_PATTERN = /^--color/.freeze
+    private_constant :COLOR_OPTION_PATTERN
+
+    # The no color environment variable name
+    #
+    # @return [String]
+    #
+    # @api private
+    NO_COLOR_ENV_NAME = "NO_COLOR"
+    private_constant :NO_COLOR_ENV_NAME
+
+    # Create a CLI instance
+    #
+    # @example
+    #   Slideck::CLI.new(runner, $stdout, $stderr)
+    #
+    # @param [Slideck::Runner] runner
+    #   the runner used to display slides
+    # @param [IO] output
+    #   the output stream
+    # @param [IO] error_output
+    #   the error output stream
+    #
+    # @api public
+    def initialize(runner, output, error_output)
+      @runner = runner
+      @output = output
+      @error_output = error_output
+    end
+
+    # Start presenting slides deck
+    #
+    # @example
+    #   cli.start(["slides.md"], {})
+    #
+    # @param [Array<String>] cmd_args
+    #   the command arguments
+    # @param [Hash{String => String}] env
+    #   the environment variables
+    #
+    # @raise [SystemExit]
+    #
+    # @return [void]
+    #
+    # @api public
+    def start(cmd_args, env)
+      parse(cmd_args, env)
+
+      print_version || print_help || print_errors
+
+      rescue_errors do
+        @runner.run(params[:file],
+                    color: color(no_color_env?(cmd_args, env)),
+                    watch: params[:watch])
+      end
+    end
+
+    private
+
+    # Print version
+    #
+    # @raise [SystemExit]
+    #
+    # @return [nil]
+    #
+    # @api private
+    def print_version
+      return unless params[:version]
+
+      @output.puts VERSION
+      exit_success
+    end
+
+    # Print help
+    #
+    # @raise [SystemExit]
+    #
+    # @return [nil]
+    #
+    # @api private
+    def print_help
+      return unless params[:help] || file_missing?
+
+      @output.print help
+      exit_success
+    end
+
+    # Check whether a file is missing
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def file_missing?
+      params.errors.size == 1 && params[:file].nil?
+    end
+
+    # Print parsing errors
+    #
+    # @raise [SystemExit]
+    #
+    # @return [nil]
+    #
+    # @api private
+    def print_errors
+      return unless params.errors.any?
+
+      @error_output.puts params.errors.summary
+      exit_error
+    end
+
+    # Rescue errors
+    #
+    # @yield a block with error rescue
+    #
+    # @raise [SystemExit]
+    #
+    # @return [void]
+    #
+    # @api private
+    def rescue_errors
+      yield
+    rescue Slideck::Error => err
+      raise err if params[:debug]
+
+      @error_output.puts "Error: #{err}"
+      exit_error
+    end
+
+    # Check whether no color environment variable is present
+    #
+    # @param [Array<String>] cmd_args
+    #   the command arguments
+    # @param [Hash{String => String}] env
+    #   the environment variables
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def no_color_env?(cmd_args, env)
+      color_option_given = cmd_args.grep(COLOR_OPTION_PATTERN).any?
+      no_color_env_given = !env[NO_COLOR_ENV_NAME].to_s.empty?
+
+      !color_option_given && no_color_env_given
+    end
+
+    # Read when to color output
+    #
+    # @param [Boolean] no_color_env
+    #   the no color environment variable presence
+    #
+    # @return [String, Symbol]
+    #
+    # @api private
+    def color(no_color_env)
+      params[:no_color] || no_color_env ? :never : params[:color]
+    end
+
+    # Exit with the error code
+    #
+    # @raise [SystemExit]
+    #
+    # @return [void]
+    #
+    # @api private
+    def exit_error
+      exit CODE_ERROR
+    end
+
+    # Exit with the success code
+    #
+    # @raise [SystemExit]
+    #
+    # @return [void]
+    #
+    # @api private
+    def exit_success
+      exit CODE_SUCCESS
+    end
+  end # CLI
+end # Slideck

data/lib/slideck/converter.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Slideck
+  # Responsible for converting Markdown into terminal output
+  #
+  # @api private
+  class Converter
+    # The allowed color display modes
+    #
+    # @return [Array<String>]
+    #
+    # @api private
+    COLOR_DISPLAY_MODES = %w[always auto never].freeze
+    private_constant :COLOR_DISPLAY_MODES
+
+    # Create a Converter instance
+    #
+    # @example
+    #   Slideck::Converter.new(TTY::Markdown, color: false)
+    #
+    # @param [TTY::Markdown] markdown_parser
+    #   the markdown parser
+    # @param [String, Symbol] color
+    #   the color display out of always, auto or never
+    #
+    # @api public
+    def initialize(markdown_parser, color: nil)
+      @markdown_parser = markdown_parser
+      @color = validate_color(color)
+    end
+
+    # Convert content into terminal output
+    #
+    # @example
+    #   converter.convert("#Title", width: 80)
+    #
+    # @param [String] content
+    #   the content to convert
+    # @param [Hash, String, Symbol] symbols
+    #   the converted content symbols
+    # @param [Hash{Symbol => Array, String, Symbol}] theme
+    #   the converted content theme
+    # @param [Integer] width
+    #   the slide width
+    #
+    # @return [String]
+    #
+    # @api public
+    def convert(content, symbols: nil, theme: nil, width: nil)
+      @markdown_parser.parse(
+        content, color: @color, symbols: symbols, theme: theme, width: width)
+    end
+
+    private
+
+    # Validate color display mode
+    #
+    # @param [Object] value
+    #   the value to validate
+    #
+    # @raise [Slideck::InvalidArgumentError]
+    #
+    # @return [String, Symbol]
+    #
+    # @api private
+    def validate_color(value)
+      return value if COLOR_DISPLAY_MODES.include?(value.to_s)
+
+      raise_invalid_color_error(value)
+    end
+
+    # Raise an error for an invalid color
+    #
+    # @param [Object] value
+    #   the invalid value
+    #
+    # @raise [Slideck::InvalidArgumentError]
+    #
+    # @return [void]
+    #
+    # @api private
+    def raise_invalid_color_error(value)
+      raise InvalidArgumentError,
+            "invalid value for color: #{value.inspect}.\n" \
+            "The color needs to be one of always, auto or never."
+    end
+  end # Converter
+end # Slideck

data/lib/slideck/errors.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Slideck
+  # Raised to signal an error condition
+  #
+  # @api public
+  Error = Class.new(StandardError)
+
+  # Raised when unable to read slides from a location
+  #
+  # @api public
+  ReadError = Class.new(Error)
+
+  # Raised when argument is invalid
+  #
+  # @api public
+  InvalidArgumentError = Class.new(Error)
+
+  # Raised when metadata key is invalid
+  #
+  # @api public
+  class InvalidMetadataKeyError < Error
+    MESSAGE = "unknown '%<keys>s' configuration %<name>s\n" \
+              "Available keys are: %<meta_keys>s"
+
+    # Create an InvalidMetadataKeyError instance
+    #
+    # @example
+    #   metadata_keys = %i[align footer pager]
+    #   Slideck::InvalidMetadataKeyError.new(metadata_keys, %i[invalid])
+    #
+    # @param [Array<Symbol>] metadata_keys
+    #   the allowed metadata keys
+    # @param [Array<String>] keys
+    #   the invalid metadata keys
+    #
+    # @api public
+    def initialize(metadata_keys, keys)
+      super(format(MESSAGE,
+                   keys: keys.join(", "),
+                   name: pluralize("key", keys.size),
+                   meta_keys: metadata_keys.map(&:inspect).join(", ")))
+    end
+
+    private
+
+    # Pluralize a noun
+    #
+    # @param [String] noun
+    #   the noun to pluralize
+    # @param [Integer] count
+    #   the count of items
+    #
+    # @return [String]
+    #
+    # @api private
+    def pluralize(noun, count = 1)
+      "#{noun}#{"s" unless count == 1}"
+    end
+  end # InvalidMetadataKeyError
+end # Slideck

data/lib/slideck/loader.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Slideck
+  # Responsible for loading slides
+  #
+  # @api private
+  class Loader
+    # Create a Loader instance
+    #
+    # @example
+    #   Slideck::Loader.new(File)
+    #
+    # @param [#read] read_handler
+    #   the read handler for slides
+    #
+    # @api public
+    def initialize(read_handler)
+      @read_handler = read_handler
+    end
+
+    # Load slides from a location
+    #
+    # @example
+    #   loader.load("slides.md")
+    #
+    # @param [String] location
+    #   the location of the slides to load
+    #
+    # @raise [Slideck::ReadError]
+    #
+    # @return [String]
+    #   the slides content
+    #
+    # @api public
+    def load(location)
+      if location.nil?
+        raise ReadError, "the location for the slides must be given"
+      end
+
+      @read_handler.read(location)
+    rescue SystemCallError => err
+      raise ReadError, err.message
+    end
+  end # Loader
+end # Slideck