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 kernel.private io generic math system
   4 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 tools.vocabs.browser ;
   8 IN: help.handbook
   9
  10 ARTICLE: "conventions" "Conventions"
  11 "Various conventions are used throughout the Factor documentation and source code."
  12 { $heading "Documentation conventions" }
  13 "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."
  14 $nl
  15 "Every article has links to parent articles at the top. These can be persued if the article is too specific."
  16 $nl
  17 "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."
  18 { $heading "Vocabulary naming conventions" }
  19 "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" } ")."
  20 $nl
  21 "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."
  22 { $heading "Word naming conventions" }
  23 "These conventions are not hard and fast, but are usually a good first step in understanding a word's behavior:"
  24 { $table
  25     { "General form" "Description" "Examples" }
  26     { { $snippet { $emphasis "foo" } "?" } "outputs a boolean" { { $link empty? } } }
  27     { { $snippet "?" { $emphasis "foo" } } { "conditionally performs " { $snippet { $emphasis "foo" } } } { { $links ?nth } } }
  28     { { $snippet "<" { $emphasis "foo" } ">" } { "creates a new " { $snippet "foo" } } { { $link <array> } } }
  29     { { $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 } } }
  30     { { $snippet { $emphasis "foo" } "*" } { "alternative form of " { $snippet "foo" } ", or a generic word called by " { $snippet "foo" } } { { $links at* pprint* } } }
  31     { { $snippet "(" { $emphasis "foo" } ")" } { "implementation detail word used by " { $snippet "foo" } } { { $link (clone) } } }
  32     { { $snippet "set-" { $emphasis "foo" } } { "sets " { $snippet "foo" } " to a new value" } { $links set-length } }
  33     { { $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" } { } }
  34     { { $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" } { } }
  35     { { $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 } }
  36     { { $snippet "$" { $emphasis "foo" } } { "help markup" } { $links $heading $emphasis } }
  37 }
  38 { $heading "Stack effect conventions" }
  39 "Stack effect conventions are documented in " { $link "effect-declaration" } "."
  40 { $heading "Glossary of terms" }
  41 "Common terminology and abbreviations used throughout Factor and its documentation:"
  42 { $table
  43     { "Term" "Definition" }
  44     { "alist" { "an association list; see " { $link "alists" } } }
  45     { "assoc" { "an associative mapping; see " { $link "assocs" } } }
  46     { "associative mapping" { "an object whose class implements the " { $link "assocs-protocol" } } }
  47     { "boolean"               { { $link t } " or " { $link f } } }
  48     { "class"                 { "a set of objects identified by a " { $emphasis "class word" } " together with a discriminating predicate. See " { $link "classes" } } }
  49     { "definition specifier"  { "a " { $link word } ", " { $link method-spec } ", " { $link link } ", vocabulary specifier, or any other object whose class implements the " { $link "definition-protocol" } } }
  50     { "generalized boolean"   { "an object interpreted as a boolean; a value of " { $link f } " denotes false and anything else denotes true" } }
  51     { "generic word"          { "a word whose behavior depends can be specialized on the class of one of its inputs. See " { $link "generic" } } }
  52     { "method"                { "a specialized behavior of a generic word on a class. See " { $link "generic" } } }
  53     { "object"                { "any datum which can be identified" } }
  54     { "ordering specifier"    { "see " { $link "order-specifiers" } } }
  55     { "pathname string"       { "an OS-specific pathname which identifies a file" } }
  56     { "sequence" { "a sequence; see " { $link "sequence-protocol" } } }
  57     { "slot"                  { "a component of an object which can store a value" } }
  58     { "stack effect"          { "a pictorial representation of a word's inputs and outputs, for example " { $snippet "+ ( x y -- z )" } ". See " { $link "effects" } } }
  59     { "true value"            { "any object not equal to " { $link f } } }
  60     { "vocabulary" { "a named set of words. See " { $link "vocabularies" } } }
  61     { "vocabulary specifier"  { "a " { $link vocab } ", " { $link vocab-link } " or a string naming a vocabulary" } }
  62     { "word"                  { "the basic unit of code, analogous to a function or procedure in other programming languages. See " { $link "words" } } }
  63 } ;
  64
  65 ARTICLE: "evaluator" "Evaluation semantics"
  66 { $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:"
  67 { $list
  68     { "a " { $link word } " - the word's definition quotation is called. See " { $link "words" } }
  69     { "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." }
  70     { "All other types of objects are pushed on the data stack." }
  71 }
  72 "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."
  73 { $see-also "compiler" } ;
  74
  75 ARTICLE: "objects" "Objects"
  76 "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."
  77 { $subsection "equality" }
  78 { $subsection "math.order" }
  79 { $subsection "destructors" }
  80 { $subsection "classes" }
  81 { $subsection "tuples" }
  82 { $subsection "generic" }
  83 { $subsection "slots" }
  84 { $subsection "mirrors" } ;
  85
  86 USE: random
  87
  88 ARTICLE: "numbers" "Numbers"
  89 { $subsection "arithmetic" }
  90 { $subsection "math-constants" }
  91 { $subsection "math-functions" }
  92 { $subsection "number-strings" }
  93 { $subsection "random-numbers" }
  94 "Number implementations:"
  95 { $subsection "integers" }
  96 { $subsection "rationals" }
  97 { $subsection "floats" }
  98 { $subsection "complex-numbers" }
  99 "Advanced features:"
 100 { $subsection "math-vectors" }
 101 { $subsection "math-intervals" }
 102 { $subsection "math-bitfields" }
 103 "Implementation:"
 104 { $subsection "math.libm" } ;
 105
 106 USE: io.buffers
 107
 108 ARTICLE: "collections" "Collections"
 109 { $heading "Sequences" }
 110 { $subsection "sequences" }
 111 { $subsection "virtual-sequences" }
 112 { $subsection "namespaces-make" }
 113 "Fixed-length sequences:"
 114 { $subsection "arrays" }
 115 { $subsection "quotations" }
 116 "Fixed-length specialized sequences:"
 117 { $subsection "strings" }
 118 { $subsection "byte-arrays" }
 119 "Resizable sequences:"
 120 { $subsection "vectors" }
 121 { $subsection "byte-vectors" }
 122 { $subsection "sbufs" }
 123 { $subsection "growable" }
 124 { $heading "Associative mappings" }
 125 { $subsection "assocs" }
 126 { $subsection "namespaces" }
 127 { $subsection "refs" }
 128 "Implementations:"
 129 { $subsection "hashtables" }
 130 { $subsection "alists" }
 131 { $subsection "enums" }
 132 { $heading "Double-ended queues" }
 133 { $subsection "deques" }
 134 "Implementations:"
 135 { $subsection "dlists" }
 136 { $subsection "search-deques" }
 137 { $heading "Other collections" }
 138 { $subsection "boxes" }
 139 { $subsection "heaps" }
 140 { $subsection "graphs" }
 141 { $subsection "buffers" }
 142 "There are also many other vocabularies tagged " { $link T{ vocab-tag { name "collections" } } } " in the library." ;
 143
 144 USING: io.encodings.utf8 io.encodings.utf16 io.encodings.binary io.encodings.ascii io.files ;
 145
 146 ARTICLE: "encodings-introduction" "An introduction to encodings"
 147 "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
 148 "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
 149 "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
 150 "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"
 151 { $code "\"file.txt\" utf8 <file-reader>" }
 152 "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"
 153 { $code "\"file.txt\" utf8 strict <file-reader>" }
 154 "In a similar way, encodings can be specified when opening a file for writing."
 155 { $code "\"file.txt\" ascii <file-writer>" }
 156 "An encoding is also needed for some words that don't return streams, such as " { $link file-contents } ", for example"
 157 { $code "\"file.txt\" utf16 file-contents" }
 158 "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."
 159 $nl
 160 "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." ;
 161
 162 ARTICLE: "io" "Input and output"
 163 { $heading "Streams" }
 164 { $subsection "streams" }
 165 { $subsection "io.files" }
 166 { $heading "Encodings" }
 167 { $subsection "encodings-introduction" }
 168 { $subsection "io.encodings" }
 169 "Wrapper streams:"
 170 { $subsection "io.streams.duplex" }
 171 { $subsection "io.streams.plain" }
 172 { $subsection "io.streams.string" }
 173 { $subsection "io.streams.byte-array" }
 174 "Utilities:"
 175 { $subsection "stream-binary" }
 176 { $subsection "styles" }
 177 { $subsection "checksums" }
 178 "Implementation:"
 179 { $subsection "io.streams.c" }
 180 { $subsection "io.ports" }
 181 { $see-also "destructors" } ;
 182
 183 ARTICLE: "tools" "Developer tools"
 184 { $subsection "tools.vocabs" }
 185 "Exploratory tools:"
 186 { $subsection "editor" }
 187 { $subsection "listener" }
 188 { $subsection "tools.crossref" }
 189 { $subsection "inspector" }
 190 { $subsection "tools.completion" }
 191 { $subsection "summary" }
 192 "Debugging tools:"
 193 { $subsection "tools.annotations" }
 194 { $subsection "tools.test" }
 195 { $subsection "tools.threads" }
 196 "Performance tools:"
 197 { $subsection "tools.memory" }
 198 { $subsection "profiling" }
 199 { $subsection "timing" }
 200 { $subsection "tools.disassembler" }
 201 "Deployment tools:"
 202 { $subsection "tools.deploy" } ;
 203
 204 ARTICLE: "article-index" "Article index"
 205 { $index [ articles get keys ] } ;
 206
 207 ARTICLE: "primitive-index" "Primitive index"
 208 { $index [ all-words [ primitive? ] filter ] } ;
 209
 210 ARTICLE: "error-index" "Error index"
 211 { $index [ all-errors ] } ;
 212
 213 ARTICLE: "type-index" "Type index"
 214 { $index [ builtins get sift ] } ;
 215
 216 ARTICLE: "class-index" "Class index"
 217 { $heading "Built-in classes" }
 218 { $index [ classes [ builtin-class? ] filter ] }
 219 { $heading "Tuple classes" }
 220 { $index [ classes [ tuple-class? ] filter ] }
 221 { $heading "Singleton classes" }
 222 { $index [ classes [ singleton-class? ] filter ] }
 223 { $heading "Union classes" }
 224 { $index [ classes [ union-class? ] filter ] }
 225 { $heading "Intersection classes" }
 226 { $index [ classes [ intersection-class? ] filter ] }
 227 { $heading "Predicate classes" }
 228 { $index [ classes [ predicate-class? ] filter ] } ;
 229
 230 ARTICLE: "program-org" "Program organization"
 231 { $subsection "definitions" }
 232 { $subsection "vocabularies" }
 233 { $subsection "parser" }
 234 { $subsection "vocabs.loader" }
 235 { $subsection "source-files" } ;
 236
 237 USING: help.cookbook help.tutorial ;
 238
 239 ARTICLE: "handbook-language-reference" "Language reference"
 240 { $subsection "conventions" }
 241 { $subsection "syntax" }
 242 { $subsection "dataflow" }
 243 { $subsection "objects" }
 244 { $subsection "program-org" }
 245 { $subsection "numbers" }
 246 { $subsection "collections" }
 247 { $subsection "io" }
 248 "Vocabularies tagged " { $link T{ vocab-tag { name "extensions" } } } " implement various additional language abstractions." ;
 249
 250 ARTICLE: "handbook-environment-reference" "Environment reference"
 251 { $subsection "prettyprint" }
 252 { $subsection "tools" }
 253 { $subsection "cli" }
 254 { $subsection "rc-files" }
 255 { $subsection "help" }
 256 { $subsection "inference" }
 257 { $subsection "compiler" }
 258 { $subsection "system" }
 259 { $subsection "images" }
 260 { $subsection "alien" }
 261 { $subsection "init" }
 262 { $subsection "layouts" }
 263 { $see-also "program-org" } ;
 264
 265 ARTICLE: "handbook-library-reference" "Library reference"
 266 "This index only includes articles from loaded vocabularies. To explore more vocabularies, see " { $link "vocab-index" } "."
 267 { $index [ "handbook" orphan-articles remove ] } ;
 268
 269 ARTICLE: "handbook" "Factor documentation"
 270 "Welcome to Factor."
 271 $nl
 272 "Explore the code base:"
 273 { $subsection "vocab-index" }
 274 "Learn the language:"
 275 { $subsection "cookbook" }
 276 { $subsection "first-program" }
 277 { $subsection "handbook-language-reference" }
 278 { $subsection "handbook-environment-reference" }
 279 { $subsection "handbook-library-reference" }
 280 "The below indices only include articles from loaded vocabularies. To explore more vocabularies, see " { $link "vocab-index" } "."
 281 { $subsection "article-index" }
 282 { $subsection "primitive-index" }
 283 { $subsection "error-index" }
 284 { $subsection "type-index" }
 285 { $subsection "class-index" } ;
 286
 287 ABOUT: "handbook"