Remember the Simplicity of BASIC’s Graphics Commands?

LINE (x1,y1)-(x2,y2),color
LINE (x1,y1)-(x2,y2),color,B
LINE (x1,y1)-(x2,y2),color,BF

Some Variants You Probably Didn’t Know About

LINE -(x2,y2),color[,B[F]]
LINE - STEP (dx2,dy2),color[,B[F]]
LINE STEP (dx1,dy1) - (x2,y2),color[,B[F]]
LINE STEP (dx1,dy1) - STEP (dx2,dy2),color[,B[F]]

Compare with Graphics APIs in C, et. al.

/* This example is for AmigaOS, since I
 * know it best.  Demonstrates how to
 * LINE (0,0)-(639,199),1 in BASIC.
 */

RastPort *rp = ... ;
/* ... */
SetAPen(rp, 1);
SetFgMode(rp, JAM1);
SetLineMode(rp, 0xFFFF);
MoveTo(rp, 0, 0);
DrawTo(rp, 639, 199);

Compare with Graphics APIs in C, et. al.

5 lines of C versus 1 for BASIC.
BASIC’s LINE statement supports over 18 different combinations
- Each with consistent and predictable syntax.
- Each with consistent and predictable behavior.
5-line C example illustrates only the most basic LINE functionality.
Most complex functionality translates to about 9 lines of C.
Ratios will vary depending on OS. Windows is more complex than AmigaOS, MacOS is simpler.

Solution 1: Discrete Entry Points for Each Combination

void lineNear_displacedBy_inColor_(dx1, dy1, dx2, dy2, color);
void rectNear_displacedBy_inColor_(dx1, dy1, dx2, dy2, color);
void boxNear_displacedBy_inColor_(dx1, dy1, dx2, dy2, color);
void lineNear_to_inColor_(dx1, dy1, x2, y2, color);
void rectNear_to_inColor_(dx1, dy1, x2, y2, color);
void boxNear_to_inColor_(dx1, dy1, x2, y2, color);
void lineFrom_displacedBy_inColor_(x1, y1, dx2, dy2, color);
void rectFrom_displacedBy_inColor_(x1, y1, dx2, dy2, color);
void boxFrom_displacedBy_inColor_(x1, y1, dx2, dy2, color);
void lineFrom_to_inColor_(x1, y1, x2, y2, color);
void rectFrom_to_inColor_(x1, y1, x2, y2, color);
void boxFrom_to_inColor_(x1, y1, x2, y2, color);
/* ... etc ... */

Solution 2: If You Use OO, You Can Use Fluent Interfaces

Draw.new.from(x1,y1).offsetBy(dx2,dy2).inColor(5).line();

Much easier!!

What’s Happening?!

Draw.new.from(x1,y1).offsetBy(dx2,dy2).inColor(5).line();

Draw.new creates a control block with a default set of fields.
from(x1,y1) configures said control block with an origin coordinate.
offsetBy(dx2,dy2) configures control block with a destination coordinate.
inColor(5) configures the color field.
line(); actually commences the drawing.
After line() finishes, garbage collection ensures memory is reclaimed.

What’s Happening?!

Draw.new.from(x1,y1).offsetBy(dx2,dy2).inColor(5).line();

Notice similarity with creating an activation frame for line()!

What are Fluent Interfaces, Really?

They expose procedure activation frames as first-class objects.
They let you select which procedure binds against the activation frame.
They let the procedure you invoke interpret your activation frame.

What are Fluent Interfaces, Really?

They expose procedure activation frames as first-class objects.
They let you select which procedure binds against the activation frame.
They let the procedure you invoke interpret your activation frame.
They let you create Domain-Specific Languages (DSLs).

Fluent Interfaces in Forth

Remember Declarative, Inquisitive, then Imperative (DItI) pattern?

Fluent Interfaces in Forth

Remember Declarative, Inquisitive, then Imperative (DItI) pattern?
DItI is proper subset of fluent interfaces.
Or, Fluent Interfaces are 100% compatible with DItI pattern.

Fluent Interfaces in Forth

Remember Declarative, Inquisitive, then Imperative (DItI) pattern?
DItI is proper subset of fluent interfaces.
Or, Fluent Interfaces are 100% compatible with DItI pattern.
Works best with vocabulary manipulation to enforce DSL namespaces.

Fluent Interfaces in Forth

But what about these activation frames? Aren’t those anti-Forth?
- Yes.

Fluent Interfaces in Forth

But what about these activation frames? Aren’t those anti-Forth?
- No!
- ALLOT, HERE, MARKER, et. al. do it, when you think about it.

Fluent Interfaces in Forth

But what about these activation frames? Aren’t those anti-Forth?
- No!
- ALLOT, HERE, MARKER, et. al. do it, when you think about it.
Implementing the activation frame is pretty easy, if you’re willing to deal with structures.

Fluent Interfaces in Forth

Let’s clone the DSL for drawing a line.
First, let’s allocate our execution frame.

VOCABULARY DRAW-DSL
\ . . . etc . . .
PREVIOUS

VARIABLE fp
5 CELLS CONSTANT /frame

: draw   fp @ ,  HERE fp !  /frame ALLOT
         DRAW-DSL ;

Fluent Interfaces in Forth

Let’s clone the DSL for drawing a line.
Next, let’s create a few initializations.
First, we need to know our frame offsets.

DRAW-DSL DEFINITIONS
: fp.x1               fp @ ;
: fp.y1               fp @ [ 1 cells ] literal + ;
: fp.x2               fp @ [ 2 cells ] literal + ;
: fp.y2               fp @ [ 3 cells ] literal + ;
: fp.clr              fp @ [ 4 cells ] literal + ;

Fluent Interfaces in Forth

Let’s clone the DSL for drawing a line.
Next, let’s create a few initializations.
Next, we need to write our setters.

DRAW-DSL DEFINITIONS
: from ( x y -- )     fp.y1 !  fp.x1 ! ;
: offsetFrom ( ... )  fp.y1 @ + fp.y1 !  fp.x1 @ + fp.x1 ! ;
: to ( x y -- )       fp.y2 !  fp.x2 ! ;
: offsetTo ( dx dy )  fp.y1 @ + fp.y2 !  fp.x1 @ + fp.x2 ! ;
: inColor ( clr -- )  fp.clr ! ;

Fluent Interfaces in Forth

Let’s clone the DSL for drawing a line.
Finally, we write the procedure which actually does the work.

DRAW-DSL DEFINITIONS
: _line ( -- )        ( bresenham's algorithm ) ;
: _box ( -- )         ( draw y2-y1 number of horizontal lines ) ;
: _rect ( -- )        ( draw four orthogonal lines ) ;

: done                /frame CELL+ NEGATE ALLOT  HERE @ fp !  PREVIOUS ;
: line ( -- )         _line  done ;
: box ( -- )          _box   done ;
: rect ( -- )         _rect  done ;

Fluent Interfaces in Forth

Because we’re working with frames, we should support recursion.
Note that our stack is in the dictionary, not on the data or return stacks.
Indefinite recursion, even on constrained hardware!

: hline   draw
            fp.x1 @ OVER from  fp.x2 @ swap to  fp.clr @ inColor
          line ;

: _box    fp.y2 @  fp.y1 @
          BEGIN   2DUP XOR
          WHILE   DUP hline  1+
          REPEAT ;

Fluent Interfaces in Forth

What happens if we invoke box with from/offsetTo instead of offset/to?

E.g,

draw 0 0 from 639 199 offsetTo 5 inColor line

Fluent Interfaces in Forth

What happens if we invoke box with from/offsetTo instead of offset/to?
Remember that offsetTo computes absolute coordinates as part of its execution.

: offsetTo ( dx dy )  fp.y1 @ + fp.y2 !  fp.x1 @ + fp.x2 ! ;

Therefore, we can invoke line with absolute coordinates from within an invokation of line called with relative coordinates safely!

: hline   draw
            fp.x1 @ OVER from  fp.x2 @ over to  fp.clr @ inColor
          line ;

: _box    fp.y2 @  fp.y1 @
          BEGIN   2DUP XOR
          WHILE   DUP hline  1+
          REPEAT ;

Revisiting LINE in Forth

LINE (0,0)-(10,10),1	draw 0 0 from 10 10 to 1 inColor line
LINE (0,0)-(10,10),1,B	draw 0 0 from 10 10 to 1 inColor rect
LINE (0,0)-(10,10),1,BF	draw 0 0 from 10 10 to 1 inColor box
LINE (0,0)-STEP(10,10),1	draw 0 0 from 10 10 offsetTo 1 inColor line
LINE (0,0)-STEP(10,10),1,B	draw 0 0 from 10 10 offsetTo 1 inColor rect
LINE (0,0)-STEP(10,10),1,BF	draw 0 0 from 10 10 offsetTo 1 inColor box
LINE STEP(0,0)-(10,10),1	draw 0 0 offsetFrom 10 10 to 1 inColor line
LINE STEP(0,0)-(10,10),1,B	draw 0 0 offsetFrom 10 10 to 1 inColor rect
LINE STEP(0,0)-(10,10),1,BF	draw 0 0 offsetFrom 10 10 to 1 inColor box
. . .	. . .

Fin!

Thank you!

Q & A