Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/caderek/gramma
command-line grammar checker
https://github.com/caderek/gramma
Last synced: 3 months ago
JSON representation
command-line grammar checker
- Host: GitHub
- URL: https://github.com/caderek/gramma
- Owner: caderek
- License: isc
- Created: 2019-07-18T20:28:07.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-03-06T13:38:15.000Z (almost 2 years ago)
- Last Synced: 2024-10-01T14:10:37.101Z (4 months ago)
- Language: JavaScript
- Homepage: https://caderek.github.io/gramma/
- Size: 39.1 MB
- Stars: 251
- Watchers: 5
- Forks: 18
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
## 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)
## 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).