updated README.txt
Slava Pestov
parent
eb9271fe1d
commit
1d2a152cb3
12
CHANGES.txt
12
CHANGES.txt
|
|
@ -1,11 +1,13 @@
|
|||
Factor 0.76:
|
||||
------------
|
||||
|
||||
- The main focus of this release was getting the UI framework in a state
|
||||
where the graphical listener is usable. This goal has largely been
|
||||
achieved. Many performance problems were fixed, and the listener now
|
||||
supports styled text output, presentations, and an
|
||||
automatically-updated data stack display.
|
||||
- Major improvements to the GUI:
|
||||
|
||||
- The listener supports styled text output and presentations
|
||||
- Gradient paint, bevel border paint
|
||||
- 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:
|
||||
|
||||
|
|
|
|||
9
Makefile
9
Makefile
|
|
@ -51,9 +51,8 @@ default:
|
|||
@echo "Run 'make' with one of the following parameters:"
|
||||
@echo ""
|
||||
@echo "bsd"
|
||||
@echo "bsd-nopthread - on FreeBSD 4, if you want to use profiling"
|
||||
@echo "linux"
|
||||
@echo "linux-ppc - to compile Factor on Linux/PowerPC"
|
||||
@echo "linux-ppc"
|
||||
@echo "macosx"
|
||||
@echo "windows"
|
||||
@echo ""
|
||||
|
|
@ -69,12 +68,6 @@ bsd:
|
|||
LIBS="$(DEFAULT_LIBS)"
|
||||
$(STRIP) f
|
||||
|
||||
bsd-nopthread:
|
||||
$(MAKE) f \
|
||||
CFLAGS="$(DEFAULT_CFLAGS) -export-dynamic" \
|
||||
LIBS="$(DEFAULT_LIBS)"
|
||||
$(STRIP) f
|
||||
|
||||
macosx:
|
||||
$(MAKE) f \
|
||||
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
|
||||
various kinds, strings of characters, and booleans. Compound data types
|
||||
include lists consisting of cons cells, vectors, and string buffers.
|
||||
* Platform support
|
||||
|
||||
Factor encourages programming in a functional style where new objects
|
||||
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).
|
||||
Factor is fully supported on the following platforms:
|
||||
|
||||
The internal representation of a Factor program is a linked list. Linked
|
||||
lists that are to be executed are referred to as ``quotations.'' The
|
||||
interpreter iterates the list, executing words, and pushing all other
|
||||
types of objects on the data stack. A word is a unique data type because
|
||||
it can be executed. Words come in two varieties: primitive and compound.
|
||||
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.
|
||||
Linux/x86
|
||||
FreeBSD/x86
|
||||
Microsoft Windows 2000 or later
|
||||
Mac OS X/PowerPC
|
||||
Linux/PowerPC
|
||||
|
||||
* 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
|
||||
example given here is preceeded with a series of declarations, such as
|
||||
the following:
|
||||
C library interface
|
||||
Non-blocking I/O
|
||||
Networking
|
||||
|
||||
USE: math
|
||||
USE: streams
|
||||
* Compiling Factor
|
||||
|
||||
When entering code at the interactive interpreter loop, most
|
||||
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.
|
||||
The Factor runtime is written in C, and is built with GNU make and gcc.
|
||||
|
||||
* 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.
|
||||
Words with compound definitions may refer to themselves, and there is
|
||||
exactly one primitive for performing conditional execution:
|
||||
Run 'make' (or 'gmake' on non-Linux platforms) with one of the following
|
||||
parameters to build the Factor runtime:
|
||||
|
||||
USE: combinators
|
||||
bsd
|
||||
linux
|
||||
linux-ppc
|
||||
macosx
|
||||
windows
|
||||
|
||||
1 10 < [ "1 is less than 10." print ] [ "whoa!" print ] ifte
|
||||
==> 1 is less than 10.
|
||||
The following options can be given to make:
|
||||
|
||||
Here is an example of a word that uses these two concepts:
|
||||
SITE_CFLAGS="..."
|
||||
DEBUG=1
|
||||
|
||||
: contains? ( element list -- remainder )
|
||||
#! If the proper list contains the element, push the
|
||||
#! remainder of the list, starting from the cell whose car
|
||||
#! is elem. Otherwise push f.
|
||||
dup [
|
||||
2dup car = [ nip ] [ cdr contains? ] ifte
|
||||
] [
|
||||
2drop f
|
||||
] ifte ;
|
||||
The former allows optimization flags to be specified, for example
|
||||
"-march=pentium4 -ffast-math -O3". Optimization flags can make a *huge*
|
||||
difference in Factor's performance, so willing hackers should
|
||||
experiment.
|
||||
|
||||
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?
|
||||
==> [ 3 4 ]
|
||||
5 [ 1 2 3 4 ] contains?
|
||||
==> f
|
||||
Compilation will yield an executable named 'f'.
|
||||
|
||||
It recurses down the list, until it reaches the end, in which case the
|
||||
outer ifte's 'false' branch is executed.
|
||||
* Building Factor
|
||||
|
||||
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 )
|
||||
nip ( x y -- y )
|
||||
2dup ( x y -- x y x y )
|
||||
2drop ( x y -- )
|
||||
Once you have compiled the Factor runtime, you must bootstrap the Factor
|
||||
system using the image that corresponds to your CPU architecture.
|
||||
|
||||
Linked list deconstruction:
|
||||
The system is bootstrapped with the following command line:
|
||||
|
||||
car ( [ x | y ] -- x )
|
||||
cdr ( [ x | y ] -- y ) - push the "tail" of a list.
|
||||
./f boot.image.<foo>
|
||||
|
||||
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
|
||||
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:
|
||||
* Running Factor
|
||||
|
||||
USE: math
|
||||
USE: prettyprint
|
||||
To run the Factor system, issue the following command:
|
||||
|
||||
[ 2 2 + . ] call
|
||||
==> 4
|
||||
./f factor.image
|
||||
|
||||
Here is an example of a word that applies a quotation to each element of
|
||||
a list. Note that it uses 'call' to execute the given quotation:
|
||||
This will start the interactive listener where Factor expressions may
|
||||
be entered.
|
||||
|
||||
: each ( list quotation -- )
|
||||
#! 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 ;
|
||||
To run the graphical user interface, issue the following command:
|
||||
|
||||
An example:
|
||||
./f factor.image -shell=ui
|
||||
|
||||
USE: lists
|
||||
USE: math
|
||||
USE: stack
|
||||
Note that on Windows, this is the default.
|
||||
|
||||
[ 1 2 3 4 ] [ dup * . ] each
|
||||
==> 1
|
||||
4
|
||||
9
|
||||
16
|
||||
On Unix, this might fail if the SDL libraries are not installed, or are
|
||||
installed under unconventional names. This can be solved by explicitly
|
||||
naming the libraries during bootstrap, as in the next section.
|
||||
|
||||
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 )
|
||||
tuck ( x y -- y x y )
|
||||
>r ( x -- r:x ) - move top of data stack to/from 'extra hand'.
|
||||
r> ( r:x -- x )
|
||||
./f boot.image.<foo> -libraries:sdl:name=libSDL-1.2.so
|
||||
-libraries:sdl-ttf:name=libSDL_ttf.so
|
||||
-libraries:sdl-gfx:name=libSDL_gfx.so
|
||||
|
||||
Writing >r foo r> is analogous to '[ foo ] dip' in Joy. Occurrences of
|
||||
>r and r> must be balanced within a single word definition.
|
||||
* Source organization
|
||||
|
||||
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
|
||||
transient, intermediate values, variables are used for more permanent
|
||||
data.
|
||||
There is a detailed language and library reference available at
|
||||
http://factor.sourceforge.net/handbook.pdf.
|
||||
|
||||
Variables are retreived and stored using the 'get' and 'set' words. For
|
||||
example:
|
||||
You can browse the source code; it is organized into small,
|
||||
well-commented files and should be easy to follow once you have a good
|
||||
grasp of the language.
|
||||
|
||||
USE: math
|
||||
USE: namespaces
|
||||
USE: prettyprint
|
||||
* Community
|
||||
|
||||
"~" get .
|
||||
==> "/home/slava"
|
||||
The Factor homepage is located at http://factor.sourceforge.net/.
|
||||
|
||||
5 "x" set
|
||||
"x" get 2 * .
|
||||
==> 10
|
||||
Factor developers meet in the #concatenative channel on the
|
||||
irc.freenode.net server. Drop by if you want to discuss anything related
|
||||
to Factor or language design in general.
|
||||
|
||||
The set of available variables is determined using ``dynamic scope''.
|
||||
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.
|
||||
Have fun!
|
||||
|
||||
While it is possible to push/pop the namestack directly using the words
|
||||
>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:)
|
||||
:tabSize=2:indentSize=2:noTabs=true:
|
||||
|
|
|
|||
Loading…
Reference in New Issue