aef-linebreak

= Linebreak

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

== DESCRIPTION:

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

== FEATURES/PROBLEMS:

• Completely written in Ruby
• Core class extensions are optionally loadable
• Tested and fully working on:
  • Ubuntu Linux 9.04 i386_64
    • Ruby 1.8.7p72
    • Ruby 1.9.1p129
    • JRuby 1.3.1 (22 tests fail, but it's fully usable)
  • Debian GNU/Linux 4.0 i386
    • Ruby 1.8.6
  • Windows XP i386
    • Ruby 1.8.6 (tests fail completely because of problems with popen4)
• The commandline tool does only work with a patched user-choices gem on Ruby 1.9 or higher. See the INSTALL section for further instructions.

== SYNOPSIS:

=== Commandline

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

linebreak encode --system windows unix.txt windows.txt

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

linebreak encode --system windows mac.txt > windows.txt

You can set the default with the environment variable LINEBREAK_SYSTEM.

export LINEBREAK_SYSTEM=mac

linebreak encode windows.txt mac.txt

If you do not specify an output file, output will be put to STDOUT. If you also do not specify an input file, input will be expected from STDIN.

You can also detect the linebreak systems contained in a file in the following way:

linebreak encodings windows_mac.txt

If you want to ensure that a file contains the exact encodings systems you specified, you can use the following command:

linebreak encodings --ensure unix,windows,mac unix.txt

The results will be outputted. In case of a file containing other linebreak encoding systems there will be an exit code of 1.

It is also possible to specify multiple input files or none to expect input from STDIN.

=== Library

First of all you have to load the Linebreak gem:

require 'aef/linebreak'

You can put strings or objects responding to to_s into the 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, while Commodore machines also use the :mac linebreak encoding.

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

Aef::Linebreak.encode(windows_string, :unix) #=> "Abcdef\nAbcdef\nAbcdef"

You can detect which decoding systems are used in a string:

mixed_unix_and_mac_string = "Abcdef\rAbcdef\nAbcdef"

Aef::Linebreak.encodings(mixed_unix_and_mac_string) #=> #<Set: {:unix, :mac}>

You can also easily ensure that a string contains exactly the linebreak encodings you expect it to contain:

mixed_windows_and_mac_string = "Abcdef\r\nAbcdef\rAbcdef"

Aef::Linebreak.encoding?(mixed_windows_and_mac_string, :windows) #=> false

Aef::Linebreak.encoding?(mixed_windows_and_mac_string, :windows, :mac) #=> true

Note that the expected linebreak systems could also be given as an array or a set.

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

require 'aef/linebreak/string_extension'

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

"Abcdef\r\nAbcdef\nAbcdef".linebreak_encodings #=> #<Set: {:unix, :windows}>

"Abcdef\nAbcdef\nAbcdef".linebreak_encoding?(:unix, :windows) #=> false

"Abcdef\nAbcdef\nAbcdef".linebreak_encoding?(:unix) #=> true

== REQUIREMENTS:

• rubygems

=== Additional for commandline

• user-choices

=== Additional for automated testing

• hoe
• rspec
• popen4

== INSTALL:

On *nix systems you may need to prefix the command with sudo to get root privileges.

If you want to use the commandline tool you need to install the following gem manually:

gem install user-choices

On Ruby 1.9 or higher you need to install an inofficially updated version from github instead:

gem install qoobaa-user-choices --source http://gems.github.com

You could also patch the normal user-choices gem yourself with a patch written by me. You can find it here: https://rubyforge.org/tracker/index.php?func=detail&aid=24307&group_id=4192&atid=16176

=== 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 linebreak --ignore-dependencies -P HighSecurity

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

=== Normal (insecure)

gem install linebreak

=== Github (also insecure)

Alternatively you could install linebreak from github which may be a bit more up to date. The version may however not be as stable as the normal gem and there is no way to install the gem securely. Therefore this is not recommended.

gem install aef-linebreak --source http://gems.github.com

=== Automated testing

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

gem which aef/linebreak

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

rake spec

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/linebreak.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 Linebreak.

Linebreak 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/.