Class: Ron::Document

Inherits:
Object
  • Object
show all
Defined in:
lib/ron/document.rb

Overview

The Document class can be used to load and inspect a ron document and to convert a ron document into other formats, like roff or HTML.

Ron files may optionally follow the naming convention: “<name>.<section>.ron”. The <name> and <section> are used in generated documentation unless overridden by the information extracted from the document’s name section.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path = nil, attributes = {}, &block) ⇒ Document

Create a Ron::Document given a path or with the data returned by calling the block. The document is loaded and preprocessed before the intialize method returns. The attributes hash may contain values for any writeable attributes defined on this class.



48
49
50
51
52
53
54
55
56
57
 
# File 'lib/ron/document.rb', line 48

def initialize(path=nil, attributes={}, &block)
  @path = path
  @basename = path.to_s =~ /^-?$/ ? nil : File.basename(path)
  @reader = block || Proc.new { |f| File.read(f) }
  @data = @reader.call(path)
  @name, @section, @tagline = nil
  @manual, @organization, @date = nil
  @fragment = preprocess
  attributes.each { |attr_name,value| send("#{attr_name}=", value) }
end

Instance Attribute Details

#data ⇒ Object (readonly)

Returns the value of attribute data.



16
17
18
 
# File 'lib/ron/document.rb', line 16

def data
  @data
end

#date ⇒ Object

The date the man page was published. If not set explicitly, this is the file’s modified time or, if no file is given, the current time.



42
43
44
 
# File 'lib/ron/document.rb', line 42

def date
  @date
end

#manual ⇒ Object

The manual this document belongs to; center displayed in the header.



34
35
36
 
# File 'lib/ron/document.rb', line 34

def manual
  @manual
end

#name ⇒ Object

Returns the manual page name based first on the document’s contents and then on the path name.



22
23
24
 
# File 'lib/ron/document.rb', line 22

def name
  @name
end

#organization ⇒ Object

The name of the group, organization, or individual responsible for this document; displayed in the left portion of the footer.



38
39
40
 
# File 'lib/ron/document.rb', line 38

def organization
  @organization
end

#path ⇒ Object (readonly)

Returns the value of attribute path.



16
17
18
 
# File 'lib/ron/document.rb', line 16

def path
  @path
end

#section ⇒ Object

Returns the manual page section based first on the document’s contents and then on the path name.



26
27
28
 
# File 'lib/ron/document.rb', line 26

def section
  @section
end

#tagline ⇒ Object

Single sentence description of the thing being described by this man page; displayed in the NAME section.



30
31
32
 
# File 'lib/ron/document.rb', line 30

def tagline
  @tagline
end

Instance Method Details

#basename(type = nil) ⇒ Object

Generate a file basename of the form “<name>.<section>.<type>” for the given file extension. Uses the name and section from the source file path but falls back on the name and section defined in the document.



63
64
65
66
67
 
# File 'lib/ron/document.rb', line 63

def basename(type=nil)
  type = nil if ['', 'roff'].include?(type.to_s)
  [path_name || @name, path_section || @section, type].
  compact.join('.')
end

#convert(format) ⇒ Object

Convert the document to :roff, :html, or :html_fragment and return the result as a string.



128
129
130
 
# File 'lib/ron/document.rb', line 128

def convert(format)
  send "to_#{format}"
end

#name? ⇒ Boolean

Truthful when the name was extracted from the name section of the document.

Returns:

  • (Boolean) 


101
102
103
 
# File 'lib/ron/document.rb', line 101

def name?
  @name
end

#path_for(type = nil) ⇒ Object

Construct a path for a file near the source file. Uses the Document#basename method to generate the basename part and appends it to the dirname of the source document.



72
73
74
75
76
77
78
 
# File 'lib/ron/document.rb', line 72

def path_for(type=nil)
  if @basename
    File.join(File.dirname(path), basename(type))
  else
    basename(type)
  end
end

#path_name ⇒ Object

Returns the <name> part of the path, or nil when no path is available. This is used as the manual page name when the file contents do not include a name section.



83
84
85
 
# File 'lib/ron/document.rb', line 83

def path_name
  @basename[/^[^.]+/] if @basename
end

#path_section ⇒ Object

Returns the <section> part of the path, or nil when no path is available.



89
90
91
 
# File 'lib/ron/document.rb', line 89

def path_section
  $1 if @basename.to_s =~ /\.(\d\w*)\./
end

#section? ⇒ Boolean

True when the section number was extracted from the name section of the document.

Returns:

  • (Boolean) 


113
114
115
 
# File 'lib/ron/document.rb', line 113

def section?
  @section
end

#to_html ⇒ Object

Convert the document to HTML and return the result as a string.



146
147
148
 
# File 'lib/ron/document.rb', line 146

def to_html
  layout_filter(to_html_fragment)
end

#to_html_fragment ⇒ Object

Convert the document to HTML and return the result as a string. The HTML does not include <html>, <head>, or <style> tags.



153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/ron/document.rb', line 153

def to_html_fragment
  buf = []
  if name? && section?
    buf << "<h2 id='NAME'>NAME</h2>"
    buf << "<p><code>#{name}</code> -- #{tagline}</p>"
  elsif tagline
    buf << "<h1>#{[name, tagline].compact.join(' -- ')}</h1>"
  end
  buf << @fragment.to_s
  buf.join("\n")
end

#to_roff ⇒ Object

Convert the document to roff and return the result as a string.



133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/ron/document.rb', line 133

def to_roff
  RoffFilter.new(
    to_html_fragment,
    name,
    section,
    tagline,
    manual,
    organization,
    date
  ).to_s
end