https://github.com/mklement0/print-nonascii
Unix CLI that prints lines that contain non-ASCII characters.
https://github.com/mklement0/print-nonascii
ascii cli diagnostic-tool unicode unix-cli
Last synced: 4 months ago
JSON representation
Unix CLI that prints lines that contain non-ASCII characters.
- Host: GitHub
- URL: https://github.com/mklement0/print-nonascii
- Owner: mklement0
- Created: 2017-09-10T21:00:40.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2022-12-27T14:09:20.000Z (over 3 years ago)
- Last Synced: 2025-01-18T17:52:27.132Z (over 1 year ago)
- Topics: ascii, cli, diagnostic-tool, unicode, unix-cli
- Language: Makefile
- Homepage:
- Size: 32.2 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
[](https://npmjs.com/package/print-nonascii)[](https://github.com/mklement0/print-nonascii/blob/master/LICENSE.md)
**Contents**
- [print-nonascii: print lines that contain non-ASCII characters.](#print-nonascii-print-lines-that-contain-non-ascii-characters)
- [Examples](#examples)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Installation from the npm registry](#installation-from-the-npm-registry)
- [Manual installation](#manual-installation)
- [Usage](#usage)
- [License](#license)
- [Acknowledgements](#acknowledgements)
- [npm dependencies](#npm-dependencies)
- [Changelog](#changelog)
# print-nonascii: print lines that contain non-ASCII characters.
`print-nonascii` is a Unix CLI that locates lines in text files or
stdin input that contain non-ASCII characters, which is helpful when
diagnosing character encoding problems.
Lines can be printed as-is and/or using abstract representations of non-ASCII
characters in one of several formats; namely:
* `-v`, `--caret` ... the same representation `cat -v` uses, based on caret notation.
* `--bash` ... per-_byte_ two-digit hex. escape sequences such as `\xc3`
* `--psh` ... PowerShell Unicode escape sequences such as `` `u{20ac} `` for `€`
Note: `--psh` only works correctly with properly UTF-8-encoded input.
Line numbers can be prepended on request, and output for multiple input
files is by default preceded with headers identifying each input file.
_Caveat: For now, no automated tests are run before releases._
# Examples
```sh
# Create a test file with 1 line containing a non-ASCII character.
$ cat <<'EOF' > /tmp/test.txt
one
twö
three
EOF
# Print only lines that have non-ASCII characters, as-is.
$ print-nonascii /tmp/test.txt
twö
# Print only lines that have non-ASCII characters, with line numbers:
$ print-nonascii -n /tmp/test.txt
2:twö
# Print only lines that have non-ASCII characters, using PowerShell
# Unicode escape-sequence notation (--psh), preceded by the
# line as-is (--raw).
# The Unicode code point of character "ö" is U+00F6:
$ print-nonascii --psh --raw /tmp/test.txt
twö
tw`u{f6}
# Ditto with line numbers and per-byte Bash escape sequences:
$ print-nonascii --bash --raw /tmp/test.txt
twö
tw\xc3\xb6
# Simulate input from multiple files by specifying the same file
# twice, so as to show the headers identifying each input file
# (suppress with -b).
# Note that each header line (invisibly) starts with control
# character U+0001, so as to allow more predictable
# identification of header lines in the output.
$ print-nonascii -n /tmp/test.txt /tmp/test.txt
### /tmp/test.txt
2:twö
### /tmp/test.txt
2:twö
```
# Installation
## Prerequisites
* When installing from the **npm registry**: **macOS** and **Linux**
* When installing **manually**: any Unix platform with `bash` that also has `perl` installed.
## Installation from the npm registry
With [Node.js](http://nodejs.org/) installed, install [the package](https://www.npmjs.com/package/print-nonascii) as follows:
[sudo] npm install print-nonascii -g
**Note**:
Note: Even if you don't use Node.js, its package manager, `npm`, works across platforms and is easy to install; try [`curl -L https://git.io/n-install | bash`](https://github.com/mklement0/n-install)
* Whether you need `sudo` depends on how you installed Node.js / io.js and whether you've [changed permissions later](https://docs.npmjs.com/getting-started/fixing-npm-permissions); if you get an `EACCES` error, try again with `sudo`.
* The `-g` ensures [_global_ installation](https://docs.npmjs.com/getting-started/installing-npm-packages-globally) and is needed to put `print-nonascii` in your system's `$PATH`.
## Manual installation
* Download [the CLI](https://raw.githubusercontent.com/mklement0/print-nonascii/stable/bin/print-nonascii) as `print-nonascii`.
* Make it executable with `chmod +x print-nonascii`.
* Move it or symlink it to a folder in your `$PATH`, such as `/usr/local/bin` (macOS) or `/usr/bin` (Linux).
# Usage
Find concise usage information below; for complete documentation, read the [manual online](doc/print-nonascii.md), or, once installed, run `man print-nonascii` (`print-nonascii --man` if installed manually).
```nohighlight
$ print-nonascii --help
Prints lines that contain non-ASCII characters.
print-nonascii [-- [-r]] [-n] [-b] [file ...]
print-nonascii -q [file ...]
-- prints abstract representations of non-ASCII chars.; one of:
--caret, -v ... use caret notation, as cat -v would.
--bash ... represent non-ASCII bytes as \xhh
--psh ... (PowerShell) represent non-ASCII Unicode characters as
Unicode escape sequences: u{h...}
-r, --raw ... with --, print each matching line as-is too, first.
-n, --line-number ... prefix the output lines with their line number from
the original file, using format ":" - decimal line numbers,
no padding, no space before or after the ":"
-b, --bare ... suppress per-input-filename headers
-q ... quiet mode: produce no output; signal presence of non-ASCII chars.
with exit code 0; exit code 100 signals that there are none.
Standard options: --help, --man, --version, --home
```
# License
Copyright (c) 2017 Michael Klement (http://same2u.net), released under the [MIT license](https://spdx.org/licenses/MIT#licenseText).
## Acknowledgements
This project gratefully depends on the following open-source components, according to the terms of their respective licenses.
[npm](https://www.npmjs.com/) dependencies below have an optional suffix denoting the type of dependency: the *absence* of a suffix denotes a required *run-time* dependency; `(D)` denotes a *development-time-only* dependency, `(O)` an *optional* dependency, and `(P)` a *peer* dependency.
## npm dependencies
* [doctoc (D)](https://github.com/thlorenz/doctoc#readme)
* [json (D)](https://github.com/trentm/json#readme)
* [marked-man (D)](https://github.com/kapouer/marked-man#readme)
* [replace (D)](https://github.com/harthur/replace#readme)
* [semver (D)](https://github.com/npm/node-semver#readme)
* [urchin (D)](https://git.sdf.org/tlevine/urchin)
# Changelog
Versioning complies with [semantic versioning (semver)](http://semver.org/).
* **[v0.0.3](https://github.com/mklement0/print-nonascii/compare/v0.0.2...v0.0.3)** (2017-09-11):
* [enhancement] Header lines are now only printed for input files that produce at least 1 output line.
* **[v0.0.2](https://github.com/mklement0/print-nonascii/compare/v0.0.1...v0.0.2)** (2017-09-10):
* [fix] Header line is no longer printed twice when `--` is combined with `--raw`.
* Header line now uses a tab char. to separate prefix `###` from the filename.
* **v0.0.1** (2017-09-10):
* Initial release.