indefinite

What is indefinite?

The 'indefinite' npm package is used to determine the correct indefinite article ('a' or 'an') for a given word or phrase. This can be particularly useful in natural language processing, text generation, and other applications where proper grammar is important.

What are indefinite's main functionalities?

Basic Usage

This feature allows you to get the correct indefinite article for a single word. The function takes a word as input and returns the word prefixed with the correct indefinite article.

const indefinite = require('indefinite');
console.log(indefinite('apple')); // Output: 'an apple'
console.log(indefinite('banana')); // Output: 'a banana'

Handling Phrases

This feature allows you to get the correct indefinite article for a phrase. The function takes a phrase as input and returns the phrase prefixed with the correct indefinite article.

const indefinite = require('indefinite');
console.log(indefinite('hour of work')); // Output: 'an hour of work'
console.log(indefinite('unicorn in the garden')); // Output: 'a unicorn in the garden'

Custom Options

This feature allows you to customize the output, such as capitalizing the first letter of the article. The function takes a word or phrase and an options object as input and returns the word or phrase prefixed with the correct indefinite article, formatted according to the options.

const indefinite = require('indefinite');
console.log(indefinite('apple', { capitalize: true })); // Output: 'An apple'
console.log(indefinite('banana', { capitalize: true })); // Output: 'A banana'

Other packages similar to indefinite

an

The 'an' package provides similar functionality by determining whether to use 'a' or 'an' before a word. It is simpler and more lightweight compared to 'indefinite', but it may not handle complex phrases as effectively.

article

The 'article' package also determines the correct indefinite article for a given word. It is comparable to 'indefinite' in terms of functionality but may have different handling for edge cases and custom options.

README

indefinite

Prefix a noun with an indefinite article - a or an - based on whether it begins with a vowel.

Installation

npm install --save indefinite

Summary

It's not hard to check whether a noun begins with a vowel and decide whether to prefix with "a" or "an," but I got tired of doing it manually every time. So now there's this. Just pass in the word, and indefinite will return the word prefixed with either "a " or "an " depending on the first letter of the word.

As of version 2.0.0, indefinite will attempt to detect when an acronym is passed in and treat the response differently. E.g. it should be "a UFO" not "an UFO" because of how we pronounce a long U. This isn't a perfect science, so you might have false positives.

As of version 2.0.2, indefinite will also consult a list of irregular words to determine the appropriate article. For example, it should be "an hour" not "a hour." It also attempts to do this with various forms of the words (checking for singular, plural, and even past tense, since past tense verbs can be used as adjectives, as in "an honored man"). This is not an exact science either, and the list of irregulars is not exhaustive (and probably won't ever be), but if you find a word that's not in the list that's returning the wrong thing, please open an issue so it can be corrected.

Usage

var a = require('indefinite');

console.log(a('apple')); // "an apple"
console.log(a('banana')); // "a banana"
console.log(a('UFO')); // 'a UFO'
console.log(a('hour')); // 'an hour'
console.log(a('ukelele')); // 'a ukelele'

Indefinite also accepts an options object as the second parameter. The following options are supported:

• articleOnly - Return only the article.
• capitalize - Capitalize the article.
• caseInsensitive - Ignore the casing of the word passed in (i.e. bypassing the acronym checking). This is useful if, for some reason, you're yelling on the internet and want to make sure "UGLY GARDEN GNOME" doesn't become "a UGLY GARDEN GNOME."
• numbers - When numbers are passed in, they are prefixed with "a" except for 8, 11, 18, and higher numbers starting with 8. However, numbers like 1100 are ambiguous. Should it be "a one thousand one hundred" or "an eleven hundred"? There's not really any programmatic way to know this for sure, but if you know for sure, you can use the numbers option to tell indefinite how to handle these cases. The default is "formal" in which numbers are read literally (the way you'd say them if they were written out), but if you pass numbers: 'colloquial', the "eleven hundred"/"eighteen hundred" readings will be used.

console.log(a('apple', { articleOnly: true })); // 'an'
console.log(a('banana', { articleOnly: true })); // 'a'
console.log(a('apple', { capitalize: true })); // 'An apple'
console.log(a('banana', { capitalize: true })); // 'A banana'
console.log(a('UGLY SWEATER', { caseInsensitive: true })); // 'an UGLY SWEATER'
console.log(a('2')); // 'a 2'
console.log(a('8')); // 'an 8'
console.log(a('1892')); // 'a 1892' -> read "a one thousand eight hundred ninety-two"
console.log(a('1892', { numbers: 'colloquial' })); // 'an 1892' -> read "an eighteen ninety-two"

Browser

Files in dist are UMD format, and package.json contains a browser field pointing to dist/indefinite.js, so you should be able to bundle this via webpack, rollup, browserify, etc. or serve it in ye olde javascript fashion and access it via window.

Detecting the need for an indefinite article

It's worth mentioning that indefintite currently only differentiates between a and an for you. It doesn't do anything to decide if an indefinite article is required, so if you pass a plural to indefinite, you'll get something like "a shoes" back, which is obviously wrong. You can look at this issue for more context on why this isn't supported at the moment. It could be in the future, but there are some prohibitive issues to work through first. For now, it is up to you (the consumer) to either call or not call indefinite depending on the plurality of the word. You can do something like the suggestion in that issue:

const indefinite = require('indefinite');
const pluralize = require('pluralize');

module.exports = (subject) => {
  if (pluralize(subject) === subject) {
    return subject;
  }

  return indefinite(subject);
};

Or you can try is-singular or is-plural.

Contributing

Please see the contribution guidelines.