tomparse 0.1.0
Sign up to get free protection for your applications and to get access to all the features.
- data/.ruby +47 -0
- data/HISTORY.md +13 -0
- data/LICENSE.txt +24 -0
- data/README.md +75 -0
- data/lib/tomparse.rb +469 -0
- data/lib/tomparse.yml +47 -0
- data/test/helper.rb +20 -0
- data/test/test_tomdoc.rb +175 -0
- metadata +83 -0
data/.ruby
ADDED
@@ -0,0 +1,47 @@
|
|
1
|
+
---
|
2
|
+
source:
|
3
|
+
- meta
|
4
|
+
authors:
|
5
|
+
- name: Trans
|
6
|
+
email: transfire@gmail.com
|
7
|
+
copyrights:
|
8
|
+
- holder: Rubyworks
|
9
|
+
year: '2012'
|
10
|
+
license: BSD-2-Clause
|
11
|
+
requirements:
|
12
|
+
- name: microtest
|
13
|
+
groups:
|
14
|
+
- test
|
15
|
+
development: true
|
16
|
+
- name: detroit
|
17
|
+
groups:
|
18
|
+
- build
|
19
|
+
development: true
|
20
|
+
dependencies: []
|
21
|
+
alternatives: []
|
22
|
+
conflicts: []
|
23
|
+
repositories:
|
24
|
+
- uri: git@github.com:rubyworks/tomparse.git
|
25
|
+
scm: git
|
26
|
+
name: upstream
|
27
|
+
resources:
|
28
|
+
home: http://rubyworks.github.com/tomparse
|
29
|
+
docs: http://rubydoc.info/gems/tomparse
|
30
|
+
code: http://github.com/rubyworks/tomparse
|
31
|
+
mail: http://groups.google.com/groups/rubyworks-mailinglist
|
32
|
+
extra: {}
|
33
|
+
load_path:
|
34
|
+
- lib
|
35
|
+
revision: 0
|
36
|
+
created: '2012-03-04'
|
37
|
+
summary: TomDoc parser for Ruby
|
38
|
+
title: TomParse
|
39
|
+
version: 0.1.0
|
40
|
+
name: tomparse
|
41
|
+
description: ! 'TomParse is a Ruby TomDoc parser. It contains no other functionality
|
42
|
+
|
43
|
+
than the ability to take a comment and parse it in accordance to the
|
44
|
+
|
45
|
+
TomDoc standard.'
|
46
|
+
organization: rubyworks
|
47
|
+
date: '2012-03-04'
|
data/HISTORY.md
ADDED
@@ -0,0 +1,13 @@
|
|
1
|
+
# Release History
|
2
|
+
|
3
|
+
## 0.1.0 / 2012-03-04
|
4
|
+
|
5
|
+
TomParse is stand-alone TomDoc parser, spun-off and rewritten from the original
|
6
|
+
tomdoc.rb code from the defunkt/tomdoc project. Having a stand-alone project
|
7
|
+
just for the parser, makes it more convenient for other libraries to make use,
|
8
|
+
including, eventually, the original tomdoc project itself.
|
9
|
+
|
10
|
+
Changes:
|
11
|
+
|
12
|
+
* Happy Birthday.
|
13
|
+
|
data/LICENSE.txt
ADDED
@@ -0,0 +1,24 @@
|
|
1
|
+
Copyright 2002 Rubyworks. All rights reserved.
|
2
|
+
|
3
|
+
Redistribution and use in source and binary forms, with or without
|
4
|
+
modification, are permitted provided that the following conditions are met:
|
5
|
+
|
6
|
+
1. Redistributions of source code must retain the above copyright notice,
|
7
|
+
this list of conditions and the following disclaimer.
|
8
|
+
|
9
|
+
2. Redistributions in binary form must reproduce the above copyright
|
10
|
+
notice, this list of conditions and the following disclaimer in the
|
11
|
+
documentation and/or other materials provided with the distribution.
|
12
|
+
|
13
|
+
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
|
14
|
+
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
15
|
+
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
|
16
|
+
COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
17
|
+
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
18
|
+
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
19
|
+
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
|
20
|
+
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
21
|
+
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
|
22
|
+
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
23
|
+
|
24
|
+
(BSD-2-Clauase License)
|
data/README.md
ADDED
@@ -0,0 +1,75 @@
|
|
1
|
+
# TomParse
|
2
|
+
|
3
|
+
[Website](http://github.com/rubyworks/tomparse) /
|
4
|
+
[Report Issue](http://github.com/rubyworks/tomparse/issues) /
|
5
|
+
[Source Code](http://github.com/rubyworks/tomparse) /
|
6
|
+
[Gem Page](http://rubygems.org/gems/tomparse)
|
7
|
+
|
8
|
+
[![Build Status](https://secure.travis-ci.org/rubyworks/tomparse.png)](http://travis-ci.org/rubyworks/tomparse)
|
9
|
+
|
10
|
+
|
11
|
+
## Description
|
12
|
+
|
13
|
+
TomParse is TomDoc parser for Ruby. It provides no other functionality
|
14
|
+
than to take a code comment and parse it in to a convenient object-oriented
|
15
|
+
structure in accordance with TomDoc standard.
|
16
|
+
|
17
|
+
See [TomDoc](https://github.com/mojombo/tomdoc) for more information about
|
18
|
+
the TomDoc format.
|
19
|
+
|
20
|
+
|
21
|
+
## Limitations
|
22
|
+
|
23
|
+
Current implmentation doesn't yet support named parameters. Hopefully
|
24
|
+
that will be fixed soon in an upcoming release --any volunteers?
|
25
|
+
|
26
|
+
|
27
|
+
## Installation
|
28
|
+
|
29
|
+
$ gem install tomparse
|
30
|
+
|
31
|
+
|
32
|
+
## Instruction
|
33
|
+
|
34
|
+
The primay interface is the `TomParse.parse` method. It will parse the
|
35
|
+
comment and return a `TomParse::TomDoc` instance.
|
36
|
+
|
37
|
+
TomParse.parse(comment) #=> TomParse::TomDoc
|
38
|
+
|
39
|
+
The comment string can have comment markers ('#') or not. The
|
40
|
+
parse will remove them if present. The resulting TomDoc object
|
41
|
+
then has a selection of methods that provide information from
|
42
|
+
the comment, such as `#arguments`, `#examples`, etc.
|
43
|
+
|
44
|
+
See the [API documention](http://rubydoc.info/gems/tomparse/frames)
|
45
|
+
for more details on this.
|
46
|
+
|
47
|
+
|
48
|
+
## Example
|
49
|
+
|
50
|
+
If you are unfamiliar with TomDoc, an example TomDoc comment for a method
|
51
|
+
looks something like this:
|
52
|
+
|
53
|
+
# Duplicate some text an abitrary number of times.
|
54
|
+
#
|
55
|
+
# text - The String to be duplicated.
|
56
|
+
# count - The Integer number of times to duplicate the text.
|
57
|
+
#
|
58
|
+
# Examples
|
59
|
+
# multiplex('Tom', 4)
|
60
|
+
# # => 'TomTomTomTom'
|
61
|
+
#
|
62
|
+
# Returns the duplicated String.
|
63
|
+
def multiplex(text, count)
|
64
|
+
text * count
|
65
|
+
end
|
66
|
+
|
67
|
+
|
68
|
+
## License
|
69
|
+
|
70
|
+
Copyright (c) 2012 Rubyworks
|
71
|
+
|
72
|
+
TomParse is distributable under the terms of the *BSD-2-Clause* license.
|
73
|
+
|
74
|
+
See LICENSE.txt for details.
|
75
|
+
|
data/lib/tomparse.rb
ADDED
@@ -0,0 +1,469 @@
|
|
1
|
+
module TomParse
|
2
|
+
|
3
|
+
# Main interface to parser.
|
4
|
+
#
|
5
|
+
# comment - code comment [String]
|
6
|
+
#
|
7
|
+
def self.parse(comment, parse_options={})
|
8
|
+
TomDoc.new(comment, parse_options)
|
9
|
+
end
|
10
|
+
|
11
|
+
# Raised when comment can't be parsed, which means it's most
|
12
|
+
# likely not valid TomDoc.
|
13
|
+
#
|
14
|
+
class ParseError < RuntimeError
|
15
|
+
# Create new ParseError object.
|
16
|
+
#
|
17
|
+
# doc - document string
|
18
|
+
#
|
19
|
+
def initialize(doc)
|
20
|
+
@doc = doc
|
21
|
+
end
|
22
|
+
|
23
|
+
# Provide access to document string.
|
24
|
+
#
|
25
|
+
# Returns String.
|
26
|
+
def message
|
27
|
+
@doc
|
28
|
+
end
|
29
|
+
|
30
|
+
# Provide access to document string.
|
31
|
+
#
|
32
|
+
# Returns String.
|
33
|
+
def to_s
|
34
|
+
@doc
|
35
|
+
end
|
36
|
+
end
|
37
|
+
|
38
|
+
# Encapsulate parsed tomdoc documentation.
|
39
|
+
#
|
40
|
+
# TODO: Currently uses lazy evaluation, eventually this should
|
41
|
+
# be removed and simply parsed at initialization time.
|
42
|
+
#
|
43
|
+
class TomDoc
|
44
|
+
attr_accessor :raw
|
45
|
+
|
46
|
+
# Public: Initialize a TomDoc object.
|
47
|
+
#
|
48
|
+
# text - The raw text of a method or class/module comment.
|
49
|
+
#
|
50
|
+
# Returns new TomDoc instance.
|
51
|
+
def initialize(text, parse_options={})
|
52
|
+
@raw = text.to_s.strip
|
53
|
+
|
54
|
+
@arguments = []
|
55
|
+
@options = [] # TODO
|
56
|
+
@examples = []
|
57
|
+
@returns = []
|
58
|
+
@raises = []
|
59
|
+
@signatures = []
|
60
|
+
@signature_fields = []
|
61
|
+
|
62
|
+
parse unless @raw.empty?
|
63
|
+
end
|
64
|
+
|
65
|
+
def to_s
|
66
|
+
@raw
|
67
|
+
end
|
68
|
+
|
69
|
+
# Validate given comment text.
|
70
|
+
#
|
71
|
+
# Returns true if comment is valid, otherwise false.
|
72
|
+
def self.valid?(text)
|
73
|
+
new(text).valid?
|
74
|
+
end
|
75
|
+
|
76
|
+
# Validate raw comment.
|
77
|
+
#
|
78
|
+
# Returns true if comment is valid, otherwise false.
|
79
|
+
def valid?
|
80
|
+
return false if !raw.include?('Returns')
|
81
|
+
return false if sections.size < 2
|
82
|
+
true
|
83
|
+
end
|
84
|
+
|
85
|
+
# Validate raw comment.
|
86
|
+
#
|
87
|
+
# Returns true if comment is valid.
|
88
|
+
# Raises ParseError if comment is not valid.
|
89
|
+
def validate
|
90
|
+
if !raw.include?('Returns')
|
91
|
+
raise ParseError.new("No `Returns' statement.")
|
92
|
+
end
|
93
|
+
|
94
|
+
if sections.size < 2
|
95
|
+
raise ParseError.new("No description section found.")
|
96
|
+
end
|
97
|
+
|
98
|
+
true
|
99
|
+
end
|
100
|
+
|
101
|
+
# The raw comment text cleaned-up and ready for section parsing.
|
102
|
+
#
|
103
|
+
# Returns cleaned-up comment String.
|
104
|
+
def tomdoc
|
105
|
+
lines = raw.split("\n")
|
106
|
+
|
107
|
+
# remove remark symbol
|
108
|
+
if lines.all?{ |line| /^\s*#/ =~ line }
|
109
|
+
lines = lines.map do |line|
|
110
|
+
line =~ /^(\s*#)/ ? line.sub($1, '') : nil
|
111
|
+
end
|
112
|
+
end
|
113
|
+
|
114
|
+
# for some reason the first line is coming in without indention
|
115
|
+
# regardless, so we temporary remove it
|
116
|
+
first = lines.shift
|
117
|
+
|
118
|
+
# remove indention
|
119
|
+
spaces = lines.map do |line|
|
120
|
+
next if line.strip.empty?
|
121
|
+
md = /^(\s*)/.match(line)
|
122
|
+
md ? md[1].size : nil
|
123
|
+
end.compact
|
124
|
+
|
125
|
+
space = spaces.min || 0
|
126
|
+
lines = lines.map do |line|
|
127
|
+
if line.empty?
|
128
|
+
line.strip
|
129
|
+
else
|
130
|
+
line[space..-1]
|
131
|
+
end
|
132
|
+
end
|
133
|
+
|
134
|
+
# put first line back
|
135
|
+
lines.unshift(first.sub(/^\s*/,''))
|
136
|
+
|
137
|
+
lines.compact.join("\n")
|
138
|
+
end
|
139
|
+
|
140
|
+
# List of comment sections. These are divided simply on "\n\n".
|
141
|
+
#
|
142
|
+
# Returns Array of comment sections.
|
143
|
+
def sections
|
144
|
+
parsed {
|
145
|
+
@sections
|
146
|
+
}
|
147
|
+
end
|
148
|
+
|
149
|
+
# Description of method or class/module.
|
150
|
+
#
|
151
|
+
# Returns description String.
|
152
|
+
def description
|
153
|
+
parsed {
|
154
|
+
@description
|
155
|
+
}
|
156
|
+
end
|
157
|
+
|
158
|
+
# Description of method or class/module.
|
159
|
+
#
|
160
|
+
# Returns description String.
|
161
|
+
def arguments
|
162
|
+
parsed {
|
163
|
+
@arguments
|
164
|
+
}
|
165
|
+
end
|
166
|
+
alias args arguments
|
167
|
+
|
168
|
+
# List of use examples of a method or class/module.
|
169
|
+
#
|
170
|
+
# Returns String of examples.
|
171
|
+
def examples
|
172
|
+
parsed {
|
173
|
+
@examples
|
174
|
+
}
|
175
|
+
end
|
176
|
+
|
177
|
+
# Description of a methods yield procedure.
|
178
|
+
#
|
179
|
+
# Returns String decription of yield procedure.
|
180
|
+
def yields
|
181
|
+
parsed {
|
182
|
+
@yields
|
183
|
+
}
|
184
|
+
end
|
185
|
+
|
186
|
+
# The list of retrun values a method can return.
|
187
|
+
#
|
188
|
+
# Returns Array of method return descriptions.
|
189
|
+
def returns
|
190
|
+
parsed {
|
191
|
+
@returns
|
192
|
+
}
|
193
|
+
end
|
194
|
+
|
195
|
+
# A list of errors a method might raise.
|
196
|
+
#
|
197
|
+
# Returns Array of method raises descriptions.
|
198
|
+
def raises
|
199
|
+
parsed {
|
200
|
+
@raises
|
201
|
+
}
|
202
|
+
end
|
203
|
+
|
204
|
+
# A list of alternate method signatures.
|
205
|
+
#
|
206
|
+
# Returns Array of signatures.
|
207
|
+
def signatures
|
208
|
+
parsed {
|
209
|
+
@signatures
|
210
|
+
}
|
211
|
+
end
|
212
|
+
|
213
|
+
# A list of signature fields.
|
214
|
+
#
|
215
|
+
# Returns Array of field definitions.
|
216
|
+
def signature_fields
|
217
|
+
parsed {
|
218
|
+
@signature_fields
|
219
|
+
}
|
220
|
+
end
|
221
|
+
|
222
|
+
# Check if method is public.
|
223
|
+
#
|
224
|
+
# Returns true if method is public.
|
225
|
+
def public?
|
226
|
+
parsed {
|
227
|
+
@status == 'Public'
|
228
|
+
}
|
229
|
+
end
|
230
|
+
|
231
|
+
# Check if method is internal.
|
232
|
+
#
|
233
|
+
# Returns true if method is internal.
|
234
|
+
def internal?
|
235
|
+
parsed {
|
236
|
+
@status == 'Internal'
|
237
|
+
}
|
238
|
+
end
|
239
|
+
|
240
|
+
# Check if method is deprecated.
|
241
|
+
#
|
242
|
+
# Returns true if method is deprecated.
|
243
|
+
def deprecated?
|
244
|
+
parsed {
|
245
|
+
@status == 'Deprecated'
|
246
|
+
}
|
247
|
+
end
|
248
|
+
|
249
|
+
private
|
250
|
+
|
251
|
+
# Has the comment been parsed yet?
|
252
|
+
def parsed(&block)
|
253
|
+
parse unless @parsed
|
254
|
+
block.call
|
255
|
+
end
|
256
|
+
|
257
|
+
# Internal: Parse the Tomdoc formatted comment.
|
258
|
+
#
|
259
|
+
# Returns true if there was a comment to parse.
|
260
|
+
def parse
|
261
|
+
@parsed = true
|
262
|
+
|
263
|
+
@sections = tomdoc.split("\n\n")
|
264
|
+
sections = @sections.dup
|
265
|
+
|
266
|
+
return false if sections.empty?
|
267
|
+
|
268
|
+
parse_description(sections.shift)
|
269
|
+
|
270
|
+
if sections.first && sections.first =~ /^\w+\s+\-/m
|
271
|
+
parse_arguments(sections.shift)
|
272
|
+
end
|
273
|
+
|
274
|
+
current = sections.shift
|
275
|
+
while current
|
276
|
+
case current
|
277
|
+
when /^Examples/
|
278
|
+
parse_examples(current, sections)
|
279
|
+
when /^Yields/
|
280
|
+
parse_yields(current)
|
281
|
+
when /^(Returns|Raises)/
|
282
|
+
parse_returns(current)
|
283
|
+
when /^Signature/
|
284
|
+
parse_signature(current, sections)
|
285
|
+
end
|
286
|
+
current = sections.shift
|
287
|
+
end
|
288
|
+
|
289
|
+
return @parsed
|
290
|
+
end
|
291
|
+
|
292
|
+
# Parse description.
|
293
|
+
#
|
294
|
+
# section - String containig description.
|
295
|
+
#
|
296
|
+
# Returns nothing.
|
297
|
+
def parse_description(section)
|
298
|
+
if md = /^([A-Z]\w+\:)/.match(section)
|
299
|
+
@status = md[1].chomp(':')
|
300
|
+
@description = md.post_match.strip
|
301
|
+
else
|
302
|
+
@description = section.strip
|
303
|
+
end
|
304
|
+
end
|
305
|
+
|
306
|
+
# Parse arguments section. Arguments occur subsequent to
|
307
|
+
# the description.
|
308
|
+
#
|
309
|
+
# section - String containing agument definitions.
|
310
|
+
#
|
311
|
+
# Returns nothing.
|
312
|
+
def parse_arguments(section)
|
313
|
+
args = []
|
314
|
+
last_indent = nil
|
315
|
+
|
316
|
+
section.split("\n").each do |line|
|
317
|
+
next if line.strip.empty?
|
318
|
+
indent = line.scan(/^\s*/)[0].to_s.size
|
319
|
+
|
320
|
+
if last_indent && indent > last_indent
|
321
|
+
args.last.description += line.squeeze(" ")
|
322
|
+
else
|
323
|
+
param, desc = line.split(" - ")
|
324
|
+
args << Argument.new(param.strip, desc.strip) if param && desc
|
325
|
+
end
|
326
|
+
|
327
|
+
last_indent = indent
|
328
|
+
end
|
329
|
+
|
330
|
+
@arguments = args
|
331
|
+
end
|
332
|
+
|
333
|
+
# Parse examples.
|
334
|
+
#
|
335
|
+
# section - String starting with `Examples`.
|
336
|
+
# sections - All sections subsequent to section.
|
337
|
+
#
|
338
|
+
# Returns nothing.
|
339
|
+
def parse_examples(section, sections)
|
340
|
+
examples = []
|
341
|
+
|
342
|
+
section = section.sub('Examples', '').strip
|
343
|
+
|
344
|
+
examples << section unless section.empty?
|
345
|
+
while sections.first && sections.first !~ /^\S/
|
346
|
+
examples << sections.shift.strip
|
347
|
+
end
|
348
|
+
|
349
|
+
@examples = examples
|
350
|
+
end
|
351
|
+
|
352
|
+
# Parse yields section.
|
353
|
+
#
|
354
|
+
# section - String contaning Yields line.
|
355
|
+
#
|
356
|
+
# Returns nothing.
|
357
|
+
def parse_yields(section)
|
358
|
+
@yields = section.strip
|
359
|
+
end
|
360
|
+
|
361
|
+
# Parse returns section.
|
362
|
+
#
|
363
|
+
# section - String contaning Returns and/or Raises lines.
|
364
|
+
#
|
365
|
+
# Returns nothing.
|
366
|
+
def parse_returns(section)
|
367
|
+
returns, raises, current = [], [], []
|
368
|
+
|
369
|
+
lines = section.split("\n")
|
370
|
+
lines.each do |line|
|
371
|
+
case line
|
372
|
+
when /^Returns/
|
373
|
+
returns << line
|
374
|
+
current = returns
|
375
|
+
when /^Raises/
|
376
|
+
raises << line
|
377
|
+
current = raises
|
378
|
+
when /^\s+/
|
379
|
+
current.last << line.squeeze(' ')
|
380
|
+
else
|
381
|
+
current << line # TODO: What to do with non-compliant line?
|
382
|
+
end
|
383
|
+
end
|
384
|
+
|
385
|
+
@returns, @raises = returns, raises
|
386
|
+
end
|
387
|
+
|
388
|
+
# Parse signature section.
|
389
|
+
#
|
390
|
+
# section - String starting with `Signature`.
|
391
|
+
# sections - All sections subsequent to section.
|
392
|
+
#
|
393
|
+
# Returns nothing.
|
394
|
+
def parse_signature(section, sections=[])
|
395
|
+
signatures = []
|
396
|
+
|
397
|
+
section = section.sub('Signature', '').strip
|
398
|
+
|
399
|
+
signatures << section unless section.empty?
|
400
|
+
|
401
|
+
while sections.first && sections.first !~ /^\S/
|
402
|
+
sigs = sections.shift
|
403
|
+
sigs.split("\n").each do |s|
|
404
|
+
signatures << s.strip
|
405
|
+
end
|
406
|
+
end
|
407
|
+
|
408
|
+
@signatures = signatures
|
409
|
+
|
410
|
+
if sections.first && sections.first =~ /^\w+\s*\-/m
|
411
|
+
parse_signature_fields(sections.shift)
|
412
|
+
end
|
413
|
+
end
|
414
|
+
|
415
|
+
# Subsequent to Signature section there can be field
|
416
|
+
# definitions.
|
417
|
+
#
|
418
|
+
# section - String subsequent to signatures.
|
419
|
+
#
|
420
|
+
# Returns nothing.
|
421
|
+
def parse_signature_fields(section)
|
422
|
+
args = []
|
423
|
+
last_indent = nil
|
424
|
+
|
425
|
+
section.split("\n").each do |line|
|
426
|
+
next if line.strip.empty?
|
427
|
+
indent = line.scan(/^\s*/)[0].to_s.size
|
428
|
+
|
429
|
+
if last_indent && indent > last_indent
|
430
|
+
args.last.description += line.squeeze(" ")
|
431
|
+
else
|
432
|
+
param, desc = line.split(" - ")
|
433
|
+
args << Argument.new(param.strip, desc.strip) if param && desc
|
434
|
+
end
|
435
|
+
|
436
|
+
last_indent = indent
|
437
|
+
end
|
438
|
+
|
439
|
+
@signature_fields = args
|
440
|
+
end
|
441
|
+
|
442
|
+
end
|
443
|
+
|
444
|
+
# Encapsulate a method argument.
|
445
|
+
#
|
446
|
+
class Argument
|
447
|
+
|
448
|
+
attr_accessor :name, :description
|
449
|
+
|
450
|
+
# Create new Argument object.
|
451
|
+
#
|
452
|
+
# name - name of argument
|
453
|
+
# description - argument description
|
454
|
+
#
|
455
|
+
def initialize(name, description = '')
|
456
|
+
@name = name.to_s.intern
|
457
|
+
@description = description
|
458
|
+
end
|
459
|
+
|
460
|
+
# Is this an optional argument?
|
461
|
+
#
|
462
|
+
# Returns Boolean.
|
463
|
+
def optional?
|
464
|
+
@description.downcase.include? 'optional'
|
465
|
+
end
|
466
|
+
|
467
|
+
end
|
468
|
+
|
469
|
+
end
|
data/lib/tomparse.yml
ADDED
@@ -0,0 +1,47 @@
|
|
1
|
+
---
|
2
|
+
source:
|
3
|
+
- meta
|
4
|
+
authors:
|
5
|
+
- name: Trans
|
6
|
+
email: transfire@gmail.com
|
7
|
+
copyrights:
|
8
|
+
- holder: Rubyworks
|
9
|
+
year: '2012'
|
10
|
+
license: BSD-2-Clause
|
11
|
+
requirements:
|
12
|
+
- name: microtest
|
13
|
+
groups:
|
14
|
+
- test
|
15
|
+
development: true
|
16
|
+
- name: detroit
|
17
|
+
groups:
|
18
|
+
- build
|
19
|
+
development: true
|
20
|
+
dependencies: []
|
21
|
+
alternatives: []
|
22
|
+
conflicts: []
|
23
|
+
repositories:
|
24
|
+
- uri: git@github.com:rubyworks/tomparse.git
|
25
|
+
scm: git
|
26
|
+
name: upstream
|
27
|
+
resources:
|
28
|
+
home: http://rubyworks.github.com/tomparse
|
29
|
+
docs: http://rubydoc.info/gems/tomparse
|
30
|
+
code: http://github.com/rubyworks/tomparse
|
31
|
+
mail: http://groups.google.com/groups/rubyworks-mailinglist
|
32
|
+
extra: {}
|
33
|
+
load_path:
|
34
|
+
- lib
|
35
|
+
revision: 0
|
36
|
+
created: '2012-03-04'
|
37
|
+
summary: TomDoc parser for Ruby
|
38
|
+
title: TomParse
|
39
|
+
version: 0.1.0
|
40
|
+
name: tomparse
|
41
|
+
description: ! 'TomParse is a Ruby TomDoc parser. It contains no other functionality
|
42
|
+
|
43
|
+
than the ability to take a comment and parse it in accordance to the
|
44
|
+
|
45
|
+
TomDoc standard.'
|
46
|
+
organization: rubyworks
|
47
|
+
date: '2012-03-04'
|
data/test/helper.rb
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
#require 'microtest/testunit'
|
2
|
+
#require 'test/unit'
|
3
|
+
#require 'test/fixtures/multiplex'
|
4
|
+
require 'tomparse'
|
5
|
+
|
6
|
+
module TomParse
|
7
|
+
class Test < ::Test::Unit::TestCase
|
8
|
+
def self.test(name, &block)
|
9
|
+
define_method("test_#{name.gsub(/\W/,'_')}", &block) if block
|
10
|
+
end
|
11
|
+
|
12
|
+
def default_test
|
13
|
+
end
|
14
|
+
|
15
|
+
def fixture(name)
|
16
|
+
@fixtures ||= {}
|
17
|
+
@fixtures[name] ||= File.read("test/fixtures/#{name}.rb")
|
18
|
+
end
|
19
|
+
end
|
20
|
+
end
|
data/test/test_tomdoc.rb
ADDED
@@ -0,0 +1,175 @@
|
|
1
|
+
require 'helper'
|
2
|
+
|
3
|
+
class TomDocTestCase < TomParse::Test
|
4
|
+
|
5
|
+
def setup
|
6
|
+
@comment = TomParse::TomDoc.new(<<comment)
|
7
|
+
# Duplicate some text an abitrary number of times.
|
8
|
+
#
|
9
|
+
# text - The String to be duplicated.
|
10
|
+
# count - The Integer number of times to
|
11
|
+
# duplicate the text.
|
12
|
+
# reverse - An optional Boolean indicating
|
13
|
+
# whether to reverse the result text or not.
|
14
|
+
#
|
15
|
+
# Examples
|
16
|
+
# multiplex('Tom', 4)
|
17
|
+
# # => 'TomTomTomTom'
|
18
|
+
#
|
19
|
+
# multiplex('Bo', 2)
|
20
|
+
# # => 'BoBo'
|
21
|
+
#
|
22
|
+
# multiplex('Chris', -1)
|
23
|
+
# # => nil
|
24
|
+
#
|
25
|
+
# Returns the duplicated String when the count is > 1.
|
26
|
+
# Returns the atomic mass of the element as a Float. The value is in
|
27
|
+
# unified atomic mass units.
|
28
|
+
# Returns nil when the count is < 1.
|
29
|
+
# Raises ExpectedString if the first argument is not a String.
|
30
|
+
# Raises ExpectedInteger if the second argument is not an Integer.
|
31
|
+
comment
|
32
|
+
|
33
|
+
@comment2 = TomParse::TomDoc.new(<<comment2)
|
34
|
+
# Duplicate some text an abitrary number of times.
|
35
|
+
#
|
36
|
+
# Returns the duplicated String.
|
37
|
+
comment2
|
38
|
+
|
39
|
+
@comment3 = TomParse::TomDoc.new(<<comment3)
|
40
|
+
# Duplicate some text an abitrary number of times.
|
41
|
+
#
|
42
|
+
# Examples
|
43
|
+
#
|
44
|
+
# multiplex('Tom', 4)
|
45
|
+
# # => 'TomTomTomTom'
|
46
|
+
#
|
47
|
+
# multiplex('Bo', 2)
|
48
|
+
# # => 'BoBo'
|
49
|
+
comment3
|
50
|
+
|
51
|
+
@comment4 = TomParse::TomDoc.new(<<comment4)
|
52
|
+
# Duplicate some text an abitrary number of times.
|
53
|
+
#
|
54
|
+
# Yields the Integer index of the iteration.
|
55
|
+
#
|
56
|
+
# Signature
|
57
|
+
#
|
58
|
+
# find_by_<field>[_and_<field>...](args)
|
59
|
+
#
|
60
|
+
# field - A field name.
|
61
|
+
comment4
|
62
|
+
|
63
|
+
@comment5 = TomParse::TomDoc.new(<<comment5)
|
64
|
+
Duplicate some text an abitrary number of times.
|
65
|
+
|
66
|
+
Yields the Integer index of the iteration.
|
67
|
+
|
68
|
+
Signature
|
69
|
+
|
70
|
+
find_by_<field>[_and_<field>...](args)
|
71
|
+
|
72
|
+
field - A field name.
|
73
|
+
comment5
|
74
|
+
|
75
|
+
end
|
76
|
+
|
77
|
+
test "knows when TomDoc is invalid" do
|
78
|
+
assert_raises TomParse::ParseError do
|
79
|
+
@comment3.validate
|
80
|
+
end
|
81
|
+
end
|
82
|
+
|
83
|
+
test "parses a description" do
|
84
|
+
assert_equal "Duplicate some text an abitrary number of times.",
|
85
|
+
@comment.description
|
86
|
+
end
|
87
|
+
|
88
|
+
test "parses args" do
|
89
|
+
assert_equal 3, @comment.args.size
|
90
|
+
end
|
91
|
+
|
92
|
+
test "knows an arg's name" do
|
93
|
+
assert_equal :text, @comment.args.first.name
|
94
|
+
assert_equal :count, @comment.args[1].name
|
95
|
+
assert_equal :reverse, @comment.args[2].name
|
96
|
+
end
|
97
|
+
|
98
|
+
test "knows an arg's description" do
|
99
|
+
assert_equal 'The Integer number of times to duplicate the text.',
|
100
|
+
@comment.args[1].description
|
101
|
+
|
102
|
+
reverse = 'An optional Boolean indicating whether to reverse the'
|
103
|
+
reverse << ' result text or not.'
|
104
|
+
assert_equal reverse, @comment.args[2].description
|
105
|
+
end
|
106
|
+
|
107
|
+
test "knows an arg's optionality" do
|
108
|
+
assert_equal false, @comment.args.first.optional?
|
109
|
+
assert_equal true, @comment.args.last.optional?
|
110
|
+
end
|
111
|
+
|
112
|
+
test "knows what to do when there are no args" do
|
113
|
+
assert_equal 0, @comment2.args.size
|
114
|
+
end
|
115
|
+
|
116
|
+
test "knows how many examples there are" do
|
117
|
+
assert_equal 3, @comment.examples.size
|
118
|
+
end
|
119
|
+
|
120
|
+
test "knows each example" do
|
121
|
+
assert_equal "multiplex('Bo', 2)\n # => 'BoBo'",
|
122
|
+
@comment.examples[1].to_s
|
123
|
+
end
|
124
|
+
|
125
|
+
test "knows what to do when there are no examples" do
|
126
|
+
assert_equal 0, @comment2.examples.size
|
127
|
+
end
|
128
|
+
|
129
|
+
test "knows how many return examples there are" do
|
130
|
+
assert_equal 3, @comment.returns.size
|
131
|
+
end
|
132
|
+
|
133
|
+
test "knows if the method raises anything" do
|
134
|
+
assert_equal 2, @comment.raises.size
|
135
|
+
end
|
136
|
+
|
137
|
+
test "knows each return example" do
|
138
|
+
assert_equal "Returns the duplicated String when the count is > 1.",
|
139
|
+
@comment.returns.first.to_s
|
140
|
+
|
141
|
+
string = ''
|
142
|
+
string << "Returns the atomic mass of the element as a Float. "
|
143
|
+
string << "The value is in unified atomic mass units."
|
144
|
+
assert_equal string, @comment.returns[1].to_s
|
145
|
+
|
146
|
+
assert_equal "Returns nil when the count is < 1.",
|
147
|
+
@comment.returns[2].to_s
|
148
|
+
end
|
149
|
+
|
150
|
+
test "knows what to do when there are no return examples" do
|
151
|
+
assert_equal 0, @comment2.examples.size
|
152
|
+
end
|
153
|
+
|
154
|
+
test "knows what the method yields" do
|
155
|
+
assert_equal "Yields the Integer index of the iteration.", @comment4.yields
|
156
|
+
end
|
157
|
+
|
158
|
+
test "knows if the method has alternate signatures" do
|
159
|
+
assert_equal 1, @comment4.signatures.size
|
160
|
+
assert_equal "find_by_<field>[_and_<field>...](args)", @comment4.signatures.first
|
161
|
+
end
|
162
|
+
|
163
|
+
test "knows the fields associated with signatures" do
|
164
|
+
assert_equal 1, @comment4.signature_fields.size
|
165
|
+
|
166
|
+
arg = @comment4.signature_fields.first
|
167
|
+
assert_equal :field, arg.name
|
168
|
+
assert_equal "A field name.", arg.description
|
169
|
+
end
|
170
|
+
|
171
|
+
test "can hande comments without comment marker" do
|
172
|
+
assert_equal "Duplicate some text an abitrary number of times.",
|
173
|
+
@comment5.description
|
174
|
+
end
|
175
|
+
end
|
metadata
ADDED
@@ -0,0 +1,83 @@
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
2
|
+
name: tomparse
|
3
|
+
version: !ruby/object:Gem::Version
|
4
|
+
version: 0.1.0
|
5
|
+
prerelease:
|
6
|
+
platform: ruby
|
7
|
+
authors:
|
8
|
+
- Trans
|
9
|
+
autorequire:
|
10
|
+
bindir: bin
|
11
|
+
cert_chain: []
|
12
|
+
date: 2012-03-04 00:00:00.000000000 Z
|
13
|
+
dependencies:
|
14
|
+
- !ruby/object:Gem::Dependency
|
15
|
+
name: microtest
|
16
|
+
requirement: &23546980 !ruby/object:Gem::Requirement
|
17
|
+
none: false
|
18
|
+
requirements:
|
19
|
+
- - ! '>='
|
20
|
+
- !ruby/object:Gem::Version
|
21
|
+
version: '0'
|
22
|
+
type: :development
|
23
|
+
prerelease: false
|
24
|
+
version_requirements: *23546980
|
25
|
+
- !ruby/object:Gem::Dependency
|
26
|
+
name: detroit
|
27
|
+
requirement: &23545320 !ruby/object:Gem::Requirement
|
28
|
+
none: false
|
29
|
+
requirements:
|
30
|
+
- - ! '>='
|
31
|
+
- !ruby/object:Gem::Version
|
32
|
+
version: '0'
|
33
|
+
type: :development
|
34
|
+
prerelease: false
|
35
|
+
version_requirements: *23545320
|
36
|
+
description: ! 'TomParse is a Ruby TomDoc parser. It contains no other functionality
|
37
|
+
|
38
|
+
than the ability to take a comment and parse it in accordance to the
|
39
|
+
|
40
|
+
TomDoc standard.'
|
41
|
+
email:
|
42
|
+
- transfire@gmail.com
|
43
|
+
executables: []
|
44
|
+
extensions: []
|
45
|
+
extra_rdoc_files:
|
46
|
+
- LICENSE.txt
|
47
|
+
- HISTORY.md
|
48
|
+
- README.md
|
49
|
+
files:
|
50
|
+
- .ruby
|
51
|
+
- lib/tomparse.rb
|
52
|
+
- lib/tomparse.yml
|
53
|
+
- test/helper.rb
|
54
|
+
- test/test_tomdoc.rb
|
55
|
+
- LICENSE.txt
|
56
|
+
- HISTORY.md
|
57
|
+
- README.md
|
58
|
+
homepage: http://rubyworks.github.com/tomparse
|
59
|
+
licenses:
|
60
|
+
- BSD-2-Clause
|
61
|
+
post_install_message:
|
62
|
+
rdoc_options: []
|
63
|
+
require_paths:
|
64
|
+
- lib
|
65
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
66
|
+
none: false
|
67
|
+
requirements:
|
68
|
+
- - ! '>='
|
69
|
+
- !ruby/object:Gem::Version
|
70
|
+
version: '0'
|
71
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
72
|
+
none: false
|
73
|
+
requirements:
|
74
|
+
- - ! '>='
|
75
|
+
- !ruby/object:Gem::Version
|
76
|
+
version: '0'
|
77
|
+
requirements: []
|
78
|
+
rubyforge_project:
|
79
|
+
rubygems_version: 1.8.11
|
80
|
+
signing_key:
|
81
|
+
specification_version: 3
|
82
|
+
summary: TomDoc parser for Ruby
|
83
|
+
test_files: []
|