Class: Parser::Parser

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

Overview

![Parser Overview](../img/md_parse_js.png)

Turns the incoming javascript-source into a stream of comments. Those comments contain the parsed doclines, which are simply all lines found in the comment and all tokenlines.

A tokenline starts with a token like ‘@token` and can span over multiple lines, if it is intended by two spaces.

The comment-scope (i.e. the javascript-language-scope beginning in the next line) will be preserved as source of the comment as well.

For example it extracts to Comments from the following source

/**
 * @object Person
 */
var Person = {}

/**
 * Some documentation here, and there
 *
 * @object Person.config
 */
Person.config = {};

#=> [#<Parser::Comment tokenlines=1 doclines=0>, #<Parser::Comment tokenlines=1 doclines=2>]

See Also:

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(input, args = {}) ⇒ Parser

A new StringScanner instance will be used to parse the given input.

Parameters:

Raises:

  • (Exception) 


90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/parser/parser.rb', line 90

def initialize(input, args = {})
  
  raise Exception, "Expected input to be a String, got #{input.class}" unless input.is_a? String
  
  # Default Values
  @filepath = args[:filepath]  || "No File specified"
  @offset   = args[:offset]    || -1 # we are adding 1 later
  
  
  # clean input and convert windows linebreaks to normal ones
  @to_parse = input.force_encoding("UTF-8").gsub(/\r\n/, "\n")
  @scanner = StringScanner.new @to_parse

  @comments = []
end

Instance Attribute Details

#filepath ⇒ Object (readonly)

Returns the value of attribute filepath.



85
86
87
 
# File 'lib/parser/parser.rb', line 85

def filepath
  @filepath
end

#offset ⇒ Object (readonly)

Returns the value of attribute offset.



85
86
87
 
# File 'lib/parser/parser.rb', line 85

def offset
  @offset
end

Class Method Details

.parse_file(path) ⇒ Object

Reads the contents of path, creates a new Parser and starts parsing all at once



139
140
141
142
 
# File 'lib/parser/parser.rb', line 139

def self.parse_file(path)
  stream = File.read path
  Parser.new(stream, :filepath => path).parse
end

Instance Method Details

#parse ⇒ Array<Parser::Comment>

TODO:

Rewrite to use StringScanner#intelligent_skip_until

Recursivly parses the given input and thereby ignores strings and regular- expressions.

Returns:



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/parser/parser.rb', line 112

def parse()
  @scanner.skip /\s/
  @scanner.skip_until /#{M_START}|#{S_START}|#{NON_COMMENT_PATTERNS.keys.join('|')}|$/
  
  found = @scanner.matched
  
  if found.match M_START
    parse_comment_until(M_END)
    
  elsif found.match S_START
    parse_comment_until(S_END)
    
  else
    matched_pattern = NON_COMMENT_PATTERNS.detect do |start_pattern, end_pattern|    
      found.match start_pattern
    end       
    @scanner.skip_escaping_until matched_pattern.last unless matched_pattern.nil?    
  end
  
  if @scanner.eos?
    return @comments
  else
    parse
  end
end