Skip to content
This repository has been archived by the owner on Jul 11, 2023. It is now read-only.

Latest commit

 

History

History
162 lines (144 loc) · 8.59 KB

README.md

File metadata and controls

162 lines (144 loc) · 8.59 KB
Raw

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. [email protected])
    • 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 [email protected])
  • listTemplates(callbacks, query, [options]) Return all available templates satisfying query
    • callbacks: standard set of UI hooks
    • query: semver-compliant string (e.g. template or [email protected] 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 [email protected] 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

development

  1. clone the repository
  2. run npm i in the project root
  3. run npm run build to generate the transpiled output
  4. ...
  5. profit