diff --git a/CHANGES.txt b/CHANGES.txt index d49954aba2..67f9932d32 100644 --- a/CHANGES.txt +++ b/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: diff --git a/Makefile b/Makefile index 1a8836b732..148077d847 100644 --- a/Makefile +++ b/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)" \ diff --git a/README.txt b/README.txt index bf405e1744..72a1bbf9d2 100644 --- a/README.txt +++ b/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. -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. -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" [ "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: