__
      /\ \
 _____\ \ \___     ___    ___   __  __
/\ '__`\ \  _ `\  / __`\/' _ `\/\ \/\ \
\ \ \L\ \ \ \ \ \/\ \L\ \\ \/\ \ \ \_\ \
 \ \ ,__/\ \_\ \_\ \____/ \_\ \_\/`____ \
  \ \ \/  \/_/\/_/\/___/ \/_/\/_/`/___/> \
   \ \_\                            /\___/
    \/_/                            \/__/

phony.js is a pure JavaScript library for translating to/from the NATO phonetic alphabet that supports extensible characters.

Install

Install using the package manager for your desired environment(s):

# for node.js:
$ npm install node-phony
# OR; for the browser:
$ bower install phony

Usage

The API has been completely redesigned to simplify translating to and from the phonetic alphabet by simply passing a string to the to and from functions respectively.

Both of which also accept an optional options parameter which can currently contain the following (all of which are optional themselves):

| Option | Description | Default | | -------------- | ------------------------------------------------------------ | --------- | | alphabet | Name of the alphabet to be used to translate the message | "itu" | | cache | Whether to cache built alphabets when calling from or to | true | | letterSplitter | Sequence of characters to split letters | " " | | wordSplitter | Sequence of characters to split words | "space" |

It's important to note that the same options should be used in order for bidirectional translations to work. Some of these strings are used to build regular expressions (or can be regular expressions), so it's recommended to familiarized yourself with the usage of the options before change them, just so you know on which you need to escape any RegExp special characters.

Command Line

If you installed node-phony globally using npm you can use this libraries built-in command line interface:

Usage: phony [options] [command]


Commands:

  from <message>  translates the message to the phonetic alphabet
  to <message>    translates the message from the phonetic alphabet

Options:

  -h, --help                     output usage information
  -V, --version                  output the version number
  -a, --alphabet [name]          name of the alphabet to be used
  -l, --letter-splitter [value]  sequence of characters to split letters
  -w, --word-splitter [value]    sequence of characters to split words

to(message[, options])

Translates the message parameter to the phonetic alphabet.

phony.to('SOS');
//=> "Sierra Oscar Sierra"

from(message[, options])

Translates the message parameter from the phonetic alphabet.

phony.from('Sierra Oscar Sierra');
//=> "SOS"

Customization

alphabets

Alphabets are key to translating messages to and from the phonetic alphabet as they contain characters use to find and replace phonetic representations in the message. Alphabets can declare fallback alphabets so that, if it does not contain a matching character or phonetic representation, it will attempt to look it up from the fallback alphabet, and so on. For this reason, if you plan on creating a custom alphabet, it's recommended that you always specify a fallback alphabet.

Here's a list of the built in alphabets:

• ansi
• faa
• icao
• itu (default)

Adding a new alphabet is as simple as the following:

phony.alphabets.foo = {
  fallback: 'itu',
  characters: {
    'H': 'hello',
    'W': 'world'
  }
};

var options = {alphabet: 'foo'};

phony.to('how', options);
//=> "Hello Oscar World"
phony.from('Hello Oscar World', options);
//=> "HOW"

clearCache()

Clears any previously built alphabets that may have been cached by phony.from and/or phony.to. This can be useful when making modifications to alphabets and having them picked up.

phony.to('SOS');
//=> "Sierra Oscar Sierra"

phony.alphabets.itu.characters['O'] = 'Oompa';
phony.clearCache();

phony.to('SOS');
//=> "Sierra Oompa Sierra"

The cache can also be bypassed by using the cache option.

defaults

This is a hash of default values to be applied to the optional options parameter and exposed to allow you to override any of them.

phony.defaults.alphabet = 'ANSI';

phony.to('A');
//=> "Alpha"

Miscellaneous

noConflict()

Returns phony in a no-conflict state, reallocating the phony global variable name to its previous owner, where possible.

This is really just intended for use within a browser.

<script src="/path/to/conflict-lib.js"></script>
<script src="/path/to/phony.min.js"></script>
<script>
  var phonyNC = phony.noConflict();
  // Conflicting lib works again and use phonyNC for this library onwards...
</script>

VERSION

The current version of phony.

phony.VERSION;
//=> "1.3.0"

Bugs

If you have any problems with this library or would like to see changes currently in development you can do so here.

Contributors

If you want to contribute, you're a legend! Information on how you can do so can be found in CONTRIBUTING.md. We want your suggestions and pull requests!

A list of phony.js contributors can be found in AUTHORS.md.

License

Copyright (c) 2015 Alasdair Mercer

See LICENSE.md for more information on our MIT license.