joy-in-the-morning/doc/joy.texi

\input texinfo
@c -*-texinfo-*-

@c %**start of header
@setfilename joy.info
@documentencoding UTF-8
@settitle Guile Joy Reference Manual
@c %**end of header

@include version.texi

@copying
Copyright @copyright{} 2016, 2017, 2018, 2020 Eric Bavier

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end copying

@dircategory Software development
@direntry
* joy: (joy).         Compiler for the Joy language.
@end direntry

@titlepage
@title Joy Reference Manual
@subtitle A compiler for the Joy programming language
@author Eric Bavier

@page
@vskip 0pt plus 1fill
Edition @value{EDITION} @*
@value{UPDATED} @*

@insertcopying
@end titlepage

@contents

@c **********************************************************************
@node Top
@top Joy

This document describes Joy version @value{VERSION}, an implementation
of the Joy programming language.

@menu
* Introduction::                What is Joy?
* Installation::                Installing Joy.
* Invoking joy::                Running the compiler.
* Programming in Joy::          The Joy of programming.
* Interactive Joy::             Programming interactively with Joy.
* API Reference::               Joy batteries included.
* GNU Free Documentation License::  The license of this manual.
@end menu

@c **********************************************************************
@node Introduction
@chapter Introduction

Joy is an implementation of the purely functional, concatenative
programming language originally invented by Manfred Thun.  It is
implemented using Guile's multi-language support.  This implementation
strays a bit from the reference implementation written in C but is
mostly compatible, except for the notable lack of support for ``sets''.

@node Installation
@chapter Installation

Installing Joy from source uses the same build procedure as that for GNU
software.  See the files @file{README} and @file{INSTALL} in the source
tree for additional details.  It requires
@url{http://gnu.org/software/guile/, GNU Guile}.

After building Joy successfully, it is a good idea to run the test
suite.  Reporting any failures is a good way to help improve the
software.  To run the test suite, type:

@example
make check
@end example

Test cases can be run in parallel using the @code{-j} option of
GNU@tie{}make.

If any failures occur, please email @email{bavier@@member.fsf.org} and
attach the @file{testsuite.log} file.

@c **********************************************************************
@node Invoking joy
@chapter Invoking joy

The following command-line options are supported:

@table @code
@item --help
@itemx -h
Show a help message and then exit.

@item --version
@itemx -V
Display Joy's version number and then exit.

@item --include=@var{dir}
@itemx -I @var{dir}
Add @var{dir} to the list of directories that are searched when using
the @code{include} operator.

@item --stack @var{atom} @dots{}
@itemx -S @var{atom} @dots{}
Initialize the stack with @var{atom} @dots{}.  Each @var{atom} may be
either a number or string.

@example
$ cat hello.joy
"base" include
"Hello " swoncat putchars
$ joy hello.joy --stack John
Hello John
$ cat double.joy
dup + .
$ joy double.joy --stack 3
6
@end example

@end table

@c **********************************************************************
@node Programming in Joy
@chapter Programming in Joy

In Joy, everything is an operator that takes a stack as an argument
and returns a (possibly modified) stack.  Operators may be further
classified by the way they manipulate their input stack to produce
their output.  E.g. some operators simply push something to the top of
the stack; some remove one or more items; some remove one or more
items and push another; and others, typically called ``combinators'',
cause some stack items to executed in some way.

Joy is called a ``concatenative'' language because in a purely
functional sense, the concatenation of two Joy programs can be
understood as the composition of their equivalent functions.

@c **********************************************************************
@node Interactive Joy
@chapter Interactive Joy

Editing text files then running them with @code{joy} is useful, and
the programs are then committed to a file, but sometimes it can be
helpful during development to be able to experiment quickly with some
code before you know what works yet.  Joy supports ``interactive''
development by providing a @acronym{REPL, read-eval-print-loop}.  If
@code{joy} is invoked with no arguments, then it enteres a REPL.

@example
> joy
@dots{}
joy-repl@@(guile-user)> 1 2 10
[10 2 1]
joy-repl@@(guile-user)> swap - +
[9]
joy-repl@@(guile-user)> "base" include
[9]
joy-repl@@(guile-user)> 7 [8 *]
[[8 *] 7 9]
joy-repl@@(guile-user)> DEFINE foo == dip +
[[8 *] 7 9]
joy-repl@@(guile-user)> foo
[79]
joy-repl@@(guile-user)> newstack
[]
@end example

One may experiment this way before committing a working sequence to
their program.  After each expression is evaluated the current stack
is displayed, so the effect that expression had on the stack can be
seen.

The Joy REPL is implemented as a Guile language @xref{Other
Languages,,Support for Other Languages,guile}.  This means Joy's REPL
can be accessed through Guile, albeit without the pretty-printing:

@example
> guile
@dots{}
scheme@@(guile-user)> (display "Hello Guile!")(newline)
Hello Guile!
scheme@@(guile-user)> ,L joy-repl
Happy hacking with Joy (REPL)!  To switch back type `,L scheme'.
joy-repl@@(guile-user)> 2 3 dup +
$1 = (6 2)
joy-repl@@(guile-user)> ,L scheme
Happy hacking with Scheme!  To switch back type `,L joy-repl'.
scheme@@(guile-user)> (length $1)
$2 = 3
scheme@@(guile-user)> (car $1)
$3 = 6
@end example

The Joy language itself can also be used in Guile.  But because every
Joy expression is an operator (i.e. a Guile procedure) that takes a
stack as input and produces another stack as output, one must apply
manually, from Scheme, every expression/operator entered in the Joy
language to a stack argument.  Despite the overhead, this might still
be useful in some circumstances.

@example
> guile
@dots{}
scheme@@(guile-user)> ,L joy
Happy hacking with Joy!  To switch back type `,L scheme'.
joy@@(guile-user)> dup + +
$1 = #<procedure 86ba230 S>
joy@@(guile-user)> ,L scheme
Happy hacking with Scheme!  To switch back type `,L joy'.
scheme@@(guile-user)> (apply $1 '(6 10))
$2 = (22)
scheme@@(guile-user)> (apply $1 '(5 3))
$3 = (13)
scheme@@(guile-user)> (apply $1 '(1 10 19))
$4 = (11 19)
@end example

@c **********************************************************************
@node API Reference
@chapter API Reference

We discuss here the various Joy operators@footnote{The term
``operator'' is used consistently here to refer to any term that
affects the stack when executed.  Indeed, one may consider every Joy
term to be an operator, even literals, e.g.@: @code{2}, because it
affects the stack by pushing itself onto the top of the stack.  We do
not distinguish in our discussion ``combinators'' from ``operators''
as the literature does.} provided for general use.  Operator
signatures are denoted by the result they have on the top of stack,
where the rightmost element is the top element.  Any element of the
stack not included in an operator signature is untouched.

Do not be confused by the ordering of the operator name and the
operator signature in the following.  Remember that Joy uses postfix
notation, so in practice an operator defined like

@deffn {Example Operator} frob [B] [A] @result{} [C]
This operator frobs @code{A} and @code{B} into @code{C}.
@end deffn

@noindent
would be used in a joy program like

@example
[B] [A] frob
@result{} [C]
@end example

@menu
* Primitives::                  Essential operators.
* Standard Library::            Generally useful operators.
* Lisp Aliases::
* Forth Aliases::
@end menu

@node Primitives
@section Primitives

This section summarizes the primitive operators that will be used
almost everywhere.  These primitives are written directly in Guile for
performance, and all other operators are written in terms of them.

@deffn {Joy Operator} dup A @result{} A A
This operator places a copy of the top element onto the stack.
@end deffn

@deffn {Joy Operator} pop A @result{}
This operator removes the top element of the stack.
@end deffn

@deffn {Joy Operator} swap B A @result{} A B
This operator swaps the position of the top two elements.
@end deffn

@deffn {Joy Operator} cons B [A @dots{}] @result{} [B A @dots{}]
This operator inserts @var{B} into the front of a quotation.
@end deffn

@deffn {Joy Operator} uncons [B A @dots{}] @result{} B [A @dots{}]
This operator removes @var{B} from the front of a quotation and places
it, followed by the rest of the quotation, back on the stack.
@end deffn

@deffn {Joy Operator} choice C B A @result{} D
This operator leaves @var{D} on the top of the stack, where @var{D} is
@var{B} if @var{C} is @var{true}, otherwise @var{A}.
@end deffn

@deffn {Joy Operator} stack @result{} [S]
This operator pushes the entire current stack as a quotation.
@end deffn

@deffn {Joy Operator} unstack @dots{} [S0 S1 @dots{} SN] @result{} S0 S1 @dots{} SN
This operator replaces the entire stack with the contents of the
quotation at the top.
@end deffn

@deffn {Joy Operator} infra [S] [A] @result{} [S']
This operator executes the quotation @var{[A]}, using the list
@var{[S]} as the stack, then takes the resulting stack and pushes it
as a list onto the original stack.

@example
1 2 [3 4 5] [+] infra
@result{} [1 2 [3 9]]
@end example
@end deffn

@deffn {Joy Operator} + B A @result{} C
Removes the two topmost integers and pushes their sum.  The current
implementation does not fully support floating point numbers.
@end deffn

@deffn {Joy Operator} - B A @result{} C
Removes the two topmost integers @var{A} and @var{B} and pushes
@math{@var{B} - @var{A}}.
@end deffn

@deffn {Joy Operator} < B A @result{} C
Removes the two topmost integers @var{A} and @var{B} and pushes
@code{true} if @math{@var{B} < @var{A}}, otherwise @code{false}.
@end deffn

@deffn {Joy Operator} > B A @result{} C
Removes the two topmost integers @var{A} and @var{B} and pushes
@code{true} if @math{@var{B} > @var{A}}, otherwise @code{false}.
@end deffn

@deffn {Joy Operator} = B A @result{} C
Removes the two topmost integers @var{A} and @var{B} and pushes
@code{true} if @math{@var{B} == @var{A}}, otherwise @code{false}.
@end deffn

@deffn {Joy Operator} logical A @result{} B
Removes the topmost stack element and if it is either @code{true} or
@code{false} pushes @code{true}, otherwise @code{false}.
@end deffn

@deffn {Joy Operator} char A @result{} B
Removes the topmost stack element and pushes @code{true} if it is a
character, otherwise @code{false}.
@end deffn

@deffn {Joy Operator} integer A @result{} B
Removes the topmost stack element and pushes @code{true} if it is an
integer, otherwise @code{false}.
@end deffn

@deffn {Joy Operator} string A @result{} B
Removes the topmost stack element and pushes @code{true} if it is a
string, otherwise @code{false}.
@end deffn

@deffn {Joy Operator} list A @result{} B
Removes the topmost stack element and pushes @code{true} if it is a
list/quotation, otherwise @code{false}.
@end deffn

@deffn {Joy Operator} putch A @result{}
This operator expects a character as the topmost stack element.  It
removes it and writes it to standard out.
@end deffn

@deffn {Joy Operator} putchars A @result{}
This operator expects a string (of characters) as the topmost stack
element.  It removes it and write it to standard out.
@end deffn

@deffn {Joy Operator} write A @result{}
@deffnx {Joy Operator} . A @result{}
This operator removes the topmost stack element and writes it to
stdout followed by a newline.

@example
1 'a [1 2] "foo" . . . .
@print{} "foo"
@print{} [1 2]
@print{} 'a
@print{} 1
@result{} []
@end example
@end deffn

@deffn {Joy Operator} def [name] [term] @result{}
This operator binds in the global scope a variable @var{name} to the
value @var{term}.  It is equivalent to using @code{DEFINE}.  Indeed,
@code{DEFINE} is implemented as syntactic sugar for @code{def}.

@example
DEFINE foo == 2 + ; @equiv{} [foo] [2 +] def
@end example
@end deffn

@deffn {Joy Operator} include filename @result{}
This operator expects a string as the topmost stack element.  A file
with that name is searched for in the standard Joy installation
directories as well as any directories given with the -I command-line
option.  If the filename ends in ``.joy'' it may be left off.  If
found, this file will be compiled and executed.  Typically files
included with this operator contain only operator definitions.
@end deffn

@deffn {Joy Operator} exit A @result{}
This operator expects an integer as the topmost stack element.
Immediately stops execution and exits with the integer status at the
top of the stack.

@example
[1 2 >] ["success" putchars] [1 exit] ifte .
@result{}
@end example
@end deffn


@node Standard Library
@section Standard Library

@subsection Literals

@deffn {Joy Operator} true @result{} true
Pushes the logical @code{true} on top of the stack.
@end deffn

@deffn {Joy Operator} false @result{} false
Pushes the logical @code{false} on top of the stack.
@end deffn

@subsection Stack Manipulation

@deffn {Joy Operator} newstack @dots{} @result{}
Remove all stack elements, leaving an empty stack.
@end deffn

@deffn {Joy Operator} popd B A @result{} A
Remove the penultimate stack element.
@end deffn

@deffn {Joy Operator} dupd B A @result{} B B A
Push a copy of the penultimate stack element under the topmost
element.
@end deffn

@deffn {Joy Operator} swapd C B A @result{} B C A
Swap the second and third stack elements.
@end deffn

@deffn {Joy Operator} dup2 B A @result{} B A B A
Push copies of the top two stack elements.
@end deffn

@deffn {Joy Operator} pop2 B A @result{}
@deffnx {Joy Operator} poppop B A @result{}
Discard the top two stack elements.
@end deffn

@deffn {Joy Operator} dig1 B A @result{} A B
@deffnx {Joy Operator} dig2 C B A @result{} B A C
@deffnx {Joy Operator} dig3 D C B A @result{} C B A D
@deffnx {Joy Operator} dig4 E D C B A @result{} D C B A E
Reaches under @var{n} elements and ``digs'' up the next element to the
top of the stack.
@end deffn

@deffn {Joy Operator} bury1 B A @result{} A B
@deffnx {Joy Operator} bury2 C B A @result{} A C B
@deffnx {Joy Operator} bury3 D C B A @result{} A D C B
@deffnx {Joy Operator} bury4 E D C B A @result{} A E D C B
Takes the topmost stack element and ``buries'' it under @var{n} elements.
@end deffn

@deffn {Joy Operator} flip2 B A @result{} A B
@deffnx {Joy Operator} flip3 C B A @result{} A B C
@deffnx {Joy Operator} flip4 D C B A @result{} A B C D
Flips the order of the top @var{n} elements.
@end deffn

@deffn {Joy Operator} rollup C B A @result{} A C B
Equivalent to @code{bury2}.
@end deffn

@deffn {Joy Operator} rolldown C B A @result{} B A C
Equivalent to @code{dig2}.
@end deffn

@deffn {Joy Operator} rotate C B A @result{} A B C
Equivalent to @code{flip3}.
@end deffn

@subsection List/Quotation Manipulation

@deffn {Joy Operator} first [A0 @dots{}] @result{} A0
Replaces the quotation at the top of the stack with its first element.
@end deffn

@deffn {Joy Operator} second [A0 A1 @dots{}] @result{} A1
Replaces the quotation at the top of the stack with its second
element.
@end deffn

@deffn {Joy Operator} third [A0 A1 A2 @dots{}] @result{} A2
Replaces the quotation at the top of the stack with its third element.
@end deffn

@deffn {Joy Operator} rest [A0 A1 @dots{}] @result{} [A1 @dots{}]
Replaces the quotation on the top of the stack with a copy of itself
without its first element.
@end deffn

@subsection Quotation Evaluation

These operators will cause the evaluation of one or more quotations.
Using them, one can achieve something similar to anonymous function
definitions.  The effect most of these operators has on the stack
depends on the contents of the quotation executed.

@deffn {Joy Operator} i [A] @result{} @dots{}
@deffnx {Joy Operator} dip0 [A] @result{} @dots{}
Dequotes and executes the quotation at the top of the stack.
@end deffn

@deffn {Joy Operator} dip B [A] @result{} @dots{} B
@deffnx {Joy Operator} dip1 B [A] @result{} @dots{} B
Dequotes and executes the topmost quotation after temporarily removing
@var{B} from the stack, then replaces @var{B} at the top of the stack.
@end deffn

@deffn {Joy Operator} dipd C B [A] @result{} @dots{} C B
@deffnx {Joy Operator} dip2 C B [A] @result{} @dots{} C B
Dequotes and executes the topmost quotation after temporarily removing
@var{B} and @var{C} from the stack, then replaces them.
@end deffn

@deffn {Joy Operator} dip3 D C B [A] @result{} @dots{} D C B
@deffnx {Joy Operator} dip4 E D C B [A] @result{} @dots{} E D C B
Dequotes and executes the topmost quotation after temporarily removing
the @var{n} stack elements below, then replaces them.
@end deffn

@deffn {Joy Operator} nullary [A] @result{} R
Removes the topmost quotation, saves the state of the stack, then
dequotes and executes the quotation, which leaves @var{R} on top of the
stack.  The saved stack is restored and @var{R} is pushed.  That is,
executing the quotation consumes no other stack elements.
@end deffn

@deffn {Joy Operator} unary B [A] @result{} R
Removes the topmost quotation, saves the state of the stack, then
dequotes and executes the quotation, which leaves @var{R} on the top
of the stack.  @var{R} is then pushed after restoring the saved stack
and discarding the topmost element.  That is, executing the quotation
consumes exactly one stack element.
@end deffn

@deffn {Joy Operator} i2 D C [B] [A] @result{} @dots{}
Executes @var{[B]} with @var{D} on top of the stack, then executes
@var{[A]} with @var{C} on top of the result.

@example
1 2 3 [+] [*] i2 .
@result{} [9]
@end example
@end deffn

@subsection General Operators

@deffn {Joy Operator} branch C [B] [A] @result{} @dots{}
If C is @code{true} this operator executes @var{[B]}, otherwise
@var{[A]}.
@end deffn

@deffn {Joy Operator} ifte [I] [T] [E] @result{} @dots{}
This operator saves the state of the stack then executes quoted
predicate @var{[I]}.  If the top of the stack is @code{true}, it then
restores the stack and executes @var{[T]}, otherwise it restores the
stack and executes @var{[E]}.  In other words, the predicate @var{[I]}
may manipulate the stack in any way, and it will be restored prior to
executing @var{[T]} or @var{[E]}.

@example
2 ['a 'b 'c]
[size <] [pop 1 +] [['d] concat] ifte .
@result{} [3]
@end example
@end deffn

@deffn {Joy Operator} step [L] [A] @result{} @dots{}
For each element in the list @var{[L]}, place it on top of the stack,
then execute quotation @var{[A]}.
@end deffn

@subsection Recursion Operators

Recursion may be achieved in Joy in the typical way by defining an
operator that refers to itself in its body.  It is, however, sometimes
useful to define anonymous recursive operators.  The following
operators assist in doing this.

@deffn {Joy Operator} tailrec [I] [T] [E] @result{} @dots{}
Much like the @code{ifte} operator, this operator executes either
@var{[T]} or @var{[E]} depending on the result of executing @var{[I]}
but if @var{[E]} is executed this operator recurses.

@example
0 [10 =] [] [dup 1 +] tailrec .
@result{} [0 1 2 3 4 5 6 7 8 9 10]
@end example
@end deffn

@deffn {Joy Operator} linrec [I] [T] [E1] [E2] @result{} @dots{}
Like @code{tailrec} but upon completion of the recursive execution,
executes @var{[E2]}.

@example
1 [10 =] [] [dup 1 +] [*] linrec .
@result{} [3628800]
@end example

@example
[1 2 3] [null] [] [uncons] [cons] linrec .
@result{} [[1 2 3]]
@end example

@example
['a 'b 'c 'd] [null] [pop 0] [rest 1 swap] [+] linrec .
@result{} [4]
@end example
@end deffn

@node Lisp Aliases
@section Lisp Aliases

Several operator aliases are provided for those familiar with
programming in Lisp-like languages.

@deffn {Joy Operator} car [A0 @dots{}] @result{} A0
This is an alias for @code{first}.
@end deffn

@deffn {Joy Operator} cadr [A0 A1 @dots{}] @result{} A1
This is an alias for @code{second}.
@end deffn

@deffn {Joy Operator} caddr [A0 A1 A2 @dots{}] @result{} A2
This is an alias for @code{third}.
@end deffn

@deffn {Joy Operator} cdr [A0 A1 @dots{}] @result{} [A1 @dots{}]
This is an alias for @code{rest}.
@end deffn

@deffn {Joy Operator} cddr [A0 A1 A2 @dots{}] @result{} [A2 @dots{}]
This is equivalent to @code{rest rest}.
@end deffn

@deffn {Joy Operator} 1+ Z @result{} Z'
This operator is equivalent to @code{succ}.
@end deffn

@deffn {Joy Operator} 1- Z @result{} Z'
This operator is equivalent to @code{pred}.
@end deffn

@node Forth Aliases
@section Forth Aliases

Several operators are provided for those familiar with programming in
the FORTH language.  They may be accessed with:

@example
"forth" include .
@end example

@deffn {Joy Operator} drop A @result{}
This is an alias for @code{pop}.
@end deffn

@deffn {Joy Operator} over B A @result{} B A B
Push a copy of the second stack item.
@end deffn

@deffn {Joy Operator} nip B A @result{} A
Remove the second item on the stack.  Equivalent to @code{swap pop},
and an alias for @code{popd}.
@end deffn

@deffn {Joy Operator} tuck B A @result{} A B A
Insert a copy of the top stack item underneath the current second
item.  Equivalent to @code{swap over} or @code{dup bury2}.
@end deffn

@deffn {Joy Operator} rot C B A @result{} B A C
An alias for @code{dig2} and @code{rolldown}.  Not to be confused with
@code{rotate}.
@end deffn

@deffn {Joy Operator} -rot C B A @result{} A C B
An alias for @code{bury2}.
@end deffn

@deffn {Joy Operator} pick Xn @dots{} X0 n @result{} Xn @dots{} X0 Xn
Retrieves a copy of the @var{n}@sup{th} stack item and places it on
top of the stack.  @code{0 pick} is equivalent to @code{dup}, @code{1
pick} to @code{over}, etc.
@end deffn

@deffn {Joy Operator} /mod Z @result{} R Q
This is an alias for @code{divmod}.
@end deffn

@deffn {Joy Operator} within X Y Z @result{} t/f
Pushes @code{true} onto the stack if the integer inequality @var{Y}
@leq{} @var{X} < @var{Z} holds, otherwise @code{false}.
@end deffn

@deffn {Joy Operator} within? X Y Z @result{} t/f
Pushes @code{true} onto the stack if the integer inequality @var{Y}
@leq{} @var{X} @leq{} @var{Z} holds, otherwise @code{false}.
@end deffn

@deffn {Joy Operator} cr A @result{} A
Causes a newline to be printed to stdout.  Equivalent to
@code{newline}.
@end deffn

@deffn {Joy Operator} bl @result{} '\032
Places a ``space'' character onto the stack.
@end deffn

@deffn {Joy Operator} emit A @result{}
Print the character on top of the stack to stdout.  Equivalent to
@code{putch}.
@end deffn

@c *********************************************************************
@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl-1.3.texi

@bye

@c Local Variables:
@c ispell-local-dictionary: "american";
@c End: