caderek/gramma

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
   • Via NPM (global)
   • Standalone binary
   • Dev tool for JS/TS projects
   • Local LanguageTool server (optional)
2. Usage
   • Check file
   • Check string
   • Git commit with grammar check
   • Command-line options
   • Usage inside VIM
3. Configuration
   • Introduction
   • Local config
   • Git integration
   • Checker settings
   • Customizing API server
   • Security
4. Managing a local server
5. JS API
6. 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
• gramma-macos-v1.6.0.zip
• 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). 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.

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 <rule> - disable specific rule
• -e / --enable <rule> - enable specific rule
• -l / --language <language_code> - mark a text as written in provided language
• -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)

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 <setting> <value> [-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 <your_word> [-g]

Examples:

gramma config dictionary aws
gramma config dictionary figma -g

Changing default language

gramma config language <language_code> [-g]

Examples:

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

Note: By default, Gramma uses US English (en-US).

Enabling and disabling rules

Enabling a specific rule:

gramma config enable <rule_name> [-g]

Disabling a specific rule:

gramma config disable <rule_name> [-g]

Examples:

gramma config enable punctuation
gramma config enable casing -g

gramma config disable typography
gramma config disable style -g

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 <custom_api_endpoint> [-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 or languagetool.org, you will receive an API key that you can use in Gramma:

gramma config api_key <your_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:

{
  "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, but if you want to be extra careful, you should use a local server or custom API endpoint.

Managing a local server

If you have configured a local 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 <port_number>

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:

const gramma = require("gramma")

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 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:

<script type="module">
  import gramma from "https://cdn.skypack.dev/gramma"
</script>

check() method

Returns a promise with a check result.

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

{
  "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 of this document.

Example with all options set:

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:

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:

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.