@purduesigbots/pros-cli-middleware NPM

pros-cli-middleware

node abstraction layer for PROS CLI

usage

run npm i --save @purduesigbots/pros-cli-middleware to add to your project

import functions into files:

import { listTemplates } from '@purduesigbots/pros-cli-middleware'

functions

all the functions listed below return a promise that resolves when the command exits successfully. this means that there are effectively two ways to call any of these functions:

let r
try {
  r = await listTemplates(...)
} catch e {
  console.error(e)
}

listTemplates(...).then(r => {...}).catch(e => console.error(e))

conductor

applyTemplate(callbacks, path, query, [options]) Upgrade or install a template to a PROS project
- callbacks: standard set of UI hooks
- path: path to PROS project
- query: semver-compliant string (e.g. template@1.0.1)
- options: an object containing zero or one each of the following fields
  - upgrade: boolean: allow upgrading templates
  - install: boolean: allow installing templates
  - download: boolean: allow downloading templates (if false, will only consider local templates)
  - user: boolean: forcibly replace all user files in templates
  - system: boolean: force insertion of system files into the project
fetchTemplate(callbacks, query) Fetch/dowload a template from a depot
- callbacks: standard set of UI hooks
- query: semver-compliant string (e.g. template or template@^0.7.0 or template@1.0.0)
listTemplates(callbacks, query, [options]) Return all available templates satisfying query
- callbacks: standard set of UI hooks
- query: semver-compliant string (e.g. template or template@1.0.1 or template^0.7.0 or 1.0.0)
- options: an object containing zero or one each of the following fields
  - offline: boolean: return offline templates
  - online: boolean: return online templates
  - refresh: boolean: force refresh of remote listings
  - limit: number: limit number of templates returned
purgeTemplate(callbacks, query, [options]) Purge templates satisfying query from the local cache
- callbacks: standard set of UI hooks
- query: semver-compliant string (e.g. template or template@1.0.1 or template^0.7.0 or 1.0.0)
- options: an object containing zero or one each of the following fields
  - force: do not prompt for removal of multiple templates
getProjectInfo(callbacks, path, [options]) Return information about a PROS project
- callbacks: standard set of UI hooks
- path: path to PROS project
- options: an object containing zero or one each of the following fields
- upgrades: boolean: add list of upgradable versions for templates that are out of date
createNewProject(callbacks, path, version, [platform='v5', options]) Create a new PROS project
- callbacks: standard set of UI hooks
- path: path at which to create project
- version: the version of the kernel to use when creating the project. can be 'latest'
- target: optionally specify the platform to target. can be either 'v5' or 'cortex'
- options: an object containing zero or one each of the following fields
  - user: boolean: forcibly replace all user files in templates
  - system: boolean: forcibly replace all system files in templates
  - refresh: boolean: force refresh of remote listings
  - compile: boolean: compile the project immediately after creation from version 1.0.0 (CLI version >=3.0.8)
  - cache: boolean: compile the project immediately after creation and build compile_commands.json file for cquery from version 1.0.0 (CLI version >=3.0.8)
upgradeProject(callbacks, path, version, [options]) Upgrade a PROS project
- callbacks: standard set of UI hooks
- path: path to PROS project
- version: version to upgrade project to
- options: an object containing zero or one each of the following fields
  - install: boolean: install libraries that are not already installed
  - download: boolean: download templates if not present locally (otherwise use latest available locally)
  - user: boolean: forcibly replace all user files in templates
  - system: boolean forcibly replace all system files in templates

general

listDevices(callbacks, [target]) List connected VEX devices
- callbacks: standard set of UI hooks
- target: 'v5'|'cortex: optionally limit results to those matching the specified target
uploadProject(callbacks, path, [options]) Upload a PROS project
- callbacks: standard set of UI hooks
- path: path to PROS project
- options: an object containing zero or one each of the following fields
  - run: boolean: run the program immmediately after uploading
  - name: string: name of the project on the uC (only applies for v5-targeted projects)
  - slot: number: the slot to which the program will be uploaded on the uC (only applies for v5-targeted projects)

v5 utility functions

listFiles(callbacks, [port]) List files on a connected V5 device
- callbacks: standard set of UI hooks
- port: string specifying the port of the device you wish to interact with. if unspecified, the CLI will try to choose a port. if multiple devices are connected, the CLI will prompt for a choice
removeAll(callbacks, [port]) Remove all program files on a connected V5 device
- callbacks: standard set of UI hooks
- port: string specifying the port of the device you wish to interact with. if unspecified, the CLI will try to choose a port. if multiple devices are connected, the CLI will prompt for a choice
removeFile(callbacks, file, [options, port]) Remove a program file from a connected V5 device
- callbacks: standard set of UI hooks
- file: the file to remove
- options: an object containing zero or one each of the following keys
  - all: boolean: erase all files matching base name
- port: string specifying the port of the device you wish to interact with. if unspecified, the CLI will try to choose a port. if multiple devices are connected, the CLI will prompt for a choice
runProgram(callbacks, [file, port]) Run a program on a connected V5 device
- callbacks: standard set of UI hooks
- file: the file to run. if unspecified, the CLI will attempt to find the correct name based on the CWD's PROS project (note: this will not work at present-- please specify a file for now)
- port: string specifying the port of the device you wish to interact with. if unspecified, the CLI will try to choose a port. if multiple devices are connected, the CLI will prompt for a choice
systemStatus(callbacks, [port]) Display information about a connected V5 device
- callbacks: standard set of UI hooks
- port: string specifying the port of the device you wish to interact with. if unspecified, the CLI will try to choose a port. if multiple devices are connected, the CLI will prompt for a choice
stopProgram(callbacks, [file, port]) Stop a program on a connected V5 device
- callbacks: standard set of UI hooks
- file: the file to run. if unspecified, the CLI will attempt to find the correct name based on the CWD's PROS project (note: this will not work at present-- please specify a file for now)
- port: string specifying the port of the device you wish to interact with. if unspecified, the CLI will try to choose a port. if multiple devices are connected, the CLI will prompt for a choice

callbacks

each function listed above takes for its first parameter a set of callbacks whose purpose is to provide an interface for GUIs to interact with data returned from the CLI. the specification for this object is as follows:

{
  notify: (data: any) => void,
  log: (data: any) => void,
  prompt: (data: any, callback: (val: any) => boolean) => void,
  finalize: (data: any) => void
}

each callback corresponds to an event that will be propagated up from an invocation of a CLI command:

notify: fired for general information updates that occur as the command runs. possible events include notify/progress (update a progress bar) and notify/echo (inform about significant operations, e.g. updating remote listings)
log: fired for debugging information about the invoked command, including warnings and errors that occur
prompt: fired when the command requests user input. this callback must in turn call the passed callback with the result of the user's input
finalize: fired just before the command exits, sending the resultant data from the command to the UI