Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/caderek/gramma

command-line grammar checker
https://github.com/caderek/gramma

Last synced: about 2 months ago
JSON representation

command-line grammar checker

Awesome Lists containing this project

README

        


gramma-logo


gramma-title

 


CircleCI
npm version
node version
npm license


 


Example

 

---

## Features

- Provides advanced grammar checks via LanguageTool (remote API or local server).
- Supports global and local (per-project) configuration.
- Supports plain text and markdown.
- Git integration!
- Fully interactive!

---

## Contents

1. [Installation](#installation)
- [Via NPM (global)](#installation-npm)
- [Standalone binary](#installation-binary)
- [Dev tool for JS/TS projects](#installation-dev)
- [Local LanguageTool server (optional)](#installation-server)
1. [Usage](#usage)
- [Check file](#usage-check)
- [Check string](#usage-listen)
- [Git commit with grammar check](#usage-commit)
- [Command-line options](#usage-options)
- [Usage inside VIM](#usage-vim)
1. [Configuration](#config)
- [Introduction](#config-intro)
- [Local config](#config-local)
- [Git integration](#config-git)
- [Checker settings](#config-checker)
- [Customizing API server](#config-server)
- [Security](#config-security)
1. [Managing a local server](#server)
1. [JS API](#js)
1. [License](#license)

---

## Installation

### Via NPM

It is the recommended way if you have Node.js already installed (or you are willing to do so).

```
npm i gramma -g
```


### Standalone binary

If you prefer a single binary file, you can download it for the most popular platforms:

- [gramma-linux64-v1.6.0.zip](https://github.com/caderek/gramma/releases/download/v1.6.0/gramma-linux64-v1.6.0.zip)
- [gramma-macos-v1.6.0.zip](https://github.com/caderek/gramma/releases/download/v1.6.0/gramma-macos-v1.6.0.zip)
- [gramma-windows64-v1.6.0.zip](https://github.com/caderek/gramma/releases/download/v1.6.0/gramma-windows64-v1.6.0.zip)

After downloading and unpacking the binary, add it to your PATH or create a symlink to your executable directory (depending on the platform).


### Dev tool for JS/TS projects

You can install Gramma locally for your JS/TS project - this method gives you a separate, project specific config.

```
npm i gramma -D
```

or

```
yarn add gramma -D
```

Then create the local config file:

```
npx gramma init
```

You will be asked if you want to integrate Gramma with Git (via hook). You can later manually toggle git hook via `npx gramma hook` command.

Git hook also works with a non-default hooks path (Husky, etc.).


### Local LanguageTool server (optional)

For this to work, you have to install Java 1.8 or higher (you can find it [here](https://adoptium.net)). You can check if you have it installed already by running:

```
java -version
```

To install the local server, use:

```
gramma server install
```

That's it - Gramma will now use and manage the local server automatically.

---

## Usage

### Check file

Interactive fix:

```
gramma check [file]
```

Just print potential mistakes and return status code:

```
gramma check -p [file]
```

Examples:

```
gramma check path/to/my_file.txt
```

```
gramma check -p path/to/other/file.txt
```


### Check string

Interactive fix:

```
gramma listen [text]
```

Just print potential mistakes and return status code:

```
gramma listen -p [text]
```

Examples:

```
gramma listen "This sentence will be checked interactively."
```

```
gramma listen -p "Suggestions for this sentence will be printed."
```


### Git commit with grammar check

_**TIP:** Instead of the commands below, you can use [Git integration](#config-git)._

Equivalent to `git commit -m [message]`:

```
gramma commit [text]
```

Equivalent to `git commit -am [message]`:

```
gramma commit -a [text]
```

Examples:

```
gramma commit "My commit message"
```

```
gramma commit -a "Another commit message (files added)"
```


### Command-line options

_Note: This section describes options for grammar-checking commands only. Other command-specific options are described in their specific sections of this document._

- `-p / --print` - check text in the non-interactive mode
- `-n / --no-colors` - when paired with the `-p` flag, removes colors from the output
- `-d / --disable ` - disable specific [rule](#available-rules)
- `-e / --enable ` - enable specific [rule](#available-rules)
- `-l / --language ` - mark a text as written in provided [language](#available-languages)
- `-m / --markdown` - treat the input as markdown (removes some false-positives)

You can enable or disable multiple rules in one command by using a corresponding option multiple times. You can also compound boolean options if you use their short version.

Example:

```
gramma listen "I like making mistkaes!" -pn -d typos -d typography -e casing -l en-GB
```


### Usage inside VIM

If you are a VIM/Neovim user, you can use Gramma directly inside the editor:

Print the potential mistakes:

```
:w !gramma check /dev/stdin -pn
```

Interactive fix of the current file:

```
:terminal gramma check %
```

It will open the interactive terminal inside VIM - to handle Gramma suggestions, enter the interactive mode (`a` or `i`) and use Gramma as usual. After you fix the mistakes and replace a file, press `Enter` to return to the editor.

Example GIF (click to expand)
Gramma VIM example

---

## Configuration

### Introduction

With Gramma, you can use a global and local configuration file. Gramma will use a proper config file following their priority:

1. Command-line options
2. Local config
3. Global config

Gramma will automatically generate a global configuration file on the first run.

You can check the path to the global configuration file (as well as other paths used by Gramma) via the following command:

```
gramma paths
```

You can change your settings by manually editing configuration files or running:

```
gramma config [-g]
```

_Note: `-g` (`--global`) flag should be used when you want to alter the global config._


### Local config

You can initialize local config by running the following command in your project's root directory:

```
gramma init
```

Gramma creates the local configuration file in your working directory under `.gramma.json` name.


### Git integration

You can toggle Git hook via:

```
gramma hook
```

It will add/remove an entry in `commit-msg` hook.

Gramma follows the Git configuration file, so it should work with a non-standard hooks location.


### Checker settings

#### Adding a word to the dictionary

Usually, you will add custom words to the local or global dictionary via interactive menu during the fix process, but you can also make it via separate command:

```
gramma config dictionary [-g]
```

Examples:

```
gramma config dictionary aws
gramma config dictionary figma -g
```

#### Changing default language

```
gramma config language [-g]
```

Examples:

```
gramma config language en-GB
gramma config language pl-PL -g
```

Available languages (click to expand)


Code
Name
languagetool.org
grammarbot.io
local


auto
automatic language detection






ar
Arabic

-



ast-ES
Asturian





be-BY
Belarusian





br-FR
Breton





ca-ES
Catalan





ca-ES-valencia
Catalan (Valencian)





zh-CN
Chinese

-



da-DK
Danish





nl
Dutch





nl-BE
Dutch (Belgium)

-



en
English





en-AU
English (Australian)





en-CA
English (Canadian)





en-GB
English (GB)





en-NZ
English (New Zealand)





en-ZA
English (South African)





en-US
English (US)





eo
Esperanto





fr
French

-



gl-ES
Galician





de
German

-



de-AT
German (Austria)

-



de-DE
German (Germany)

-



de-CH
German (Swiss)

-



el-GR
Greek





ga-IE
Irish

-



it
Italian

-



ja-JP
Japanese





km-KH
Khmer





fa
Persian





pl-PL
Polish





pt
Portuguese

-



pt-AO
Portuguese (Angola preAO)

-



pt-BR
Portuguese (Brazil)

-



pt-MZ
Portuguese (Moçambique preAO)

-



pt-PT
Portuguese (Portugal)

-



ro-RO
Romanian





ru-RU
Russian

-



de-DE-x-simple-language
Simple German





sk-SK
Slovak





sl-SI
Slovenian





es
Spanish

-



es-AR
Spanish (voseo)

-



sv
Swedish





tl-PH
Tagalog





ta-IN
Tamil





uk-UA
Ukrainian





_Note: By default, Gramma uses US English (`en-US`)._

#### Enabling and disabling rules

Enabling a specific rule:

```
gramma config enable [-g]
```

Disabling a specific rule:

```
gramma config disable [-g]
```

Examples:

```
gramma config enable punctuation
gramma config enable casing -g

gramma config disable typography
gramma config disable style -g
```

Available rules (click to expand)

RuleDescription
casingRules about detecting uppercase words where lowercase is required and vice versa.
colloquialismsColloquial style.
compoundingRules about spelling terms as one word or as as separate words.
confused_wordsWords that are easily confused, like 'there' and 'their' in English.
false_friendsFalse friends: words easily confused by language learners because a similar word exists in their native language.
gender_neutralityHelps to ensure gender-neutral terms.
grammarBasic grammar check.
miscMiscellaneous rules that don't fit elsewhere.
punctuationPunctuation mistakes.
redundancyRedundant words.
regionalismsRegionalisms: words used only in another language variant or used with different meanings.
repetitionsRepeated words.
semanticsLogic, content, and consistency problems.
styleGeneral style issues not covered by other categories, like overly verbose wording.
typographyProblems like incorrectly used dash or quote characters.
typosSpelling issues.

_Note: By default, all rules are enabled._


### Customizing API server

#### Defining custom API endpoint

If you want to use remote LanguageTool server, or use the one already installed in your system (not installed via `gramma server install`), you can define a custom API endpoint:

```
gramma config api_url [-g]
```

Examples:

```
gramma config api_url https://my-custom-api-url.xyz/v2/check
gramma config api_url http://localhost:8081/v2/check -g
```

#### Running local server only when needed

If you do not want the local server to run all the time, you can configure Gramma to run it only when needed (`run → check → close`). It is useful when you run Gramma only from time to time and want to lower the memory consumption:

```
gramma config server_once true -g

```

Revert:

```
gramma config server_once false -g
```

#### Adding API key

If you use a paid option on [grammarbot.io](https://www.grammarbot.io/) or [languagetool.org](https://languagetool.org), you will receive an API key that you can use in Gramma:

```
gramma config api_key [-g]
```


### Security

If you need to store some sensitive data in your local config file (API key etc.) you can use environment variables directly in the config file (supports `.env` files).

Example:

```json
{
"api_url": "https://my-language-tool-api.com/v2/check",
"api_key": "${MY_ENV_VARIABLE}",
...other_settings
}
```

_Note: The default API (`api.languagetool.org`) is generally [safe and does not store your texts](https://languagetool.org/pl/legal/privacy), but if you want to be extra careful, you should use a [local server](#installation-server) or custom API endpoint._

---

## Managing a local server

If you have [configured a local server](#installation-server), Gramma will manage the server automatically - nevertheless, there might be situations when you want to manage the server manually. Gramma simplifies this by exposing basic server commands:

#### Starting the server

```
gramma server start
```

You can also specify a custom port:

```
gramma server start --port
```

_Note: When you use this command, Gramma will ignore the `server_once` config option. This is expected behavior - I assume that if you use this command, you want the server to actually run, not stop after the first check._

#### Stopping the server

```
gramma server stop
```

#### Getting the server info

```
gramma server info
```

#### Getting the server PID

```
gramma server pid
```

_Note: You can use `gramma server info` instead - this command is kept to not break backward compatibility._

#### Opening the built-in GUI

```
gramma server gui
```

---

## JS API

In addition to command-line usage, you can use two exposed methods if you want to handle mistakes by yourself.

#### Imports

If you use Node.js or a bundler for your browser build, you can use CommonJS or esm:

```js
const gramma = require("gramma")
```

```js
import gramma from "gramma"
```

If you don't use a bundler and want to use gramma in the browser, there are some prebuild packages in [/bundle](https://github.com/caderek/gramma/tree/master/bundle) directory:

- `gramma.esm.js` - ES Modules bundle
- `gramma.esm.min.js` - minified ES Modules bundle
- `gramma.min.js` - IIFE bundle exposing global `gramma` variable

You can also import ESM bundle directly from CDN:

```html

import gramma from "https://cdn.skypack.dev/gramma"

```


#### check() method

Returns a promise with a check result.

```js
const gramma = require("gramma")

gramma.check("Some text to check.").then(console.log)
```

You can also pass a second argument - an options object. Available options:

- `api_url` - url to a non-default API server
- `api_key` - server API key
- `dictionary` - an array of words that should be whitelisted
- `language` - language code to specify the text language
- `rules` - object defining which rules should be disabled

Default options object (click to expand)


{
"api_url": "https://api.languagetool.org/v2/check",
"api_key": "",
"dictionary": [],
"language": "en-US",
"rules": {
"casing": true,
"colloquialisms": true,
"compounding": true,
"confused_words": true,
"false_friends": true,
"gender_neutrality": true,
"grammar": true,
"misc": true,
"punctuation": true,
"redundancy": true,
"regionalisms": true,
"repetitions": true,
"semantics": true,
"style": true,
"typography": true,
"typos": true
}
}

You can find all available values for each setting in the [configuration section](#config) of this document.

Example with all options set:

```js
const gramma = require("gramma")

gramma
.check("Some text to check.", {
api_url: "http://my-custom-language-tool-server.xyz/v2/check",
api_key: "SOME_API_KEY",
dictionary: ["npm", "gramma"],
language: "pl-PL",
rules: {
typography: false,
casing: false,
},
})
.then(console.log)
```


#### replaceAll() method

Replace words with provided ones. It takes an array of objects in the following format:

```js
const exampleReplacements = [
{ offset: 6, length: 3, change: "correct phrase" },
{ offset: 20, length: 7, change: "another phrase" },
]
```

You can find proper `offset` and `length` values in the object returned by the `check()` method.

Example usage:

```js
const gramma = require("gramma")

/** Your custom function **/
const prepareReplacements = (matches) => {
// your code...
}

const fix = async (text) => {
const { matches } = await gramma.check(text)
const replacements = prepareReplacements(matches)

return gramma.replaceAll(text, replacements)
}

const main = () => {
const correctText = await fix("Some text to check")
console.log(correctText)
}

main()
```

---

## License

The project is under open, non-restrictive [ISC license](https://github.com/caderek/gramma/blob/master/LICENSE.md).