basis/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 prettyprint.custom kernel.private io generic
   4 math system strings sbufs vectors byte-arrays quotations
   5 io.streams.byte-array classes.builtin parser lexer
   6 classes.predicate classes.union classes.intersection
   7 classes.singleton classes.tuple help.vocabs math.parser
   8 accessors definitions sets ;
   9 IN: help.handbook
  10
  11 ARTICLE: "conventions" "Conventions"
  12 "Various conventions are used throughout the Factor documentation and source code."
  13 { $heading "Documentation conventions" }
  14 "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."
  15 $nl
  16 "Every article has links to parent articles at the top. Explore these if the article you are reading is too specific."
  17 $nl
  18 "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."
  19 { $heading "Vocabulary naming conventions" }
  20 "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" } ")."
  21 $nl
  22 "You 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."
  23 { $heading "Word naming conventions" }
  24 "These conventions are not hard and fast, but are usually a good first step in understanding a word's behavior:"
  25 { $table
  26     { "General form" "Description" "Examples" }
  27     { { $snippet { $emphasis "foo" } "?" } "outputs a boolean" { { $link empty? } } }
  28     { { $snippet "?" { $emphasis "foo" } } { "conditionally performs " { $snippet { $emphasis "foo" } } } { { $links ?nth } } }
  29     { { $snippet "<" { $emphasis "foo" } ">" } { "creates a new " { $snippet "foo" } } { { $link <array> } } }
  30     { { $snippet ">" { $emphasis "foo" } } { "converts the top of the stack into a " { $snippet "foo" } } { { $link >array } } }
  31     { { $snippet { $emphasis "foo" } ">" { $emphasis "bar" } } { "converts a " { $snippet "foo" } " into a " { $snippet "bar" } } { { $link number>string } } }
  32     { { $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 } } }
  33     { { $snippet { $emphasis "foo" } "*" } { "alternative form of " { $snippet "foo" } ", or a generic word called by " { $snippet "foo" } } { { $links at* pprint* } } }
  34     { { $snippet "(" { $emphasis "foo" } ")" } { "implementation detail word used by " { $snippet "foo" } } { { $link (clone) } } }
  35     { { $snippet "set-" { $emphasis "foo" } } { "sets " { $snippet "foo" } " to a new value" } { $links set-length } }
  36     { { $snippet { $emphasis "foo" } ">>" } { "gets the " { $snippet "foo" } " slot of the tuple at the top of the stack; see " { $link "accessors" } } { { $link name>> } } }
  37     { { $snippet ">>" { $emphasis "foo" } } { "sets the " { $snippet "foo" } " slot of the tuple at the top of the stack; see " { $link "accessors" } } { { $link >>name } } }
  38     { { $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-input-stream with-output-stream } }
  39     { { $snippet "$" { $emphasis "foo" } } { "help markup" } { $links $heading $emphasis } }
  40 }
  41 { $heading "Stack effect conventions" }
  42 "Stack effect conventions are documented in " { $link "effects" } "."
  43 { $heading "Glossary of terms" }
  44 "Common terminology and abbreviations used throughout Factor and its documentation:"
  45 { $table
  46     { "Term" "Definition" }
  47     { "alist" { "an association list; see " { $link "alists" } } }
  48     { "assoc" { "an associative mapping; see " { $link "assocs" } } }
  49     { "associative mapping" { "an object whose class implements the " { $link "assocs-protocol" } } }
  50     { "boolean"               { { $link t } " or " { $link f } } }
  51     { "class"                 { "a set of objects identified by a " { $emphasis "class word" } " together with a discriminating predicate. See " { $link "classes" } } }
  52     { "combinator"            { "a word taking a quotation or another word as input; a higher-order function. See " { $link "combinators" } } }
  53     { "definition specifier"  { "an instance of " { $link definition } " which implements the " { $link "definition-protocol" } } }
  54     { "generalized boolean"   { "an object interpreted as a boolean; a value of " { $link f } " denotes false and anything else denotes true" } }
  55     { "generic word"          { "a word whose behavior depends can be specialized on the class of one of its inputs. See " { $link "generic" } } }
  56     { "method"                { "a specialized behavior of a generic word on a class. See " { $link "generic" } } }
  57     { "object"                { "any datum which can be identified" } }
  58     { "ordering specifier"    { "see " { $link "order-specifiers" } } }
  59     { "pathname string"       { "an OS-specific pathname which identifies a file" } }
  60     { "quotation"             { "an anonymous function; an instance of the " { $link quotation } " class. More generally, instances of the " { $link callable } " class can be used in many places documented to expect quotations" } }
  61     { "sequence" { "a sequence; see " { $link "sequence-protocol" } } }
  62     { "slot"                  { "a component of an object which can store a value" } }
  63     { "stack effect"          { "a pictorial representation of a word's inputs and outputs, for example " { $snippet "+ ( x y -- z )" } ". See " { $link "effects" } } }
  64     { "true value"            { "any object not equal to " { $link f } } }
  65     { "vocabulary" { "a named set of words. See " { $link "vocabularies" } } }
  66     { "vocabulary specifier"  { "a " { $link vocab } ", " { $link vocab-link } " or a string naming a vocabulary" } }
  67     { "word"                  { "the basic unit of code, analogous to a function or procedure in other programming languages. See " { $link "words" } } }
  68 } ;
  69
  70 ARTICLE: "tail-call-opt" "Tail-call optimization"
  71 "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 " { $emphasis "tail-call optimization" } " and the Factor implementation guarantees that it will be performed."
  72 $nl
  73 "Tail-call optimization allows iterative algorithms to be implemented in an efficient manner using recursion, without the need for any kind of primitive looping construct in the language. However, in practice, most iteration is performed via combinators such as " { $link while } ", " { $link each } ", " { $link map } ", " { $link assoc-each } ", and so on. The definitions of these combinators do bottom-out in recursive words, however." ;
  74
  75 ARTICLE: "evaluator" "Stack machine model"
  76 { $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:"
  77 { $list
  78     { "a " { $link word } " - the word's definition quotation is called. See " { $link "words" } }
  79     { "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." }
  80     { "All other types of objects are pushed on the data stack." }
  81 }
  82 { $subsection "tail-call-opt" }
  83 { $see-also "compiler" } ;
  84
  85 ARTICLE: "objects" "Objects"
  86 "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."
  87 { $subsection "equality" }
  88 { $subsection "math.order" }
  89 { $subsection "classes" }
  90 { $subsection "tuples" }
  91 { $subsection "generic" }
  92 "Advanced features:"
  93 { $subsection "delegate" }
  94 { $subsection "mirrors" }
  95 { $subsection "slots" } ;
  96
  97 ARTICLE: "numbers" "Numbers"
  98 { $subsection "arithmetic" }
  99 { $subsection "math-constants" }
 100 { $subsection "math-functions" }
 101 { $subsection "number-strings" }
 102 "Number implementations:"
 103 { $subsection "integers" }
 104 { $subsection "rationals" }
 105 { $subsection "floats" }
 106 { $subsection "complex-numbers" }
 107 "Advanced features:"
 108 { $subsection "math-vectors" }
 109 { $subsection "math-intervals" }
 110 { $subsection "math-bitfields" }
 111 "Implementation:"
 112 { $subsection "math.libm" } ;
 113
 114 USE: io.buffers
 115
 116 ARTICLE: "collections" "Collections"
 117 { $heading "Sequences" }
 118 { $subsection "sequences" }
 119 { $subsection "virtual-sequences" }
 120 { $subsection "namespaces-make" }
 121 "Fixed-length sequences:"
 122 { $subsection "arrays" }
 123 { $subsection "quotations" }
 124 { $subsection "strings" }
 125 { $subsection "byte-arrays" }
 126 { $subsection "specialized-arrays" }
 127 "Resizable sequences:"
 128 { $subsection "vectors" }
 129 { $subsection "byte-vectors" }
 130 { $subsection "sbufs" }
 131 { $subsection "growable" }
 132 { $heading "Associative mappings" }
 133 { $subsection "assocs" }
 134 { $subsection "linked-assocs" }
 135 { $subsection "biassocs" }
 136 { $subsection "refs" }
 137 "Implementations:"
 138 { $subsection "hashtables" }
 139 { $subsection "alists" }
 140 { $subsection "enums" }
 141 { $heading "Double-ended queues" }
 142 { $subsection "deques" }
 143 "Implementations:"
 144 { $subsection "dlists" }
 145 { $subsection "search-deques" }
 146 { $heading "Other collections" }
 147 { $subsection "lists" }
 148 { $subsection "disjoint-sets" }
 149 { $subsection "interval-maps" }
 150 { $subsection "heaps" }
 151 { $subsection "boxes" }
 152 { $subsection "graphs" }
 153 { $subsection "buffers" }
 154 "There are also many other vocabularies tagged " { $link T{ vocab-tag { name "collections" } } } " in the library." ;
 155
 156 USING: io.encodings.utf8 io.encodings.binary io.files ;
 157
 158 ARTICLE: "encodings-introduction" "An introduction to encodings"
 159 "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
 160 "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
 161 "Factor uses a system of encoding descriptors to denote encodings. Encoding descriptors are objects which describe encodings. Examples are " { $link utf8 } " 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
 162 "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"
 163 { $code "\"file.txt\" utf8 <file-reader>" }
 164 "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"
 165 { $code "\"file.txt\" utf8 strict <file-reader>" }
 166 "In a similar way, encodings can be specified when opening a file for writing."
 167 { $code "USE: io.encodings.ascii" "\"file.txt\" ascii <file-writer>" }
 168 "An encoding is also needed for some words that don't return streams, such as " { $link file-contents } ", for example"
 169 { $code "USE: io.encodings.utf16" "\"file.txt\" utf16 file-contents" }
 170 "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."
 171 $nl
 172 "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." ;
 173
 174 ARTICLE: "io" "Input and output"
 175 { $heading "Streams" }
 176 { $subsection "streams" }
 177 { $subsection "io.files" }
 178 { $heading "The file system" }
 179 { $subsection "io.pathnames" }
 180 { $subsection "io.files.info" }
 181 { $subsection "io.files.links" }
 182 { $subsection "io.directories" }
 183 { $heading "Encodings" }
 184 { $subsection "encodings-introduction" }
 185 { $subsection "io.encodings" }
 186 { $heading "Wrapper streams" }
 187 { $subsection "io.streams.duplex" }
 188 { $subsection "io.streams.plain" }
 189 { $subsection "io.streams.string" }
 190 { $subsection "io.streams.byte-array" }
 191 { $heading "Utilities" }
 192 { $subsection "stream-binary" }
 193 { $subsection "io.styles" }
 194 { $subsection "checksums" }
 195 { $heading "Implementation" }
 196 { $subsection "io.streams.c" }
 197 { $subsection "io.ports" }
 198 { $see-also "destructors" } ;
 199
 200 ARTICLE: "article-index" "Article index"
 201 { $index [ articles get keys ] } ;
 202
 203 ARTICLE: "primitive-index" "Primitive index"
 204 { $index [ all-words [ primitive? ] filter ] } ;
 205
 206 ARTICLE: "error-index" "Error index"
 207 { $index [ all-errors ] } ;
 208
 209 ARTICLE: "type-index" "Type index"
 210 { $index [ builtins get sift ] } ;
 211
 212 ARTICLE: "class-index" "Class index"
 213 { $heading "Built-in classes" }
 214 { $index [ classes [ builtin-class? ] filter ] }
 215 { $heading "Tuple classes" }
 216 { $index [ classes [ tuple-class? ] filter ] }
 217 { $heading "Singleton classes" }
 218 { $index [ classes [ singleton-class? ] filter ] }
 219 { $heading "Union classes" }
 220 { $index [ classes [ union-class? ] filter ] }
 221 { $heading "Intersection classes" }
 222 { $index [ classes [ intersection-class? ] filter ] }
 223 { $heading "Predicate classes" }
 224 { $index [ classes [ predicate-class? ] filter ] } ;
 225
 226 USING: help.cookbook help.tutorial ;
 227
 228 ARTICLE: "handbook-language-reference" "The language"
 229 { $heading "Fundamentals" }
 230 { $subsection "conventions" }
 231 { $subsection "syntax" }
 232 { $heading "The stack" }
 233 { $subsection "evaluator" }
 234 { $subsection "effects" }
 235 { $subsection "inference" }
 236 { $heading "Basic data types" }
 237 { $subsection "booleans" }
 238 { $subsection "numbers" }
 239 { $subsection "collections" }
 240 { $heading "Evaluation" }
 241 { $subsection "words" }
 242 { $subsection "shuffle-words" }
 243 { $subsection "combinators" }
 244 { $subsection "threads" }
 245 { $heading "Named values" }
 246 { $subsection "locals" }
 247 { $subsection "namespaces" }
 248 { $subsection "namespaces-global" }
 249 { $subsection "values" }
 250 { $heading "Abstractions" }
 251 { $subsection "fry" }
 252 { $subsection "objects" }
 253 { $subsection "errors" }
 254 { $subsection "destructors" }
 255 { $subsection "memoize" }
 256 { $subsection "parsing-words" }
 257 { $subsection "macros" }
 258 { $subsection "continuations" }
 259 { $heading "Program organization" }
 260 { $subsection "vocabs.loader" }
 261 "Vocabularies tagged " { $link T{ vocab-tag { name "extensions" } } } " implement various additional language abstractions." ;
 262
 263 ARTICLE: "handbook-system-reference" "The implementation"
 264 { $heading "Parse time and compile time" }
 265 { $subsection "parser" }
 266 { $subsection "definitions" }
 267 { $subsection "vocabularies" }
 268 { $subsection "source-files" }
 269 { $subsection "compiler" }
 270 { $subsection "tools.errors" }
 271 { $heading "Virtual machine" }
 272 { $subsection "images" }
 273 { $subsection "cli" }
 274 { $subsection "rc-files" }
 275 { $subsection "init" }
 276 { $subsection "system" }
 277 { $subsection "layouts" } ;
 278
 279 ARTICLE: "handbook-tools-reference" "Developer tools"
 280 "The below tools are text-based. " { $link "ui-tools" } " are documented separately."
 281 { $heading "Workflow" }
 282 { $subsection "listener" }
 283 { $subsection "editor" }
 284 { $subsection "vocabs.refresh" }
 285 { $subsection "tools.test" }
 286 { $subsection "help" }
 287 { $heading "Debugging" }
 288 { $subsection "prettyprint" }
 289 { $subsection "inspector" }
 290 { $subsection "tools.inference" }
 291 { $subsection "tools.annotations" }
 292 { $subsection "tools.deprecation" }
 293 { $heading "Browsing" }
 294 { $subsection "see" }
 295 { $subsection "tools.crossref" }
 296 { $subsection "vocabs.hierarchy" }
 297 { $heading "Performance" }
 298 { $subsection "timing" }
 299 { $subsection "profiling" }
 300 { $subsection "tools.memory" }
 301 { $subsection "tools.threads" }
 302 { $subsection "tools.destructors" }
 303 { $subsection "tools.disassembler" }
 304 { $heading "Deployment" }
 305 { $subsection "tools.deploy" } ;
 306
 307 ARTICLE: "handbook-library-reference" "Libraries"
 308 "This index lists articles from loaded vocabularies which are not subsections of any other article. To explore more vocabularies, see " { $link "vocab-index" } "."
 309 { $index [ orphan-articles { "help.home" "handbook" } diff ] } ;
 310
 311 ARTICLE: "handbook" "Factor handbook"
 312 "Learn the language:"
 313 { $subsection "cookbook" }
 314 { $subsection "first-program" }
 315 "Reference material:"
 316 { $subsection "handbook-language-reference" }
 317 { $subsection "io" }
 318 { $subsection "ui" }
 319 { $subsection "handbook-system-reference" }
 320 { $subsection "handbook-tools-reference" }
 321 { $subsection "ui-tools" }
 322 { $subsection "alien" }
 323 { $subsection "handbook-library-reference" }
 324 "Explore loaded libraries:"
 325 { $subsection "article-index" }
 326 { $subsection "primitive-index" }
 327 { $subsection "error-index" }
 328 { $subsection "type-index" }
 329 { $subsection "class-index" }
 330 "Explore the code base:"
 331 { $subsection "vocab-index" } ;
 332
 333 ABOUT: "handbook"