dnote 0.9 → 1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. data/HISTORY +13 -0
  2. data/README.rdoc +62 -17
  3. data/lib/dnote.rb +3 -1
  4. data/lib/dnote/notes.rb +57 -31
  5. data/meta/version +1 -1
  6. metadata +2 -2
data/HISTORY CHANGED
@@ -1,5 +1,17 @@
1
1
  = RELEASE HISTORY
2
2
 
3
+ == 1.0 / 2009-10-25
4
+
5
+ This relase adds support for arbitrary note labels.
6
+ Any all-caps word followed by a colon will be
7
+ picked-up. Common labels like TODO and FIXME are
8
+ recognized without the trailing ':'.
9
+
10
+ Changes:
11
+
12
+ * Added support for arbitrary labels.
13
+
14
+
3
15
  == 0.9 / 2009-10-10
4
16
 
5
17
  This release adds a syckle plugin and improves output.
@@ -11,6 +23,7 @@ Changes:
11
23
  * If output not specified, sends rdoc to stdout.
12
24
  * If no paths specified, will scan '**/*.rb'
13
25
 
26
+
14
27
  == 0.8 / 2009-10-09
15
28
 
16
29
  This is the initial release of DNote. DNote is a spin-off
@@ -13,38 +13,83 @@ output formats for them.
13
13
 
14
14
  == SYNOPSIS
15
15
 
16
- Developer notes it the source code must be formatted as follows:
16
+ === Note Structure
17
+
18
+ D'Note scans for the common noting pattern used by develepors of many laguages of an all-caps label
19
+ followed bt a colon. To be more specific, for D'Note to recogznie a note, it needs ot follow this
20
+ simple set of rules:
21
+
22
+ 1) Notes start with an all-caps label puctuated with a colon, followed by the note's text.
17
23
 
18
24
  # LABEL: description ...
19
25
 
20
- Any description that takes up more than one line must remain flush to the left
21
- margin (if the first line is flush to the left margin too) b/c RDoc will mistake
22
- of formatting the remaining lines as a +pre+ block it if is not. So...
26
+ 2) Specially designated notes can omit the colon. By default these are +TODO+,
27
+ +FIXME+ and +OPTIMIZE+.
23
28
 
24
- # LABEL: ... description ...
25
- # continue ...
29
+ # TODO description ...
26
30
 
27
- All consecutive notes must be separated by a blank lines.
31
+ 3) Any note that requires more than one line must remain flush to the left
32
+ margin (the margin is set by the first line). This is done because RDoc will mistake
33
+ the note for a <tt>&lt;pre&gt;</tt> block if it is indented.
28
34
 
29
35
  # LABEL: description ...
30
- #
31
- # LABEL: description ...
32
-
33
- Without the blank line the second note will be taken to be part of the first.
36
+ # continue ...
34
37
 
35
- Alternately the whole note can be made a +pre+ block by indention. Then the
36
- layout if freed-form.
38
+ 4) An alternative to the limitation of the last rule is to indent the whole note, making it
39
+ a <tt>&lt;pre&gt;</tt> block. Then the text layout is free-form.
37
40
 
38
41
  # This is a description of something...
39
42
  #
40
43
  # LABEL: description ...
41
- # continued ...
44
+ # continue ...
45
+
46
+ That's all there is to it, if I can convince the developers of RDoc to add recognize labels,
47
+ we may eventually be able to relax the flush rule, which would be very nice.
48
+
49
+
50
+ === Generating Notes
51
+
52
+ As you can see the commandline interface is quite straight-forward.
53
+
54
+ Usage: dnote [OPTIONS] path1 [path2 ...]
55
+
56
+ OUTPUT FORMAT: (choose one)
57
+ --rdoc RDoc comment format
58
+ --markdown Markdown wiki format
59
+ --xml XML markup format
60
+ --html HTML markup format
61
+ --yaml YAML serialization format
62
+ --json JSON serialization format
63
+
64
+ OTHER OPTIONS:
65
+ --label labels to collect
66
+ -t, --title [TITLE] title to use in headers
67
+
68
+ STANDARD OPTIONS:
69
+ -v, --verbose extra verbose output
70
+ --debug debug mode
71
+ -h, --help show this help information
72
+
73
+ The default path is <tt>**/*.rb</tt> and the default format <tt>--rdoc</tt>.
74
+ Here is an example of DNote's current notes in RDoc format:
75
+
76
+ = Development Notes
77
+
78
+ == TODO
79
+
80
+ === file://lib/dnote/notes.rb
81
+
82
+ * TODO: Add ability to read header notes. They oftern
83
+ have a outline format, rather then the single line. (19)
84
+ * TODO: Need good CSS file. (22)
85
+ * TODO: Need XSL? (24)
86
+
87
+ === file://plug/syckle/services/dnote.rb
42
88
 
43
- With properly formatted notes, we then use the +dnote+ command line tool.
89
+ * TODO: Should this service be part of the +site+ cycle? (18)
44
90
 
45
- $ dnote
91
+ (4 TODOs)
46
92
 
47
- And lo! Pretty output. See <tt>dnote --help</tt> for more options.
48
93
 
49
94
 
50
95
  == INSTALLATION
@@ -1,10 +1,12 @@
1
1
  require 'dnote/notes'
2
2
 
3
3
  module DNote
4
- VERSION = "0.9" #:till: VERSION = "<%= version %>"
4
+ VERSION = "1.0" #:till: VERSION = "<%= version %>"
5
5
 
6
6
  def self.new(*args)
7
7
  Notes.new(*args)
8
8
  end
9
9
  end
10
10
 
11
+ # TEST: This is a test of arbitraty note labels.
12
+
@@ -125,42 +125,31 @@ module DNote
125
125
 
126
126
  # Gather and count notes. This returns two elements,
127
127
  # a hash in the form of label=>notes and a counts hash.
128
- def parse
129
- files = self.paths.map do |path|
130
- if File.directory?(path)
131
- Dir.glob(File.join(path, '**/*'))
132
- else
133
- Dir.glob(path)
134
- end
135
- end.flatten.uniq
136
128
 
137
- #
129
+ def parse
138
130
  records, counts = [], Hash.new(0)
139
-
140
- # iterate through files extracting notes
141
131
  files.each do |fname|
142
132
  next unless File.file?(fname)
143
- #next unless fname =~ /\.rb$/ # TODO should this be done?
133
+ #next unless fname =~ /\.rb$/ # TODO: should this be done?
144
134
  File.open(fname) do |f|
145
- line_no, save, text = 0, nil, nil
135
+ lineno, save, text = 0, nil, nil
146
136
  while line = f.gets
147
- line_no += 1
148
- labels.each do |label|
149
- if line =~ /^\s*#\s*#{Regexp.escape(label)}[:]?\s*(.*?)$/
150
- file = fname
151
- text = ''
152
- save = {'label'=>label,'file'=>file,'line'=>line_no,'note'=>text}
153
- records << save
154
- counts[label] += 1
155
- end
156
- end
157
- if text
158
- if line =~ /^\s*[#]{0,1}\s*$/ or line !~ /^\s*#/ or line =~ /^\s*#[+][+]/
159
- text.strip!
160
- text = nil
161
- #records << save
162
- else
163
- text << line.gsub(/^\s*#\s*/,'')
137
+ lineno += 1
138
+ save = match_common(line, lineno, fname) || match_arbitrary(line, lineno, fname)
139
+ if save
140
+ #file = fname
141
+ text = save['note']
142
+ #save = {'label'=>label,'file'=>file,'line'=>line_no,'note'=>text}
143
+ records << save
144
+ counts[save['label']] += 1
145
+ else
146
+ if text
147
+ if line =~ /^\s*[#]{0,1}\s*$/ or line !~ /^\s*#/ or line =~ /^\s*#[+][+]/
148
+ text.strip!
149
+ text = nil
150
+ else
151
+ text << ' ' << line.gsub(/^\s*#\s*/,'')
152
+ end
164
153
  end
165
154
  end
166
155
  end
@@ -172,6 +161,43 @@ module DNote
172
161
  @notes, @counts = notes, counts
173
162
  end
174
163
 
164
+ #
165
+ def files
166
+ @files ||= (
167
+ self.paths.map do |path|
168
+ if File.directory?(path)
169
+ Dir.glob(File.join(path, '**/*'))
170
+ else
171
+ Dir.glob(path)
172
+ end
173
+ end.flatten.uniq
174
+ )
175
+ end
176
+
177
+ #
178
+ def match_common(line, lineno, file)
179
+ rec = nil
180
+ labels.each do |label|
181
+ if md = /\#\s*#{Regexp.escape(label)}[:]?\s*(.*?)$/.match(line)
182
+ text = md[1]
183
+ rec = {'label'=>label,'file'=>file,'line'=>lineno,'note'=>text}
184
+ end
185
+ end
186
+ return rec
187
+ end
188
+
189
+ #
190
+ def match_arbitrary(line, lineno, file)
191
+ rec = nil
192
+ labels.each do |label|
193
+ if md = /\#\s*([A-Z]+)[:]\s*(.*?)$/.match(line)
194
+ label, text = md[1], md[2]
195
+ rec = {'label'=>label,'file'=>file,'line'=>lineno,'note'=>text}
196
+ end
197
+ end
198
+ return rec
199
+ end
200
+
175
201
  # Organize records in heirarchical form.
176
202
  #
177
203
  def organize(records)
@@ -302,7 +328,7 @@ module DNote
302
328
 
303
329
  #
304
330
  def to_json
305
- require 'json'
331
+ require 'json' # TODO: fallback to json_pure
306
332
  notes.to_json
307
333
  end
308
334
 
@@ -1 +1 @@
1
- 0.9
1
+ 1.0
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: dnote
3
3
  version: !ruby/object:Gem::Version
4
- version: "0.9"
4
+ version: "1.0"
5
5
  platform: ruby
6
6
  authors: []
7
7
 
@@ -9,7 +9,7 @@ autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
11
 
12
- date: 2009-10-24 00:00:00 -04:00
12
+ date: 2009-10-25 00:00:00 -04:00
13
13
  default_executable:
14
14
  dependencies: []
15
15