# @supercollider/lang
> Client library for the SuperCollider language: sclang. This package enables calling SuperCollider code from JavaScript.
Latest version **1.0.1** (published 2020-01-30) · MIT license · 0 weekly downloads
## Install
```sh
npm install @supercollider/lang
pnpm add @supercollider/lang
yarn add @supercollider/lang
bun add @supercollider/lang
```
Provides the commands `supercollider`, `compile-synthdefs`.
## Health
**Score 20/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities.
Warnings: low downloads; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 1.0.1 |
| Published | 2020-01-30 |
| First published | 2019-10-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 9 |
| Unpacked size | 201.4 KB |
| Known vulnerabilities | 0 (+5 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 507 |
| Author | Chris Sattinger |
| Maintainers | crucialfelix |
| Keywords | supercollider |
## Links
- npm: https://www.npmjs.com/package/@supercollider/lang
- Repository: https://github.com/crucialfelix/supercolliderjs
- Homepage: https://crucialfelix.github.io/supercolliderjs/
- Issues: https://github.com/crucialfelix/supercolliderjs/issues
- npm.io page: https://npm.io/package/@supercollider/lang
## Dependencies (9)
- [cuid](https://npm.io/package/cuid.md) ^2.1.6
- [temp](https://npm.io/package/temp.md) ~0.9.0
- [tslib](https://npm.io/package/tslib.md) 1.10.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.15
- [js-yaml](https://npm.io/package/js-yaml.md) 3.13.1
- [commander](https://npm.io/package/commander.md) ^2.9.0
- [untildify](https://npm.io/package/untildify.md) ^4.0.0
- [@supercollider/logger](https://npm.io/package/@supercollider/logger.md) ^1.0.0
- [@supercollider/server](https://npm.io/package/@supercollider/server.md) ^1.0.0
## Alternatives
- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads
## Recent versions
- 1.0.1 (latest) — 2020-01-30
- 1.0.0 — 2020-01-09
- 1.0.0-beta.1 — 2019-11-27
- 1.0.0-beta.0 — 2019-11-24
- 1.0.0-alpha.2 — 2019-11-15
- 1.0.0-alpha.1 — 2019-11-05
- 1.0.0-alpha.0 — 2019-10-20
## README
# @supercollider/lang
[![NPM downloads][npm-downloads-image]][npm-url] [![MIT License][license-image]][license-url]
Client library for the SuperCollider language: sclang. This package enables calling SuperCollider code from JavaScript.
- Spawns and manages one or more `sclang` processes.
- Interpret SuperCollider code and return results as equivalent JavaScript objects.
- Compile SynthDefs written in the SuperCollider language and return byte code.
- Used by atom-supercollider
If you are building something that just needs to communicate with sclang then you can install just this package.
## Usage
### Boot
Start the `sclang` executable as a subprocess, returning a Promise.
```js
const sc = require("supercolliderjs");
sc.lang.boot().then(
function(lang) {
// Up and ready for action
console.log(lang);
// quit the process programmatically
lang.quit();
},
// Error handler if it fails to start or fails to compile
error => console.error,
);
```
source
```js
const Lang = require("supercolliderjs").lang.default;
const l = new Lang(options);
l.boot();
```
`sclang` will compile it's class library, and this may result in syntax or compile errors.
Resolves with a list of SuperCollider class file directories that were compiled:
```typescript
{dirs: [/*compiled directories*/]}
```
or rejects with:
```typescript
{
dirs: [],
compileErrors: [],
parseErrors: [],
duplicateClasses: [],
errors[],
extensionErrors: [],
stdout: 'compiling class library...etc.'
}
```
See `SclangCompileResult` in `packages/lang/src/internals/sclang-io.ts` for full details.
### Interpret simple async await style
```js
const sc = require("supercolliderjs");
sc.lang.boot().then(async function(lang) {
// This function is declared as `async`
// so for any function calls that return a Promise we can `await` the result.
// This is an `async` function, so we can `await` the results of Promises.
const pyr8 = await lang.interpret("(1..8).pyramid");
console.log(pyr8);
const threePromises = [16, 24, 32].map(n => {
return lang.interpret(`(1..${n}).pyramid`);
});
// `interpret` many at the same time and wait until all are fulfilled.
// Note that `lang` is single threaded,
// so the requests will still be processed by the interpreter one at a time.
const pyrs = await Promise.all(threePromises);
console.log(pyrs);
// Get a list of all UGen subclasses
const allUgens = await lang.interpret("UGen.allSubclasses");
// Post each one to STDOUT
allUgens.forEach(ugenClass => console.log(ugenClass));
await lang.quit();
});
```
source
### Interpret with full error handling
```js
const sc = require("supercolliderjs");
function makePyramid(lang) {
lang.interpret("(1..8).pyramid").then(
function(result) {
// result is a native javascript array
console.log("= " + result);
lang.quit();
},
function(error) {
// syntax or runtime errors
// are returned as javascript objects
console.error(error);
},
);
}
// Verbose example to show Promises and full error handling
sc.lang.boot().then(
// ok booted
lang => {
makePyramid(lang);
},
// failed to boot
error => {
console.error(error);
// Either:
// 1. The executable may be missing, incorrect path etc.
// 2. The class library may have failed with compile errors
},
);
```
source
### Options
```typescript
sc.lang.boot(options)
// or
const Lang = require("supercolliderjs").lang.default;
const l = new Lang(options);
l.boot();
```
```typescript
{
// post verbose messages to console
debug: boolean;
// echo all commands sent TO sclang to console
echo: boolean;
// provide an alternate console like object for logging. eg. winston
log?: Console;
// path to sclang executable
sclang: string;
// To start sclang and immediately execute one file
executeFile?: string;
// path to existing non-default conf file
sclang_conf?: string;
// post sclang stdin to console
stdin: boolean;
// if specifying a non-default conf file then you may wish to fail if you got the path wrong
// rather than fall back to the default one
failIfSclangConfIsMissing: boolean;
// pass in a configuration without having to write it to a file
conf: SCLangConf;
}
```
See: packages/lang/src/options.ts
### executeFile
```js
await lang.executeFile("./some-supercollider-piece.scd");
```
Documentation
-------------
[Documentation](https://crucialfelix.github.io/supercolliderjs/#/packages/lang/api)
Compatibility
-------------
Works on Node 10+
Source code is written in TypeScript and is usable in JavaScript [es2018](https://2ality.com/2017/02/ecmascript-2018.html) or [TypeScript](https://www.typescriptlang.org/docs/home.html) projects.
Contribute
----------
- Issue Tracker: https://github.com/crucialfelix/supercolliderjs/issues
- Source Code: https://github.com/crucialfelix/supercolliderjs
License
-------
MIT license
[license-image]: http://img.shields.io/badge/license-MIT-blue.svg?style=flat
[license-url]: LICENSE
[npm-url]: https://npmjs.org/package/@supercollider/lang
[npm-version-image]: http://img.shields.io/npm/v/@supercollider/lang.svg?style=flat
[npm-downloads-image]: http://img.shields.io/npm/dm/@supercollider/lang.svg?style=flat
[travis-url]: http://travis-ci.org/crucialfelix/supercolliderjs
[travis-image]: https://travis-ci.org/crucialfelix/supercolliderjs.svg?branch=master
---
_Source: https://npm.io/package/@supercollider/lang · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._