Class: Tap::Support::Lazydoc::Document

Inherits:
Object
  • Object
show all
Defined in:
lib/tap/support/lazydoc/document.rb

Overview

A Document tracks constant attributes and code comments for a particular source file. Documents may be assigned a default_const_name to be used when a constant attribute does not specify a constant.

# KeyWithConst::key value a
# ::key value b

doc = Document.new(__FILE__, 'DefaultConst')
doc.resolve
doc['KeyWithConst']['key'].value      # => 'value a'
doc['DefaultConst']['key'].value      # => 'value b'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source_file = nil, default_const_name = '') ⇒ Document

Returns a new instance of Document.



40
41
42
43
44
45
46
47
 
# File 'lib/tap/support/lazydoc/document.rb', line 40

def initialize(source_file=nil, default_const_name='')
  self.source_file = source_file
  @default_const_name = default_const_name
  @comments = []
  @const_attrs = {}
  @resolved = false
  self.reset
end

Instance Attribute Details

#comments ⇒ Object (readonly)

An array of Comment objects identifying lines resolved or to-be-resolved



26
27
28
 
# File 'lib/tap/support/lazydoc/document.rb', line 26

def comments
  @comments
end

#const_attrs ⇒ Object (readonly)

A hash of [const_name, attributes] pairs tracking the constant attributes resolved or to-be-resolved for self. Attributes are hashes of [key, comment] pairs.



31
32
33
 
# File 'lib/tap/support/lazydoc/document.rb', line 31

def const_attrs
  @const_attrs
end

#default_const_name ⇒ Object

The default constant name used when no constant name is specified for a constant attribute



35
36
37
 
# File 'lib/tap/support/lazydoc/document.rb', line 35

def default_const_name
  @default_const_name
end

#resolved ⇒ Object

Flag indicating whether or not self has been resolved



38
39
40
 
# File 'lib/tap/support/lazydoc/document.rb', line 38

def resolved
  @resolved
end

#source_file ⇒ Object

The source file for self, used during resolve



22
23
24
 
# File 'lib/tap/support/lazydoc/document.rb', line 22

def source_file
  @source_file
end

Instance Method Details

#[](const_name) ⇒ Object

Returns the attributes for the specified const_name.



75
76
77
 
# File 'lib/tap/support/lazydoc/document.rb', line 75

def [](const_name)
  const_attrs[const_name] ||= {}
end

#const_names ⇒ Object

Returns an array of the const_names in self with at least one attribute.



81
82
83
84
85
86
87
 
# File 'lib/tap/support/lazydoc/document.rb', line 81

def const_names
  names = []
  const_attrs.each_pair do |const_name, attrs|
    names << const_name unless attrs.empty?
  end
  names
end

#register(line_number, comment_class = Comment) ⇒ Object

Register the specified line number to self. Register may take an integer or a regexp for late-evaluation. See Comment#resolve for more details.

Returns a comment_class instance corresponding to the line.



94
95
96
97
98
99
100
101
102
103
 
# File 'lib/tap/support/lazydoc/document.rb', line 94

def register(line_number, comment_class=Comment)
  comment = comments.find {|c| c.class == comment_class && c.line_number == line_number }

  if comment == nil
    comment = comment_class.new(line_number)
    comments << comment
  end

  comment
end

#register_method(method, comment_class = Comment) ⇒ Object

Registers a regexp matching methods by the specified name.



107
108
109
 
# File 'lib/tap/support/lazydoc/document.rb', line 107

def register_method(method, comment_class=Comment)
  register(/^\s*def\s+#{method}(\W|$)/, comment_class)
end

#reset ⇒ Object

Resets self by clearing const_attrs, comments, and setting resolved to false. Generally NOT recommended as this clears any work you’ve done registering lines; to simply allow resolve to re-scan a document, manually set resolved to false.



54
55
56
57
58
59
 
# File 'lib/tap/support/lazydoc/document.rb', line 54

def reset
  @const_attrs.clear
  @comments.clear
  @resolved = false
  self
end

#resolve(str = nil) ⇒ Object

Scans str for constant attributes and adds them to to self. Code comments are also resolved against str. If no str is specified, the contents of source_file are used instead.

Resolve does nothing if resolved == true. Returns true if str was resolved, or false otherwise.



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/tap/support/lazydoc/document.rb', line 117

def resolve(str=nil)
  return(false) if resolved

  str = File.read(source_file) if str == nil
  Lazydoc.parse(str) do |const_name, key, comment|
    const_name = default_const_name if const_name.empty?
    self[const_name][key] = comment
  end

  unless comments.empty?
    lines = str.split(/\r?\n/)  
    comments.each do |comment|
      comment.resolve(lines)
    end
  end

  @resolved = true
end

#to_hash ⇒ Object 



136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/tap/support/lazydoc/document.rb', line 136

def to_hash
  const_hash = {}
  const_attrs.each_pair do |const_name, attributes|
    next if attributes.empty?
  
    attr_hash = {}
    attributes.each_pair do |key, comment|
      attr_hash[key] = (block_given? ? yield(comment) : comment)
    end
    const_hash[const_name] = attr_hash
  end
  const_hash
end