vail¶ ↑

vail converts text into audible Morse code. It currently uses the beep gem to interact with the PC speaker - so this means it is restricted to Linux distros that have the beep commandline utility available.

Installation¶ ↑

Due to vail’s reliance on beep, prior to installing the vail gem (or running the executable after cloning the repo), you will need the beep utility to be installed. AFAIK, this would restrict usage to Linux distros or related systems that have the beep utility available. After that, it is as simple as:

gem install vail

Customisable Settings¶ ↑

• duration - this can be set for a dot or a dash and the units are milliseconds

• pause - this is the time in milliseconds that vail will pause for before proceeding to the next set of instructions. A pause can be applied after the following elements:

  • a dot

  • a dash

  • a letter

  • a group of letters (separated by a space)

  • a line

  • a repetition

• frequency - of the sound generated, in Hz. It is applied to both dots and dashes

• repetitions - the number of times the provided string will be repeated

Usage - executable¶ ↑

The vail executable can be run to output Morse code from the commandline. Executing is as simple as:

vail

You will be prompted to enter the text and you should be rewarded with a sequence of beeps representing the dots and dashes for the various letters. To exit, simply hit Ctrl-C.

The following options can be passed when running the executable from the commandline:

• –export, -e : Export settings

• –import, -i : Import settings

• –text, -t : Load a file containing text to be converted to Morse

• –help, -h : Help

Export settings¶ ↑

The settings are dumped as YAML, and the output can be redirected to a file of your choice to server as a template for a custom settings file:

vail -e > current_settings.yaml

When the export parameter is provided, vail exits after outputting the settings.

Importing settings¶ ↑

Settings may be imported to override the default settings for the gem. An exported file may be used as a template for the import file. The settings imported will only be used for that execution of the binary and they will temporarily override the default settings. Currently, there is no user-friendly way to do this permanenently.

vail -i /path/to/custom/settings

Load text from file¶ ↑

Text can be loaded from a file and then converted into Morse. vail will treat each line as a seperate set of instructions. Therefore if repeptitions have been applied each line will be repeated for the given number of repetitions before proceeding on to the next line.

vail -t /path/to/input/file

Vail will wait the number of milliseconds provided for in the line pause before proceeding to the next line.

Usage - in Ruby code¶ ↑

To use the vail module in Ruby code is reasonably simple - just bear in mind that it is subject to the same restrictions as the executable (linux only, requires the beep utility):

require 'rubygems'
require 'vail'

Vail::Generator.new.to_morse("E")

Providing custom settings¶ ↑

The default settings can be overridden by passing a hash of custom settings - in the code below, only the repetitions element is optional. Excluding any of the other options will result in Vail puking horribly :)

@settings = { 
  "dot" => { "duration" => 100, "pause" => 200 },
  "dash" => { "duration" => 300, "pause" => 400 },
  "frequency" => 250,
  "letter" => { "pause" => 100 },
  "group" => { "pause" => 200 }, 
  "line" => { "pause" => 1200 }, 
  "repetitions" =>  { "pause" => 800, "repeat" => 2 }
}

Vail::Generator.new(@settings).to_morse("T")

If the value of @settings[“repeat”] is 0, vail will run through the text provided once. In addition, to allow backwards compatibility, vail will allow the repetitions element to be an integer. In this case, due to poor reasoning by the developer :), the number of repetitions is the total number of times it will run (repetitions => 1 means it will run once) - so, far better to go with the new settings format if you can.

Contributing to vail¶ ↑

• Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet

• Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it

• Fork the project

• Start a feature/bugfix branch

• Commit and push until you are happy with your contribution

• Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright¶ ↑

Copyright © 2011 Rory McKinley. See LICENSE.txt for further details.