Command-Line Programs

#!/usr/bin/env ruby
# frozen_string_literal: true

puts "hi"

$ chmod +x hi
$ ./hi
hi

exit Shelf::CLI.run(ARGV) if __FILE__ == $PROGRAM_NAME

# frozen_string_literal: true

p ARGV
p ARGV.frozen?
p ARGV.class
p __FILE__ == $PROGRAM_NAME
command = ARGV.shift
p command
p ARGV

["search", "--limit", "3", "ruby basics", ""]
false
Array
true
"search"
["--limit", "3", "ruby basics", ""]

# frozen_string_literal: true

# Reads every file named in ARGV, or standard input when ARGV is empty.
ARGF.each_line do |line|
  printf("%<file>s:%<lineno>d: %<text>s\n", file: ARGF.filename, lineno: ARGF.file.lineno, text: line.chomp)
end
puts "done after #{ARGF.lineno} lines"

titles.txt:1: ruby basics
titles.txt:2: freezing objects
more.txt:1: gems and bundler
done after 3 lines

-:1: piped
done after 1 lines

titles.txt:1: ruby basics
titles.txt:2: freezing objects
-:1: piped
more.txt:1: gems and bundler
done after 4 lines

# frozen_string_literal: true

p ARGF.class
p ARGF.filename
first = ARGF.gets
p first
p ARGF.filename
p ARGF.eof?
ARGF.skip
p ARGF.filename
rest = ARGF.read
p rest
p ARGF.argv
p $FILENAME

ARGF.class
"titles.txt"
"ruby basics\n"
"titles.txt"
false
"more.txt"
"gems and bundler\n"
[]
"more.txt"

# frozen_string_literal: true

require "stringio"

p $stdout.equal?(STDOUT) # rubocop:disable Style/GlobalStdStream
p [$stdin.fileno, $stdout.fileno, $stderr.fileno]
p $stdout.sync
p $stderr.sync

puts "to standard output"
warn "to standard error"
$stderr.print "also to standard error\n"
$stdout.print "no newline, "
$stdout.write("write returns the byte count\n")

# Redirect the global for a block of code, for example in a test.
captured = StringIO.new
original = $stdout
begin
  $stdout = captured
  puts "captured"
ensure
  $stdout = original
end
p captured.string

# STDOUT is the original stream even when $stdout was reassigned.
$stdout = StringIO.new
STDOUT.puts "still the terminal" # rubocop:disable Style/GlobalStdStream
$stdout = STDOUT

true
[0, 1, 2]
false
true
to standard output
no newline, write returns the byte count
"captured\n"
still the terminal

to standard error
also to standard error

# frozen_string_literal: true

begin
  1_000_000.times { |i| puts "line #{i}" }
rescue Errno::EPIPE
  exit 0
end

line 0
0

# frozen_string_literal: true

require "English"

at_exit { puts "at_exit handler runs last (#{$ERROR_INFO.inspect})" }

begin
  exit 3
rescue SystemExit => e
  puts "caught SystemExit: status=#{e.status} success?=#{e.success?} message=#{e.message.inspect}"
end

begin
  exit(false)
rescue SystemExit => e
  puts "exit(false): status=#{e.status}"
end

begin
  abort "fatal: cannot open the catalogue"
rescue SystemExit => e
  puts "abort: status=#{e.status}"
end

begin
  exit
ensure
  puts "ensure blocks run on exit"
end

fatal: cannot open the catalogue
caught SystemExit: status=3 success?=false message="exit"
exit(false): status=1
abort: status=1
ensure blocks run on exit
at_exit handler runs last (#<SystemExit: exit>)
status: 0

# frozen_string_literal: true

at_exit { puts "never printed" }

begin
  exit! 4
ensure
  puts "never printed either"
end

# frozen_string_literal: true

Integer("12x")

# frozen_string_literal: true

t = Thread.new { exit 5 }
t.join
puts "not reached"

$ ruby -e 'abort'
status=1
$ ruby -e 'exit 256'
status=0
$ ruby -e 'exit(-1)'
status=255
$ ruby -e 'at_exit { puts 1 }; at_exit { puts 2 }; exit 7'
2
1
status=7
$ ruby -e 'at_exit { exit 9 }; exit 7'
status=9
$ ruby -e 'raise Interrupt'
-e:1:in '<main>': Interrupt (Interrupt)
status=130
$ ruby -e 'Process.kill("TERM", $$); sleep'
status=143
$ ruby exit_bang.rb
status=4
$ ruby exit_in_thread.rb
status=5

# frozen_string_literal: true

require "optparse"

Options = Struct.new(:term, :limit, :format, :color, :verbose, :tags)

def search_options(opts, options)
  opts.separator "Search options:"
  opts.on("-t", "--title=TERM", "Match titles containing TERM") { |value| options.term = value }
  opts.on("-n", "--limit=N", Integer, "Show at most N books (default #{options.limit})") { |n| options.limit = n }
  opts.on("-f", "--format=FORMAT", %i[text json], "Output format: text or json") { |v| options.format = v }
  opts.on("--tag=TAG[,TAG]", Array, "Only books with these tags") { |value| options.tags.concat(value) }
end

def finish(text)
  puts text
  exit
end

def common_options(opts, options)
  opts.separator "Common options:"
  opts.on("--[no-]color", "Colorize the output (default on)") { |value| options.color = value }
  opts.on("-v", "--verbose", "Increase verbosity (repeatable)") { options.verbose += 1 }
  opts.on_tail("-h", "--help", "Show this help") { finish(opts.help) }
  opts.on_tail("--version", "Show the version") { finish(opts.ver) }
end

def build_parser(options)
  OptionParser.new do |opts|
    opts.program_name = "shelf"
    opts.version = "0.1.0"
    opts.banner = "Usage: shelf [options] [TERM]"
    opts.separator ""
    search_options(opts, options)
    opts.separator ""
    common_options(opts, options)
  end
end

def parse_options(argv)
  options = Options.new(nil, 10, :text, true, 0, [])
  rest = build_parser(options).parse(argv)
  options.term ||= rest.shift
  [options, rest]
end

options, rest = parse_options(ARGV)
p options.to_h
p rest

Usage: shelf [options] [TERM]

Search options:
    -t, --title=TERM                 Match titles containing TERM
    -n, --limit=N                    Show at most N books (default 10)
    -f, --format=FORMAT              Output format: text or json
        --tag=TAG[,TAG]              Only books with these tags

Common options:
        --[no-]color                 Colorize the output (default on)
    -v, --verbose                    Increase verbosity (repeatable)
    -h, --help                       Show this help
        --version                    Show the version

{term: "ruby", limit: 5, format: :json, color: false, verbose: 2, tags: ["ruby", "gems", "oop"]}
["extra"]

options_basic.rb:42:in 'Object#parse_options': invalid argument: -n abc (OptionParser::InvalidArgument)
	from options_basic.rb:47:in '<main>'

# frozen_string_literal: true

Thread.new do
  sleep 0.1
  Process.kill("INT", Process.pid)
end

begin
  sleep # waits for input, a socket or a long computation in a real program
rescue Interrupt => e
  puts "caught #{e.class} (#{e.message.inspect}), signo=#{e.signo}"
  puts "Interrupt is a SignalException, not a StandardError: #{Interrupt.ancestors.take(3).inspect}"
ensure
  puts "ensure still runs"
end

caught Interrupt (""), signo=2
Interrupt is a SignalException, not a StandardError: [Interrupt, SignalException, Exception]
ensure still runs

# frozen_string_literal: true

# Graceful shutdown: the handler only sets a flag, the main loop notices it between units of work.
stop = false
%w[INT TERM].each { |name| Signal.trap(name) { stop = true } }

Thread.new do # stands in for the user pressing Ctrl-C
  sleep 0.2
  Process.kill("INT", Process.pid)
end

processed = 0
until stop
  processed += 1 # one unit of work, for example importing one row
  sleep 0.05
end
puts "interrupted after #{processed.positive? ? 'some' : 'no'} work; cleaning up"
exit 130

interrupted after some work; cleaning up
status: 130

# frozen_string_literal: true

mutex = Thread::Mutex.new
Signal.trap("USR1") do
  mutex.synchronize { puts "unreachable" }
rescue ThreadError => e
  puts "in a trap handler: #{e.message}"
end
Process.kill("USR1", Process.pid)
sleep 0.1
p Signal.list.slice("INT", "TERM", "HUP", "USR1", "PIPE", "KILL", "WINCH")
p Signal.signame(15)
begin
  Signal.trap("KILL") { nil }
rescue Errno::EINVAL => e
  puts e.message
end

in a trap handler: can't be called from trap context
{"INT" => 2, "TERM" => 15, "HUP" => 1, "USR1" => 30, "PIPE" => 13, "KILL" => 9, "WINCH" => 28}
"TERM"
Invalid argument - SIGKILL

#!/usr/bin/env ruby
# frozen_string_literal: true

require "optparse"
require "shelf"

options = { search: nil }
OptionParser.new do |opts|
  opts.banner = "Usage: shelf [options]"
  opts.on("-sTERM", "--search=TERM", "Search titles") { |t| options[:search] = t }
  opts.on("-v", "--version", "Show version") do
    puts Shelf::VERSION
    exit
  end
end.parse!

catalog = Shelf::Catalog.new
catalog.add(Shelf::Book.new(Shelf::Isbn.new("978-0-306-40615-7"), "ruby basics", Shelf::Author.new("A. Writer")))
term = options[:search]
catalog.select { |b| term.nil? || b.title.include?(term) }.each { |b| puts b }

exe/shelf:15:in '<main>': invalid option: --nope (OptionParser::InvalidOption)

#!/usr/bin/env ruby
# frozen_string_literal: true

require "shelf/cli"

begin
  exit Shelf::CLI.run(ARGV)
rescue Interrupt
  warn "" # finish the line the terminal echoed ^C on
  exit 130 # 128 + SIGINT, what a shell reports for a process killed by Ctrl-C
rescue Errno::EPIPE
  exit 0 # the reader of our output (for example head) went away
end

# frozen_string_literal: true

require "json"
require "optparse"
require "shelf"
require "shelf/json_file"
require "shelf/painter"

module Shelf
  # The command-line front end. #run returns an exit status instead of calling exit,
  # so a test can run it in-process with fake streams.
  class CLI
    EX_USAGE = 64 # from BSD sysexits.h: the command was used incorrectly
    EX_FAILURE = 1

    BANNER = <<~TEXT
      Usage: shelf [options] COMMAND [ARGS]

      Commands: list, search TERM, add ISBN TITLE AUTHOR, import [FILE]
    TEXT

    Settings = Struct.new(:store, :format, :color)

    def self.run(argv, **) = new(**).run(argv)

    def initialize(stdin: $stdin, stdout: $stdout, stderr: $stderr, env: ENV)
      @stdin = stdin
      @stdout = stdout
      @stderr = stderr
      @env = env
      @settings = Settings.new(JsonFile.default_path(env), :text, :auto)
    end

    def run(argv)
      argv = argv.dup
      catch(:done) do
        parser.order!(argv) # stop at the first operand: the command name
        dispatch(argv)
      end
    rescue OptionParser::ParseError => e
      usage_error(e.message)
    rescue ArgumentError, KeyError, JSON::ParserError, SystemCallError => e
      failure(e.message)
    end

    private

    def dispatch(argv)
      command = argv.shift
      case command
      when "list" then show(books.sort_by(&:title))
      when "search" then search(argv)
      when "add" then add(argv)
      when "import" then import(argv)
      when nil then usage_error("missing command")
      else usage_error("unknown command: #{command}")
      end
    end

    def parser
      OptionParser.new do |opts|
        opts.program_name = "shelf"
        opts.version = Shelf::VERSION
        opts.banner = BANNER
        opts.separator ""
        global_options(opts)
        opts.on_tail("-h", "--help", "Show this help") { finish(opts.help) }
        opts.on_tail("--version", "Show the version") { finish(opts.ver) }
      end
    end

    def finish(text)
      @stdout.puts text
      throw :done, 0
    end

    def global_options(opts)
      opts.on("--store=PATH", "JSON file holding the books (env: SHELF_STORE)") { |v| @settings.store = v }
      opts.on("-f", "--format=FORMAT", %i[text json], "text (default) or json") { |v| @settings.format = v }
      opts.on("--color=WHEN", %i[auto always never], "auto (default), always or never") { |v| @settings.color = v }
    end

    def search(argv)
      limit = nil
      OptionParser.new("Usage: shelf search [options] TERM") do |opts|
        opts.on("-n", "--limit=N", Integer, "Show at most N books") { |v| limit = v }
      end.parse!(argv)
      return usage_error("search needs a TERM") if argv.empty?

      found = books.select { |book| book.title.downcase.include?(argv.first.downcase) }
      show(limit ? found.first(limit) : found)
    end

    def add(argv)
      return usage_error("add needs ISBN TITLE AUTHOR") unless argv.size == 3

      isbn, title, author = argv
      store.save(store.load.add(Book.new(Isbn.new(isbn), title, Author.new(author))))
      0
    end

    def import(argv)
      source = argv.empty? ? @stdin.read : File.read(argv.first)
      catalog = store.load
      JsonFile.books_from_json(source).each { |book| catalog.add(book) }
      store.save(catalog)
      0
    end

    def show(found)
      if @settings.format == :json
        @stdout.puts JSON.pretty_generate(found.map { |book| JsonFile.book_to_h(book) })
      else
        found.each { |book| @stdout.puts book }
      end
      found.empty? ? 1 : 0 # like grep: 1 means "nothing found"
    end

    def usage_error(message)
      failure(message)
      @stderr.puts "Try 'shelf --help' for usage."
      EX_USAGE
    end

    def failure(message)
      @stderr.puts "#{painter.paint('shelf:', :red)} #{message}"
      EX_FAILURE
    end

    def painter = Painter.new(@stderr, mode: @settings.color, env: @env)

    def store = JsonFile.new(@settings.store)

    def books = store.load.to_a
  end
end

# frozen_string_literal: true

require "fileutils"
require "json"
require "shelf"

module Shelf
  # Keeps a catalogue in a JSON file: the persistence the command-line program needs.
  class JsonFile
    def self.default_path(env = ENV)
      env.fetch("SHELF_STORE") do
        data_home = env.fetch("XDG_DATA_HOME") { File.join(Dir.home, ".local", "share") }
        File.join(data_home, "shelf", "books.json")
      end
    end

    def self.books_from_json(text)
      JSON.parse(text, symbolize_names: true).map do |row|
        Book.new(Isbn.new(row.fetch(:isbn)), row.fetch(:title), Author.new(row.fetch(:author)))
      end
    end

    def self.book_to_h(book) = { isbn: book.isbn.to_s, title: book.title, author: book.author.name }

    def initialize(path) = @path = path

    def load
      catalog = Catalog.new(store: Store::Memory.new)
      books_from_file.each { |book| catalog.add(book) }
      catalog
    end

    def save(catalog)
      FileUtils.mkdir_p(File.dirname(@path))
      File.write(@path, JSON.pretty_generate(catalog.map { |book| self.class.book_to_h(book) }))
    end

    private

    def books_from_file
      File.exist?(@path) ? self.class.books_from_json(File.read(@path)) : []
    end
  end
end

$ shelf list
[exit 1]
$ shelf add 978-0-306-40615-7 Ruby Basics A. Writer
[exit 0]
$ shelf add 978-0-306-40615-8 Broken A. Writer
shelf: invalid ISBN: 978-0-306-40615-8
[exit 1]
$ shelf add 978-0-306-40615-7 Only two
shelf: add needs ISBN TITLE AUTHOR
Try 'shelf --help' for usage.
[exit 64]
$ shelf import ../ex/import.json
[exit 0]
$ shelf list
Learning Ruby by M. Fitzgerald
Ruby Basics by A. Writer
The C Programming Language by B. Kernighan
[exit 0]
$ shelf search ruby
Ruby Basics by A. Writer
Learning Ruby by M. Fitzgerald
[exit 0]
$ shelf --format json search --limit 1 ruby
[
  {
    "isbn": "9780306406157",
    "title": "Ruby Basics",
    "author": "A. Writer"
  }
]
[exit 0]
$ shelf search nothing-here
[exit 1]
$ shelf --format xml list
shelf: invalid argument: --format xml
Try 'shelf --help' for usage.
[exit 64]
$ shelf frobnicate
shelf: unknown command: frobnicate
Try 'shelf --help' for usage.
[exit 64]
$ shelf
shelf: missing command
Try 'shelf --help' for usage.
[exit 64]
$ shelf --color always --bogus
^[[31mshelf:^[[0m invalid option: --bogus
Try 'shelf --help' for usage.
[exit 64]
$ shelf --store /dev/null/x.json add 978-0-306-40615-7 t a
shelf: File exists @ dir_s_mkdir - /dev/null
[exit 1]
$ shelf --version
shelf 0.1.0
[exit 0]
$ shelf import ../ex/bad.json
shelf: expected object key, got 'bad' at line 1 column 2
[exit 1]

# frozen_string_literal: true

require "open3"
require "stringio"
require "tmpdir"
require_relative "test_helper"
require "shelf/cli"

class CliTest < Minitest::Test
  ISBN = "978-0-306-40615-7"

  def setup
    @dir = Dir.mktmpdir("shelf-test")
    @store = File.join(@dir, "books.json")
  end

  def teardown = FileUtils.remove_entry(@dir)

  # In-process: fast, and the streams are plain StringIO objects.
  def run_cli(*argv, stdin: "")
    out = StringIO.new
    err = StringIO.new
    status = Shelf::CLI.run(["--store", @store, *argv], stdin: StringIO.new(stdin), stdout: out, stderr: err, env: {})
    [status, out.string, err.string]
  end

  def test_add_then_search
    assert_equal 0, run_cli("add", ISBN, "Ruby Basics", "A. Writer").first
    status, out, = run_cli("search", "ruby")
    assert_equal 0, status
    assert_equal "Ruby Basics by A. Writer\n", out
  end

  def test_unknown_command_is_a_usage_error
    status, out, err = run_cli("frobnicate")
    assert_equal Shelf::CLI::EX_USAGE, status
    assert_empty out
    assert_includes err, "unknown command: frobnicate"
  end

  def test_nothing_found_returns_one
    assert_equal 1, run_cli("search", "missing").first
  end

  # Out of process: the real executable, real exit status, real streams.
  def test_exe_reports_the_version
    exe = File.expand_path("../exe/shelf", __dir__)
    out, err, status = Open3.capture3(RbConfig.ruby, "-I#{File.expand_path('../lib', __dir__)}", exe, "--version")
    assert_predicate status, :success?
    assert_equal "shelf #{Shelf::VERSION}\n", out
    assert_empty err
  end
end