Module: BinMan

Extended by:
BinMan
Included in:
BinMan
Defined in:
lib/binman.rb,
lib/binman/version.rb

Constant Summary

VERSION =
"3.3.2"

Instance Method Summary (collapse)

Instance Method Details

- (Object) conv(source = nil)

Converts given markdown(7) source into roff(7).



33
34
35
36
37
# File 'lib/binman.rb', line 33

def conv source=nil
  require_md2man
  require 'md2man/roff/engine'
  Md2Man::Roff::ENGINE.render(read(source))
end

- (Object) dump(source = nil)

Extracts leading comment header content from given source and returns the roff(7) conversion thereof.



41
42
43
# File 'lib/binman.rb', line 41

def dump source=nil
  conv load(source)
end

- (Object) help(source = nil, argv = ARGV)

Shows leading comment header from given source as UNIX man page and exits if the given argument vector contains '-h' or '–help', except after '–'.



88
89
90
91
92
93
94
95
# File 'lib/binman.rb', line 88

def help source=nil, argv=ARGV
  limit = argv.index('--') || argv.length
  index = [argv.index('-h'), argv.index('--help')].compact.min
  if index and index < limit
    show source
    exit
  end
end

- (Object) load(source = nil)

Extracts content of leading comment header (which can be one of the following two choices) from given source (IO, file name, or string).

(1) A contiguous sequence of single-line comments starting at the

beginning of the file (after shebang and encoding comments plus
optional blank lines) and ending at the first single blank line.

(2) First embedded document delimited by `=begin` and `=end` lines.

Comment markers and shebang/encoding comments are omitted from result.



17
18
19
20
21
22
23
24
25
26
27
28
29
30
# File 'lib/binman.rb', line 17

def load source=nil
  header = read(source)

  # strip shebang and encoding comments
  header.sub! /\A#!.+\n?/, ''
  header.sub! /\A#.*coding:.+\n?/, ''

  # extract the leading comment header
  if header =~ /\A\s*^#/
    header.split(/^\s*$/, 2).first.gsub(/^# ?/, '')
  else
    header[/^=begin\b.*?$(.*?)^=end\b.*?$/m, 1].to_s
  end.strip
end

- (Object) require_md2man

Requires that the correct version of Md2Man is available on this system.



98
99
100
101
102
103
104
# File 'lib/binman.rb', line 98

def require_md2man
  require 'rubygems' unless respond_to? :gem
  gem 'md2man', '~> 2.0' if respond_to? :gem
  require 'md2man/version'
rescue LoadError
  raise 'Run `gem install md2man --version "~> 2.0"` to use BinMan::conv().'
end

- (Object) show(source = nil)

Shows leading comment header from given source as UNIX man page if possible, else falls back to showing leading comment header as-is.



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
# File 'lib/binman.rb', line 47

def show source=nil
  # try showing existing man page files for given source
  if file = find(source) and File.exist? file
    man_page = File.basename(file)
    man_path = File.expand_path('../../man', file)

    # try showing HTML manual page in a web browser in background
    require 'opener'
    Dir["#{man_path}/**/#{man_page}.*.html"].each do |man_html|
      # close streams to avoid interference with man(1) reader below
      begin
        Opener.spawn man_html, 0 => :close, 1 => :close, 2 => :close
      rescue Errno::ENOENT
        # designated opener program could not be found on this system
      end
    end

    # try showing roff manual page in man(1) reader in foreground;
    # close STDERR to avoid interference with the fall back below
    return if system 'man', '-M', man_path, '-a', man_page, 2 => :close
  end

  # fall back to showing leading comment header as-is
  header = load(source)

  begin
    roff = conv(header)
    require 'tempfile'
    Tempfile.open 'binman' do |temp|
      temp.write roff
      temp.close
      system 'man', temp.path
    end
  rescue => error
    warn "binman: #{error}"
    puts header
  end
end