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 (firstname.lastname@example.org) 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>] Options: --prefix, -p <prefix> Use <prefix> as the comment prefix. --shortthreshold -s <n> Lines of length <= n are single line blocks. --cols, -c <n> How many columns to wrap to (default: 78) --tabsize, -t <n> 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.
on 2006-06-07 17:55