describe.rb

#!/usr/bin/env ruby

#!DESCRIBE: Describe the purpose of an executable

require 'ptools'

def fatal(filename, msg)
  $stderr.puts("[ERR] #{filename}: #{msg}")
  exit 1
end

filename = ARGV.shift

fatal("???", "File name not given.") if filename.nil?

unless File.exist?(filename)
  ENV["PATH"].split(?:).each do |path|
    test = File.join(path, filename)
    if File.exist?(test)
      filename = test
      break
    end
  end
end

basename = File.basename(filename)

fatal(basename, "File does not exist.") unless File.exist?(filename)
fatal(basename, "File is not executable.") unless File.executable?(filename)
fatal(basename, "File is binary.") if File.binary?(filename)

file = File.readlines(filename)

describelines = file.select { |line|
    line =~ /\A[#\/]*!DESCRIBE:/
  }.map { |line|
    line.split("!DESCRIBE:")[1].strip
  }

fatal(basename, "File is indescribable!") if describelines.empty?

puts "#{basename}: #{describelines[0]}"
describelines[1..-1].each { |line|
  puts "#{" " * (basename.length + 2)}#{line}"
}

#!DESCRIBE: Usage: describe FILE