extra/help/handbook/handbook.factor

   1 USING: help help.markup help.syntax help.definitions help.topics
   2 namespaces words sequences classes assocs vocabs kernel arrays
   3 prettyprint.backend kernel.private io generic math system
   4 strings sbufs vectors byte-arrays bit-arrays float-arrays
   5 quotations io.streams.byte-array io.encodings.string
   6 classes.builtin parser ;
   7 IN: help.handbook
   8
   9 ARTICLE: "conventions" "Conventions"
  10 "Various conventions are used throughout the Factor documentation and source code."
  11 { $heading "Documentation conventions" }
  12 "Factor documentation consists of two distinct bodies of text. There is a hierarchy of articles, much like this one, and there is word documentation. Help articles reference word documentation, and vice versa, but not every documented word is referenced from some help article."
  13 $nl
  14 "Every article has links to parent articles at the top. These can be persued if the article is too specific."
  15 $nl
  16 "Some generic words have " { $strong "Description" } " headings, and others have " { $strong "Contract" } " headings. A distinction is made between words which are not intended to be extended with user-defined methods, and those that are."
  17 { $heading "Vocabulary naming conventions" }
  18 "A vocabulary name ending in " { $snippet ".private" } " contains words which are either implementation detail, unsafe, or both. For example, the " { $snippet "sequence.private" } " vocabulary contains words which access sequence elements without bounds checking (" { $link "sequences-unsafe" } ")."
  19 $nl
  20 "You should should avoid using internal words from the Factor library unless absolutely necessary. Similarly, your own code can place words in internal vocabularies if you do not want other people to use them unless they have a good reason."
  21 { $heading "Word naming conventions" }
  22 "These conventions are not hard and fast, but are usually a good first step in understanding a word's behavior:"
  23 { $table
  24     { "General form" "Description" "Examples" }
  25     { { $snippet { $emphasis "foo" } "?" } "outputs a boolean" { { $link empty? } } }
  26     { { $snippet "?" { $emphasis "foo" } } { "conditionally performs " { $snippet { $emphasis "foo" } } } { { $links ?nth } } }
  27     { { $snippet "<" { $emphasis "foo" } ">" } { "creates a new " { $snippet "foo" } } { { $link <array> } } }
  28     { { $snippet "new-" { $emphasis "foo" } } { "creates a new " { $snippet "foo" } ", taking some kind of parameter from the stack which determines the type of the object to be created" } { { $link new-sequence } ", " { $link new-lexer } ", " { $link new } } }
  29     { { $snippet { $emphasis "foo" } "*" } { "alternative form of " { $snippet "foo" } ", or a generic word called by " { $snippet "foo" } } { { $links at* pprint* } } }
  30     { { $snippet "(" { $emphasis "foo" } ")" } { "implementation detail word used by " { $snippet "foo" } } { { $link (clone) } } }
  31     { { $snippet "set-" { $emphasis "foo" } } { "sets " { $snippet "foo" } " to a new value" } { $links set-length } }
  32     { { $snippet { $emphasis "foo" } "-" { $emphasis "bar" } } { "(tuple accessors) outputs the value of the " { $snippet "bar" } " slot of the " { $snippet "foo" } " at the top of the stack" } { } }
  33     { { $snippet "set-" { $emphasis "foo" } "-" { $emphasis "bar" } } { "(tuple mutators) sets the value of the " { $snippet "bar" } " slot of the " { $snippet "foo" } " at the top of the stack" } { } }
  34     { { $snippet "with-" { $emphasis "foo" } } { "performs some kind of initialization and cleanup related to " { $snippet "foo" } ", usually in a new dynamic scope" } { $links with-scope with-stream } }
  35     { { $snippet "$" { $emphasis "foo" } } { "help markup" } { $links $heading $emphasis } }
  36 }
  37 { $heading "Stack effect conventions" }
  38 "Stack effect conventions are documented in " { $link "effect-declaration" } "."
  39 { $heading "Glossary of terms" }
  40 "Common terminology and abbreviations used throughout Factor and its documentation:"
  41 { $table
  42     { "Term" "Definition" }
  43     { "alist" { "an association list. See " { $link "alists" } } }
  44     { "assoc" "an associative mapping" }
  45     { "associative mapping" { "an object whose class implements the " { $link "assocs-protocol" } } }
  46     { "boolean"               { { $link t } " or " { $link f } } }
  47     { "class"                 { "a set of objects identified by a " { $emphasis "class word" } " together with a discriminating predicate. See " { $link "classes" } } }
  48     { "definition specifier"  { "a " { $link word } ", " { $link method-spec } ", " { $link link } ", vocabulary specifier, or any other object whose class implements the " { $link "definition-protocol" } } }
  49     { "generalized boolean"   { "an object interpreted as a boolean; a value of " { $link f } " denotes false and anything else denotes true" } }
  50     { "generic word"          { "a word whose behavior depends can be specialized on the class of one of its inputs. See " { $link "generic" } } }
  51     { "method"                { "a specialized behavior of a generic word on a class. See " { $link "generic" } } }
  52     { "object"                { "any datum which can be identified" } }
  53     { "pathname string"       { "an OS-specific pathname which identifies a file" } }
  54     { "sequence" { "an object whose class implements the " { $link "sequence-protocol" } } }
  55     { "slot"                  { "a component of an object which can store a value" } }
  56     { "stack effect"          { "a pictorial representation of a word's inputs and outputs, for example " { $snippet "+ ( x y -- z )" } ". See " { $link "effects" } } }
  57     { "true value"            { "any object not equal to " { $link f } } }
  58     { "vocabulary" { "a named set of words. See " { $link "vocabularies" } } }
  59     { "vocabulary specifier"  { "a " { $link vocab } ", " { $link vocab-link } " or a string naming a vocabulary" } }
  60     { "word"                  { "the basic unit of code, analogous to a function or procedure in other programming languages. See " { $link "words" } } }
  61 } ;
  62
  63 ARTICLE: "evaluator" "Evaluation semantics"
  64 { $link "quotations" } " are evaluated sequentially from beginning to end. When the end is reached, the quotation returns to its caller. As each object in the quotation is evaluated in turn, an action is taken based on its type:"
  65 { $list
  66     { "a " { $link word } " - the word's definition quotation is called. See " { $link "words" } }
  67     { "a " { $link wrapper } " - the wrapped object is pushed on the data stack. Wrappers are used to push word objects directly on the stack when they would otherwise execute. See the " { $link POSTPONE: \ } " parsing word." }
  68     { "All other types of objects are pushed on the data stack." }
  69 }
  70 "If the last action performed is the execution of a word, the current quotation is not saved on the call stack; this is known as " { $snippet "tail-recursion" } " and allows iterative algorithms to execute without incurring unbounded call stack usage."
  71 { $see-also "compiler" } ;
  72
  73 USING: concurrency.combinators
  74 concurrency.messaging
  75 concurrency.promises
  76 concurrency.futures
  77 concurrency.locks
  78 concurrency.semaphores
  79 concurrency.count-downs
  80 concurrency.exchangers
  81 concurrency.flags ;
  82
  83 ARTICLE: "concurrency" "Concurrency"
  84 "Factor supports a variety of concurrency abstractions, however they are mostly used to multiplex input/output operations since the thread scheduling is co-operative and only one CPU is used at a time."
  85 $nl
  86 "Factor's concurrency support was insipired by Erlang, Termite, Scheme48 and Java's " { $snippet "java.util.concurrent" } " library."
  87 $nl
  88 "The basic building blocks:"
  89 { $subsection "threads" }
  90 "High-level abstractions:"
  91 { $subsection "concurrency.combinators" }
  92 { $subsection "concurrency.promises" }
  93 { $subsection "concurrency.futures" }
  94 { $subsection "concurrency.mailboxes" }
  95 { $subsection "concurrency.messaging" }
  96 "Shared-state abstractions:"
  97 { $subsection "concurrency.locks" }
  98 { $subsection "concurrency.semaphores" }
  99 { $subsection "concurrency.count-downs" }
 100 { $subsection "concurrency.exchangers" }
 101 { $subsection "concurrency.flags" }
 102 "Other concurrency abstractions include " { $vocab-link "concurrency.distributed" } " and " { $vocab-link "channels" } "." ;
 103
 104 ARTICLE: "objects" "Objects"
 105 "An " { $emphasis "object" } " is any datum which may be identified. All values are objects in Factor. Each object carries type information, and types are checked at runtime; Factor is dynamically typed."
 106 { $subsection "equality" }
 107 { $subsection "classes" }
 108 { $subsection "tuples" }
 109 { $subsection "generic" }
 110 { $subsection "slots" }
 111 { $subsection "mirrors" } ;
 112
 113 USE: random
 114
 115 ARTICLE: "numbers" "Numbers"
 116 { $subsection "arithmetic" }
 117 { $subsection "math-constants" }
 118 { $subsection "math-functions" }
 119 { $subsection "number-strings" }
 120 { $subsection "random-numbers" }
 121 "Number implementations:"
 122 { $subsection "integers" }
 123 { $subsection "rationals" }
 124 { $subsection "floats" }
 125 { $subsection "complex-numbers" }
 126 "Advanced features:"
 127 { $subsection "math-vectors" }
 128 { $subsection "math-intervals" }
 129 { $subsection "math-bitfields" } ;
 130
 131 USE: io.buffers
 132
 133 ARTICLE: "collections" "Collections"
 134 { $heading "Sequences" }
 135 { $subsection "sequences" }
 136 "Fixed-length sequences:"
 137 { $subsection "arrays" }
 138 { $subsection "quotations" }
 139 "Fixed-length specialized sequences:"
 140 { $subsection "strings" }
 141 { $subsection "bit-arrays" }
 142 { $subsection "byte-arrays" }
 143 { $subsection "float-arrays" }
 144 "Resizable sequence:"
 145 { $subsection "vectors" }
 146 "Resizable specialized sequences:"
 147 { $subsection "sbufs" }
 148 { $subsection "bit-vectors" }
 149 { $subsection "byte-vectors" }
 150 { $subsection "float-vectors" }
 151 { $heading "Associative mappings" }
 152 { $subsection "assocs" }
 153 { $subsection "namespaces" }
 154 "Implementations:"
 155 { $subsection "hashtables" }
 156 { $subsection "alists" }
 157 { $subsection "enums" }
 158 { $heading "Other collections" }
 159 { $subsection "boxes" }
 160 { $subsection "dlists" }
 161 { $subsection "heaps" }
 162 { $subsection "graphs" }
 163 { $subsection "buffers" } ;
 164
 165 USING: io.sockets io.launcher io.mmap io.monitors
 166 io.encodings.utf8 io.encodings.binary io.encodings.ascii io.files ;
 167
 168 ARTICLE: "encodings-introduction" "An introduction to encodings"
 169 "In order to express text in terms of binary, some sort of encoding has to be used. In a modern context, this is understood as a two-way mapping between Unicode code points (characters) and some amount of binary. Since English isn't the only language in the world, ASCII is not sufficient as a mapping from binary to Unicode; it can't even express em-dashes or curly quotes. Unicode was designed as a universal character set that could potentially represent everything." $nl
 170 "Not all encodings can represent all Unicode code points, but Unicode can represent basically everything that exists in modern encodings. Some encodings are language-specific, and some can represent everything in Unicode. Though the world is moving toward Unicode and UTF-8, the reality today is that there are several encodings which must be taken into account." $nl
 171 "Factor uses a system of encoding descriptors to denote encodings. Encoding descriptors are objects which describe encodings. Examples are " { $link utf8 } ", " { $link ascii } " and " { $link binary } ". Encoding descriptors can be passed around independently. Each encoding descriptor has some method for constructing an encoded or decoded stream, and the resulting stream has an encoding descriptor stored which has methods for reading or writing characters." $nl
 172 "Constructors for streams which deal with bytes usually take an encoding as an explicit parameter. For example, to open a text file for reading whose contents are in UTF-8, use the following"
 173 { $code "\"file.txt\" utf8 <file-reader>" }
 174 "If there is an error in the encoded stream, a replacement character (0xFFFD) will be inserted. To throw an exception upon error, use a strict encoding as follows"
 175 { $code "\"file.txt\" utf8 strict <file-reader>" }
 176 "In a similar way, encodings can be specified when opening a file for writing."
 177 { $code "\"file.txt\" ascii <file-writer>" }
 178 "An encoding is also needed for some words that don't return streams, such as " { $link file-contents } ", for example"
 179 { $code "\"file.txt\" utf16 file-contents" }
 180 "Encoding descriptors are also used by " { $link "io.streams.byte-array" } " and taken by combinators like " { $link with-file-writer } " and " { $link with-byte-reader } " which deal with streams. It is " { $emphasis "not" } " used with " { $link "io.streams.string" } " because these deal with abstract text."
 181 $nl
 182 "When the " { $link binary } " encoding is used, a " { $link byte-array } " is expected for writing and returned for reading, since the stream deals with bytes. All other encodings deal with strings, since they are used to represent text." ;
 183
 184 ARTICLE: "io" "Input and output"
 185 { $heading "Streams" }
 186 { $subsection "streams" }
 187 "Wrapper streams:"
 188 { $subsection "io.streams.duplex" }
 189 { $subsection "io.streams.plain" }
 190 { $subsection "io.streams.string" }
 191 { $subsection "io.streams.byte-array" }
 192 "Utilities:"
 193 { $subsection "stream-binary" }
 194 { $subsection "styles" }
 195 { $heading "Files" }
 196 { $subsection "io.files" }
 197 { $subsection "io.mmap" }
 198 { $subsection "io.monitors" }
 199 { $heading "Encodings" }
 200 { $subsection "encodings-introduction" }
 201 { $subsection "io.encodings" }
 202 { $subsection "io.encodings.string" }
 203 { $heading "Other features" }
 204 { $subsection "network-streams" }
 205 { $subsection "io.launcher" }
 206 { $subsection "io.timeouts" } ;
 207
 208 ARTICLE: "tools" "Developer tools"
 209 { $subsection "tools.vocabs" }
 210 "Exploratory tools:"
 211 { $subsection "editor" }
 212 { $subsection "listener" }
 213 { $subsection "tools.crossref" }
 214 { $subsection "inspector" }
 215 "Debugging tools:"
 216 { $subsection "tools.annotations" }
 217 { $subsection "tools.test" }
 218 { $subsection "tools.threads" }
 219 "Performance tools:"
 220 { $subsection "tools.memory" }
 221 { $subsection "profiling" }
 222 { $subsection "timing" }
 223 { $subsection "tools.disassembler" }
 224 "Deployment tools:"
 225 { $subsection "tools.deploy" } ;
 226
 227 ARTICLE: "article-index" "Article index"
 228 { $index [ articles get keys ] } ;
 229
 230 ARTICLE: "primitive-index" "Primitive index"
 231 { $index [ all-words [ primitive? ] subset ] } ;
 232
 233 ARTICLE: "error-index" "Error index"
 234 { $index [ all-errors ] } ;
 235
 236 ARTICLE: "type-index" "Type index"
 237 { $index [ builtins get [ ] subset ] } ;
 238
 239 ARTICLE: "class-index" "Class index"
 240 { $index [ classes ] } ;
 241
 242 ARTICLE: "program-org" "Program organization"
 243 { $subsection "definitions" }
 244 { $subsection "vocabularies" }
 245 { $subsection "parser" }
 246 { $subsection "vocabs.loader" } ;
 247
 248 USING: help.cookbook help.tutorial ;
 249
 250 ARTICLE: "handbook" "Factor documentation"
 251 "Welcome to Factor."
 252 { $heading "Starting points" }
 253 { $subsection "cookbook" }
 254 { $subsection "first-program" }
 255 { $subsection "vocab-index" }
 256 { $heading "Language reference" }
 257 { $subsection "conventions" }
 258 { $subsection "syntax" }
 259 { $subsection "dataflow" }
 260 { $subsection "objects" }
 261 { $subsection "program-org" }
 262 { $heading "Library reference" }
 263 { $subsection "numbers" }
 264 { $subsection "collections" }
 265 { $subsection "io" }
 266 { $subsection "concurrency" }
 267 { $subsection "system" }
 268 { $subsection "alien" }
 269 { $heading "Environment reference" }
 270 { $subsection "cli" }
 271 { $subsection "images" }
 272 { $subsection "prettyprint" }
 273 { $subsection "tools" }
 274 { $subsection "help" }
 275 { $subsection "inference" }
 276 { $subsection "compiler" }
 277 { $subsection "layouts" }
 278 { $heading "User interface" }
 279 { $about "ui" }
 280 { $about "ui.tools" }
 281 { $heading "Index" }
 282 { $subsection "primitive-index" }
 283 { $subsection "error-index" }
 284 { $subsection "type-index" }
 285 { $subsection "class-index" } ;
 286
 287 { <array> <string> <sbuf> <vector> <byte-array> <bit-array> <float-array> }
 288 related-words
 289
 290 { >array >quotation >string >sbuf >vector >byte-array >bit-array >float-array }
 291 related-words