steve
/
factor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

starting to port tutorial to help markup

cvs
Slava Pestov 2005-12-23 02:44:15 +00:00
parent cec0fc6ddd
commit 1b92cf2f53
3 changed files with 94 additions and 268 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
library/help/markup.factor
View File

@ -43,6 +43,8 @@ M: array print-element
: $emphasis emphasis-style ($span) ; : $emphasis emphasis-style ($span) ;
: $url url-style ($span) ;
: $terpri terpri drop ; : $terpri terpri drop ;
! Some blocks ! Some blocks

8
library/help/stylesheet.factor
View File

@ -18,16 +18,20 @@ USING: styles ;
: parameter-style : parameter-style
H{ H{
{ font "Monospaced" } { font "Monospaced" }
{ font-size 12 }
{ font-style italic } { font-style italic }
} ; } ;
: code-style : code-style
H{ H{
{ font "Monospaced" } { font "Monospaced" }
{ font-size 12 }
{ page-color { 0.9 0.9 0.9 1 } } { page-color { 0.9 0.9 0.9 1 } }
{ border-color { 0.95 0.95 0.95 1 } } { border-color { 0.95 0.95 0.95 1 } }
{ border-width 5 } { border-width 5 }
{ wrap-margin f } { wrap-margin f }
} ; } ;
: url-style
H{
{ font "Monospaced" }
{ foreground { 0.0 0.0 1.0 1.0 } }
} ;

352
library/help/tutorial.factor
View File

@ -1,67 +1,27 @@
IN: help IN: help
USING: gadgets gadgets-books gadgets-borders gadgets-buttons USING: gadgets gadgets-books gadgets-borders gadgets-buttons
gadgets-editors gadgets-labels gadgets-layouts gadgets-panes gadgets-labels gadgets-panes io kernel namespaces sequences ;
gadgets-presentations gadgets-theme generic kernel lists math
namespaces sdl sequences strings styles ;
: tutorial-font { "Serif" plain 14 } swap set-label-font ;
: heading-font { "Serif" plain 24 } swap set-label-font ;
: <slide-title> ( text -- gadget )
<label> dup heading-font ;
: <underline> ( -- gadget )
<gadget>
T{ gradient f { { 0.25 0.25 0.25 1.0 } { 1.0 1.0 1.0 1.0 } } }
over set-gadget-interior
{ 0 10 0 } over set-gadget-dim
{ 1 0 0 } over set-gadget-orientation ;
GENERIC: tutorial-line ( object -- gadget )
M: string tutorial-line
{
{ [ "* " ?head ] [ <slide-title> ] }
{ [ dup "--" = ] [ drop <underline> ] }
{ [ t ] [ <label> dup tutorial-font ] }
} cond ;
: example-theme
T{ solid f { 0.8 0.8 1.0 1.0 } } swap set-gadget-interior ;
! M: general-list tutorial-line
! car <input-button> dup example-theme ;
: page-theme : page-theme
T{ gradient f { { 0.8 0.8 1.0 1.0 } { 1.0 0.8 1.0 1.0 } } } T{ gradient f { { 0.8 0.8 1.0 1.0 } { 1.0 0.8 1.0 1.0 } } }
swap set-gadget-interior ; swap set-gadget-interior ;
: <page> ( list -- gadget ) : <page> ( markup -- gadget )
[ tutorial-line ] map make-pile 1 over set-pack-fill [ default-style [ print-element ] with-style ] make-pane
dup page-theme <default-border> ; dup page-theme <default-border> ;
: tutorial-pages : tutorial-pages
{ {
{ {
"* Factor: a dynamic language" { $heading "Factor: a dynamic language" }
"--"
"This series of slides presents a quick overview of Factor." "This series of slides presents a quick overview of Factor."
"" "Factor is interactive, which means you can test out the code in this tutorial immediately."
"Factor is interactive, which means you can test out the code" "Code examples will insert themselves in the listener's input area when clicked:"
"in this tutorial immediately." { $code "\"hello world\" print" }
""
"Code examples will insert themselves in the listener's input"
"area when clicked:"
""
[ "\"hello world\" print" ]
""
"You can then press ENTER to execute the code, or edit it first." "You can then press ENTER to execute the code, or edit it first."
"" { $url "http://factorcode.org" }
"http://factor.sourceforge.net"
} { } {
"* The view from 10,000 feet" { $heading "The view from 10,000 feet" }
"--"
"- Everything is an object" "- Everything is an object"
"- A word is a basic unit of code" "- A word is a basic unit of code"
"- Words are identified by names, and organized in vocabularies" "- Words are identified by names, and organized in vocabularies"
@ -69,266 +29,131 @@ M: string tutorial-line
"- Code blocks can be passed as parameters to words" "- Code blocks can be passed as parameters to words"
"- Word definitions are very short with very high code reuse" "- Word definitions are very short with very high code reuse"
} { } {
"* Basic syntax" { $heading "Basic syntax" }
"--" "Factor code is made up of whitespace-speparated tokens. Recall the example from the first slide:"
"Factor code is made up of whitespace-speparated tokens." { $code "\"hello world\" print" }
"Recall the example from the first slide:"
""
[ "\"hello world\" print" ]
""
"The first token (\"hello world\") is a string." "The first token (\"hello world\") is a string."
"The second token (print) is a word." "The second token (print) is a word."
"The string is pushed on the stack, and the print word prints it." "The string is pushed on the stack, and the print word prints it."
} { } {
"* The stack" { $heading "The stack" }
"--"
"- The stack is like a pile of papers." "- The stack is like a pile of papers."
"- You can ``push'' papers on the top of the pile," "- You can ``push'' papers on the top of the pile,"
" and ``pop'' papers from the top of the pile." " and ``pop'' papers from the top of the pile."
""
"Here is another code example:" "Here is another code example:"
"" { $code "2 3 + ." }
[ "2 3 + ." ]
""
"Try running it in the listener now." "Try running it in the listener now."
} { } {
"* Postfix arithmetic" { $heading "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."
"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."
""
"This is called postfix arithmetic." "This is called postfix arithmetic."
"Traditional arithmetic is called infix: 3 + (6 * 2)" "Traditional arithmetic is called infix: 3 + (6 * 2)"
"Lets translate this into postfix: 3 6 2 * + ." "Lets translate this into postfix: 3 6 2 * + ."
} { } {
"* Colon definitions" { $heading "Colon definitions" }
"--"
"We can define new words in terms of existing words." "We can define new words in terms of existing words."
"" { $code ": twice 2 * ;" }
[ ": twice 2 * ;" ] "This defines a new word named ``twice'' that calls ``2 *''. Try the following in the listener:"
"" { $code "3 twice twice ." }
"This defines a new word named ``twice'' that calls ``2 *''."
"Try the following in the listener:"
""
[ "3 twice twice ." ]
""
"The result is the same as if you wrote:" "The result is the same as if you wrote:"
"" { $code "3 2 * 2 * ." }
[ "3 2 * 2 * ." ]
} { } {
"* Stack effects" { $heading "Stack effects" }
"--" "When we look at the definition of the ``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 ``stack effect''."
"When we look at the definition of the ``twice'' word," "A stack effect comment is written between ( and ). Factor ignores stack effect comments. Don't you!"
"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"
"``stack effect''."
""
"A stack effect comment is written between ( and )."
"Factor ignores stack effect comments. Don't you!"
""
"The stack effect of twice is ( x -- 2*x )." "The stack effect of twice is ( x -- 2*x )."
"The stack effect of + is ( x y -- x+y )." "The stack effect of + is ( x y -- x+y )."
"The stack effect of . is ( object -- )." "The stack effect of . is ( object -- )."
} { } {
"* Reading user input" { $heading "Reading user input" }
"--" "User input is read using the readln ( -- string ) word. Note its stack effect; it puts a string on the stack."
"User input is read using the readln ( -- string ) word."
"Note its stack effect; it puts a string on the stack."
""
"This program will ask your name, then greet you:" "This program will ask your name, then greet you:"
"" { $code "\"What is your name?\" print\nreadln \"Hello, \" write print" }
[ "\"What is your name?\" print" ]
[ "readln \"Hello, \" write print" ]
} { } {
"* Shuffle words" { $heading "Shuffle words" }
"--" "The word ``twice'' we defined is useless. Let's try something more useful: squaring a number."
"The word ``twice'' we defined is useless." "We want a word with stack effect ( n -- n*n ). We cannot use * by itself, since its stack effect is ( x y -- x*y ); it expects two inputs."
"Let's try something more useful: squaring a number." "However, we can use the word ``dup''. It has stack effect ( object -- object object ), and it does exactly what we need. The ``dup'' word is known as a shuffle word."
""
"We want a word with stack effect ( n -- n*n )."
"However, we cannot use * by itself, since its stack effect"
"is ( x y -- x*y ); it expects two inputs."
""
"However, we can use the word ``dup''. It has stack effect"
"( object -- object object ), and it does exactly what we"
"need. The ``dup'' word is known as a shuffle word."
} { } {
"* The squared word" { $heading "The squared word" }
"--"
"Try entering the following word definition:" "Try entering the following word definition:"
"" { $code ": square ( n -- n*n ) dup * ;" }
[ ": square ( n -- n*n ) dup * ;" ] "Shuffle words solve the problem where we need to compose two words, but their stack effects do not ``fit''."
""
"Shuffle words solve the problem where we need to compose"
"two words, but their stack effects do not ``fit''."
""
"Some of the most commonly-used shuffle words:" "Some of the most commonly-used shuffle words:"
"" { $code "drop ( object -- )\nswap ( obj1 obj2 -- obj2 obj1 )\nover ( obj1 obj2 -- obj1 obj2 obj1 )" }
"drop ( object -- )"
"swap ( obj1 obj2 -- obj2 obj1 )"
"over ( obj1 obj2 -- obj1 obj2 obj1 )"
} { } {
"* Another shuffle example" { $heading "Another shuffle example" }
"--"
"Now let us write a word that negates a number." "Now let us write a word that negates a number."
"Start by entering the following in the listener" "Start by entering the following in the listener"
"" { $code "0 10 - ." }
[ "0 10 - ." ]
""
"It will print -10, as expected. Now notice that this the same as:" "It will print -10, as expected. Now notice that this the same as:"
"" { $code "10 0 swap - ." }
[ "10 0 swap - ." ]
""
"So indeed, we can factor out the definition ``0 swap -'':" "So indeed, we can factor out the definition ``0 swap -'':"
"" { $code ": negate ( n -- -n ) 0 swap - ;" }
[ ": negate ( n -- -n ) 0 swap - ;" ]
} { } {
"* Seeing words" { $heading "Seeing words" }
"--" "If you have entered every definition in this tutorial, you will now have several new colon definitions:"
"If you have entered every definition in this tutorial," { $code "twice\nsquare\nnegate" }
"you will now have several new colon definitions:" "You can look at previously-entered word definitions using 'see'. Try the following:"
"" { $code "\\ negate see" }
" twice" "Prefixing a word with \\ pushes it on the stack, instead of executing it. So the see word has stack effect ( word -- )."
" square"
" negate"
""
"You can look at previously-entered word definitions using 'see'."
"Try the following:"
""
[ "\\ negate see" ]
""
"Prefixing a word with \\ pushes it on the stack, instead of"
"executing it. So the see word has stack effect ( word -- )."
} { } {
"* Branches" { $heading "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."
"Now suppose we want to write a word that computes the" { $code ": absolute ( x -- |x| ) dup 0 < [ negate ] when ;" }
"absolute value of a number; that is, if it is less than 0," "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."
"the number will be negated to yield a positive result."
""
[ ": 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."
"- The f object is false." "- The f object is false."
"- Anything else is true." "- Anything else is true."
} { } {
"* More branches" { $heading "More branches" }
"--"
"On the previous slide, you saw the 'when' conditional:" "On the previous slide, you saw the 'when' conditional:"
"" { $code " ... condition ... [ ... true case ... ] when" }
[ " ... condition ... [ ... true case ... ] when" ]
""
"Another commonly-used form is 'unless':" "Another commonly-used form is 'unless':"
"" { $code " ... condition ... [ ... false case ... ] unless" }
[ " ... condition ... [ ... false case ... ] unless" ]
""
"The 'if' conditional takes action on both branches:" "The 'if' conditional takes action on both branches:"
"" { $code " ... condition ... [ ... ] [ ... ] if" }
[ " ... condition ... [ ... ] [ ... ] if" ]
} { } {
"* Combinators" { $heading "Combinators" }
"--"
"if, when, unless are words that take lists of code as input." "if, when, unless are words that take lists of code as input."
"" "Lists of code are called ``quotations''. Words that take quotations are called ``combinators''."
"Lists of code are called ``quotations''." "Another combinator is times ( n quot -- ). It calls a quotation n times."
"Words that take quotations are called ``combinators''."
""
"Another combinator is times ( n quot -- )."
"It calls a quotation n times."
""
"Try this:" "Try this:"
"" { $code "10 [ \"Hello combinators\" print ] times" }
[ "10 [ \"Hello combinators\" print ] times" ]
} { } {
"* Sequences" { $heading "Sequences" }
"--"
"You have already seen strings, very briefly:" "You have already seen strings, very briefly:"
""
" \"Hello world\"" " \"Hello world\""
"" "Strings are part of a class of objects called sequences. Two other types of sequences you will use a lot are:"
"Strings are part of a class of objects called sequences." "Lists: [ 1 3 \"hi\" 10 2 ]"
"Two other types of sequences you will use a lot are:" "Arrays: { \"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."
" Lists: [ 1 3 \"hi\" 10 2 ]"
" Arrays: { \"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."
} { } {
"* Sequences and combinators" { $heading "Sequences and combinators" }
"--" "A very useful combinator is each ( seq quot -- ). It calls a quotation with each element of the sequence in turn."
"A very useful combinator is each ( seq quot -- )."
"It calls a quotation with each element of the sequence in turn."
""
"Try this:" "Try this:"
"" { $code "{ 10 20 30 } [ . ] each" }
[ "{ 10 20 30 } [ . ] each" ] "A closely-related combinator is 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."
"A closely-related combinator is 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:" "Try this:"
"" { $code "{ 10 20 30 } [ 3 + ] map ." }
[ "{ 10 20 30 } [ 3 + ] map ." ]
"==> { 13 23 33 }"
} { } {
"* Numbers - integers and ratios" { $heading "Numbers - integers and ratios" }
"--" "Factor supports arbitrary-precision integers and ratios."
"Factor's supports arbitrary-precision integers and ratios."
""
"Try the following:" "Try the following:"
"" { $code ": factorial ( n -- n! ) 1 swap <range> product ;\n100 factorial .\n1 3 / 1 2 / + ." }
[ ": factorial ( n -- n! ) 1 swap <range> product ;" ] "Rational numbers are added, multiplied and reduced to lowest terms in the same way you learned in grade school."
[ "100 factorial ." ]
""
[ "1 3 / 1 2 / + ." ]
""
"Rational numbers are added, multiplied and reduced to"
"lowest terms in the same way you learned in grade school."
} { } {
"* Object oriented programming" { $heading "Object oriented programming" }
"--" "Each object belongs to a class. Generic words act differently based on an object's class."
"Each object belongs to a class." { $code "GENERIC: describe ( object -- )\nM: integer describe \"The integer \" write . ;\nM: string describe \"The string \" write . ;\nM: object describe drop \"Unknown object\" print ;" }
"Generic words act differently based on an object's class." "Each M: line defines a ``method.'' Method definitions may appear in independent source files. Examples of built-in classes are integer, string, and object."
""
[ "GENERIC: describe ( object -- )" ]
[ "M: integer describe \"The integer \" write . ;" ]
[ "M: string describe \"The string \" write . ;" ]
[ "M: object describe drop \"Unknown object\" print ;" ]
""
"Each M: line defines a ``method.''"
"Method definitions may appear in independent source files."
""
"integer, string, object are built-in classes."
} { } {
"* Defining new classes" { $heading "Defining new classes" }
"--"
"New classes can be defined:" "New classes can be defined:"
"" { $code "TUPLE: point x y ;\nM: point describe\n \"x =\" write dup point-x .\n \"y =\" write point-y . ;\n100 200 <point> describe" }
[ "TUPLE: point x y ;" ] "A tuple is a collection of named slots. Tuples support custom constructors, delegation... see the developer's handbook for details."
[ "M: point describe" ]
[ " \"x =\" write dup point-x ." ]
[ " \"y =\" write point-y . ;" ]
[ "100 200 <point> describe" ]
""
"A tuple is a collection of named slots."
""
"Tuples support custom constructors, delegation..."
"see the developer's handbook for details."
} { } {
"* The library" { $heading "The library" }
"--"
"Offers a good selection of highly-reusable words:" "Offers a good selection of highly-reusable words:"
"- Operations on sequences" "- Operations on sequences"
"- Variety of mathematical functions" "- Variety of mathematical functions"
@ -336,22 +161,17 @@ M: string tutorial-line
"- Graphical user interface framework" "- Graphical user interface framework"
"Browsing the library:" "Browsing the library:"
"- To list all vocabularies:" "- To list all vocabularies:"
[ "vocabs ." ] { $code "vocabs." }
"- To list all words in a vocabulary:" "- To list all words in a vocabulary:"
[ "\"sequences\" words ." ] { $code "\"sequences\" words." }
"- To show a word definition:" "- To show a word definition:"
[ "\\ reverse see" ] { $code "\\ reverse see" }
} { } {
"* Learning more" { $heading "Learning more" }
"--"
"Hopefully this tutorial has sparked your interest in Factor." "Hopefully this tutorial has sparked your interest in Factor."
""
"You can learn more by reading the Factor developer's handbook:" "You can learn more by reading the Factor developer's handbook:"
"" { $url "http://factorcode.org/handbook.pdf" }
"http://factor.sourceforge.net/handbook.pdf" "Also, point your IRC client to irc.freenode.net and hop in the #concatenative channel to chat with other Factor geeks."
""
"Also, point your IRC client to irc.freenode.net and hop in the"
"#concatenative channel to chat with other Factor geeks."
} }
} ; } ;