After getting frustrated with existing solutions I threw together a
script to wrap comments in my ruby code. It understands headers,
basic lists, some rdoc formatting, indentation both before and after
the #, passes code through without modification and has some options
for customization. Full documentations follows.
It can be downloaded from my website at:
http://www.math.wisc.edu/~alfeld/code/rubywrap/rubywrap.rb
and documentation is also available at
http://www.math.wisc.edu/~alfeld/code/rubywrap/
Please feel free to send me feedback at this e-mail or the e-mail
below. I hope some of you find this useful.
File: rubywrap.rb
Wraps comments in ruby files.
== License
Copyright (c) 2006 Christopher Alfeld
Permission is hereby granted, free of charge, to any person obtaining a
copy
of this software and associated documentation files (the “Software”), to
deal in the Software without restriction, including without limitation
the
rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or
sell copies of the Software, and to permit persons to whom the Software
is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included
in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS
IN THE SOFTWARE.
== Author
Christopher Alfeld ([email protected])
Web: http://www.math.wisc.edu/~alfeld/code/rubywrap/
Please feel free to e-mail bugs, questions, comments, etc.
== Description
RubyWrap is a word wrapper utility designed for ruby scripts. It
should,
however work for any programming language which uses an initial prefix
for
comments (see --prefix). RubyWrap correctly handles indented comments,
indented text within comments, header comments, and many forms of lists.
It
will also pass through code without change and detabify.
See Example.
== Example
The following text will all wrap correctly.
This a header…
… it will not absorb this line.
This block of text will be left alone by default as it represents
a verbatim block of RDoc text. If the -n option is given then
RDoc-Style is off then it will be correctly wrapped, maintaining
it’s
indentation level. In any case it will not abosrb…
… this line because this line has a different indentation level.
# This comment will retain it's indentation and correctly wrap
when
# it goes over over the page width.
label This is a list. It contains a label and some text. If the
text
is indented past the label and the final space lines up then
it
is considered to be a single block and properly wrapped. Note
that this requires at least two lines to get right.
* This is an rdoc list element. It properly wraps even as a single
line
and does not require a second line to wrap correctly.
* Here are two rdoc list elements. Even though they are adjacent…
* … they will not wrap.
== Headers
RubyWrap uses a very simple algorithm for identifying headers: it looks
for
short lines. Any line below a certain threshold is not-wrapped. By
default
this threshold is 50, it can be changed with -s.
== Non Rdoc Style
When RDoc style is turned off (-n) RubyWrap identifies list items by
looking
for a label and then a second line indented past the label. This means
that
single line list items do not wrap, the second line is required.
Blocks of text indented after the # are wrapped maintaining their
indentation level.
== RDoc Style (Default)
In RDOc style RubyWrap looks for lines that appear to be RDoc list
items.
These lines are then properly wrapped with later lines indented properly
and
closely set list items do not wrap together.
Text indented after the # is considered to be verbatim and left alone.
RDoc tries to find a natural margin for comments. RubyWrap currently
does
not do this. If you use more than a single space after your # then you
should redefine the prefix with -p.
== Comment Prefix
The comment prefix can be changed with -p. By default the comment
prefix is
"# ". Note the trailing space. You will generally want a trailing
space
for any prefix. If you prefer to indent your comments more than a
single
space past the # then change the prefix appropriately.
== Limitations
- Doesn’t handle multilevel RDoc lists correctly. This is a balance
between
recognizing verbatim blocks and list items. A nice solution would be
to
treat it is a list item if it appeared to be a part of a list but that
would require context beyond the current block. - Doesn’t find the natural margin like RDoc does. This can easily be
overcome by -p but it would be a nice feature. Probably not too hard.
== Using with other languages
With appropriate use of -r and -p RubyWrap should work for any language
that
distinguishes comments by some prefix. Languages that use "# " should
work
well out of the box.
== Usage
rubywrap.rb []
Options:
–prefix, -p Use as the comment prefix.
–shortthreshold -s Lines of length <= n are single line
blocks.
–cols, -c How many columns to wrap to (default: 78)
–tabsize, -t How many spaces a tab is (default: 2)
–no-rdoc-style, -n Do not use RDoc conventions.
–retabify, -r Retabify output.
–help, -h Display this help.
–doc, -d Display full documentation.
Reads commented code from stdin and outputs wrapped commented code to
stdout.