aef-breakverter

= BreakVerter

• Project: https://rubyforge.org/projects/aef/
• RDoc: http://aef.rubyforge.org/breakverter/
• Github: http://github.com/aef/breakverter/

== DESCRIPTION:

BreakVerter is a Ruby library and commandline tool for conversion of text between linebreak encoding formats of unix, windows or mac.

== FEATURES/PROBLEMS:

• Usable as library and commandline tool
• Tested and fully working on:
  • Ubuntu Linux 8.10 i386_64 (Ruby 1.8.7 and 1.9.1p0)
  • Debian GNU/Linux 4.0 i386 (Ruby 1.8.6)
  • Windows XP i386 (Ruby 1.8.6)
• The commandline tool doesn't work with Ruby 1.9.x because the user-choices gem is not yet updated. A patch is available here: https://rubyforge.org/tracker/index.php?func=detail&aid=24307&group_id=4192&atid=16176

== SYNOPSIS:

=== Commandline

The default output encoding is unix. You can also choose mac and windows.

breakverter -o windows unix.txt windows.txt

If no target file is specified the output will be sent to STDOUT.

breakverter -o windows mac.txt > windows.txt

You can set the default with the environment variable BREAKVERTER_OUTPUT.

export BREAKVERTER_OUTPUT=mac

breakverter windows.txt mac.txt

=== Library

First of all you have to load the BreakVerter gem:

require 'breakverter'

You can put strings or objects responding to to_s into the convert method and optionally define a target linebreak encoding. The default encoding is :unix. You can also choose :mac and :windows. Notice that the :mac encoding is deprecated. Modern Apple machines also use :unix linebreak encoding.

windows_string = "Abcdef\r\nAbcdef\r\nAbcdef"

Aef::BreakVerter.convert(windows_string, :unix) #=> "Abcdef\nAbcdef\nAbcdef"

Alternatively you could include BreakVerter into the String class and use it in the following way:

class String include Aef::BreakVerter end

"Abcdef\nAbcdef\nAbcdef".linebreaks(:mac) #=> "Abcdef\rAbcdef\rAbcdef"

== REQUIREMENTS:

• rubygems

=== Additional for commandline

• user-choices

=== Additional for automated testing

• hoe
• rspec
• sys-uname

== INSTALL:

=== Normal

gem install breakverter

Additionally for the commandline tool:

gem install user-choices

=== High security (recommended)

There is a high security installation option available through rubygems. It is highly recommended over the normal installation, although it may be a bit less comfortable. To use the installation method, you will need my public key, which I use for cryptographic signatures on all my gems. You can find the public key and more detailed verification information in the aef-certificates section of my rubyforge project[https://rubyforge.org/frs/?group_id=7890&release_id=31749]

Add the key to your rubygems' trusted certificates by the following command:

gem cert --add aef.pem

Now you can install the gem while automatically verifying it's signature by the following command:

gem install breakverter --ignore-dependencies -P HighSecurity

Please notice that you will need other keys for dependent libraries, so you may have to install dependencies manually.

=== Automated testing

You can test this package through rspec on your system. First find the path where the gem was installed to:

gem which breakverter

Go into the root directory of the installed gem and run the following command to start the test runner:

rake spec

On Windows systems you have to run the following instead:

spec spec/**/*_spec.rb

If something goes wrong you should be noticed through failing examples.

== DEVELOPMENT:

This software is developed in the source code management system git hosted at github.com. You can download the most recent sourcecode through the following command:

git clone git://github.com/aef/breakverter.git

Help on making this software better is always very appreciated. If you want your changes to be included in the official release, please send me a patch through the project's tracker[https://rubyforge.org/tracker/?group_id=7890] at rubyforge.org. You can generate a patch-file by the following command:

git diff > patch.diff

Please make sure to write tests for your changes and notice that I can't promise to include your changes before reviewing them.

== LICENSE:

Copyright 2009 Alexander E. Fischer [e-mail]

This file is part of BreakVerter.

BreakVerter is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.