Tweak stdlib semantics to remove past tense verbs

Favor creating copies.
Favor popping the pre-existing scale.

ref #256

documentation/advanced-dsl.md

@@ -155,7 +155,7 @@ Ternary expressions short-circuit i.e. only the test expression and the chosen r
 Functions are declared using the `riff` keyword followed by the name of the function followed by the parameters of the function.
 ```ocaml
 riff subharmonics(start, end) {
-  return retroverted(start::end)
+  return /end::start
 }
 ```
 Above the `return` statement is suprefluous. We could've left it out and let the result unroll out of the block.
@@ -165,7 +165,7 @@ Default values for function parameters may be given using `param = value` syntax
 Due to popular demand there's also the `fn` alias for function declaration.
 ```ocaml
 fn pythagoras(up, down = 0) {
-  sorted([3^i rdc 2 for i of [-down..up]])
+  sort([3^i rdc 2 for i of [-down..up]])
 }
 ```
 
@@ -174,8 +174,21 @@ Once declared, functions can be called: `subharmonics(4, 8)` evaluates to `[8/7,
 
 while `pythagoras(4)` evaluates to `[9/8, 81/64, 3/2, 27/16, 2]`. The missing `down` argument defaulted to `0`.
 
+#### Stblib conventions
+You may have noticed that we passed an argument to `sort` in the body of `fn pythagoras`. We could've achieved the same with.
+```ocaml
+fn pythagoras(up, down = 0) {
+  [3^i rdc 2 for i of [-down..up]]
+  return sort()
+}
+```
+
+This is because by convention built-in and standard library functions use the popped parent scale `££` (i.e. `pop$$`) as a default argument. If an argument is passed in, the pop doesn't happen and anything the riff/function produces is concatenated onto the current scale instead of replacing its contents.
+
+Some functions like `sort` and `reverse` have in-place variants (`sortInPlace` and `reverseInplace`) that return nothing but modify the contents of the input array instead.
+
 ### Lambda expressions
-Functions can be defined inline using the arrow (`=>`). e.g. `const subharmonics = ((start, end) => retroverted(start::end))`.
+Functions can be defined inline using the arrow (`=>`). e.g. `const subharmonics = ((start, end) => retrovert(start::end))`.
 
 ## Throwing
 To interupt execution you can throw a string message.
@@ -207,7 +220,7 @@ sort()
 ```
 This first results in `$ = [3, 5, 7, 11, 13, 17]` which gets reduced to `$ = [3/2, 5/4, 7/4, 11/8, 13/8, 17/16]`. Adding the octave and sorting gives the final result `$ = [17/16, 5/4, 11/8, 3/2, 13/8, 7/4, 2]`.
 
-Or the same with a oneliner `sorted(primes(17) rdc 2)` demonstrating the utility of broadcasting and *ceiling reduction* in a context where the unison is implicit and coincides with repeated octaves.
+Or the same with a oneliner `sort(primes(17) rdc 2)` demonstrating the utility of broadcasting and *ceiling reduction* in a context where the unison is implicit and coincides with repeated octaves.
 
 ## Stdlib
 SonicWeave comes with batteries included.

documentation/intermediate-dsl.md

@@ -616,7 +616,7 @@ The logarithmic rounding operator (`by`) measures closeness geometrically `dista
 
 The non-ceiling a.k.a floor variants of modulo behave as they commonly do in mathematics where `x mod x` evaluates to `0` while the ceiling variants are more useful in a musical context.
 
-Just as the clockface starts from 12 `12 modc 12` evaluates to `12`. The fact that `P1 modc P8` evaluates to `P8` and that the unison is implicit in SonicWeave environments like Scale Workshop means that the major pentatonic scale becomes a simple oneliner `sorted([-1..3] * P5 modc P8)` evaluating to:
+Just as the clockface starts from 12 `12 modc 12` evaluates to `12`. The fact that `P1 modc P8` evaluates to `P8` and that the unison is implicit in SonicWeave environments like Scale Workshop means that the major pentatonic scale becomes a simple oneliner `sort([-1..3] * P5 modc P8)` evaluating to:
 ```ocaml
 M2
 P4

examples/hexany.sw

@@ -19,11 +19,11 @@ for (const i in factors) {
 
 (* Now we have a scale with combinations {3, 5, 7, 15, 21, 35} (in some order) *)
 
-(* Make 3 the root *)
+(* Make 3 the root using implicit mapping *)
 combo => combo % 3
 
-(* Reduce each by the octave *)
-combo => combo rd 2
+(* Reduce each by the octave using vector broadcasting over the popped scale *)
+pop$ rd 2
 
 (* Sort in ascending order *)
 sort()

src/parser/__tests__/expression.spec.ts

@@ -685,7 +685,7 @@ describe('SonicWeave expression evaluator', () => {
   });
 
   it('has array comprehensions', () => {
-    const pyth12 = evaluate('map(str, sorted([3^i rdc 2 for i of [-4..7]]))');
+    const pyth12 = evaluate('map(str, sort([3^i rdc 2 for i of [-4..7]]))');
     expect(pyth12).toEqual([
       '2187/2048',
       '9/8',
@@ -1742,7 +1742,7 @@ describe('SonicWeave expression evaluator', () => {
   });
 
   it('can sort an array of strings', () => {
-    const swac = evaluate('sorted([..."SonicWeave"])') as string[];
+    const swac = evaluate('sort([..."SonicWeave"])') as string[];
     expect(swac.join('')).toBe('SWaceeinov');
   });
 

src/parser/__tests__/source.spec.ts

@@ -159,7 +159,7 @@ describe('SonicWeave parser', () => {
     const scale = parseSource(`
       const segment = [1..5];
       segment;
-      reverse(segment);
+      reverseInPlace(segment);
       map(i => i + 10, segment);
     `);
     expect(scale).toHaveLength(10);
@@ -1313,9 +1313,9 @@ describe('SonicWeave parser', () => {
     const scale = expand(`{
       riff popSort(i) {
         if (isArray(i)) {
-          return sorted(popAll(i));
+          return sort(popAll(i));
         }
-        return sorted(popAll($$));
+        return sort(popAll($$));
       }
 
       5:8:7:9:6:10;
@@ -1850,7 +1850,7 @@ describe('SonicWeave parser', () => {
       5/4
       3/2
       2/1
-      sorted(%£ rdc pop$[-1])
+      sort(%£ rdc pop$[-1])
     `);
     expect(scale).toEqual(['4/3', '8/5', '2']);
   });
@@ -1881,4 +1881,26 @@ describe('SonicWeave parser', () => {
       '12\\12',
     ]);
   });
+
+  it('can label intervals after generating', () => {
+    const scale = parseSource(`
+      4/3
+      3/2
+      2
+      £ ["fourth", "fifth", "octave"]
+    `);
+    expect(scale).toHaveLength(3);
+    expect(scale[0].label).toBe('fourth');
+    expect(scale[1].label).toBe('fifth');
+    expect(scale[2].label).toBe('octave');
+  });
+
+  it('can paint the whole scale', () => {
+    const scale = expand('3::6;white;£ "bob"');
+    expect(scale).toEqual([
+      '4/3 "bob" white',
+      '5/3 "bob" white',
+      '6/3 "bob" white',
+    ]);
+  });
 });

src/parser/__tests__/stdlib.spec.ts

@@ -400,19 +400,19 @@ describe('SonicWeave standard library', () => {
   });
 
   it('can spell the just major chord sub-overtonally', () => {
-    const subOvertone = parseSource('revposed(6:5:4)');
+    const subOvertone = parseSource('revpose(6:5:4)');
     expect(subOvertone[0].totalCents()).toBeCloseTo(386.313714); // major third
     expect(subOvertone[1].totalCents()).toBeCloseTo(701.955001); // perfect fifth
   });
 
   it('can spell the just major chord retroverted', () => {
-    const retroversion = parseSource('retroverted(10:12:15)');
+    const retroversion = parseSource('retrovert(10:12:15)');
     expect(retroversion[0].totalCents()).toBeCloseTo(386.313714); // major third
     expect(retroversion[1].totalCents()).toBeCloseTo(701.955001); // perfect fifth
   });
 
   it('can spell the just major chord reflected', () => {
-    const reflection = parseSource('reflected(15:12:10)');
+    const reflection = parseSource('reflect(15:12:10)');
     expect(reflection[0].totalCents()).toBeCloseTo(386.313714); // major third
     expect(reflection[1].totalCents()).toBeCloseTo(701.955001); // perfect fifth
   });
@@ -438,13 +438,13 @@ describe('SonicWeave standard library', () => {
   });
 
   it('can spell the just minor chord in first inversion with root on 1/1', () => {
-    const firstInversion = parseSource('reflected(3:5:4)');
+    const firstInversion = parseSource('reflect(3:5:4)');
     expect(firstInversion[0].totalCents()).toBeCloseTo(-884.358713); // major sixth
     expect(firstInversion[1].totalCents()).toBeCloseTo(-498.044999); // perfect fourth
   });
 
   it('can spell the just minor chord in second inversion with root on 1/1', () => {
-    const secondInversion = parseSource('reflected(6:5:8)');
+    const secondInversion = parseSource('reflect(6:5:8)');
     expect(secondInversion[0].totalCents()).toBeCloseTo(315.641287); // major sixth
     expect(secondInversion[1].totalCents()).toBeCloseTo(-498.044999); // perfect fourth
   });
@@ -498,25 +498,12 @@ describe('SonicWeave standard library', () => {
   });
 
   it('has a copying repeater', () => {
-    const bigScale = expand('repeated(2, 3::6)');
+    const bigScale = expand('repeat(2, 3::6)');
     // XXX: Would be cool if that last 4/1 was 12/3, but can't come up
     // with formatting rules that wouldn't mess up everything else.
     expect(bigScale).toEqual(['4/3', '5/3', '6/3', '8/3', '10/3', '4/1']);
   });
 
-  it('can label intervals after generating', () => {
-    const scale = parseSource(`
-      4/3
-      3/2
-      2
-      label(["fourth", "fifth", "octave"])
-    `);
-    expect(scale).toHaveLength(3);
-    expect(scale[0].label).toBe('fourth');
-    expect(scale[1].label).toBe('fifth');
-    expect(scale[2].label).toBe('octave');
-  });
-
   it('preserves color upon reflection', () => {
     const scale = parseSource('4/3 green;3/2;2/1 red;reflect()');
     expect(scale).toHaveLength(3);
@@ -757,8 +744,8 @@ describe('SonicWeave standard library', () => {
       const ls = labelsOf()
       clear()
       3::6
-      label(cs)
-      label(ls)
+      £ cs
+      £ ls
     }`);
     expect(scale).toEqual(['4/3 "one" red', '5/3 "two"', '6/3']);
   });
@@ -808,8 +795,8 @@ describe('SonicWeave standard library', () => {
 
   it('has inline labeling', () => {
     const pythagoras = expand(`
-      labeled(['F', 'C', 'G', 'D', 'A', 'E', 'B'], [3^i rdc 2 white for i of [-2..4]])
-      labeled(['Gb', 'Db', 'Ab', 'Eb', 'Bb'], [3^i rdc 2 black for i of [-7..-3]])
+      ['F', 'C', 'G', 'D', 'A', 'E', 'B'] [3^i rdc 2 white for i of [-2..4]]
+      ['Gb', 'Db', 'Ab', 'Eb', 'Bb'] [3^i rdc 2 black for i of [-7..-3]]
       sort()
     `);
     expect(pythagoras).toEqual([
@@ -920,15 +907,6 @@ describe('SonicWeave standard library', () => {
     ]);
   });
 
-  it('can paint the whole scale', () => {
-    const scale = expand('3::6;white;label("bob")');
-    expect(scale).toEqual([
-      '4/3 "bob" white',
-      '5/3 "bob" white',
-      '6/3 "bob" white',
-    ]);
-  });
-
   it('can detect domains (linear)', () => {
     const scale = expand(
       '10/8;12/10;7/6;stack();i => simplify(i) if isLinear(i) else i'
@@ -1008,12 +986,12 @@ describe('SonicWeave standard library', () => {
   });
 
   it('is stacked', () => {
-    const scale = expand('stacked([5/4, 6/5])');
+    const scale = expand('stack([5/4, 6/5])');
     expect(scale).toEqual(['5/4', '3/2']);
   });
 
   it("isn't that stacked actually", () => {
-    const scale = expand('unstacked([5/4, 3/2])');
+    const scale = expand('unstack([5/4, 3/2])');
     expect(scale).toEqual(['5/4', '6/5']);
   });
 

src/parser/expression.ts

@@ -902,6 +902,15 @@ export class ExpressionVisitor {
       return empty;
     }
 
+    if (
+      node.start === null &&
+      node.second === null &&
+      node.penultimate === false &&
+      node.end === null
+    ) {
+      return typeof object === 'string' ? object : ([...object] as Interval[]);
+    }
+
     let start = 0;
     let step = 1;
     const pu = node.penultimate;

src/parser/statement.ts

@@ -7,7 +7,7 @@ import {
   repr,
   upcastBool,
   SonicWeavePrimitive,
-  sort,
+  sortInPlace,
   temper,
   absolute,
 } from '../stdlib';
@@ -866,7 +866,7 @@ export class StatementVisitor {
       }
       const tail = scale.slice(-entries.length);
       scale.length = scale.length - tail.length;
-      sort.bind(subVisitor)(tail);
+      sortInPlace.bind(subVisitor)(tail);
       scale.push(...tail);
     } else {
       this.spendGas(scale.length);