__
/\ \
_____\ \ \___ ___ ___ __ __
/\ '__`\ \ _ `\ / __`\/' _ `\/\ \/\ \
\ \ \L\ \ \ \ \ \/\ \L\ \\ \/\ \ \ \_\ \
\ \ ,__/\ \_\ \_\ \____/ \_\ \_\/`____ \
\ \ \/ \/_/\/_/\/___/ \/_/\/_/`/___/> \
\ \_\ /\___/
\/_/ \/__/
phony.js is a pure JavaScript library for translating to/from the NATO phonetic alphabet that supports extensible characters.
Install using the package manager for your desired environment(s):
# for node.js:
$ npm install node-phony
# OR; for the browser:
$ bower install phony
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.
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
Translates the message
parameter to the phonetic alphabet.
phony.to('SOS');
//=> "Sierra Oscar Sierra"
Translates the message
parameter from the phonetic alphabet.
phony.from('Sierra Oscar Sierra');
//=> "SOS"
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"
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.
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"
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>
The current version of phony
.
phony.VERSION;
//=> "1.3.0"
If you have any problems with this library or would like to see changes currently in development you can do so here.
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.
Copyright (c) 2015 Alasdair Mercer
See LICENSE.md for more information on our MIT license.