feat: move cli tools to their own packages (#1664)

- update cli docs - fix #1659 close / disconnect error for serialport-terminal - rename serialport-term to serialport-terminal - stop `test:require` because it's not necessary and breaks on the cli packages
serialport · Sep 15, 2018 · 103498e · 103498e
1 parent 160cf33
commit 103498e
Show file tree

Hide file tree

Showing 23 changed files with 461 additions and 175 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -73,7 +73,6 @@ install:
 
 script:
 - npm run lint
-- npm run test:require
 - npm test
 
 # if publishing, do it

diff --git a/docs/api-overview.md b/docs/api-overview.md
@@ -22,10 +22,18 @@ Parsers are used to take raw binary data and transform them into usable messages
 
 Parsers are traditionally Transform streams, but Duplex streams and other non stream interfaces are acceptable.
 
-- [@serialport/parser-byte-length](api-parser-byte-length.md)
-- [@serialport/parser-cctalk](api-parser-cctalk.md)
-- [@serialport/parser-delimiter](api-parser-delimiter.md)
-- [@serialport/parser-readline](api-parser-readline.md)
-- [@serialport/parser-ready](api-parser-ready.md)
-- [@serialport/parser-regex](api-parser-regex.md)
-- [@serialport/parser-slip-encoder](api-parser-slip-encoder.md)
+- [`@serialport/parser-byte-length`](api-parser-byte-length.md)
+- [`@serialport/parser-cctalk`](api-parser-cctalk.md)
+- [`@serialport/parser-delimiter`](api-parser-delimiter.md)
+- [`@serialport/parser-readline`](api-parser-readline.md)
+- [`@serialport/parser-ready`](api-parser-ready.md)
+- [`@serialport/parser-regex`](api-parser-regex.md)
+- [`@serialport/parser-slip-encoder`](api-parser-slip-encoder.md)
+
+## Command Line Tools
+
+The [Command Line Tools](guide-cli.md) provide helpful utilities for working with serial ports.
+
+- [`@serialport/list`](guide-cli.md#serialport-list)
+- [`@serialport/repl`](guide-cli.md#serialport-repl)
+- [`@serialport/terminal`](guide-cli.md#serialport-terminal)
diff --git a/docs/guide-cli.md b/docs/guide-cli.md
@@ -3,19 +3,35 @@ id: guide-cli
 title: Command Line Tools
 ---
 
-If you install `serialport` globally (e.g., `npm install -g serialport`), you'll receive two command line tools. These can also be run with `npx` if serialport is a dependency in your project.
+(These cli tools were formally part of the `serialport` package and have now been moved to their own packages for ease of use.)
+
+All cli tools can be run via [`npx`](https://www.npmjs.com/package/npx) or installed globally.
 
 For Example:
 ```bash
-$ npm install --save serialport
-$ npx serialport-list
+$ npx @serialport/list
 /dev/tty.Bluetooth-Incoming-Port
 /dev/tty.usbmodem1421    Arduino (www.arduino.cc)
 
+#or
+
+$ npm install -g @serialport/list
+$ serialport-list
+/dev/tty.Bluetooth-Incoming-Port
+/dev/tty.usbmodem1421    Arduino (www.arduino.cc)
+
+```
+
+## SerialPort List
+
+```bash
+$ npx @serialport/list [options]
+# or
+$ npm install -g @serialport/list
+$ serialport-list [options]
 ```
 
-## `serialport-list`
-`serialport-list` will list all available serial ports in different formats.
+The package `@serialport/list` will install the `serialport-list` cli tool which lists all available serial ports in different formats.
 
 ```bash
 $ serialport-list -h
@@ -43,35 +59,15 @@ $ serialport-list -f jsonline
 {"comName":"/dev/tty.usbmodem1421","manufacturer":"Arduino (www.arduino.cc)","serialNumber":"752303138333518011C1","locationId":"14200000","vendorId":"2341","productId":"0043"}
 ```
 
-## `serialport-term`
-`serialport-term` provides a basic terminal interface for communicating over a serial port. `ctrl+c` will exit.
-
+## SerialPort Repl
 ```bash
-$ serialport-term -h
-
-  Usage: serialport-term -p <port> [options]
-
-  A basic terminal interface for communicating over a serial port. Pressing ctrl+c exits.
-
-  Options:
-
-    -h, --help                     output usage information
-    -V, --version                  output the version number
-    -l --list                      List available ports then exit
-    -p, --port, --portname <port>  Path or name of serial port
-    -b, --baud <baudrate>          Baud rate default: 9600
-    --databits <databits>          Data bits default: 8
-    --parity <parity>              Parity default: none
-    --stopbits <bits>              Stop bits default: 1
-    --echo --localecho             Print characters as you type them
-
-$ serialport-term -l
-/dev/tty.Bluetooth-Incoming-Port
-/dev/tty.usbmodem1421    Arduino (www.arduino.cc)
+$ npx @serialport/repl <port>
+# or
+$ npm install -g @serialport/repl
+$ serialport-repl <port>
 ```
 
-## `serialport-repl`
-`serialport-repl` provides a nodejs repl for working with serialport. This is valuable when debugging.
+The package `@serialport/repl` will install the `serialport-repl` cli tool which provides a nodejs repl for working with serialport. This is valuable when debugging.
 
 You can make use of the `serialport-repl` command with;
 ```bash
@@ -103,3 +99,37 @@ null
   serialport:main opening path: /dev/tty.usbmodem1421 +30s
   serialport:bindings open +1ms
 ```
+
+## SerialPort Terminal
+```bash
+$ npx @serialport/terminal  -p <port> [options]
+# or
+$ npm install -g @serialport/terminal
+$ serialport-terminal  -p <port> [options]
+```
+
+The package `@serialport/terminal` will install the `serialport-terminal` cli tool which provides a basic terminal interface for communicating over a serial port. `ctrl+c` will exit.
+
+```bash
+$ serialport-terminal -h
+
+  Usage: serialport-terminal -p <port> [options]
+
+  A basic terminal interface for communicating over a serial port. Pressing ctrl+c exits.
+
+  Options:
+
+    -h, --help                     output usage information
+    -V, --version                  output the version number
+    -l --list                      List available ports then exit
+    -p, --port, --portname <port>  Path or name of serial port
+    -b, --baud <baudrate>          Baud rate default: 9600
+    --databits <databits>          Data bits default: 8
+    --parity <parity>              Parity default: none
+    --stopbits <bits>              Stop bits default: 1
+    --echo --localecho             Print characters as you type them
+
+$ serialport-terminal -l
+/dev/tty.Bluetooth-Incoming-Port
+/dev/tty.usbmodem1421    Arduino (www.arduino.cc)
+```
diff --git a/package.json b/package.json
@@ -20,7 +20,6 @@
     "publish": "lerna publish",
     "test": "nyc --reporter=html --reporter=text --reporter lcovonly mocha",
     "test:arduino": "TEST_PORT=$(./bin/find-arduino.js) npm test",
-    "test:require": "lerna exec \"node -e \\\"require('./')\\\"\"",
     "test:watch": "mocha -w"
   },
   "repository": {

diff --git a/packages/list/.npmignore b/packages/list/.npmignore
@@ -0,0 +1,2 @@
+*.test.js
+CHANGELOG.md
diff --git a/packages/list/LICENSE b/packages/list/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright 2018 Francis Gulotta. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
diff --git a/packages/list/README.md b/packages/list/README.md
@@ -0,0 +1,36 @@
+## SerialPort List
+
+```bash
+$ npx @serialport/list [options]
+# or
+$ npm install -g @serialport/list
+$ serialport-list [options]
+```
+
+The package `@serialport/list` will install the `serialport-list` cli tool which lists all available serial ports in different formats.
+
+```bash
+$ serialport-list -h
+
+  Usage: serialport-list [options]
+
+  List available serial ports
+
+  Options:
+
+    -h, --help           output usage information
+    -V, --version        output the version number
+    -f, --format <type>  Format the output as text, json, or jsonline. default: text
+
+
+$ serialport-list
+/dev/tty.Bluetooth-Incoming-Port
+/dev/tty.usbmodem1421    Arduino (www.arduino.cc)
+
+$ serialport-list -f json
+[{"comName":"/dev/tty.Bluetooth-Incoming-Port"},{"comName":"/dev/tty.usbmodem1421","manufacturer":"Arduino (www.arduino.cc)","serialNumber":"752303138333518011C1","locationId":"14200000","vendorId":"2341","productId":"0043"}]
+
+$ serialport-list -f jsonline
+{"comName":"/dev/tty.Bluetooth-Incoming-Port"}
+{"comName":"/dev/tty.usbmodem1421","manufacturer":"Arduino (www.arduino.cc)","serialNumber":"752303138333518011C1","locationId":"14200000","vendorId":"2341","productId":"0043"}
+```
diff --git a/packages/list/lib/list.js b/packages/list/lib/list.js
@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const bindings = require('@serialport/bindings')
+const { version } = require('../package.json')
+const args = require('commander')
+
+args
+  .version(version)
+  .description('List available serial ports')
+  .option(
+    '-f, --format <type>',
+    'Format the output as text, json, or jsonl. default: text',
+    /^(text|json|jsonline|jsonl)$/i,
+    'text'
+  )
+  .parse(process.argv)
+
+function jsonl(ports) {
+  ports.forEach(port => {
+    console.log(JSON.stringify(port))
+  })
+}
+
+const formatters = {
+  text(ports) {
+    ports.forEach(port => {
+      console.log(
+        `${port.comName}\t${port.pnpId || ''}\t${port.manufacturer || ''}`
+      )
+    })
+  },
+  json(ports) {
+    console.log(JSON.stringify(ports))
+  },
+  jsonl,
+  jsonline: jsonl,
+}
+
+bindings.list().then(formatters[args.format], err => {
+  console.error(JSON.stringify(err))
+  process.exit(1)
+})
diff --git a/packages/list/package.json b/packages/list/package.json
@@ -0,0 +1,23 @@
+{
+  "name": "@serialport/list",
+  "version": "1.0.0",
+  "main": "lib/list.js",
+  "bin": {
+    "serialport-list": "./lib/list.js"
+  },
+  "dependencies": {
+    "commander": "^2.13.0",
+    "@serialport/bindings": "^2.0.2"
+  },
+  "engines": {
+    "node": ">=6.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/node-serialport/node-serialport.git"
+  }
+}
diff --git a/packages/repl/.npmignore b/packages/repl/.npmignore
@@ -0,0 +1,2 @@
+*.test.js
+CHANGELOG.md
diff --git a/packages/repl/LICENSE b/packages/repl/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright 2018 Francis Gulotta. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
diff --git a/packages/repl/README.md b/packages/repl/README.md
@@ -0,0 +1,40 @@
+## SerialPort Repl
+```bash
+$ npx @serialport/repl <port>
+# or
+$ npm install -g @serialport/repl
+$ serialport-repl <port>
+```
+
+The package `@serialport/repl` will install the `serialport-repl` cli tool which provides a nodejs repl for working with serialport. This is valuable when debugging.
+
+You can make use of the `serialport-repl` command with;
+```bash
+$ serialport-repl # to auto detect an arduino
+$ serialport-repl /dev/tty.usbmodem1421 # to connect to a specific port
+```
+
+It will load a serialport object with debugging turned on.
+```bash
+$ serialport-repl
+  serialport:binding:auto-detect loading DarwinBinding +0ms
+port = SerialPort("/dev/tty.usbmodem1421", { autoOpen: false })
+globals { SerialPort, portName, port }
+> SerialPort.list()
+  serialport:main .list +6s
+[ { comName: '/dev/tty.usbmodem1421',
+    manufacturer: 'Arduino (www.arduino.cc)',
+    serialNumber: '752303138333518011C1',
+    pnpId: undefined,
+    locationId: '14200000',
+    vendorId: '2341',
+    productId: '0043' } ]
+> port.write('Calling all Autobots!')
+true
+> port.read()
+  serialport:main _read queueing _read for after open +1m
+null
+> port.open()
+  serialport:main opening path: /dev/tty.usbmodem1421 +30s
+  serialport:bindings open +1ms
+```
diff --git a/packages/serialport/bin/repl.js → packages/repl/lib/repl.js b/packages/serialport/bin/repl.js → packages/repl/lib/repl.js
@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
+const { promirepl } = require('promirepl')
 const repl = require('repl')
-const promirepl = require('promirepl').promirepl
+const SerialPort = require('serialport')
 
 process.env.DEBUG = process.env.DEBUG || '*'
-const SerialPort = require('../')
 
 // outputs the path to an arduino or nothing
 function findArduino() {

diff --git a/packages/repl/package.json b/packages/repl/package.json
@@ -0,0 +1,23 @@
+{
+  "name": "@serialport/repl",
+  "version": "1.0.0",
+  "main": "lib/repl.js",
+  "bin": {
+    "serialport-repl": "./lib/repl.js"
+  },
+  "dependencies": {
+    "promirepl": "^1.0.1",
+    "serialport": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=6.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/node-serialport/node-serialport.git"
+  }
+}