mvz-dnote 1.7.1

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 (55) hide show
  1. checksums.yaml +7 -0
  2. data/COPYING.rdoc +31 -0
  3. data/HISTORY.rdoc +171 -0
  4. data/README.rdoc +113 -0
  5. data/bin/dnote +4 -0
  6. data/lib/dnote.rb +4 -0
  7. data/lib/dnote.yml +1 -0
  8. data/lib/dnote/core_ext.rb +92 -0
  9. data/lib/dnote/format.rb +173 -0
  10. data/lib/dnote/note.rb +150 -0
  11. data/lib/dnote/notes.rb +320 -0
  12. data/lib/dnote/rake/dnotetask.rb +116 -0
  13. data/lib/dnote/session.rb +269 -0
  14. data/lib/dnote/templates/html.erb +49 -0
  15. data/lib/dnote/templates/html/file.erb +48 -0
  16. data/lib/dnote/templates/html/label.erb +49 -0
  17. data/lib/dnote/templates/html/list.erb +42 -0
  18. data/lib/dnote/templates/json.erb +8 -0
  19. data/lib/dnote/templates/json/file.erb +8 -0
  20. data/lib/dnote/templates/json/label.erb +8 -0
  21. data/lib/dnote/templates/json/list.erb +8 -0
  22. data/lib/dnote/templates/md.erb +19 -0
  23. data/lib/dnote/templates/md/file.erb +14 -0
  24. data/lib/dnote/templates/md/label.erb +19 -0
  25. data/lib/dnote/templates/md/list.erb +10 -0
  26. data/lib/dnote/templates/rdoc.erb +12 -0
  27. data/lib/dnote/templates/rdoc/file.erb +10 -0
  28. data/lib/dnote/templates/rdoc/label.erb +12 -0
  29. data/lib/dnote/templates/rdoc/list.erb +7 -0
  30. data/lib/dnote/templates/soap.erb +4 -0
  31. data/lib/dnote/templates/soap/file.erb +4 -0
  32. data/lib/dnote/templates/soap/label.erb +4 -0
  33. data/lib/dnote/templates/soap/list.erb +4 -0
  34. data/lib/dnote/templates/text.erb +12 -0
  35. data/lib/dnote/templates/text/file.erb +11 -0
  36. data/lib/dnote/templates/text/label.erb +11 -0
  37. data/lib/dnote/templates/text/list.erb +8 -0
  38. data/lib/dnote/templates/xml.erb +23 -0
  39. data/lib/dnote/templates/xml/file.erb +23 -0
  40. data/lib/dnote/templates/xml/label.erb +23 -0
  41. data/lib/dnote/templates/xml/list.erb +14 -0
  42. data/lib/dnote/templates/xoxo.erb +4 -0
  43. data/lib/dnote/templates/xoxo/file.erb +4 -0
  44. data/lib/dnote/templates/xoxo/label.erb +4 -0
  45. data/lib/dnote/templates/xoxo/list.erb +6 -0
  46. data/lib/dnote/templates/yaml.erb +1 -0
  47. data/lib/dnote/templates/yaml/file.erb +1 -0
  48. data/lib/dnote/templates/yaml/label.erb +1 -0
  49. data/lib/dnote/templates/yaml/list.erb +1 -0
  50. data/lib/dnote/version.rb +17 -0
  51. data/test/notes_case.rb +59 -0
  52. data/try/sample.bas +7 -0
  53. data/try/sample.js +11 -0
  54. data/try/sample.rb +11 -0
  55. metadata +131 -0
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: 98fb559fd41018e820045b6bc49f6d8bba90b0fb
4
+ data.tar.gz: 3d6ebc561fd714f6ff33ecb45f9e55396b8fb6c7
5
+ SHA512:
6
+ metadata.gz: 571aec135e69a01abab0658f214f9ac0baa3913081598a5026e73f6660efc31f80c14b22b7291521f8e6a1c7be5fb3c88a862f4c86ac98e87351b9497c6b5975
7
+ data.tar.gz: 413450876f72af24fb04d3a81e62a86f28d459ac504931a5d8856eabe77d7638ad0f0e795b244a98ffc73460521fc5d45003db1aa718388ea07e118ab8f3a45a
@@ -0,0 +1,31 @@
1
+ = COPYRIGHT NOTICES
2
+
3
+ == DNote
4
+
5
+ Copyright:: (c) 2006 Thomas Sawyer, Rubyworks
6
+ License:: BSD-2-Clause
7
+ Website:: http://rubyworks.github.com/tapout
8
+
9
+ Copyright 2006 Thomas Sawyer, Rubyworks. All rights reserved.
10
+
11
+ Redistribution and use in source and binary forms, with or without
12
+ modification, are permitted provided that the following conditions are met:
13
+
14
+ 1. Redistributions of source code must retain the above copyright notice,
15
+ this list of conditions and the following disclaimer.
16
+
17
+ 2. Redistributions in binary form must reproduce the above copyright
18
+ notice, this list of conditions and the following disclaimer in the
19
+ documentation and/or other materials provided with the distribution.
20
+
21
+ THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
22
+ INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
23
+ AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
24
+ COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25
+ INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26
+ NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
28
+ OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
29
+ NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30
+ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31
+
@@ -0,0 +1,171 @@
1
+ = RELEASE HISTORY
2
+
3
+
4
+ == 1.7.0 / 2011-10-25
5
+
6
+ This release finishes adding code context support to all formats. Use the `-c`
7
+ option to set the number of lines to include. Note also that the rake task has
8
+ been moved to `dnote/rake/dnotetask`.
9
+
10
+ Changes:
11
+
12
+ * Support code contexts in all formats.
13
+ * Rake task moved to `dnote/rake/dnotetask`.
14
+
15
+
16
+ == 1.6.1 / 2011-05-18
17
+
18
+ Last release reused the `-c` option for context lines. This clobbered
19
+ the shortcut option for `--custom`. To fix, this release capitalizes
20
+ the custom shortcut to `-C`.
21
+
22
+ Changes:
23
+
24
+ * Capitalize custom shortcut option (-c becomes -C).
25
+
26
+
27
+ == 1.6.0 / 2011-05-17
28
+
29
+ This release adds code conext output. Select the number of
30
+ context lines to display with the `-c` option. Currently
31
+ only the HTML, YAML and JSON formats support context.
32
+
33
+ This release also fixes the false note match that can arise when
34
+ a class or module name with double-colons starts a comment line.
35
+ We have changed the regex to ALWAYS REQUIRE a space after the
36
+ label colon. Please make a note of it!
37
+
38
+ Changes:
39
+
40
+ * Add code context count option and output.
41
+ * Regex changed to REQUIRE space after label colon.
42
+
43
+
44
+ == 1.5.0 / 2010-11-27
45
+
46
+ This release adds a `--url` option for defining a URL template
47
+ string used in certain HTML/XML formats. In addition a parsing
48
+ bug was corrected that limited some notes to one line.
49
+
50
+ Changes:
51
+
52
+ * Add support for configurable URLs.
53
+ * Fix multi-line note parsing bug.
54
+
55
+
56
+ == 1.4.0 / 2010-06-26
57
+
58
+ This release adds auto-determination of marker based on file
59
+ extension. This means DNote can now scan multiple file types
60
+ in a single pass. The supported types are fairly small at this
61
+ point, but cover the command cases and will expand in the future.
62
+ The fallback marker is '#'. You can still force a particular
63
+ marker using the --marker option.
64
+
65
+ Changes:
66
+
67
+ * Add support for automatic markers.
68
+
69
+
70
+ == 1.3.1 / 2010-06-11
71
+
72
+ This release fixes a simple bug. Some version of Ruby do not have
73
+ the Enumerable#group_by method. This release provides it if it is
74
+ missing.
75
+
76
+ Changes:
77
+
78
+ * Bug fix, provide #group_by when it is not present.
79
+
80
+
81
+ == 1.3.0 / 2010-06-04
82
+
83
+ This release adds support for alternate comment markers. Simply
84
+ supply the marker with the -m option.
85
+
86
+ Changes:
87
+
88
+ * Add support for languages other than Ruby.
89
+
90
+
91
+ == 1.2.0 / 2010-02-18
92
+
93
+ By request this release adds additional formats, allowing notes to be
94
+ sorted by filename as well a label. In addition, paths can now be
95
+ excluded from the search. To implement these changes it was necessary
96
+ to makes some significant under-the-hood adjustments, and this required
97
+ making some adjustments to the design of the templates and the
98
+ command-line interface.
99
+
100
+ If are using any of your own custom templates you will have to make
101
+ adjustments accordingly --which basically entails exchanging +notes.each+
102
+ for +notes.by_label_file.each+. Also, notice that the serialization formats
103
+ have changed accordingly to match the improved underlying model.
104
+
105
+ On the command-line, the format type itself is no longer used as the
106
+ option name, e.g. "--yaml", but instead use "-f", e.g. "-f yaml". This
107
+ opens DNote up to many more templates. Use "-T" to get a list of all
108
+ template format available.
109
+
110
+ Changes:
111
+
112
+ * Improve underlying model by adding a Note class.
113
+ * Add --exclude and --ignore options.
114
+ * Add new formats and rename "gnu" formats to "text".
115
+ * Use --format/-f to designate formats.
116
+ * Renamed --template/-t option to --custom/-c.
117
+ * Add --templates/-T to list all format templates.
118
+
119
+
120
+ == 1.1.0 / 2010-02-06
121
+
122
+ This relase primarily adjusts the way output it rendered
123
+ underthehood. Serialization formats are rendered as
124
+ before but markup formats now use Erb. In the process
125
+ two new serialization formats have been added: soap and xoxo.
126
+
127
+ Also, this release renames the lib/plugin directory to
128
+ lib/plugins (plural) per the new convention of the latest
129
+ Plugin gem. This only matters to Syckle users.
130
+
131
+ Changes:
132
+
133
+ * Add Soap and XOXO formats.
134
+ * Add actual --output option.
135
+ * Move lib/plugin to lib/plugins.
136
+
137
+
138
+ == 1.0.0 / 2009-10-25
139
+
140
+ This relase adds support for arbitrary note labels.
141
+ Any all-caps word followed by a colon will be
142
+ picked-up. Common labels like TODO and FIXME are
143
+ recognized without the trailing ':'.
144
+
145
+ Changes:
146
+
147
+ * Added support for arbitrary labels.
148
+
149
+
150
+ == 0.9.0 / 2009-10-10
151
+
152
+ This release adds a syckle plugin and improves output.
153
+
154
+ Changes:
155
+
156
+ * Add syckle plugin, based on old Notes plugin.
157
+ * Improved HTML output (</div> tag should have been </ol>).
158
+ * If output not specified, sends rdoc to stdout.
159
+ * If no paths specified, will scan '**/*.rb'
160
+
161
+
162
+ == 0.8.0 / 2009-10-09
163
+
164
+ This is the initial release of DNote. DNote is a spin-off
165
+ of a Syckle (formerlly Reap) plugin which scans source
166
+ code and compiles a list of developer notes.
167
+
168
+ Changes:
169
+
170
+ * Happy Birthday!
171
+
@@ -0,0 +1,113 @@
1
+ = DNote
2
+
3
+ * {Homepage}[http://rubyworks.github.com/dnote]
4
+ * {Mailing List}[http://googlegroups.com/group/rubyworks-mailinglist]
5
+ * {Source Code}[http://github.com/rubyworks/dnote]
6
+
7
+
8
+ == DESCRIPTION
9
+
10
+ Extract development notes from source code and generate some nice
11
+ output formats for them.
12
+
13
+
14
+ == SYNOPSIS
15
+
16
+ === Note Structure
17
+
18
+ DNote scans for the common note patterns used by developers of many languages in the form of an
19
+ all-caps labels followed by a colon. To be more specific, for DNote to recognize a note,
20
+ it needs to follow this simple set of rules:
21
+
22
+ 1) Notes start with an all-caps label punctuated with a colon, followed by the note's text.
23
+
24
+ # LABEL: description ...
25
+
26
+ 2) Any note that requires more than one line must remain flush to the left
27
+ margin (the margin is set by the first line). This is done because RDoc will mistake
28
+ the note for a <code>pre</code> block if it is indented.
29
+
30
+ # LABEL: description ...
31
+ # continue ...
32
+
33
+ 3) An alternative to the previous limitation is to indent the whole note, making it
34
+ a <tt>&lt;pre&gt;</tt> block when rendered by RDoc. Then the text layout is free-form.
35
+
36
+ # This is a description of something...
37
+ #
38
+ # LABEL: description ...
39
+ # continue ...
40
+
41
+ That's all there is to it, if I can convince the developers of RDoc to recognize labels,
42
+ we may eventually be able to relax the flush rule too, which would be very nice.
43
+
44
+ There is also a command-line option, <code>--no-colon</code>, which deactives the need for
45
+ a colon after the note label. However this often produces false positives, so it's use is
46
+ discouraged.
47
+
48
+
49
+ === Generating Notes
50
+
51
+ As you can see the commandline interface is pretty straight-forward.
52
+
53
+ USAGE:
54
+
55
+ dnote [OPTIONS] path1 [path2 ...]
56
+
57
+ OUTPUT FORMAT: (choose one)
58
+ -f, --format NAME select a format [text]
59
+ -c, --custom FILE use a custom ERB template
60
+ --file shortcut for text/file format
61
+ --list shortcut for text/list format
62
+
63
+ OTHER OPTIONS:
64
+ -l, --label LABEL labels to collect
65
+ --[no-]colon match labels with/without colon suffix
66
+ -m, --marker MARK alternative remark marker
67
+ -u --url TEMPLATE url template for line entries (for HTML)
68
+ -x, --exclude PATH exclude file or directory
69
+ -i, --ignore NAME ignore based on any part of the pathname
70
+ -t, --title TITLE title to use in header
71
+ -o, --output PATH name of file or directory
72
+ -n, --dryrun do not actually write to disk
73
+ --debug debug mode
74
+
75
+ COMMAND OPTIONS:
76
+ -T, --templates list available format templates
77
+ -h, --help show this help information
78
+
79
+ The default path is <tt>**/*.rb</tt> and the default format is <tt>-f rdoc</tt>.
80
+ Here is an example of DNote's current notes in RDoc format:
81
+
82
+ = Development Notes
83
+
84
+ == TODO
85
+
86
+ === file://lib/dnote/notes.rb
87
+
88
+ * TODO: Add ability to read header notes. They often
89
+ have a outline format, rather then the single line. (19)
90
+ * TODO: Need good CSS file. (22)
91
+ * TODO: Need XSL? (24)
92
+
93
+ === file://plug/syckle/services/dnote.rb
94
+
95
+ * TODO: Should this service be part of the +site+ cycle? (18)
96
+
97
+ (4 TODOs)
98
+
99
+
100
+ == INSTALLATION
101
+
102
+ The usual RubyGem's command will do the trick.
103
+
104
+ $ sudo gem install dnote
105
+
106
+
107
+ == COPYRIGHT
108
+
109
+ Copyright (c) 2006 Thomas Sawyer, Rubyworks
110
+
111
+ DNote is distributable in accordance with the terms of the *FreeBSD* license.
112
+
113
+ See COPYING.rdoc for details.
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env ruby
2
+ require "dnote"
3
+ DNote::Session.main(*ARGV)
4
+
@@ -0,0 +1,4 @@
1
+ require 'dnote/version'
2
+ require 'dnote/session'
3
+
4
+ # TEST: This is a test of an arbitrary label.
@@ -0,0 +1 @@
1
+ lib/../.ruby
@@ -0,0 +1,92 @@
1
+ module Enumerable
2
+
3
+ # Taken from Ruby Facets.
4
+ def group_by #:yield:
5
+ #h = k = e = nil
6
+ r = Hash.new
7
+ each{ |e| (r[yield(e)] ||= []) << e }
8
+ r
9
+ end unless method_defined?(:group_by)
10
+
11
+ end
12
+
13
+ module DNote
14
+
15
+ # Extensions for String class.
16
+ # These methods are taken directly from Ruby Facets.
17
+ #
18
+ module String
19
+
20
+ # Provides a margin controlled string.
21
+ #
22
+ # x = %Q{
23
+ # | This
24
+ # | is
25
+ # | margin controlled!
26
+ # }.margin
27
+ #
28
+ #
29
+ # NOTE: This may still need a bit of tweaking.
30
+ #
31
+ # CREDIT: Trans
32
+
33
+ def margin(n=0)
34
+ #d = /\A.*\n\s*(.)/.match( self )[1]
35
+ #d = /\A\s*(.)/.match( self)[1] unless d
36
+ d = ((/\A.*\n\s*(.)/.match(self)) ||
37
+ (/\A\s*(.)/.match(self)))[1]
38
+ return '' unless d
39
+ if n == 0
40
+ gsub(/\n\s*\Z/,'').gsub(/^\s*[#{d}]/, '')
41
+ else
42
+ gsub(/\n\s*\Z/,'').gsub(/^\s*[#{d}]/, ' ' * n)
43
+ end
44
+ end
45
+
46
+ # Preserves relative tabbing.
47
+ # The first non-empty line ends up with n spaces before nonspace.
48
+ #
49
+ # CREDIT: Gavin Sinclair
50
+
51
+ def tabto(n)
52
+ if self =~ /^( *)\S/
53
+ indent(n - $1.length)
54
+ else
55
+ self
56
+ end
57
+ end
58
+
59
+ # Indent left or right by n spaces.
60
+ # (This used to be called #tab and aliased as #indent.)
61
+ #
62
+ # CREDIT: Gavin Sinclair
63
+ # CREDIT: Trans
64
+
65
+ def indent(n)
66
+ if n >= 0
67
+ gsub(/^/, ' ' * n)
68
+ else
69
+ gsub(/^ {0,#{-n}}/, "")
70
+ end
71
+ end
72
+
73
+ #
74
+ #
75
+ def tabset(n)
76
+ i = lines.map do |line|
77
+ line.strip.empty? ? nil : line.index(/\S/)
78
+ end
79
+ x = i.compact.min
80
+ t = n - x.to_i
81
+ t = 0 if t < 0
82
+ indent(t)
83
+ end
84
+
85
+ end
86
+
87
+ class ::String #:nodoc:
88
+ include DNote::String
89
+ end
90
+
91
+ end
92
+
@@ -0,0 +1,173 @@
1
+ module DNote
2
+
3
+ # = Notes Formatter
4
+ #
5
+ #--
6
+ # TODO: Need good CSS file.
7
+ #
8
+ # TODO: Need XSL?
9
+ #++
10
+ class Format
11
+
12
+ require 'fileutils'
13
+ require 'erb'
14
+ require 'rexml/text'
15
+ require 'dnote/core_ext'
16
+
17
+ #DEFAULT_OUTPUT_DIR = "log/dnote"
18
+
19
+ EXTENSIONS = { 'text'=>'txt', 'soap'=>'xml', 'xoxo'=>'xml' }
20
+
21
+ #
22
+ attr :notes
23
+
24
+ #
25
+ attr_accessor :format
26
+
27
+ #
28
+ attr_accessor :subtype
29
+
30
+ #
31
+ attr_accessor :output
32
+
33
+ #
34
+ attr_accessor :template
35
+
36
+ #
37
+ attr_accessor :title
38
+
39
+ #
40
+ attr_accessor :dryrun
41
+
42
+ #
43
+ def initialize(notes, options={})
44
+ @notes = notes
45
+ @format = 'text'
46
+ @subtype = 'label'
47
+ @title = "Developer's Notes"
48
+ @dryrun = false
49
+ options.each{ |k,v| __send__("#{k}=", v) if v }
50
+ yield(self) if block_given?
51
+ end
52
+
53
+ #
54
+ def render
55
+ if notes.empty?
56
+ $stderr << "No #{notes.labels.join(', ')} notes.\n"
57
+ else
58
+ case format
59
+ when 'custom'
60
+ render_custom
61
+ else
62
+ render_template
63
+ end
64
+ end
65
+ end
66
+
67
+ # C U S T O M
68
+
69
+ #
70
+ def render_custom
71
+ #raise ArgumentError unless File.exist?(template)
72
+ result = erb(template)
73
+ publish(result)
74
+ end
75
+
76
+ # T E M P L A T E
77
+
78
+ #
79
+ def render_template
80
+ template = File.join(File.dirname(__FILE__), 'templates', "#{format}.erb")
81
+ raise "No such format - #{format}" unless File.exist?(template)
82
+ result = erb(template)
83
+ publish(result)
84
+ end
85
+
86
+ private
87
+
88
+ #
89
+ def erb(file)
90
+ scope = ErbScope.new(:notes=>notes, :title=>title)
91
+ scope.render(file)
92
+ end
93
+
94
+ #
95
+ def publish(result, fname=nil)
96
+ if output
97
+ write(result, fname)
98
+ else
99
+ puts(result)
100
+ end
101
+ $stderr << "(" + notes.counts.map{|l,n| "#{n} #{l}s"}.join(', ') + ")\n"
102
+ end
103
+
104
+ #
105
+ def write(result, fname=nil)
106
+ if output.to_s[-1,1] == '/' || File.directory?(output)
107
+ fmt = format.split('/').first
108
+ ext = EXTENSIONS[fmt] || fmt
109
+ file = File.join(output, fname || "notes.#{ext}")
110
+ else
111
+ file = output
112
+ end
113
+ if dryrun?
114
+ puts "mkdir: #{File.dirname(file)}"
115
+ puts "write: #{file}"
116
+ else
117
+ dir = File.dirname(file)
118
+ fu.mkdir(dir) unless File.exist?(dir)
119
+ File.open(file, 'w'){ |f| f << result }
120
+ end
121
+ return file
122
+ end
123
+
124
+ #
125
+ def dryrun?
126
+ @dryrun
127
+ end
128
+
129
+ #
130
+ def debug?
131
+ $DEBUG
132
+ end
133
+
134
+ #
135
+ def fu
136
+ @fu ||= (
137
+ if dryrun? and debug?
138
+ FileUtils::DryRun
139
+ elsif dryrun?
140
+ FileUtils::Noop
141
+ elsif debug?
142
+ FileUtils::Verbose
143
+ else
144
+ FileUtils
145
+ end
146
+ )
147
+ end
148
+
149
+ #
150
+ class ErbScope
151
+ #
152
+ def initialize(data={})
153
+ @data = data
154
+ end
155
+ #
156
+ def render(file)
157
+ erb = ERB.new(File.read(file), nil, '<>')
158
+ erb.result(binding)
159
+ end
160
+ #
161
+ def h(string)
162
+ REXML::Text.normalize(string)
163
+ end
164
+ #
165
+ def method_missing(s, *a)
166
+ @data[s.to_sym]
167
+ end
168
+ end
169
+
170
+ end
171
+
172
+ end
173
+