git stults online u / master README.md
master

Tree @master (Download .tar.gz)

README.md @masterraw · history · blame

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
ulang
--

u is a streaming language for building interpolators.

### overview

The paradigm of u is to construct chains of "one-to-many"
functions. The main language construct is the *stream*. Most things
are streams, or behave consistently with the streaming syntax. Streams
specify how we want to interpolate and segment data. They can be
linked together and channelized so as to pass and transform data
frames in a sequence or parallel sequences. Data *advances* and is
interpolated only when a stream that can generate data is linked to an
output; otherwise the link relationships are promises only.

u includes four primitive stream identifier builtins (we'll just refer
to these as *primitive streams*), which on their surface behave a lot
like primitive types in that they try to promote data elements passed
into them and will throw if an invalid type is passed in or an invalid
operation is performed on their data. They are:

 * `int`
 * `float`
 * `bool`
 * `str`

Comments are in-out style using `~`, like

```
~ this is a comment ~
```

There are several operators; the term "operator" here ise used more
flexibly than operators usual.

 * `=` define
 * `+`, `-`, `*`, `/`, `%` arithmetic operations (bind right)
 * `|`, `&`, `^`, `!` boolean operations (bind right)
 * `==`, `!=`, `<`, `<=`, `>`, `>=` comparison operators (bind right)
 * `:` link
 * `.` dupe
 * `,` tee and join
 * `[]`, `][` channelize and munge
 * `()` parameterize
 * `?`, `!!` throw and catch
 * `@` sync

The following additional keywords are also provided for "traditional"
flow control, code organization, and dependency management outside the
streaming paradigm

 * `do`
 * `end`
 * `break`
 * `goto`
 * `if .. do .. elif do .. else do`
 * `while .. do`
 * `continue`
 * `use`
 * `interface`

There are also some language-specific literals:

 * `null`
 * `true`
 * `false`

### fundamentals

#### define `=`

Define is used to declare a new identifier. An identifier is a token
composed from any number of the following characters
`[a-zA-z0-9_-]`. Identifiers can be used only within the *scope* in
which they are declared and they cannot be redefined within that scope
(redefinition encompassing a redeclaration of the type in question,
not assignment of a literal or instantiated value of a certain
type). The type of an identifier must be explicitly declared or be
inferrable from what is assigned to it. Defining an identifier to be a
literal makes it assume that value. Defining an identifier to be a
stream makes it an instance of that stream (no underlying data is
transferred). Defining an identifier to be another identifier (which is
not a stream definition) functions as an alias.

```
~ a is the integer 10 ~
a = 10
b = 1
a = b ~ legal ~

~ c is an int stream ~
c = int

~ d is the same int stream that c is ~
d = c
c = a ~ illegal ~
```

The primitive streams `bool`, `int`, `float`, and `str` may only be
used as the object of an identifier declaration. That is, they cannot
be used directly to manipulate data, or aliased to something else. Any
identifier defined as an instance of a primitive stream automatically
type-checks any data assigned or passed into it as appropriate. This
will be more clear when we talk about streams and stream linkage
below.

#### scoping, control, and reuse

Identifiers, as well as standard inputs and outputs (which we will
come to shortly) are defined only within a scope. A file itself
defines the highest-level scope called the *file scope*. The only
things permitted within the file scope are

 * any number of `use` directives
 * a single `interface` directive; *or* a single `do .. end` block
 * the declaration of identifiers

Scopes are used to

 * define the equivalent of a program *main* in a file scope
 * protect identifiers from reuse or abuse
 * define anonymous blocks of executable code
 * define named executable blocks of code for reuse

The `do .. end` construct defines a sub-scope within the current scope
-- the scope encompasses everything between the `do` and `end`
words. To make this very explicit, the other control structures, like
`while` and `if`, require `do` to be present and must terminate with
an `end`.

```
~ hello world ~
do
  : "hello world"
end
```

```
do
    ~ an anonymous block (dead code in this case) ~
    do
        x = 10
        y = 11
        while x < y do
            x = x + y
        end
    end
end
```

```
~ a reusable block bound to identifier foo ~
foo = do
    : 10
end
```

Here note an important distinction between reusable and anonymous
blocks. Anonymous blocks can have data written directly to them and
read directly from them at the point of definition. Conversely,
reusable blocks bound to an identifier *cannot* have data written
directly to or read from them. They must first be bound to a new
identifier, in the same way as the primitive streams (primitive stream
*identifiers*) must be.

```
~ because this uses io, not feeding data to it or reading data from it
would result in dead code ~
: do
    x = :
    : x + 2. / 3.
end: 0 3 5 7

~ .. but you *cannot* do the same here .. ~
wiggle = do
    x = :
    : x + 2. / 3.
end

~ ... or do this! exception! ~
wiggle: 0 3 5 7

~ you must do ~
wiggle1 = wiggle
wiggle1: 0 3 5 7
```

The `use` directive allows for one u program file to use code
present in another, like `use package`. Every identifier declared at
the top level of a program file's file scope is available in another
program file `use`ing it by `package.identifier`. Additionally, the
top-level `do .. end` is available by using the read/write link
operator on the file name itself that is the object of the `use`
directive (see below). For example,

```
~ in a file named hello-three-ways.u ~
foo = "hello world"

bar = do
    : "hello" "world"
end

do
    : "hello world"
    baz = 10
end
```
```
~ in another file ~
use hello-three-ways

do
    : hello-three-ways.foo
    ~ writes hello world to standard out ~

    : hello-three-ways.bar
    ~ writes hello\nworld to standard out ~

    : hello-three-ways
    ~ writes hello world to standard out ~

    : hello-three-ways.baz ~ exception -- not available ~
end
```

The `interface` directive is declared at the top of a program
file. That file can then only contain identifiers at the file scope
top level. When another file `use`es a file using the `interface`
directive, it must define all the identifiers declared there.

```
~ in iface.u ~
interface

circle-trace(rad = float, pts = float) = float[2] do
end
```
```
~ in another file ~
use math
use iface

~ *must* define circle-trace as (float, float) = float[2] ~
circle-trace(rad = float, pts = float) = float[2] do
    wedge = 2. * math.pi / pts
    curpt = 0
    while curpt < pts do
        : rad * math.cos(curpt * wedge), rad * math.sin(curpt * wedge)
	curpt = curpt + 1
    end
end
```

#### streams and the link operator `:`

The link operator defines a data flow relationship between two
language constructs, usually streams. It is used to sequence language
constructs together into a read-from / write-to relationship. The data
flow goes from right to left: data is read from the right, and written
to the left. The unit of data flow is called a *frame*, which is
composed of some number of *channels*. The number of channels is
referred to as the *width*. With no language identifier or literal,
link refers (in the appropriate place) to the standard input or output
stream *in the current scope*. Standard input and output must be used
only within a subscope of the file scope.

```
do
    ~ write 10 to standard out ~
    : 10

    ~ read the string literal "quit" from standard in ~
    "quit" :

    ~ write to a stream named foo, which is an int stream ~
    foo = int
    foo: 1 2 3

    ~ illegal -- int is a primitive stream! ~
    int: 5 5 5
end
```

When a data element is written to a stream, it is added to the tail of
that stream like the stream was a fifo queue. The stream will
automatically interpret that data element as a frame. The frames
remain in a stream until that stream, or some stream it is linked to,
is linked to an output. At that point, each frame in the stream is
interpolated from the previous frame in the stream, and those values
are written out to the next linked construct, after which the frame is
removed.

```
do
    foo = int
    foo: 1 2 3
    : foo
    ~ 1\n2\n3 written to stdout ~
end
```

Notice that elements (in this case literals but we'll get to
identifiers shortly) separated by white space are sequentially written
into the stream. Where is the interpolation, you might ask. Actually,
it's already there -- the primitive streams by default interpolate by
the relation `(a, b) -> b`. We will talk about changing this default
and defining initialization parameters of this kind when we talk about
parameterization, below.

There is some special syntax around `=` and `:` allowing for
initializer list and direct write-through functionality.

```
: foo = bool: true
~ is the same as ~
foo = bool
foo: true
: foo

~ defines x to be next frame element from the standard input stream ~
x = :
```

#### parameterizing identifiers with `()`

The parameterize operator allows for initialization data to be passed
into a block identifier at the time of definition. Identifiers that do
not have initializers or have default values can simply omit the `()`
when they are the object of a define operation. What the fuck does
this mean?

For example take the primitive streams. They each can take a single
parameter which is the interpolation increment. They default to no
interpolation between elements. So writing `int` is the same as
writing `int(null)`, because the `null` increment is the default and
the `int` stream internal logic handles it appropriately.

```
: by-one = int(1) : 0 2
~ 0\n1\n2 goes to standard out ~

: play-telephone = str(" ") : "hello" "world" "!"
~ hello\nhello world\nhello world ! ~
```

When we define a block of code by assigning an identifier to it, we
can, as part of the definition, use the parameterize operation to
define input parameters. These parameters are themselves named
identifiers, which can abuse the initializer list syntax to define
default values.

```
prefixed-write(prefix = str: "") = str do
    in = :
    : in = prefix + in
end

: my-prefixed-write = prefixed-write("john wayne says ") : "hello"
~ john wayne says hello ~
: my-prefixed-write: "goodbye"
~ john wayne says goodbye ~
```

#### "streaming" arithmetic

Arithemetic and boolean operations (and expressions composed of them)
exist within two different contexts. The first is as the rval of a
define operator. In this case, they function "as normal".

```
x = 10 + 2 / 3
~ x is 4 ~
```

The other case is as the rval of a link operation. In this case, the
operators bind right to the next literal or identifier, and represent
a relationship with the previous element in the stream they are being
written to.

```
~ foo is an int stream ~
: foo: 10 + 2 / 3
~ 10\n12\n4 ~
```

Parentheses can be overloaded to "parameterize" what would be a
sequence of terms into a single expression. In this case, the group is
evaluated before it is passed in:

```
: foo: (10 + 2 / 3.)
~ 4 ~
```

What happens when an arithmetic operation is applied to an arbitrary
identifer, say an float stream? In that case, the operator again binds
right, and is then distributed across each element coming from the
target that it binds to. Whether the distribution happens before or
after interpolation depends on the presence of the link operator.

```
~ foo and bar are float streams ~

~ each element from bar gets - applied to it; then that is
interpolated and written to foo ~
foo: - bar

~ the same, but the result must be captured by a third identifier --
it's out of place ~
foo - bar

~ each interpolated element from bar gets written to the foo as
-element, so the operation is accumulative  ~
foo: - :bar

~ the same, but the result must be captured by a third identifier --
it's out of place ~
foo - :bar
```

#### duping with `.`

The dupe operator indicates that we want to write the previous element
to the stream again.

```
: "hello" .
~ hello\nhello ~
```

#### tee, join, channelize, and munge with `,` `[]` and `][`

The channelize and join operators functionally go together. Joined
data needs channels on the left; channelized streams do not
necessarily need joined data. Channelize says that a stream should
split elements written to it into a number of parallel channels. Join
allows data to be written or read in parallel to or from some number
of channels. Non-joined values are written into or read from the first
channel.

```
a, b :
a, b = :
: a, b
```

Notice that a stream `foo` is equivalent to `foo[1]`, and in fact to
`int(null)[1]`.

Differences between comman-separated and sequential. Need a frame
notation for literals so that the commas are not so confusing.

#### syncing with `@`

The sync operator creates instances of a typeless element with no
width that can be written to any channel. Interpolation happening in a
channel will wait at a sync element until all other channels in the
same stream also reach that element. Then all the channels will
continue interpolating.

```
sync = @
```

#### exception handling with `?` and `!!`

The throw and catch operators allow for exceptions to be raised and
handled. There are two ways to raise an exception. The first is to
write the throw operator into a stream, followed by a literal or
identifier. The throw operator suspends the stream's type checking and
allows for whatever follows the operator to be handled.

```
float: ? "error!"
```

Pushing an exception into a stream can be useful because it can allow
for interesting flow control. This is because exceptions thrown in
this way will be raised when it is time to interpolate the throw
operator element in the stream. In fact, when something tries to read
from an empty stream, it throws an exception that delivers control to
the line following the read.

To raise immediately outside the stream mechanisms, just use the throw
operator directly, like

```
? "die immediately"
```