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:
and documentation is also available at
Please feel free to send me feedback at this e-mail or the e-mail
below. I hope some of you find this useful.
Wraps comments in ruby files.
Copyright © 2006 Christopher Alfeld
Permission is hereby granted, free of charge, to any person obtaining a
of this software and associated documentation files (the “Software”), to
deal in the Software without restriction, including without limitation
rights to use, copy, modify, merge, publish, distribute, sublicense,
sell copies of the Software, and to permit persons to whom the Software
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
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
IN THE SOFTWARE.
Christopher Alfeld (email@example.com)
Please feel free to e-mail bugs, questions, comments, etc.
RubyWrap is a word wrapper utility designed for ruby scripts. It
however work for any programming language which uses an initial prefix
comments (see --prefix). RubyWrap correctly handles indented comments,
indented text within comments, header comments, and many forms of lists.
will also pass through code without change and detabify.
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
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
# it goes over over the page width.
label This is a list. It contains a label and some text. If the
is indented past the label and the final space lines up then
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
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.
RubyWrap uses a very simple algorithm for identifying headers: it looks
short lines. Any line below a certain threshold is not-wrapped. By
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
for a label and then a second line indented past the label. This means
single line list items do not wrap, the second line is required.
Blocks of text indented after the # are wrapped maintaining their
== RDoc Style (Default)
In RDOc style RubyWrap looks for lines that appear to be RDoc list
These lines are then properly wrapped with later lines indented properly
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
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
"# ". Note the trailing space. You will generally want a trailing
for any prefix. If you prefer to indent your comments more than a
space past the # then change the prefix appropriately.
- Doesn’t handle multilevel RDoc lists correctly. This is a balance
recognizing verbatim blocks and list items. A nice solution would be
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
distinguishes comments by some prefix. Languages that use "# " should
well out of the box.
–prefix, -p Use as the comment prefix.
–shortthreshold -s Lines of length <= n are single line
–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