Using tabular-output in room. and heap-stats., better looking $list, new $table markup, use $table in a few places in the docs

TODO.FACTOR.txt

@@ -6,6 +6,7 @@
 [ 1 2 3 4 5 6 7 8 9 10 10 10 10 10 10 10 10 10 10 11 11 11 113 
 ]
 
+- unix i/o: problems with passing f to syscalls
 - if a primitive throws an error, :c doesn't show the call frame there
 - "benchmark/help": without a yield UI runs out of memory
 - x11 title bars are funny
@@ -37,9 +38,7 @@
   - better line spacing in ui and html - related issue
 
 + tabular formatting in UI
-  - $values
   - other help aspects
-  - setting grid gap
 
 + fix compiled gc check
   - there was a performance hit, investigate

doc/handbook/alien.facts

@@ -60,19 +60,20 @@ $terpri
 
 ARTICLE: "c-types-numeric" "Integer and floating point C types"
 "The following numerical types are available; a " { $snippet "u" } " prefix denotes an unsigned type:"
-{ $list
+{ $table
-    { { $snippet "char" } " - always 1 byte" }
+    { "C type" "Notes" }
+    { { $snippet "char" } "always 1 byte" }
     { $snippet "uchar" }
-    { { $snippet "short" } " - always 2 bytes" }
+    { { $snippet "short" } "always 2 bytes" }
     { $snippet "ushort" }
-    { { $snippet "int" } " - always 4 bytes" }
+    { { $snippet "int" } "always 4 bytes" }
     { $snippet "uint" }
-    { { $snippet "long" } " - same size as CPU word size and " { $snippet "void*" } ", except on 64-bit Windows, where it is 4 bytes" }
+    { { $snippet "long" } { "same size as CPU word size and " { $snippet "void*" } ", except on 64-bit Windows, where it is 4 bytes" } }
-    { $snippet "ulong" }
+    { { $snippet "ulong" } { }
-    { { $snippet "longlong" } " - always 8 bytes" }
+    { { $snippet "longlong" } "always 8 bytes" }
-    { $snippet "ulonglong" }
+    { { $snippet "ulonglong" } { }
-    { $snippet "float" }
+    { { $snippet "float" } { } }
-    { { $snippet "double" } " - same format as " { $link float } " objects" }
+    { { $snippet "double" } "same format as " { $link float } " objects" }
 }
 "When making alien calls, Factor numbers are converted to and from the above types in a canonical way. Converting a Factor number to a C value may result in a loss of precision."
 $terpri
@@ -113,9 +114,10 @@ $terpri
 
 ARTICLE: "c-types-strings" "C string types"
 "The C library interface defines two types of C strings:"
-{ $list
+{ $table
-    { { $snippet "char*" } " - 8-bit per character null-terminated ASCII" }
+    { "C type" "Notes" }
-    { { $snippet "ushort*" } " - 16-bit per character null-terminated UTF16" }
+    { { $snippet "char*" } "8-bit per character null-terminated ASCII" }
+    { { $snippet "ushort*" } "16-bit per character null-terminated UTF16" }
 }
 "Passing an instance of " { $link c-ptr } " to a C function expecting a C string will simply pass in the address of the " { $link c-ptr } "."
 $terpri

doc/handbook/parser.facts

@@ -44,11 +44,12 @@ ARTICLE: "parsing-word-nest" "Nested structure"
 "The first thing to look at is how the parse tree is built. When parsing begins, " { $link f } " is pushed on the data stack; when a new object is parsed, " { $link ?push } " is called to add it to the parse tree. The first call to " { $link ?push } " creates a new one-element vector, and subsequent calls add elements to the end of this vector. When parsing is complete, the vector is converted into a quotation."
 $terpri
 "Lets look at a simple example; the parsing of " { $snippet "1 2 3" } ":"
-{ $list
+{ $table
-    { "Initial stack after parsing begins:" { $snippet "f" } }
+    { "Action" "Stack" }
-    { "Token: " { $snippet "1" } " - stack top: " { $snippet "V{ 1 }" } }
+    { "Initial stack after parsing begins" { $snippet "f" } }
-    { "Token: " { $snippet "2" } " - stack top: " { $snippet "V{ 1 2 }" } }
+    { { "Token: " { $snippet "1" } } { $snippet "V{ 1 }" } }
-    { "Token: " { $snippet "3" } " - stack top: " { $snippet "V{ 1 2 3 }" } }
+    { { "Token: " { $snippet "2" } } { $snippet "V{ 1 2 }" } }
+    { { "Token: " { $snippet "3" } } { $snippet "V{ 1 2 3 }" } }
     { "Final stack upon completion:" { $snippet "[ 1 2 3 ]" } }
 }
 "Nested structure is a bit more involved. The basic idea is that parsing words can push " { $link f } " on the stack to begin a new level of nesting, then all subsequent objects are pushed onto this sequence, until another parsing word adds this sequence to the vector underneath."
@@ -58,15 +59,16 @@ $terpri
 { $subsection POSTPONE: ] }
 "Let us ponder, then, how one particular string will parse:"
 { $snippet "\"1 [ 2 3 ] 4\"" }
-{ $list
+{ $table
-    { "Initial stack after parsing begins:" { $snippet "f" } }
+    { "Action" "Stack" }
-    { "Token: " { $snippet "1" } " - stack top: " { $snippet "V{ 1 }" } }
+    { "Initial stack after parsing begins" { $snippet "f" } }
-    { "Token: " { $snippet "[" } " - stack top: " { $snippet "V{ 1 } f" } }
+    { { "Token: " { $snippet "1" } } { $snippet "V{ 1 }" } }
-    { "Token: " { $snippet "2" } " - stack top: " { $snippet "V{ 1 } V{ 2 }" } }
+    { { "Token: " { $snippet "[" } } { $snippet "V{ 1 } f" } }
-    { "Token: " { $snippet "3" } " - stack top: " { $snippet "V{ 1 } V{ 2 3 }" } }
+    { { "Token: " { $snippet "2" } } { $snippet "V{ 1 } V{ 2 }" } }
-    { "Token: " { $snippet "]" } " - stack top: " { $snippet "V{ 1 [ 2 3 ] }" } }
+    { { "Token: " { $snippet "3" } } { $snippet "V{ 1 } V{ 2 3 }" } }
-    { "Token: " { $snippet "4" } " - stack top: " { $snippet "V{ 1 [ 2 3 ] 4 }" } }
+    { { "Token: " { $snippet "]" } } { $snippet "V{ 1 [ 2 3 ] }" } }
-    { "Final stack upon completion:" { $snippet "[ 1 [ 2 3 ] 4 ]" } }
+    { { "Token: " { $snippet "4" } } { $snippet "V{ 1 [ 2 3 ] 4 }" } }
+    { "Final stack upon completion" { $snippet "[ 1 [ 2 3 ] 4 ]" } }
 }
 "Notice how in the definition of the quotation parsing words, the final word " { $link POSTPONE: ] } " does all the work. A closely related set of parsing words for reading various other literal types implements another useful idiom."
 $terpri

doc/handbook/syntax.facts

@@ -168,16 +168,16 @@ ARTICLE: "syntax-strings" "Character and string syntax"
 "Strings are documented in " { $link "strings" } "." ;
 
 ARTICLE: "escape" "Character escape codes"
-"The following escape codes may be used:"
+{ $table
-{ $list
+    { "Escape code" "Meaning" }
-    { { $snippet "\\\\" } " - " { $snippet "\\" } }
+    { { $snippet "\\\\" } { $snippet "\\" } }
-    { { $snippet "\\s" } " - a space" }
+    { { $snippet "\\s" } "a space" }
-    { { $snippet "\\t" } " - a tab" }
+    { { $snippet "\\t" } "a tab" }
-    { { $snippet "\\n" } " - a newline" }
+    { { $snippet "\\n" } "a newline" }
-    { { $snippet "\\r" } " - a carriage return" }
+    { { $snippet "\\r" } "a carriage return" }
-    { { $snippet "\\0" } " - a null byte (ASCII 0)" }
+    { { $snippet "\\0" } "a null byte (ASCII 0)" }
-    { { $snippet "\\e" } " - escape (ASCII 27)" }
+    { { $snippet "\\e" } "escape (ASCII 27)" }
-    { { $snippet "\\\"" } " - " { $snippet "\"" } }
+    { { $snippet "\\\"" } { $snippet "\"" } }
 }
 "A Unicode character can be specified by its code number by writing " { $snippet "\\u" } " followed by a four-digit hexadecimal number. That is, the following two expressions are equivalent:"
 { $code

doc/handbook/tutorial.facts

@@ -1,198 +0,0 @@
-IN: help
-USING: io ;
-
-ARTICLE: "tutorial-overview" "The view from 10,000 feet"
-{ $list
-    "Everything is an object"
-    "A word is a basic unit of code"
-    "Words are identified by names, and organized in vocabularies"
-    "Words pass parameters on the stack"
-    "Code blocks can be passed as parameters to words"
-    "Word definitions are very short with very high code reuse"
-} ;
-
-ARTICLE: "tutorial-syntax" "Basic syntax"
-"Factor code is made up of whitespace-separated tokens. Recall the example from the first page:"
-{ $code "\"hello world\" print" }
-{ $list 
-    { "The first token (" { $snippet "\"hello world\"" } ") is a string." }
-    { "The second token (" { $snippet "print" } ") is a word." }
-    "The string is pushed on the stack, and the print word prints it."
-} ;
-
-ARTICLE: "tutorial-stack" "The stack"
-"The stack is like a pile of papers. You can ``push'' papers on the top of the pile and ``pop'' papers from the top of the pile. Here is another code example:"
-{ $code "2 3 + ." }
-"Try running it in the listener now." ;
-
-ARTICLE: "tutorial-postfix" "Postfix arithmetic"
-"What happened when you ran it? The two numbers (2 3) are pushed on the stack. Then, the + word pops them and pushes the result (5). Then, the . word prints this result."
-{ $list
-    "This is called postfix arithmetic."
-    { "Traditional arithmetic is called infix: " { $snippet "3 + (6 * 2)" } }
-    { "Lets translate this into postfix: " { $snippet "3 6 2 * + ." } }
-} ;
-
-ARTICLE: "tutorial-colon-def" "Colon definitions"
-"We can define new words in terms of existing words."
-{ $code ": twice  2 * ;" }
-"This defines a new word named " { $snippet "twice" } " that calls " { $snippet "2 *" } ". Try the following in the listener:"
-{ $code "3 twice twice ." }
-"The result is the same as if you wrote:"
-{ $code "3 2 * 2 * ." } ;
-
-ARTICLE: "tutorial-stack-effects" "Stack effects"
-"When we look at the definition of the " { $snippet "twice" } " word, it is intuitively obvious that it takes one value from the stack, and leaves one value behind. However, with more complex definitions, it is better to document this so-called " { $emphasis "stack effect" } ". A stack effect comment is written between ( and ). Factor ignores stack effect comments. Don't you!"
-$terpri
-"The stack effect of " { $snippet "twice" } " is " { $snippet "( x -- 2*x )" } "."
-$terpri
-"The stack effect of " { $snippet "+" } " is " { $snippet "( x y -- x+y )" } "."
-$terpri
-"The stack effect of " { $snippet "." } " is " { $snippet "( object -- )" } "." ;
-
-ARTICLE: "tutorial-input" "Reading user input"
-"User input is read using the " { $snippet "readln ( -- string )" } " word. Note its stack effect; it puts a string on the stack."
-"This program will ask your name, then greet you:"
-{ $code "\"What is your name?\" print\nreadln \"Hello, \" write print" } ;
-
-ARTICLE: "tutorial-shuffle" "Shuffle words"
-"The word " { $snippet "twice" } " we defined is useless. Let's try something more useful: squaring a number."
-$terpri
-"We want a word with stack effect " { $snippet "( n -- n*n )" } ". We cannot use " { $snippet "*" } " by itself, since its stack effect is " { $snippet "( x y -- x*y )" } "; it expects two inputs."
-$terpri
-"However, we can use the word " { $snippet "dup ( object -- object object )" } ". The " { $snippet "dup" } " word is known as a shuffle word." ;
-
-ARTICLE: "tutorial-squared" "The squared word"
-"Try entering the following word definition:"
-{ $code ": square ( n -- n*n ) dup * ;" }
-"Shuffle words solve the problem where we need to compose two words, but their stack effects do not ``fit''."
-$terpri
-"Some of the most commonly-used shuffle words:"
-{ $code "drop ( object -- )\nswap ( obj1 obj2 -- obj2 obj1 )\nover ( obj1 obj2 -- obj1 obj2 obj1 )" } ;
-
-ARTICLE: "tutorial-shuffle-again" "Another shuffle example"
-"Now let us write a word that negates a number."
-"Start by entering the following in the listener"
-{ $code "0 10 - ." }
-"It will print -10, as expected. Now notice that this the same as:"
-{ $code "10 0 swap - ." }
-"So indeed, we can factor out the definition " { $snippet "0 swap -" } ":"
-{ $code ": negate ( n -- -n ) 0 swap - ;" } ;
-
-ARTICLE: "tutorial-see" "Seeing words"
-"If you have entered every definition in this tutorial, you will now have several new colon definitions:"
-{ $code "twice\nsquare\nnegate" }
-"You can look at previously-entered word definitions using " { $snippet "see" } ". Try the following:"
-{ $code "\\ negate see" }
-"Prefixing a word with " { $snippet "\\" } " pushes it on the stack, instead of executing it. So the see word has stack effect " { $snippet "( word -- )" } "." ;
-
-ARTICLE: "tutorial-branches" "Branches"
-"Now suppose we want to write a word that computes the absolute value of a number; that is, if it is less than 0, the number will be negated to yield a positive result."
-{ $code ": absolute ( x -- |x| ) dup 0 < [ negate ] when ;" }
-"If the top of the stack is negative, the word negates it again, making it positive. The < ( x y -- x<y ) word outputs a boolean. In Factor, any object can be used as a truth value."
-{ $list
-    "The f object is false."
-    "Anything else is true."
-}
-"Another commonly-used form is 'unless':"
-{ $code "... condition ... [ ... false case ... ] unless" }
-"The 'if' conditional takes action on both branches:"
-{ $code "... condition ... [ ... ] [ ... ] if" } ;
-
-ARTICLE: "tutorial-combinators" "Combinators"
-{ $snippet "if" } ", " { $snippet "when" } ", " { $snippet "unless" } " are words that take lists of code as input. Lists of code are called " { $emphasis "quotations" } ". Words that take quotations are called " { $emphasis "combinators" } ". Another combinator is " { $snippet "times ( n quot -- )" } ". It calls a quotation n times. Try this:"
-{ $code "10 [ \"Hello combinators\" print ] times" } ;
-
-ARTICLE: "tutorial-sequences" "Sequences"
-"You have already seen strings, very briefly:"
-{ $code "\"Hello world\"" }
-"Strings are part of a class of objects called sequences. Two other types of sequences you will use a lot are lists:"
-{ $code "[ 1 3 \"hi\" 10 2 ]" }
-"and arrays:"
-{ $code "{ \"the\" { \"quick\" \"brown\" } \"fox\" }" }
-"As you can see in the second example, lists and arrays can contain any type of object, including other lists and arrays." ;
-
-ARTICLE: "tutorial-seq-combinators" "Sequences and combinators"
-"A very useful combinator is " { $snippet "each ( seq quot -- )" } ". It calls a quotation with each element of the sequence in turn."
-"Try this:"
-{ $code "{ 10 20 30 } [ . ] each" }
-"A closely-related combinator is " { $snippet "map ( seq quot -- seq )" } ". It also calls a quotation with each element."
-"However, it then collects the outputs of the quotation into a new sequence. Try this:"
-{ $code "{ 10 20 30 } [ 3 + ] map ." } ;
-
-ARTICLE: "tutorial-rationals" "Numbers - integers and ratios"
-"Factor supports arbitrary-precision integers and ratios. Try the following:"
-{ $code ": factorial ( n -- n! ) [ 1+ ] map product ;\n100 factorial .\n1 3 / 1 2 / + ." }
-"Rational numbers are added, multiplied and reduced to lowest terms in the same way you learned in grade school." ;
-
-ARTICLE: "tutorial-oop" "Object oriented programming"
-"Each object belongs to a class. Generic words act differently based on an object's class."
-{ $code "GENERIC: explain ( object -- )\nM: integer explain \"The integer \" write . ;\nM: string explain \"The string \" write . ;\nM: object explain drop \"Unknown object\" print ;" }
-"Each " { $snippet "M:" } " line defines a " { $emphasis "method" } ". Method definitions may appear in independent source files. Examples of built-in classes are " { $snippet "integer" } ", " { $snippet "string" } ", and " { $snippet "object" } "." ;
-
-ARTICLE: "tutorial-classes" "Defining new classes"
-"New classes can be defined:"
-{ $code "TUPLE: point x y ;\nM: point explain\n  \"x = \" write dup point-x .\n  \"y = \" write point-y . ;\n100 200 <point> explain" }
-"A tuple is a collection of named slots. Tuples support custom constructors, delegation... see the developer's handbook for details." ;
-
-ARTICLE: "tutorial-library" "The library"
-"Offers a good selection of highly-reusable words:"
-{ $list
-    "Operations on sequences"
-    "Variety of mathematical functions"
-    "Web server and web application framework"
-    "Graphical user interface framework"
-}
-"Browsing the library:"
-{ $list
-    {
-        "To list all vocabularies:"
-        { $code "vocabs ." }
-    }
-    {
-        "To list all words in a vocabulary:"
-        { $code "\"sequences\" words ." }
-    }
-    {
-        "To show a word definition:"
-        { $code "\\ reverse see" }
-    }
-} ;
-
-ARTICLE: "tutorial-more" "Learning more"
-"Hopefully this tutorial has sparked your interest in Factor."
-"You can learn more by reading the Factor developer's handbook:"
-$terpri
-{ $url "http://factorcode.org/handbook.pdf" }
-$terpri
-"Also, point your IRC client to irc.freenode.net and hop in the #concatenative channel to chat with other Factor geeks." ;
-
-ARTICLE: "tutorial" "Factor tutorial"
-"Welcome to the Factor tutorial!"
-$terpri
-"Factor is interactive, which means you can test out the code in this tutorial immediately."
-$terpri
-"Code examples will insert themselves in the listener's input area when clicked:"
-{ $code "\"hello world\" print" }
-"You can then press ENTER to execute the code, or edit it first."
-{ $url "http://factorcode.org" }
-{ $subsection "tutorial-overview" }
-{ $subsection "tutorial-syntax" }
-{ $subsection "tutorial-stack" }
-{ $subsection "tutorial-postfix" }
-{ $subsection "tutorial-colon-def" }
-{ $subsection "tutorial-stack-effects" }
-{ $subsection "tutorial-input" }
-{ $subsection "tutorial-shuffle" }
-{ $subsection "tutorial-squared" }
-{ $subsection "tutorial-shuffle-again" }
-{ $subsection "tutorial-see" }
-{ $subsection "tutorial-branches" }
-{ $subsection "tutorial-combinators" }
-{ $subsection "tutorial-sequences" }
-{ $subsection "tutorial-seq-combinators" }
-{ $subsection "tutorial-rationals" }
-{ $subsection "tutorial-oop" }
-{ $subsection "tutorial-classes" }
-{ $subsection "tutorial-library" }
-{ $subsection "tutorial-more" } ;

library/bootstrap/boot-stage1.factor

@@ -296,7 +296,6 @@ vectors words ;
         "/doc/handbook/streams.facts"
         "/doc/handbook/syntax.facts"
         "/doc/handbook/tools.facts"
-        "/doc/handbook/tutorial.facts"
         "/doc/handbook/words.facts"
     } [ parse-resource* % ] each
     

library/help/markup.factor

@@ -154,10 +154,12 @@ M: f >link <link> ;
 : $see-also ( content -- )
     "See also" $heading [ 1array $link ] textual-list ;
 
+: $table ( content -- ) [ print-element ] tabular-output ;
+
 : $values ( content -- )
     "Arguments and values" $heading
-    [ unclip $snippet " -- " format* print-element ]
+    [ first2 >r \ $snippet swap 2array r> 2array ] map
-    [ terpri ] interleave ;
+    $table ;
 
 : $predicate ( content -- )
     { { "object" "an object" } } $values
@@ -167,12 +169,7 @@ M: f >link <link> ;
         " class." ,
     ] { } make $description ;
 
-: $list ( content -- )
+: $list ( content -- ) [  "-" swap 2array ] map $table ;
-    [
-        [
-            list-element-style [ print-element ] with-nesting*
-        ] ($block)
-    ] each ;
 
 : $errors ( content -- )
     "Errors" $heading print-element ;

library/help/stylesheet.factor

@@ -63,6 +63,3 @@ USING: styles ;
         { border-color { 1 0 0 1 } }
         { border-width 5 }
     } ;
-
-: list-element-style
-    H{ { border-color { 0.8 0.8 0.8 1 } } { border-width 5 } } ;

library/tools/memory.factor

@@ -9,26 +9,31 @@ sequences strings vectors words ;
 
 ! Printing an overview of heap usage.
 
-: kb.
+: total/used/free, ( free total str -- )
-    1024 /i number>string
+    [
-    6 CHAR: \s pad-left  write
+        ,
-    " KB" write ;
+        dup number>string ,
+        over - number>string ,
+        number>string ,
+    ] { } make , ;
 
-: (room.) ( free total -- )
+: total, ( n str -- )
-    2dup swap - swap ( free used total )
+    [ , number>string , "" , "" , ] { } make , ;
-    kb. " total " write
+
-    kb. " used " write
+: room-table ( -- table )
-    kb. " free" print ;
+    room [
+        { "" "Total" "Used" "Free" } ,
+        0 [
+            "Generation " pick number>string append
+            >r first2 r> total/used/free, 1+
+        ] reduce drop
+        "Semi-space" total,
+        "Cards" total,
+        "Code space" total/used/free,
+    ] [ ] make ;
 
 : room. ( -- )
-    room
+    room-table [ write ] tabular-output ;
-    0 swap [
-        "Generation " write over pprint ":" write
-        first2 (room.) 1+
-    ] each drop
-    "Semi-space:  " write kb. terpri
-    "Cards:       " write kb. terpri
-    "Code space:  " write (room.) ;
 
 ! Some words for iterating through the heap.
 
@@ -76,13 +81,12 @@ M: object each-slot ( obj quot -- )
     H{ } clone H{ } clone
     [ >r 2dup r> heap-stat-step ] each-object ;
 
-: heap-stat. ( instances bytes class -- )
-    pprint ": " write
-    pprint " bytes, " write
-    pprint " instances" print ;
-
 : heap-stats. ( -- )
     heap-stats dup hash-keys natural-sort [
-        ( hash hash key -- )
+        { "Class" "Bytes" "Instances" } ,
-        [ [ pick hash ] keep pick hash ] keep heap-stat.
+        [
-    ] each 2drop ;
+            ( hash hash key -- )
+            [ dup , dup pick hash , pick hash , ] { } make ,
+        ] each 2drop
+    ] { } make
+    [ dup string? [ write ] [ pprint ] if ] tabular-output ;

library/ui/gadgets/grids.factor

@@ -36,10 +36,15 @@ C: grid ( children -- grid )
 : with-grid ( grid quot -- | quot: horiz vert -- )
     [ >r grid set compute-grid r> call ] with-scope ; inline
 
-: +gap+ + grid get grid-gap + ;
+: gap grid get grid-gap ;
 
 M: grid pref-dim* ( grid -- dim )
-    [ [ 0 [ +gap+ ] reduce ] 2apply 0 3array ] with-grid ;
+    [
+        [
+            [ 0 [ + ] reduce ] keep length
+            1- 0 max gap * +
+        ] 2apply 0 3array
+    ] with-grid ;
 
 : pair-up ( horiz vert -- dims )
     [ swap [ swap 0 3array ] map-with ] map-with ;
@@ -50,7 +55,7 @@ M: grid pref-dim* ( grid -- dim )
     ] 2each drop ; inline
 
 : position-grid ( horiz vert -- )
-    [ 0 [ +gap+ ] accumulate ] 2apply
+    [ 0 [ + gap + ] accumulate ] 2apply
     pair-up [ set-rect-loc ] do-grid ;
 
 : resize-grid ( horiz vert -- )

library/ui/gadgets/panes.factor

@@ -141,5 +141,6 @@ M: pane stream-close ( pane -- ) drop ;
     <pane> [ swap with-pane ] keep ; inline
 
 M: pane with-stream-table ( quot grid pane -- )
-    >r [ [ swap make-pane ] map-with ] map-with <grid>
+    >r [ [ swap make-pane ] map-with ] map-with
+    <grid> 5 over set-grid-gap
     r> [ write-gadget ] keep stream-terpri ;