LoicTouzard / acronym-generator

Smartly generate acronyms from a word database

acronym-generator

Smartly generates acronyms from a words database you can fill.

This module allows you generate acronyms and add or remove words in the database.

This project is inpired from another project of mine generating bullshit acronyms : BAG. It uses almost the same logic to generate acronyms, except that this module use a database to store and retreive words.

Index

Install
Full Example
Full Example
Usage and Documentation
getAcronym(text)
addWord(word,details)
removeWord(word)
hasWord(word)
findWordsBeginningWith(letter)
positions
types
WordNotFoundError

Install

$ npm install --save acronym-generator

The modules uses a mongoDB database, and mongoose. So before using this module you must install MongoDB.
The document path by the module to store words is ag_Word.
A mongoose connection must be established before using the module. To do so install mongoose at first :

$ npm install --save mongoose

Full example

This is an example of how to use the acronym-generator module.
It add three words in the database, ask for an acronym, remove one word from the database.

'use strict'
const mongoose = require('mongoose')
const AG = require('acronym-generator')

mongoose.connect('mongodb://localhost/myDatabaseName') // connect your database
mongoose.Promise = global.Promise // override the deprecated mongoose Promise

mongoose.connection.once('open', () => {
    const types = AG.types
    const positions = AG.positions
    // create 3 words for the database
    let addWordPromises = [
        AG.addWord("Algorithm",{type:types.NOUN, position: positions.END}),
        AG.addWord("Binary",{type:types.ADJECTIVE, position: positions.START}),
        AG.addWord("Tree", {type:types.NOUN})
    ]

    Promise.all(addWordPromises) // execute all the addWord promises
    .then(wordsAdded => {
        console.log("ADDED :", wordsAdded.)
        /* =>
        ADDED : [{value: 'Algorithm', preposition: '', type: 'NOUN', position: 'END'},
                {value: 'Binary', preposition: '', type: 'ADJ', position: 'START'},
                {value: 'Tree', preposition: '', type: 'NOUN', position: 'ANY'}]
        */
        return AG.getAcronym("BTA") // chain Promise with asking an acronym for "BTA"
    })
    .then(acronym => {
        console.log(acronym)
        // => "Binary Tree Algorithm"
        return AG.removeWord("Binary") // chain Promise with removing the word Binary
    })
    .then(wordRemoved => {
        console.log("REMOVED :", wordRemoved)
        // => REMOVED : { value: 'Binary', preposition: '', type: 'ADJ', position: 'START'}
        return AG.hasWord("Binary") // chain Promise with checking the existence of the word Binary
    })
    .then(has => {
        console.log("HAS BINARY :", has)
        // => HAS BINARY : false
        mongoose.disconnect()
        Promise.resolve()
    })
    .catch(err => {
        console.error(err)
        mongoose.disconnect()
        Promise.reject()
    })
})

Note that if we chain again with AG.getAcronym("BTA") the Promise would be rejected and given an WordNotFoundError object.

Usage and Documentation

Once you've installed everything, you can open the connection. You should override mongoose.Promise because they are deprecated, prefer the global.Promise model from ES6.

'use strict'
const mongoose = require('mongoose')
const AG = require('acronym-generator')

mongoose.connect('mongodb://localhost/myDatabaseName')
mongoose.Promise = global.Promise

mongoose.connection.once('open', () => {

    /* You can use the module here */
    
    mongoose.disconnect() // you can log out of the database if you don't need it anymore
})

For now on the examples are assuming you connected correctly to the database, and that the mongoose.Promise are set.

Get an Acronym

You can get an acronym made of the words from your database with :

getAcronym(text) // return Promise

The parameter is :

• text {string} The word you want to find an acronym for.

This function return a Promise.
The resolve callback gets the acronym.
The reject callback gets a database error, or an instance of WordNotFoundError when the database has not enough word beginning by a specific letter needed in the algorithm.
Note : The algorithm doens't use the same word twice in the same acronym. The acronym for "AA" can't be "Algorithm Algorithm".

Example

const AG = require('acronym-generator')
let text = "BTA"
// assuming the words "Binary", "Tree" and "Algorithm" are in the database

AG.getAcronym(text)
.then(acronym => console.log("GOT ACRONYM : ", acronym)) // => "Binary Tree Algorithm"
.catch(err => {
    if(err instanceof AG.WordNotFoundError) console.error(err.message) // WordNotFoundError error
    else console.error(err) // database error
}) 

Add a word to the database

You can add a word to the database so that it can be picked to form the future acronyms.
Note : You can't insert two word with the same value, even if the details are different.

addWord(word, details) // return Promise

The parameters are :

• word {String} The actual word to add to the database
• details {Object} Option to add details to the word, to get a better acronym generation

The different values for details are all optional. If one is not provided, the default value will prevail.
Here are the default values :

{
    preposition : '',               // The preposition which fit the word if necessary : "de", "d'", ...
    type: AG.types.OTHER,           // The Word's type : takes values from 
    position: AG.positions.ANYWHERE // The Word's prefered position in an acronym : takes values from AcronymGenerator.positions
}

The value for type and position must be from the object AG.types and AG.positions.
This function return a Promise.
The resolve callback gets the created word.
The reject callback gets a database error, or a duplication error, or an error saying that the values in parameters some incorrect values.

Example

const AG = require('acronym-generator')
let word = "Algorithm"
let details = {
    preposition: '',
    type: AG.types.NOUN,
    position: AG.position.END
}
AG.addWord(word, details)
.then((wordCreated) => console.log("SAVED : ", wordCreated))
.catch((err) => console.error(err)) // db error or duplication error or an error because the input values were not correct

Remove a word from the database

You can remove a word from the database.

removeWord(word) // return Promise

The parameter is :

• word {string|Word} The word you want to delete from the database. It can be either the string which value is the word you are looking for, or directly the word Object (that you could have get from addWord(word, details) for example)

This function return a Promise.
The resolve callback gets the deleted word.
The reject callback gets a database error.

Example

const AG = require('acronym-generator')
let word = "Algorithm"

AG.removeWord(word)
.then(wordRemoved => console.log("REMOVED : ", wordRemoved))
.catch(err => console.error(err)) // db error, or the word wasn't found in database

Check the existence of a word

You can check if a word already exists in the database.

hasWord(word) // return Promise

The parameter is :

• word {string} The string value of the word you want to check in the database.

This function return a Promise.
The resolve callback gets a boolean to true if the word exists, else false.
The reject callback gets a database error.

Example

const AG = require('acronym-generator')
let word = "Algorithm"

AG.hasWord(word)
.then(has => console.log("HAS : ", has)) // true / false
.catch(err => console.error(err)) // db error

Find words beginning with some string

You can get all the words stored beginning with a given string :

findWordsBeginningWith(letter) // return Promise

The parameter is :

• letter {string} The string (mostly letter) that you want to find words beginning with.

This function return a Promise.
The resolve callback gets an array of words beginning with th given letter. The length of the array can be 0 if there is no result.
The reject callback gets a database error.

Example

const AG = require('acronym-generator')
const letter = "A"
// assuming the words "Algorithm" and "Acronym" are in the database

AG.findWordsBeginningWith(letter)
.then(words => console.log("GOT WORDS : ", words))
/* =>
    GOT WORDS : [{value: 'Algorithm', preposition: '', type: 'NOUN', position: 'END'},
            {value: 'Acronym', preposition: '', type: 'NOUN', position: 'END'}]
*/ 
.catch(err => {
    else console.error(err) // database error
}) 

Positions

Contains the available positions for a word.
Use these values in the details.position parameter of the function addWord(word, details) to set the preferred position of the word in an acronym.

const AG = require('acronym-generator')

console.log(AG.positions)
/* =>
{
    'ANYWHERE':'ANY',
    'START':'START',
    'MIDDLE':'MID',
    'END':'END'
} */

Use these values as following :

• Use AG.positions.ANYWHERE when the word can fit anywhere in an acronym (default value)
• Use AG.positions.START when the word can only be placed at the beginning of the acronym
• Use AG.positions.MIDDLE when the word can't be placed at the beginning, nor the end of an acronym
• Use AG.positions.END when the word can only be placed at the end of the word

Types

Contains the available types for a word.
Use these values in the details.type parameter of the function addWord(word, details) to set the type of the word.

const AG = require('acronym-generator')

console.log(AG.types)
/*=> 
{
    'NOUN':'NOUN',
    'PROPER_NOUN':'PR_NOUN',
    'ADJECTIVE':'ADJ',
    'ADVERB':'ADVB',
    'VERB_CONJUGATED':'VB_CJGT',
    'VERB_INFINITIVE':'VB_INF',
    'OTHER':'OTHER'
} */

Use thes values as following :

• AG.types.NOUN when the word's type is noun
• AG.types.PROPER_NOUN : when the word's type is a proper noun
• AG.types.ADJECTIVE when the word's type is adjective
• AG.types.ADVERB when the word's type is adverb
• AG.types.VERB_CONJUGATED when the word's type is a verb conjugated to the 3rd person singular
• AG.types.VERB_INFINITIVE when the word's type is a verb in infinitive form
• AG.types.OTHER when the word's type doesn't fit any of these

WordNotFoundError class

WordNotFoundError is returned in the rejected Promise of the getAcronym(text) function.

const AG = require('acronym-generator')
AG.WordNotFoundError    // class

Source

It is a simple class containing some information :

class WordNotFoundError {
    constructor(message, letter){
        this.message = message              // the error message
        this.name = "WordNotFoundError"     // the name of the exception
        this.letter = letter                // the letter that triggered the error
    }
}

Lasts words...

Feel free to use it !

Loïc Touzard