Module: Lazydoc

Defined in:
lib/lazydoc.rb,
lib/lazydoc/utils.rb,
lib/lazydoc/method.rb,
lib/lazydoc/comment.rb,
lib/lazydoc/subject.rb,
lib/lazydoc/trailer.rb,
lib/lazydoc/document.rb,
lib/lazydoc/arguments.rb,
lib/lazydoc/attributes.rb

Defined Under Namespace

Modules: Attributes, Utils Classes: Arguments, Comment, Document, Method, Subject, Trailer

Constant Summary collapse

ATTRIBUTE_REGEXP =

A regexp matching an attribute start or end. After a match:

$1:: const_name
$3:: key
$4:: end flag

/([A-Z][A-z]*(::[A-Z][A-z]*)*)?::([a-z_]+)(-?)/
CONSTANT_REGEXP =

A regexp matching constants from the ATTRIBUTE_REGEXP leader

/#.*?([A-Z][A-z]*(::[A-Z][A-z]*)*)?$/
CALLER_REGEXP =

A regexp matching a caller line, to extract the calling file and line number. After a match:

$1:: file
$3:: line number (as a string, obviously)

Note that line numbers in caller start at 1, not 0.

/^(([A-z]:)?[^:]+):(\d+)/

Class Method Summary collapse

Class Method Details

.[](source_file) ⇒ Object

Returns the Document in registry for the specified source file. If no such Document exists, one will be created for it.



13
14
15
16
 
# File 'lib/lazydoc.rb', line 13

def [](source_file)
  source_file = File.expand_path(source_file.to_s)
  registry.find {|doc| doc.source_file == source_file } || register_file(source_file)
end

.register(source_file, line_number, comment_class = Comment) ⇒ Object

Registers the line number to the document for source_file and returns the corresponding comment.



37
38
39
 
# File 'lib/lazydoc.rb', line 37

def register(source_file, line_number, comment_class=Comment)
  Lazydoc[source_file].register(line_number, comment_class)
end

.register_caller(comment_class = Comment, caller_index = 1) ⇒ Object

Registers the method at the specified index in the call stack to the file where the method was called. Using the default index of 1, register_caller registers the caller of the method where register_caller is called (whew!). For instance:

module Sample
  module_function
  def method
    Lazydoc.register_caller
  end
end

# this is the line that gets registered
c = Sample.method

c.resolve
c.subject   # => "c = Sample.method"
c.comment   # => "this is the line that gets registered"



60
61
62
63
 
# File 'lib/lazydoc.rb', line 60

def register_caller(comment_class=Comment, caller_index=1)
  caller[caller_index] =~ CALLER_REGEXP
  Lazydoc[$1].register($3.to_i - 1, comment_class)
end

.register_file(source_file, default_const_name = nil) ⇒ Object

Generates a Document the source_file and default_const_name and adds it to registry, or returns the document already registered to source_file. An error is raised if you try to re-register a source_file with an inconsistent default_const_name.



22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/lazydoc.rb', line 22

def register_file(source_file, default_const_name=nil)
  source_file = File.expand_path(source_file.to_s)
  lazydoc = registry.find {|doc| doc.source_file == source_file }
  
  unless lazydoc
    lazydoc = Document.new(source_file)
    registry << lazydoc
  end
  
  lazydoc.default_const_name = default_const_name
  lazydoc
end

.registry ⇒ Object

An array of documents registered with Lazydoc.



7
8
9
 
# File 'lib/lazydoc.rb', line 7

def registry
  @registry ||= []
end

.usage(path, cols = 80) ⇒ Object

Parses the usage for a file (ie the first comment in the file following an optional bang line), wrapped to n cols. For example, with this:

[hello_world.rb]
#!/usr/bin/env ruby
# This is your basic hello world
# script:
#
#   % ruby hello_world.rb

puts 'hello world'

You get this:

"\n" + Lazydoc.usage('hello_world.rb')  
# => %Q{
# This is your basic hello world script:
#
#   % ruby hello_world.rb}



86
87
88
89
90
91
 
# File 'lib/lazydoc.rb', line 86

def usage(path, cols=80)
  scanner = StringScanner.new(File.read(path))
  scanner.scan(/#!.*?\r?\n/)
  scanner.scan(/\s*#/m)
  Comment.new.parse_down(scanner, nil, false).wrap(cols, 2).strip
end