updated README.txt
Slava Pestov
parent
eb9271fe1d
commit
1d2a152cb3
12
CHANGES.txt
12
CHANGES.txt
|
|
@ -1,11 +1,13 @@
|
||||||
Factor 0.76:
|
Factor 0.76:
|
||||||
------------
|
------------
|
||||||
|
|
||||||
- The main focus of this release was getting the UI framework in a state
|
- Major improvements to the GUI:
|
||||||
where the graphical listener is usable. This goal has largely been
|
|
||||||
achieved. Many performance problems were fixed, and the listener now
|
- The listener supports styled text output and presentations
|
||||||
supports styled text output, presentations, and an
|
- Gradient paint, bevel border paint
|
||||||
automatically-updated data stack display.
|
- Wheel mouse scrolling
|
||||||
|
- Slide-show tutorial with live code examples
|
||||||
|
- Performance improvements, code cleanups, bug fixes
|
||||||
|
|
||||||
- The following formely list-specific words are now generic:
|
- The following formely list-specific words are now generic:
|
||||||
|
|
||||||
|
|
|
||||||
9
Makefile
9
Makefile
|
|
@ -51,9 +51,8 @@ default:
|
||||||
@echo "Run 'make' with one of the following parameters:"
|
@echo "Run 'make' with one of the following parameters:"
|
||||||
@echo ""
|
@echo ""
|
||||||
@echo "bsd"
|
@echo "bsd"
|
||||||
@echo "bsd-nopthread - on FreeBSD 4, if you want to use profiling"
|
|
||||||
@echo "linux"
|
@echo "linux"
|
||||||
@echo "linux-ppc - to compile Factor on Linux/PowerPC"
|
@echo "linux-ppc"
|
||||||
@echo "macosx"
|
@echo "macosx"
|
||||||
@echo "windows"
|
@echo "windows"
|
||||||
@echo ""
|
@echo ""
|
||||||
|
|
@ -69,12 +68,6 @@ bsd:
|
||||||
LIBS="$(DEFAULT_LIBS)"
|
LIBS="$(DEFAULT_LIBS)"
|
||||||
$(STRIP) f
|
$(STRIP) f
|
||||||
|
|
||||||
bsd-nopthread:
|
|
||||||
$(MAKE) f \
|
|
||||||
CFLAGS="$(DEFAULT_CFLAGS) -export-dynamic" \
|
|
||||||
LIBS="$(DEFAULT_LIBS)"
|
|
||||||
$(STRIP) f
|
|
||||||
|
|
||||||
macosx:
|
macosx:
|
||||||
$(MAKE) f \
|
$(MAKE) f \
|
||||||
CFLAGS="$(DEFAULT_CFLAGS)" \
|
CFLAGS="$(DEFAULT_CFLAGS)" \
|
||||||
|
|
|
||||||
339
README.txt
339
README.txt
|
|
@ -1,263 +1,174 @@
|
||||||
THE CONCATENATIVE LANGUAGE FACTOR
|
The Factor programming language
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
* Introduction
|
This file covers installation and basic usage of the Factor
|
||||||
|
implementation. It is not an introduction to the language itself.
|
||||||
|
|
||||||
Factor supports various data types; atomic types include numbers of
|
* Platform support
|
||||||
various kinds, strings of characters, and booleans. Compound data types
|
|
||||||
include lists consisting of cons cells, vectors, and string buffers.
|
|
||||||
|
|
||||||
Factor encourages programming in a functional style where new objects
|
Factor is fully supported on the following platforms:
|
||||||
are returned and input parameters remain unmodified, but does not
|
|
||||||
enforce this. No manifest type declarations are necessary, and all data
|
|
||||||
types use exactly one slot each on the stack (unlike, say, FORTH).
|
|
||||||
|
|
||||||
The internal representation of a Factor program is a linked list. Linked
|
Linux/x86
|
||||||
lists that are to be executed are referred to as ``quotations.'' The
|
FreeBSD/x86
|
||||||
interpreter iterates the list, executing words, and pushing all other
|
Microsoft Windows 2000 or later
|
||||||
types of objects on the data stack. A word is a unique data type because
|
Mac OS X/PowerPC
|
||||||
it can be executed. Words come in two varieties: primitive and compound.
|
Linux/PowerPC
|
||||||
Primitive words have an implementation coded in the host language (C or
|
|
||||||
Java). Compound words are executed by invoking the interpreter
|
|
||||||
recursively on their definition, which is also a linked list.
|
|
||||||
|
|
||||||
* A note about code examples
|
While Factor may run on other platforms (Solaris/Sparc, Linux/Alpha, and
|
||||||
|
so on), the native compiler will not be available, and thus much
|
||||||
|
functionality will be missing. In particular, the following features
|
||||||
|
require the native compiler and only work on supported platforms:
|
||||||
|
|
||||||
Factor words are separated out into multiple ``vocabularies''. Each code
|
C library interface
|
||||||
example given here is preceeded with a series of declarations, such as
|
Non-blocking I/O
|
||||||
the following:
|
Networking
|
||||||
|
|
||||||
USE: math
|
* Compiling Factor
|
||||||
USE: streams
|
|
||||||
|
|
||||||
When entering code at the interactive interpreter loop, most
|
The Factor runtime is written in C, and is built with GNU make and gcc.
|
||||||
vocabularies are already in the search path, and the USE: declarations
|
|
||||||
can be omitted. However, in a source file they must all be specified,
|
|
||||||
by convention at the beginning of the file.
|
|
||||||
|
|
||||||
* Control flow
|
Note that on x86 systems, Factor _cannot_ be compiled with gcc 3.3. This
|
||||||
|
is due to a bug in gcc and there is nothing we can do about it. Please
|
||||||
|
use gcc 2.95, 3.4, or 4.0.
|
||||||
|
|
||||||
Control flow rests on two basic concepts: recursion, and branching.
|
Run 'make' (or 'gmake' on non-Linux platforms) with one of the following
|
||||||
Words with compound definitions may refer to themselves, and there is
|
parameters to build the Factor runtime:
|
||||||
exactly one primitive for performing conditional execution:
|
|
||||||
|
|
||||||
USE: combinators
|
bsd
|
||||||
|
linux
|
||||||
|
linux-ppc
|
||||||
|
macosx
|
||||||
|
windows
|
||||||
|
|
||||||
1 10 < [ "1 is less than 10." print ] [ "whoa!" print ] ifte
|
The following options can be given to make:
|
||||||
==> 1 is less than 10.
|
|
||||||
|
|
||||||
Here is an example of a word that uses these two concepts:
|
SITE_CFLAGS="..."
|
||||||
|
DEBUG=1
|
||||||
|
|
||||||
: contains? ( element list -- remainder )
|
The former allows optimization flags to be specified, for example
|
||||||
#! If the proper list contains the element, push the
|
"-march=pentium4 -ffast-math -O3". Optimization flags can make a *huge*
|
||||||
#! remainder of the list, starting from the cell whose car
|
difference in Factor's performance, so willing hackers should
|
||||||
#! is elem. Otherwise push f.
|
experiment.
|
||||||
dup [
|
|
||||||
2dup car = [ nip ] [ cdr contains? ] ifte
|
|
||||||
] [
|
|
||||||
2drop f
|
|
||||||
] ifte ;
|
|
||||||
|
|
||||||
An example:
|
The latter flag disables optimization and builds an executable with
|
||||||
|
debug symbols. This is probably only of interest to people intending to
|
||||||
|
hack on the runtime sources.
|
||||||
|
|
||||||
USE: lists
|
Compilation may print a handful of warnings about singled/unsigned
|
||||||
|
comparisons, and violated aliasing contracts. They may safely be
|
||||||
|
ignored.
|
||||||
|
|
||||||
3 [ 1 2 3 4 ] contains?
|
Compilation will yield an executable named 'f'.
|
||||||
==> [ 3 4 ]
|
|
||||||
5 [ 1 2 3 4 ] contains?
|
|
||||||
==> f
|
|
||||||
|
|
||||||
It recurses down the list, until it reaches the end, in which case the
|
* Building Factor
|
||||||
outer ifte's 'false' branch is executed.
|
|
||||||
|
|
||||||
A quick overview of the words used here, along with their stack effects:
|
The Factor source distribution ships with four boot image files:
|
||||||
|
|
||||||
Shuffle words:
|
boot.image.le32 - for x86
|
||||||
|
boot.image.be32 - for PowerPC, SPARC
|
||||||
|
boot.image.le64 - for x86-64
|
||||||
|
boot.image.be64 - for Alpha, PowerPC/64, UltraSparc
|
||||||
|
|
||||||
dup ( x -- x x )
|
Once you have compiled the Factor runtime, you must bootstrap the Factor
|
||||||
nip ( x y -- y )
|
system using the image that corresponds to your CPU architecture.
|
||||||
2dup ( x y -- x y x y )
|
|
||||||
2drop ( x y -- )
|
|
||||||
|
|
||||||
Linked list deconstruction:
|
The system is bootstrapped with the following command line:
|
||||||
|
|
||||||
car ( [ x | y ] -- x )
|
./f boot.image.<foo>
|
||||||
cdr ( [ x | y ] -- y ) - push the "tail" of a list.
|
|
||||||
|
|
||||||
Equality:
|
Additional options may be specified to load external C libraries; see
|
||||||
|
the next section for details.
|
||||||
|
|
||||||
= ( x y -- ? )
|
Bootstrap can take a while, depending on your system. When the process
|
||||||
|
completes, a 'factor.image' file will be generated. Note that this image
|
||||||
|
is both CPU and OS-specific, so in general cannot be shared between
|
||||||
|
machines.
|
||||||
|
|
||||||
More complicated control flow constructs, such as loops and higher order
|
* Running Factor
|
||||||
functions, are usually built with the help of another primitive that
|
|
||||||
simply executes a quotation at the top of the stack, removing it from
|
|
||||||
the stack:
|
|
||||||
|
|
||||||
USE: math
|
To run the Factor system, issue the following command:
|
||||||
USE: prettyprint
|
|
||||||
|
|
||||||
[ 2 2 + . ] call
|
./f factor.image
|
||||||
==> 4
|
|
||||||
|
|
||||||
Here is an example of a word that applies a quotation to each element of
|
This will start the interactive listener where Factor expressions may
|
||||||
a list. Note that it uses 'call' to execute the given quotation:
|
be entered.
|
||||||
|
|
||||||
: each ( list quotation -- )
|
To run the graphical user interface, issue the following command:
|
||||||
#! Push each element of a proper list in turn, and apply a
|
|
||||||
#! quotation to each element.
|
|
||||||
over [
|
|
||||||
>r uncons r> tuck >r >r call r> r> each
|
|
||||||
] [
|
|
||||||
2drop
|
|
||||||
] ifte ;
|
|
||||||
|
|
||||||
An example:
|
./f factor.image -shell=ui
|
||||||
|
|
||||||
USE: lists
|
Note that on Windows, this is the default.
|
||||||
USE: math
|
|
||||||
USE: stack
|
|
||||||
|
|
||||||
[ 1 2 3 4 ] [ dup * . ] each
|
On Unix, this might fail if the SDL libraries are not installed, or are
|
||||||
==> 1
|
installed under unconventional names. This can be solved by explicitly
|
||||||
4
|
naming the libraries during bootstrap, as in the next section.
|
||||||
9
|
|
||||||
16
|
|
||||||
|
|
||||||
A quick overview of the words used here:
|
* Setting up SDL libraries for use with Factor
|
||||||
|
|
||||||
Printing top of stack:
|
Factor's UI requires recent versions of the following three libraries in
|
||||||
|
order to operate:
|
||||||
|
|
||||||
. ( x -- ) print top of stack in a form that is valid Factor syntax.
|
libSDL.so
|
||||||
|
libSDL_ttf.so
|
||||||
|
libSDL_gfx.so
|
||||||
|
|
||||||
Shuffle words:
|
If you have installed these libraries but the UI still fails with an
|
||||||
|
error, you will need to find out the exact names that they are installed
|
||||||
|
as, and issue a command similar to the following to bootstrap Factor:
|
||||||
|
|
||||||
over ( x y -- x y x )
|
./f boot.image.<foo> -libraries:sdl:name=libSDL-1.2.so
|
||||||
tuck ( x y -- y x y )
|
-libraries:sdl-ttf:name=libSDL_ttf.so
|
||||||
>r ( x -- r:x ) - move top of data stack to/from 'extra hand'.
|
-libraries:sdl-gfx:name=libSDL_gfx.so
|
||||||
r> ( r:x -- x )
|
|
||||||
|
|
||||||
Writing >r foo r> is analogous to '[ foo ] dip' in Joy. Occurrences of
|
* Source organization
|
||||||
>r and r> must be balanced within a single word definition.
|
|
||||||
|
|
||||||
Linked list deconstruction:
|
doc/ - the developer's handbook, and various other bits and pieces
|
||||||
|
native/ - sources for the Factor runtime, written in C
|
||||||
|
library/ - sources for the library, written in Factor
|
||||||
|
alien/ - C library interface
|
||||||
|
bootstrap/ - code for generating boot images
|
||||||
|
collections/ - data types including but not limited to lists,
|
||||||
|
vectors, hashtables, and operations on them
|
||||||
|
compiler/ - optimizing native compiler
|
||||||
|
generic/ - generic words, for object oriented programming style
|
||||||
|
help/ - online help system
|
||||||
|
httpd/ - HTTP client, server, and web application framework
|
||||||
|
icons/ - images used by web framework and UI
|
||||||
|
inference/ - stack effect inference, used by compiler, as well as a
|
||||||
|
useful development tool of its own
|
||||||
|
io/ - input and output streams
|
||||||
|
math/ - integers, ratios, floats, complex numbers, vectors, matrices
|
||||||
|
sdl/ - bindings for libSDL, libSDL_ttf and libSDL_gfx
|
||||||
|
syntax/ - parser and object prettyprinter
|
||||||
|
test/ - unit test framework and test suite
|
||||||
|
tools/ - interactive development tools
|
||||||
|
ui/ - UI framework
|
||||||
|
unix/ - Unix-specific I/O code
|
||||||
|
win32/ - Windows-specific I/O code
|
||||||
|
contrib/ - various handy libraries not part of the core
|
||||||
|
examples/ - small examples illustrating various language features
|
||||||
|
factor/ - Java code for the Factor jEdit plugin
|
||||||
|
fonts/ - TrueType fonts used by UI
|
||||||
|
|
||||||
uncons ( [ x | y ] -- x y )
|
* Learning Factor
|
||||||
|
|
||||||
* Variables
|
The UI has a simple tutorial that will show you the most basic concepts.
|
||||||
|
|
||||||
Factor supports a notion of ``variables''. Whereas the stack is used for
|
There is a detailed language and library reference available at
|
||||||
transient, intermediate values, variables are used for more permanent
|
http://factor.sourceforge.net/handbook.pdf.
|
||||||
data.
|
|
||||||
|
|
||||||
Variables are retreived and stored using the 'get' and 'set' words. For
|
You can browse the source code; it is organized into small,
|
||||||
example:
|
well-commented files and should be easy to follow once you have a good
|
||||||
|
grasp of the language.
|
||||||
|
|
||||||
USE: math
|
* Community
|
||||||
USE: namespaces
|
|
||||||
USE: prettyprint
|
|
||||||
|
|
||||||
"~" get .
|
The Factor homepage is located at http://factor.sourceforge.net/.
|
||||||
==> "/home/slava"
|
|
||||||
|
|
||||||
5 "x" set
|
Factor developers meet in the #concatenative channel on the
|
||||||
"x" get 2 * .
|
irc.freenode.net server. Drop by if you want to discuss anything related
|
||||||
==> 10
|
to Factor or language design in general.
|
||||||
|
|
||||||
The set of available variables is determined using ``dynamic scope''.
|
Have fun!
|
||||||
A ``namespace'' is a set of variable name/value pairs. Namespaces can be
|
|
||||||
pushed onto the ``name stack'', and later popped. The 'get' word
|
|
||||||
searches all namespaces on the namestack in turn. The 'set' word stores
|
|
||||||
a variable value into the namespace at the top of the name stack.
|
|
||||||
|
|
||||||
While it is possible to push/pop the namestack directly using the words
|
:tabSize=2:indentSize=2:noTabs=true:
|
||||||
>n and n>, most of the time using the 'bind' combinator is more
|
|
||||||
desirable.
|
|
||||||
|
|
||||||
Good examples of namespace use are found in the I/O system.
|
|
||||||
|
|
||||||
Factor provides two sets of words for working with I/O streams: words
|
|
||||||
whose stream operand is specified on the stack (freadln, fwrite,
|
|
||||||
fprint...) and words that use the standard input/output stream (read,
|
|
||||||
write, print...).
|
|
||||||
|
|
||||||
An I/O stream is a namespace with a slot for each I/O operation. I/O
|
|
||||||
operations taking an explicit stream operand are all defined as follows:
|
|
||||||
|
|
||||||
: freadln ( stream -- string )
|
|
||||||
[ "freadln" get call ] bind ;
|
|
||||||
|
|
||||||
: fwrite ( string stream -- )
|
|
||||||
[ "fwrite" get call ] bind ;
|
|
||||||
|
|
||||||
: fclose ( stream -- )
|
|
||||||
[ "fclose" get call ] bind ;
|
|
||||||
|
|
||||||
( ... et cetera )
|
|
||||||
|
|
||||||
The second set of I/O operations, whose stream is the implicit 'standard
|
|
||||||
input/output' stream, are defined as follows:
|
|
||||||
|
|
||||||
: read ( -- string )
|
|
||||||
"stdio" get freadln ;
|
|
||||||
|
|
||||||
: write ( string -- )
|
|
||||||
"stdio" get fwrite ;
|
|
||||||
|
|
||||||
( ... et cetera )
|
|
||||||
|
|
||||||
In the global namespace, the 'stdio' variable corresponds to a stream
|
|
||||||
whose operations read/write from the standard file descriptors 0 and 1.
|
|
||||||
|
|
||||||
However, the 'with-stream' combinator provides a way to rebind the
|
|
||||||
standard input/output stream for the duration of the execution of a
|
|
||||||
single quotation. The following example writes the source of a word
|
|
||||||
definition to a file named 'definition.txt':
|
|
||||||
|
|
||||||
USE: prettyprint
|
|
||||||
USE: streams
|
|
||||||
|
|
||||||
"definition.txt" <filebw> [ "with-stream" see ] with-stream
|
|
||||||
|
|
||||||
The 'with-stream' word is implemented by pushing a new namespace on the
|
|
||||||
namestack, setting the 'stdio' variable therein, and execution the given
|
|
||||||
quotation.
|
|
||||||
|
|
||||||
* Continuations
|
|
||||||
|
|
||||||
A continuation is a quotation that restores execution to the point where
|
|
||||||
it was captured. Continuations are captured using the callcc0 and
|
|
||||||
callcc1 words in the 'continuations' vocabulary.
|
|
||||||
|
|
||||||
The word names are abbreviations for 'call with current continuation';
|
|
||||||
the 0 or 1 refers to the arity of the continuation.
|
|
||||||
|
|
||||||
Consider the phrase 'call with current continuation':
|
|
||||||
|
|
||||||
- 'call' -- it calls a quotation given as a parameter...
|
|
||||||
- 'with' -- with a value on the stack....
|
|
||||||
- 'current continuation' -- that is a quotation that can be called
|
|
||||||
to restore execution at the current point.
|
|
||||||
|
|
||||||
A continuation can either have arity 0 or 1. This refers to the number
|
|
||||||
of parameters the quotation transfers from the caller stack to the
|
|
||||||
restored point.
|
|
||||||
|
|
||||||
Three very simple examples:
|
|
||||||
|
|
||||||
[ call ] callcc0 "Hello world." print
|
|
||||||
^
|
|
||||||
------- captured continuation restores here.
|
|
||||||
==> Hello world.
|
|
||||||
|
|
||||||
[ "my-c" set ] callcc0 "Hello world." print
|
|
||||||
^
|
|
||||||
-------- captured continuation restores here.
|
|
||||||
==> Hello world.
|
|
||||||
|
|
||||||
"my-c" get call
|
|
||||||
==> Hello world.
|
|
||||||
|
|
||||||
Continuations are an advanced feature and are used in the implementation
|
|
||||||
of error handling, multi-tasking, co-routines, and generators.
|
|
||||||
|
|
||||||
(This is for my editor. It can be removed.
|
|
||||||
:tabSize=4:indentSize=4:noTabs=true:)
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue