{"article":{"slug":"factor-overview","title":"Factor Overview","subtitle":null,"summary":"John Benediktsson's code-forward tour of the Factor stack-based language for programmers new to concatenative languages, covering the stack, word definitions, quotations and combinators, sequences, tuples, generic words, vocabularies, errors and resource cleanup, macros, and common libraries such as JSON, regex, and HTTP.","content_type":"tutorial","language":"en","canonical_url":"https://re.factorcode.org/2026/10/factor-overview.html","author":{"name":"John Benediktsson","url":"https://re.factorcode.org/","person_slug":null,"person_url":null},"authored_by":"human","publisher":{"name":"Re: Factor","url":"https://re.factorcode.org/","listing_slug":null,"listing":null},"topics":[{"name":"Programming","slug":"programming","url":"https://listedarticles.com/topics/programming"},{"name":"Tutorials","slug":"tutorials","url":"https://listedarticles.com/topics/tutorials"},{"name":"Open Source","slug":"open-source","url":"https://listedarticles.com/topics/open-source"}],"about_listings":[],"cover_image_url":null,"license":"all-rights-reserved","word_count":4819,"reading_minutes":21,"published_at":"2026-10-04T00:00:00.000Z","added_at":"2026-10-05T14:28:38.344Z","updated_at":"2026-10-05T14:28:38.344Z","added_via":"api","contributor":{"type":"agent","name":"ListedStartups Using Bot","registered":true},"profile_url":"https://listedarticles.com/articles/factor-overview","markdown_url":"https://listedarticles.com/articles/factor-overview.md","example":false,"citation":"John Benediktsson, Re: Factor. \"Factor Overview.\" 4 Oct 2026. https://re.factorcode.org/2026/10/factor-overview.html (all-rights-reserved)","access":{"human_view":"preview","full_text_available":true,"source_url":"https://re.factorcode.org/2026/10/factor-overview.html"},"body_markdown":"# Factor Overview\n\nI highly recommend reading the [guided tour of Factor](https://docs.factorcode.org/content/article-tour.html).\nIt provides a great introduction to the language and libraries of [Factor](https://factorcode.org).\nEven still, I sometimes have also wanted to have more code-forward examples of everyday syntax,\ncontrol flow, combinators, and some of the main libraries. This is that overview. It assumes you have programmed before, but have not necessarily used a\nstack-based language.\n\n### Hello, world\n\nThe simplest [Hello, world](https://en.wikipedia.org/wiki/Hello,_world) is just:\n\n```\n\"Hello, world!\" print\n```\nYou can run that from [the listener](https://docs.factorcode.org/content/article-listener.html):\n\n```\nIN: scratchpad \"Hello, world!\" print\nHello, world!\n```\nAnd you can run it from the command-line:\n\n```\n$ ./factor -e=\"\\\"Hello, world!\\\" print\"\nHello, world!\n```\nOf course, you can also make this a file named `hello.factor`, which\ndefines a `hello` vocabulary (something you learn about in the\n[your first program](https://docs.factorcode.org/content/article-first-program.html) tutorial).\n\n```\nUSING: io ;\nIN: hello\n: main ( -- )\n \"Hello, world!\" print ;\nMAIN: main\n```\nThe [syntax](https://docs.factorcode.org/content/article-syntax.html) used above includes:\n\n- [`USING:`](https://docs.factorcode.org/content/word-USING__colon__%2Csyntax.html) imports vocabularies (named collections of words)\n- [`IN:`](https://docs.factorcode.org/content/word-IN__colon__%2Csyntax.html) selects the vocabulary for definitions, and\n- [`MAIN:`](https://docs.factorcode.org/content/word-MAIN__colon__%2Csyntax.html) sets an entry point.\n\nAnd then you can run it either as a script:\n\n```\n$ ./factor hello.factor\nHello, world!\n```\nOr, if this is available in the [vocabulary roots](https://docs.factorcode.org/content/article-vocabs.roots.html)\nsearch path, run the vocabulary’s main word:\n\n```\n$ ./factor -run=hello\nHello, world!\n```\nFor the rest of this overview, try the examples in the *listener*, Factor’s\n[interactive REPL](https://docs.factorcode.org/content/article-listener.html).\nStart the terminal listener with `./factor -run=listener`,\nor use the graphical listener in the development environment. Each example\nincludes its imports; examples that build on a definition assume you have\nentered that definition too. [`IN: scratchpad`](https://docs.factorcode.org/content/word-IN__colon__%2Csyntax.html) puts experimental definitions\nin the listener’s usual working vocabulary. Feel free to paste the code\ndirectly, to see what it does. Comments beginning with `!` are part of\nvalid Factor source.\n\nFor a quick start, work through the stack, word definitions, quotations, control flow, and sequences. The later sections introduce objects, metaprogramming, and libraries that you can return to as you need them.\n\n### Values and the stack\n\n[Literals](https://docs.factorcode.org/content/article-literals.html) push values onto the data stack. Words consume inputs from the top\nof that stack and push their outputs. Code runs from left to right:\n\n```\nUSING: math prettyprint ;\n2 3 + . ! 5\n10 4 - . ! 6\n2 3 + 4 * . ! 20\n```\n[`.`](https://docs.factorcode.org/content/word-.%2Cprettyprint.html) consumes and prints an object. [`print`](https://docs.factorcode.org/content/word-print%2Cio.html) consumes and prints a string.\nThe comments beside examples show the output. Because printing removes the\nvalue, these examples leave the stack empty unless stated otherwise.\nThere are no parentheses around function arguments: put the arguments on\nthe stack, then invoke the word. Below, the top of the stack is on the right:\n\n```\nCode Stack\n2 2\n3 2 3\n+ 5\n4 5 4\n* 20\n. (empty)\n```\nSpaces matter. `2 3 +` is three tokens; `2+3` is a single token, which would\nneed to be the name of a word. Names like [`number>string`](https://docs.factorcode.org/content/word-number__gt__string%2Cmath.parser.html), [`empty?`](https://docs.factorcode.org/content/word-empty__que__%2Csequences.html), and\n[`set-at`](https://docs.factorcode.org/content/word-set-at%2Cassocs.html) are ordinary word names. A trailing `?` conventionally marks a\npredicate; `>` often appears in conversion names. Those characters are part\nof the name, not separate operators. A trailing `!` often marks a mutating\nvariant, such as [`append!`](https://docs.factorcode.org/content/word-append%21%2Csequences.html); `*` usually marks an alternative form. There are some\n[conventions](https://docs.factorcode.org/content/article-conventions.html) useful\nfor learning word and type naming.\n\n### Comments and literals\n\n```\nUSING: math multiline prettyprint ;\n! A comment runs to the end of the line.\n/* A block comment can span\n several lines. */\n42 . ! Integer\n-17 . ! Negative integer\n0xff . ! 255, hexadecimal\n0b1010 . ! 10, binary\n3/4 . ! Exact rational\n1.25 . ! Floating point\nC{ 2 3 } . ! Complex number: 2 + 3i\nt . ! True\nf . ! False\n\"hello\\nworld\" . ! String with an escape\nCHAR: A . ! 65, a character code point\n{ 1 2 3 } . ! Array\nV{ 1 2 3 } . ! Growable vector\nB{ 0 127 255 } . ! Byte array\nH{ { \"name\" \"Ada\" } } . ! Hashtable\n[ 1 + ] . ! Quotation: code as a value\n```\nArrays and quotations contain objects without executing them. Collection\nliterals are useful for fixed data; when mutating one inside a word, use\n[`clone`](https://docs.factorcode.org/content/word-clone%2Ckernel.html) to obtain a fresh copy rather than changing a shared literal.\nThis is a shallow copy: objects inside the collection are still shared.\n\nBlock comments come from the [`multiline`](https://docs.factorcode.org/content/vocab-multiline.html) vocabulary.\n\n[`CHAR:`](https://docs.factorcode.org/content/word-CHAR__colon__%2Csyntax.html) produces an integer code point; Factor has no separate character\ntype. `{ ... }` is an array, while `[ ... ]` is executable code held as a\nvalue called a [quotation](https://docs.factorcode.org/content/article-quotations.html).\nSpaces separate the literal openers, their contents, and the closing\ndelimiters, as in `{ 1 2 3 }` and `[ 1 + ]`.\n\n### Strings and escape characters\n\nString literals use double quotes. A backslash introduces a\n[character escape](https://docs.factorcode.org/content/article-escape.html):\n\n| Escape | Meaning | \n|---|---|\n| `\\\"` | Double quote | \n| `\\\\` | Backslash | \n| `\\a` | Bell (code point 7) | \n| `\\b` | Backspace (8) | \n| `\\e` | Escape (27) | \n| `\\f` | Form feed (12) | \n| `\\n` | Newline (10) | \n| `\\r` | Carriage return (13) | \n| `\\s` | Space (32) | \n| `\\t` | Tab (9) | \n| `\\v` | Vertical tab (11) | \n| `\\0` | Null (0) | \n| `\\ooo` | Code point given by one to three octal digits | \n| `\\xHH` | Code point given by exactly two hexadecimal digits | \n| `\\uHHHHHH` | Code point given by exactly six hexadecimal digits | \n| `\\u{H...}` | Code point given by hexadecimal digits inside braces | \n| `\\u{name}` | Named Unicode character, with Unicode support loaded | \n\nFor example:\n\n```\nUSING: io prettyprint sequences unicode ;\n\"She said \\\"hello\\\".\" print ! She said \"hello\".\n\"C:\\\\Users\\\\Ada\" print ! C:\\Users\\Ada\n\"\\x41\\u000042\\u{43}\" print ! ABC\n\"\\u{greek-small-letter-pi}\" print ! π\n\"first\\nsecond\" print ! Prints two lines\n\"\\t\" length . ! 1: the escape represents one character\n\"hello\" length . ! 5\n\"hello\" >upper . ! \"HELLO\"\n\"a,b,c\" \",\" split . ! { \"a\" \"b\" \"c\" }\n{ \"a\" \"b\" \"c\" } \", \" join . ! \"a, b, c\"\n\"42\" string>number . ! 42\n42 number>string . ! \"42\"\n\"oops\" string>number . ! f\n```\nThe six-digit `\\u` form differs from languages that use four digits; the\nbraced form is often easier to read. Unknown escapes are errors. Strings\ncan also span source lines directly: an actual newline becomes part of the\nstring. A backslash immediately before a source newline continues the\nstring without including that newline. A backslash followed by a literal\nspace also represents a space, like `\\s`.\n\n*Note: the length of a [string](https://docs.factorcode.org/content/article-strings.html)\nis the number of code points, not the number of visible glyphs. You can learn a bit more\nby reading about Factor’s [Unicode](https://re.factorcode.org/2023/05/unicode.html) support.*\n\n### Stack shuffling\n\nTypical of [concatenative languages](https://concatenative.org/wiki/view/Concatenative%20language),\nthe stack is a data structure with it’s own access patterns that we often call\n[stack shuffling](https://docs.factorcode.org/content/article-tour-stack-shuffling.html).\n\n```\nUSING: kernel prettyprint ;\n10 dup . . ! Prints 10, then 10\n10 20 swap . . ! Prints 10, then 20\n10 20 over . . . ! Prints 10, then 20, then 10\n10 20 nip . ! 20: discard the second item\n10 20 drop . ! 10: discard the top item\n```\nThe usual [stack shuffling words](https://docs.factorcode.org/content/article-shuffle-words.html) have these effects:\n\n```\n! dup ( x -- x x )\n! drop ( x -- )\n! swap ( x y -- y x )\n! over ( x y -- x y x )\n! nip ( x y -- y )\n! rot ( x y z -- y z x )\n```\nMost Factor code uses short definitions and combinators to keep explicit shuffling to a minimum.\n\nIn a stack effect, inputs and outputs run from left to right, with the\ntopmost value last. [`swap`](https://docs.factorcode.org/content/word-swap%2Ckernel.html) therefore changes a stack ending in `x y` into\none ending in `y x`; values below those inputs are untouched. Repeated\n[`.`](https://docs.factorcode.org/content/word-.%2Cprettyprint.html) calls print the topmost result first.\n\n### Defining words\n\nYou can create [words](https://docs.factorcode.org/content/article-words.html) that\ncontain code that is executed when called:\n\n```\nUSING: kernel math prettyprint ;\nIN: scratchpad\n: square ( n -- n-squared ) dup * ;\n: neighbors ( n -- below above )\n dup 1 - swap 1 + ;\n5 square . ! 25\n5 neighbors . . ! Prints 6, then 4\nCONSTANT: answer 42\nanswer . ! 42\n```\n[`:`](https://docs.factorcode.org/content/article-colon-definition.html) begins a definition and [`;`](https://docs.factorcode.org/content/word-%3B%2Csyntax.html) ends it. The [stack effect](https://docs.factorcode.org/content/article-effects.html) `( inputs -- outputs )` documents how many values the word consumes and produces. Its\nnames describe the values; they do not bind variables or specify types.\nThe compiler checks stack effects, including compatible effects for branches.\nWords can return several values simply by leaving them on the stack.\nThere is no explicit `return`: execution finishes at the end of the word.\n\n[`ALIAS: new-name existing-word`](https://docs.factorcode.org/content/word-ALIAS__colon__%2Csyntax.html) defines another name for a word.\n\n### Arithmetic and comparisons\n\nLots of [arithmetic](https://docs.factorcode.org/content/article-arithmetic.html) is\navailable for computing with [numbers](https://docs.factorcode.org/content/article-numbers.html):\n\n```\nUSING: kernel math math.functions math.order prettyprint ;\n7 2 / . ! 3+1/2, an exact rational\n7 2 /i . ! 3, integer division\n7 2 mod . ! 1\n2 10 ^ . ! 1024\n9 sqrt . ! 3.0\n-5 abs . ! 5\n3 8 min . ! 3\n3 8 max . ! 8\n2 3 < . ! t\n2 3 >= . ! f\n\"hello\" \"hello\" = . ! t, value equality\n```\n[Integers](https://docs.factorcode.org/content/article-integers.html) grow beyond machine size automatically, and division of integers\ncan produce [exact ratios](https://docs.factorcode.org/content/article-rationals.html). Use floating-point inputs when you want\nfloating-point arithmetic.\n\nBitwise operations have their own names, separate from boolean logic:\n\n```\nUSING: math prettyprint ;\n0b1100 0b1010 bitand . ! 8\n0b1100 0b1010 bitor . ! 14\n0b1100 0b1010 bitxor . ! 6\n1 3 shift . ! 8: shift left\n8 -1 shift . ! 4: shift right\n```\n### Quotations\n\nSquare brackets produce a [quotation](https://docs.factorcode.org/content/article-quotations.html). [`call`](https://docs.factorcode.org/content/word-call,kernel.html) executes it:\n\n```\nUSING: kernel math prettyprint sequences ;\n5 [ 1 + ] call . ! 6\n{ 1 2 3 } [ 2 * ] map . ! { 2 4 6 }\n```\nQuotations can be passed to words, returned from words, and stored in\ncollections. Words that take quotations are called\n[*combinators*](https://docs.factorcode.org/content/article-combinators.html).\n\n### Booleans and conditionals\n\nIn [boolean tests](https://docs.factorcode.org/content/article-booleans.html), only [`f`](https://docs.factorcode.org/content/word-f%2Csyntax.html) is false. Zero, an empty string, and an empty array are all true.\n\n```\nUSING: kernel math prettyprint ;\nt f and . ! f\nt f or . ! t\nf not . ! t\n3 2 > [ \"yes\" ] [ \"no\" ] if . ! \"yes\"\n0 [ \"truthy\" ] [ \"false\" ] if . ! \"truthy\"\nt [ \"runs\" . ] when\nf [ \"runs too\" . ] unless\n```\n[`if`](https://docs.factorcode.org/content/word-if,kernel.html) consumes a condition and two quotations. It calls the first quotation\nfor a true condition and the second for [`f`](https://docs.factorcode.org/content/word-f%2Csyntax.html). [`when`](https://docs.factorcode.org/content/word-when%2Ckernel.html) and [`unless`](https://docs.factorcode.org/content/word-unless%2Ckernel.html) take one\nquotation. These are words that operate on code values, just like [`+`](https://docs.factorcode.org/content/word-%2B%2Cmath.html)\noperates on numbers.\n\nFor several alternatives, use [`cond` or `case`](https://docs.factorcode.org/content/article-conditionals.html):\n\n```\nUSING: combinators kernel math prettyprint ;\nIN: scratchpad\n: sign-name ( n -- string )\n {\n { [ dup 0 < ] [ drop \"negative\" ] }\n { [ dup 0 = ] [ drop \"zero\" ] }\n [ drop \"positive\" ]\n } cond ;\n-3 sign-name . ! \"negative\"\n: color-name ( color -- string )\n {\n { \"r\" [ \"red\" ] }\n { \"g\" [ \"green\" ] }\n [ drop \"unknown\" ]\n } case ;\n\"g\" color-name . ! \"green\"\n```\n[`cond`](https://docs.factorcode.org/content/word-cond%2Ccombinators.html) tries predicate quotations in order. [`case`](https://docs.factorcode.org/content/word-case%2Ccombinators.html) compares an input with\neach key; a matching branch consumes the key automatically, while the\ndefault branch receives the unmatched input.\n\n[`and`](https://docs.factorcode.org/content/word-and%2Ckernel.html) and [`or`](https://docs.factorcode.org/content/word-or%2Ckernel.html) combine values that have already been computed. For\n[short-circuit evaluation](https://docs.factorcode.org/content/article-combinators.short-circuit.html), pass predicate quotations instead:\n\n```\nUSING: combinators.short-circuit kernel math prettyprint ;\n5 { [ 0 > ] [ 10 < ] } 1&& . ! t: positive and less than ten\n-5 { [ 0 < ] [ 10 > ] } 1|| . ! t: negative or greater than ten\n```\nEach predicate receives the same input. [`1&&`](https://docs.factorcode.org/content/word-1%26%26%2Ccombinators.short-circuit.html) stops at the first false\nresult; [`1||`](https://docs.factorcode.org/content/word-1__pipe____pipe__%2Ccombinators.short-circuit.html) stops at the first true result. The leading number is the\nnumber of inputs passed to each predicate.\n\n### Keeping and hiding values\n\nThe [`dip`](https://docs.factorcode.org/content/word-dip,kernel.html) word temporarily hides a value while a quotation works on the stack below\nit. [`keep`](https://docs.factorcode.org/content/word-keep,kernel.html) gives a quotation a value and also preserves that value:\n\n```\nUSING: kernel math prettyprint ;\n10 20 [ 1 + ] dip + . ! 31: increment 10, then restore 20\n5 [ 1 + ] keep . . ! Prints 5, then 6\n```\n```\n! dip ( ..a x quot -- ..b x )\n! keep ( ..a x quot -- ..b x )\n```\nThe overall shapes look alike, but `dip` hides `x` from the quotation and\n`keep` passes it in. [`2dip`](https://docs.factorcode.org/content/word-2dip%2Ckernel.html) hides two values; [`2keep`](https://docs.factorcode.org/content/word-2keep%2Ckernel.html) preserves two inputs.\n\n### Applying several quotations\n\nThe [`bi` family](https://docs.factorcode.org/content/article-cleave-combinators.html) covers several common ways to distribute inputs:\n\n```\nUSING: kernel math prettyprint ;\n! Apply two quotations to the same input.\n5 [ 1 + ] [ 2 * ] bi . . ! Prints 10, then 6\n! Apply one quotation to each of two inputs.\n3 4 [ 2 * ] bi@ . . ! Prints 8, then 6\n! Apply separate quotations to separate inputs.\n3 4 [ 1 + ] [ 2 * ] bi* . . ! Prints 8, then 4\n! Apply two quotations to the same pair of inputs.\n3 4 [ + ] [ * ] 2bi . . ! Prints 12, then 7\n```\nFor example, [`2bi`](https://docs.factorcode.org/content/word-2bi%2Ckernel.html) lets a word calculate two results from the same inputs:\n\n```\nUSING: kernel math prettyprint ;\nIN: scratchpad\n: sum-and-product ( a b -- sum product )\n [ + ] [ * ] 2bi ;\n3 4 sum-and-product . . ! Prints 12, then 7\n```\nThen [`tri`](https://docs.factorcode.org/content/word-tri%2Ckernel.html), [`tri@`](https://docs.factorcode.org/content/word-tri__at__%2Ckernel.html), and [`tri*`](https://docs.factorcode.org/content/word-tri__star__%2Ckernel.html) extend these patterns to three quotations or\ninputs.\n\nYou can find [`cleave`](https://docs.factorcode.org/content/word-cleave%2Ccombinators.html), [`napply`](https://docs.factorcode.org/content/word-napply%2Cgeneralizations.html) and [`spread`](https://docs.factorcode.org/content/word-spread%2Ccombinators.html) as the generalizations\nof those patterns.\n\n### Partial application and composition\n\nThe [`curry`](https://docs.factorcode.org/content/word-curry,kernel.html) word binds a value to the beginning of a quotation.\n[`compose`](https://docs.factorcode.org/content/word-compose,kernel.html) joins two\nquotations so that one runs after the other:\n\n```\nUSING: kernel math prettyprint sequences ;\n{ 1 2 3 } 10 [ + ] curry map . ! { 11 12 13 }\n5 [ 1 + ] [ 2 * ] compose call . ! 12\n```\n`10 [ + ] curry` behaves like `[ 10 + ]`. This is a convenient way to build\na quotation using a value computed at runtime.\n\nThe [`fry` vocabulary](https://docs.factorcode.org/content/article-fry.html) provides quotation templates. [`_`](https://docs.factorcode.org/content/word-_%2Csyntax.html) inserts a value;\n[`@`](https://docs.factorcode.org/content/word-__at__%2Csyntax.html) inserts a call to a supplied quotation:\n\n```\nUSING: fry kernel math prettyprint sequences ;\n{ 1 2 3 } 10 '[ _ + ] map . ! { 11 12 13 }\n5 [ 1 + ] '[ @ 2 * ] call . ! 12\n```\nThe apostrophe in `'[ ... ]` makes this a template rather than an ordinary\nquotation. Its placeholders consume their values when the template is\nconstructed, not when the resulting quotation is called.\n\n### Defining combinators\n\nA combinator can be an ordinary word with quotation inputs. Give those\ninputs their own [stack effects](https://docs.factorcode.org/content/article-inference-combinators.html) and declare the word [`inline`](https://docs.factorcode.org/content/word-inline%2Csyntax.html) so the\ncompiler can infer the effects at its call sites:\n\n```\nUSING: kernel math prettyprint ;\nIN: scratchpad\n: twice ( ... quot: ( ... -- ... ) -- ... )\n dup [ call ] dip call ; inline\n3 [ 2 * ] twice . ! 12\n```\nThe `...` represents values carried through the combinator. Here, the\nsupplied quotation must preserve stack height, and `twice` calls it twice.\n\n### Loops and recursion\n\n```\nUSING: kernel math prettyprint sequences ;\n3 [ \"hello\" . ] times ! Print three times\n{ \"Ada\" \"Grace\" } [ . ] each ! Visit each element\n5 [ . ] each ! Print 0 through 4\n0 [ dup 3 < ] [ dup . 1 + ] while drop\n! Print 0, 1, 2; keep the counter on the stack\n```\nThe [looping combinator](https://docs.factorcode.org/content/article-looping-combinators.html) [`while`](https://docs.factorcode.org/content/word-while%2Ckernel.html) calls its predicate before each iteration. The predicate leaves\na condition; the body updates the loop’s values. [`until`](https://docs.factorcode.org/content/word-until%2Ckernel.html) reverses the\ncondition. Often [`each`](https://docs.factorcode.org/content/word-each%2Csequences.html), [`map`](https://docs.factorcode.org/content/word-map%2Csequences.html), or [`reduce`](https://docs.factorcode.org/content/word-reduce%2Csequences.html) expresses the loop directly.\n\nRecursion uses an ordinary call to the word being defined:\n\n```\nUSING: kernel math prettyprint ;\nIN: scratchpad\n: factorial ( n -- n! )\n dup 1 <=\n [ drop 1 ]\n [ dup 1 - factorial * ] if ;\n5 factorial . ! 120\n```\nDefinitions are read in order: define helper words before words that use\nthem. [`DEFER:`](https://docs.factorcode.org/content/article-deferred.html)\ndeclares a word before its implementation, allowing mutual recursion:\n\n```\nUSING: kernel math prettyprint ;\nIN: scratchpad\nDEFER: odd-count?\n: even-count? ( n -- ? )\n dup 0 = [ drop t ] [ 1 - odd-count? ] if ;\n: odd-count? ( n -- ? )\n dup 0 = [ drop f ] [ 1 - even-count? ] if ;\n6 even-count? . ! t\n7 odd-count? . ! t\n```\nThese examples accept nonnegative integers. Factor guarantees\n[tail-call optimization](https://docs.factorcode.org/content/article-tail-call-opt.html),\nso a final call such as the one to `odd-count?` can continue without growing\nthe call stack.\n\n### Local variables and closures\n\nWhen names make an algorithm easier to read, import\n[`locals`](https://docs.factorcode.org/content/article-locals.html) and define\na word with [`::`](https://docs.factorcode.org/content/word-__colon____colon__%2Csyntax.html). Inputs become lexical variables:\n\n```\nUSING: kernel locals math prettyprint sequences ;\nIN: scratchpad\n:: rectangle-area ( width height -- area )\n width height * ;\n:: add-offset ( seq offset -- newseq )\n seq [| n | n offset + ] map ;\n3 4 rectangle-area . ! 12\n{ 1 2 3 } 10 add-offset . ! { 11 12 13 }\n:: hypotenuse-squared ( a b -- n )\n a a * :> a-squared\n b b * :> b-squared\n a-squared b-squared + ;\n```\n[`:>`](https://docs.factorcode.org/content/word-__colon____gt__%2Csyntax.html) binds a computed value. [`\\[| n | ... \\]`](https://docs.factorcode.org/content/word-%5B__pipe__%2Csyntax.html) names quotation inputs and can\ncapture enclosing variables, as `offset` does above. Output names in [`::`](https://docs.factorcode.org/content/word-__colon____colon__%2Csyntax.html)\nstill describe stack results; there is no implicit return variable.\n\n[Mutable locals](https://docs.factorcode.org/content/article-locals-mutable.html) have an exclamation point in their declaration and an\nassociated setter:\n\n```\nUSING: kernel locals math prettyprint ;\n[let\n 0 :> total!\n 5 [ total 1 + total! ] times\n total . ! 5\n]\n```\n[`\\[let ... \\]`](https://docs.factorcode.org/content/word-%5Blet%2Csyntax.html) establishes a lexical scope, including in the listener.\n\n### Sequences\n\nArrays, vectors, strings, and several other types share the sequence\n[protocol](https://docs.factorcode.org/content/article-sequence-protocol.html). Most sequence words work across these types:\n\n```\nUSING: kernel math prettyprint sequences sorting ;\n{ 10 20 30 } length . ! 3\n{ 10 20 30 } first . ! 10\n1 { 10 20 30 } nth . ! 20, zero-based indexing\n{ 1 2 } { 3 4 } append . ! { 1 2 3 4 }\n{ 1 2 3 } reverse . ! { 3 2 1 }\n{ 1 2 3 4 } [ dup * ] map . ! { 1 4 9 16 }\n{ 1 2 3 4 } [ 2 mod 0 = ] filter . ! { 2 4 }\n{ 1 2 3 4 } 0 [ + ] reduce . ! 10\n{ 1 2 3 } [ 0 > ] all? . ! t\n{ 1 2 3 } [ 2 = ] any? . ! t\n{ 3 1 2 } natural-sort . ! { 1 2 3 }\nV{ 1 2 } clone\n3 over push . ! V{ 1 2 3 }\n```\nThe [sequence combinator](https://docs.factorcode.org/content/article-sequences-combinators.html) [`map`](https://docs.factorcode.org/content/word-map%2Csequences.html) collects quotation results; [`each`](https://docs.factorcode.org/content/word-each%2Csequences.html) is for side effects. [`reduce`](https://docs.factorcode.org/content/word-reduce%2Csequences.html)\nthreads an accumulator through the sequence. [`push`](https://docs.factorcode.org/content/word-push%2Csequences.html) mutates a growable\nsequence and consumes both the new element and the sequence.\n\nFor incremental construction, [`make`](https://docs.factorcode.org/content/article-namespaces-make.html)\ncollects values produced inside a quotation. [`,`](https://docs.factorcode.org/content/word-__comma__%2Cmake.html) adds one element and [`%`](https://docs.factorcode.org/content/word-__percent__%2Cmake.html)\nadds the elements of a sequence:\n\n```\nUSING: make prettyprint ;\n[ 1 , { 2 3 } % 4 , ] { } make . ! { 1 2 3 4 }\n[ \"Hello\" % CHAR: \\s , \"Ada\" % ] \"\" make . ! \"Hello Ada\"\n```\nThe final exemplar (`{ }` or `\"\"`) chooses the result type. Prefer [`map`](https://docs.factorcode.org/content/word-map%2Csequences.html),\n[`filter`](https://docs.factorcode.org/content/word-filter%2Csequences.html), or [`append`](https://docs.factorcode.org/content/word-append%2Csequences.html) when one of those directly expresses the operation.\n\n[`Specialized arrays`](https://docs.factorcode.org/content/article-specialized-arrays.html)\nstore elements as C numeric types in contiguous memory while supporting\nthe sequence protocol:\n\n```\nUSING: alien.c-types prettyprint sequences specialized-arrays ;\nSPECIALIZED-ARRAY: double\ndouble-array{ 1.0 2.0 3.0 } length . ! 3\n```\n### Hashtables and sets\n\nAssociative collections use the [`assocs` protocol](https://docs.factorcode.org/content/article-assocs.html):\n\n```\nUSING: assocs kernel prettyprint ;\n\"Ada\" H{ { \"Ada\" 36 } { \"Grace\" 85 } } at . ! 36\n\"missing\" H{ { \"Ada\" 36 } } at . ! f\n\"enabled\" H{ { \"enabled\" f } } at* . . ! Prints t, then f\nH{ { \"Ada\" 36 } } clone\n37 \"Ada\" pick set-at\n\"Ada\" swap at . ! 37\n```\n[`at*`](https://docs.factorcode.org/content/word-at__star__%2Cassocs.html) returns a presence flag as well as a value, distinguishing a missing\nkey from a key whose value is [`f`](https://docs.factorcode.org/content/word-f%2Csyntax.html). [`set-at`](https://docs.factorcode.org/content/word-set-at%2Cassocs.html) takes a value, key, and assoc.\n\n[Sets](https://docs.factorcode.org/content/article-sets.html) also have a protocol, with useful operations on ordinary sequences:\n\n```\nUSING: prettyprint sets ;\n{ 1 2 2 3 } members . ! { 1 2 3 }\n2 { 1 2 3 } in? . ! t\n{ 1 2 } { 2 3 } union . ! { 1 2 3 }\n{ 1 2 } { 2 3 } intersect . ! { 2 }\n{ 1 2 } { 2 3 } diff . ! { 1 }\n```\nFor repeated membership checks, use a hash set rather than scanning a sequence:\n\n```\nUSING: hash-sets prettyprint sets ;\n2 HS{ 1 2 3 } in? . ! t\n```\n### Tuples and accessors\n\n[Tuples](https://docs.factorcode.org/content/article-tuples.html) define classes with named slots. [`boa`](https://docs.factorcode.org/content/word-boa%2Ckernel.html) constructs a tuple from\nslot values in declaration order:\n\n```\nUSING: accessors kernel prettyprint ;\nIN: scratchpad\nTUPLE: person name age ;\nC: person\n\"Ada\" 36 \ndup name>> . ! \"Ada\"\n37 >>age\nage>> . ! 37\n```\n[`C:`](https://docs.factorcode.org/content/word-C__colon__%2Csyntax.html) defines a constructor using [`boa`](https://docs.factorcode.org/content/word-boa%2Ckernel.html). [`name>>`](https://docs.factorcode.org/content/article-accessors.html) reads a slot; [`>>age`](https://docs.factorcode.org/content/article-accessors.html)\nwrites a slot and returns the tuple, allowing chained updates. You can also\nconstruct an instance with `person new` and set its slots explicitly.\nNames such as `` conventionally denote constructors; the angle\nbrackets are part of the word’s name.\n\nTuple literals use [`T{ ... }`](https://docs.factorcode.org/content/word-T%7B%2Csyntax.html). Slots can also declare a class, an initial\nvalue, or the [`read-only`](https://docs.factorcode.org/content/word-read-only%2Csyntax.html) attribute:\n\n```\nUSING: accessors kernel math prettyprint ;\nIN: scratchpad\nT{ person { name \"Grace\" } { age 85 } } name>> . ! \"Grace\"\nTUPLE: counter { value integer initial: 0 } ;\ncounter new\n[ 1 + ] change-value\nvalue>> . ! 1\n```\n[`Slot declarations`](https://docs.factorcode.org/content/article-tuple-declarations.html)\nconstrain stored values. `{ name string read-only }`, for example, declares\na string slot that is initialized at construction and has no generated\nsetter. [`change-value`](https://docs.factorcode.org/content/article-accessors.html) applies a quotation to the current slot value,\nstores the result, and returns the tuple.\n\n### Structs and C layouts\n\n[`STRUCT:`](https://docs.factorcode.org/content/article-classes.struct.html)\ndefines a record backed by a C memory layout. Every field declares a C\ntype, and the usual slot accessors work on struct instances:\n\n```\nUSING: accessors alien.c-types classes.struct kernel prettyprint ;\nIN: scratchpad\nSTRUCT: c-point\n { x double }\n { y double } ;\n3.0 4.0 c-point boa\ndup x>> . ! 3.0\ny>> . ! 4.0\nPACKED-STRUCT: packet-header\n { kind uint8_t }\n { length uint32_t } ;\npacket-header heap-size . ! 5\n```\n[`boa`](https://docs.factorcode.org/content/word-boa%2Ckernel.html) initializes fields from stack values; `c-point ` creates an\ninstance with its declared initial field values. These constructors use\ngarbage-collected storage. [`STRUCT:`](https://docs.factorcode.org/content/word-STRUCT__colon__%2Cclasses.struct.html) includes alignment padding according\nto the platform’s C layout rules. [`PACKED-STRUCT:`](https://docs.factorcode.org/content/word-PACKED-STRUCT__colon__%2Cclasses.struct.html) removes padding between\nfields and at the end, for layouts that explicitly require packed storage.\nIt does not choose byte order.\n\n[`UNION-STRUCT:`](https://docs.factorcode.org/content/word-UNION-STRUCT__colon__%2Cclasses.struct.html) defines overlapping C fields that share the same storage.\nIt serves a different purpose from [`UNION:`](https://docs.factorcode.org/content/word-UNION__colon__%2Csyntax.html), which groups Factor classes.\nUse tuples for ordinary Factor records and structs when you need C-compatible\nmemory or an explicitly specified binary layout.\n\n### Generic words and classes\n\nA [generic word](https://docs.factorcode.org/content/article-generic.html) chooses a method based on the class of its topmost input.\nThis example reuses `person` and `` from “Tuples and accessors”:\n\n```\nUSING: accessors kernel math math.parser prettyprint ;\nIN: scratchpad\nGENERIC: description ( obj -- string )\nM: person description name>> ;\nM: integer description number>string ;\n\"Ada\" 36 description . ! \"Ada\"\n42 description . ! \"42\"\n```\nA [tuple subclass](https://docs.factorcode.org/content/article-tuple-subclassing.html)\ninherits its parent’s slots and can add its own. An overriding method can\nreuse the next less-specific method with\n[`call-next-method`](https://docs.factorcode.org/content/article-call-next-method.html):\n\n```\nUSING: accessors kernel prettyprint sequences ;\nIN: scratchpad\nTUPLE: employee < person role ;\nC: employee\nM: employee description\n [ call-next-method ] [ role>> ] bi \" - \" glue ;\n\"Ada\" 36 \"programmer\" description .\n! \"Ada - programmer\"\n```\nThe constructor takes inherited slots first (`name`, `age`), then `role`.\nHere [`call-next-method`](https://docs.factorcode.org/content/word-call-next-method%2Csyntax.html) receives the employee, calls the `person` method,\nand returns `\"Ada\"`; the override combines that with the employee’s role.\nIt must appear inside a method definition and receives its inputs from the\nstack, just like an ordinary call.\n\n[`M:`](https://docs.factorcode.org/content/word-M__colon__%2Csyntax.html) defines a method. This is how protocols such as sequences and assocs\nprovide common operations for many concrete types. Classes also have\npredicate words, and you can define narrower predicate classes or unions:\n\n```\nUSING: kernel math prettyprint strings ;\nIN: scratchpad\nPREDICATE: positive-integer < integer 0 > ;\nUNION: text-or-integer string integer ;\n3 positive-integer? . ! t\n-3 positive-integer? . ! f\n\"hello\" text-or-integer? . ! t\n```\n[`Mixin classes`](https://docs.factorcode.org/content/article-mixins.html)\nare open groups of classes: [`INSTANCE:`](https://docs.factorcode.org/content/word-INSTANCE__colon__%2Csyntax.html) adds a member, including after the\nmixin was defined. They are useful for protocols spanning unrelated types:\n\n```\nUSING: prettyprint ;\nIN: scratchpad\nMIXIN: named\nINSTANCE: person named\n\"Ada\" 36 named? . ! t\n```\n[`Singleton classes`](https://docs.factorcode.org/content/article-singletons.html)\neach have one stateless instance, useful as distinct states or options.\nUnlike a plain symbol, each can have its own generic methods:\n\n```\nUSING: prettyprint ;\nIN: scratchpad\nSINGLETONS: pending running finished ;\nUNION: job-state pending running finished ;\npending job-state? . ! t\n```\n[`UNION:`](https://docs.factorcode.org/content/word-UNION__colon__%2Csyntax.html) accepts instances of any listed class. [`INTERSECTION:`](https://docs.factorcode.org/content/word-INTERSECTION__colon__%2Csyntax.html) requires\nmembership in all listed classes. For named numeric values,\n[`ENUMERATION:`](https://docs.factorcode.org/content/article-enums.html)\nis available in [`classes.enumeration`](https://docs.factorcode.org/content/vocab-classes.enumeration.html):\n\n```\nUSING: classes.enumeration prettyprint ;\nIN: scratchpad\nENUMERATION: priority low medium high ;\npriority.low . ! 0\npriority.high . ! 2\n```\n### Symbols and dynamic variables\n\nLexical locals are scoped by source structure. [`namespaces`](https://docs.factorcode.org/content/vocab-namespaces.html) provides\n[variables scoped dynamically](https://docs.factorcode.org/content/article-namespaces.html) around a quotation:\n\n```\nUSING: namespaces prettyprint ;\nIN: scratchpad\nSYMBOL: current-user\n\"Ada\" current-user [\n current-user get . ! \"Ada\"\n] with-variable\n```\nCalled words inside the quotation see the binding too. [`with-variable`](https://docs.factorcode.org/content/word-with-variable%2Cnamespaces.html)\nrestores the previous binding on exit. [`set`](https://docs.factorcode.org/content/word-set%2Cnamespaces.html) changes a binding in the\ncurrent namespace; [`set-global`](https://docs.factorcode.org/content/word-set-global%2Cnamespaces.html) sets a global binding. A symbol is itself\na value, so symbols also work as distinct markers and hashtable keys.\n\n### Errors and cleanup\n\n```\nUSING: continuations kernel prettyprint ;\nIN: scratchpad\nERROR: invalid-age age ;\n[ -1 invalid-age ] [ drop \"handled\" ] recover . ! \"handled\"\n[ \"work\" . ] [ \"cleanup\" . ] finally\n! Prints \"work\", then \"cleanup\"\n```\nThe [exception handling](https://docs.factorcode.org/content/article-errors.html) form [`ERROR:`](https://docs.factorcode.org/content/word-ERROR__colon__%2Csyntax.html) defines an error class and a word that throws an instance.\n[`recover`](https://docs.factorcode.org/content/word-recover%2Ccontinuations.html) calls a handler with the thrown object. The data stack is restored\nto its state before the protected quotation, then the error is pushed.\n[`finally`](https://docs.factorcode.org/content/word-finally%2Ccontinuations.html) runs cleanup on either normal completion or an error.\n\nFactor also exposes [continuations](https://docs.factorcode.org/content/article-continuations.html),\nwhich capture execution state and can later resume it. They underpin error\nhandling and cooperative threads; most everyday code uses those higher-level\nfacilities directly.\n\n### Resource disposal\n\nOrdinary objects are garbage collected. Resources such as open streams\nalso need [deterministic disposal](https://docs.factorcode.org/content/article-destructors.html).\n[`dispose`](https://docs.factorcode.org/content/word-dispose%2Cdestructors.html) releases a resource explicitly. [`with-disposal`](https://docs.factorcode.org/content/word-with-disposal%2Cdestructors.html) passes a resource\nto a quotation and disposes it when the quotation finishes or throws:\n\n```\nUSING: destructors io io.encodings.utf8 io.files prettyprint ;\n\"Hello!\\n\" \"disposal.txt\" utf8 set-file-contents\n\"disposal.txt\" utf8 \n[ stream-readln . ] with-disposal ! \"Hello!\"\n```\nThis example creates `disposal.txt` in the current directory. The reader\nis closed after reading the line. For several resources, use\n[`with-destructors`](https://docs.factorcode.org/content/article-destructors-using.html)\nand register each one for cleanup:\n\n```\nUSING: destructors io io.encodings.utf8 io.files prettyprint ;\n[\n \"disposal.txt\" utf8 &dispose\n stream-readln . ! \"Hello!\"\n] with-destructors\n```\nBoth registration words leave the resource on the stack so you can use it:\n\n| Word | When the resource is disposed | \n|---|---|\n| [`&dispose`](https://docs.factorcode.org/content/word-%26dispose%2Cdestructors.html) | When the enclosing [`with-destructors`](https://docs.factorcode.org/content/word-with-destructors%2Cdestructors.html) scope finishes, on success or error | \n| [`\\|dispose`](https://docs.factorcode.org/content/word-__pipe__dispose%2Cdestructors.html) | When the enclosing [`with-destructors`](https://docs.factorcode.org/content/word-with-destructors%2Cdestructors.html) scope exits with an error | \n\n[`&dispose`](https://docs.factorcode.org/content/word-%26dispose%2Cdestructors.html) is for resources used within a scope. [`|dispose`](https://docs.factorcode.org/content/word-__pipe__dispose%2Cdestructors.html) is useful when\nbuilding a result that owns resources: if construction fails, clean up;\nif it succeeds, return the resources to the caller. For example:\n\n```\nUSING: destructors io.encodings.utf8 io.files kernel ;\nIN: scratchpad\n: open-two-readers ( path1 path2 -- reader1 reader2 )\n [ [ utf8 |dispose ] bi@ ] with-destructors ;\n\"disposal.txt\" \"disposal.txt\" open-two-readers\n[ dispose ] bi@ ! Caller closes both readers\n```\nIf opening the second reader throws, the first reader is disposed. On\nsuccess, both readers remain open and the caller owns their cleanup.\nWithin each registration group, destructors run in reverse registration\norder. The [`with-file-reader`](https://docs.factorcode.org/content/word-with-file-reader%2Cio.files.html) and [`with-file-writer`](https://docs.factorcode.org/content/word-with-file-writer%2Cio.files.html) combinators shown below\nmanage stream cleanup automatically.\n\n### Vocabularies\n\nA [vocabulary](https://docs.factorcode.org/content/article-vocabularies.html) is a namespace and a unit of source organization. A vocabulary\nnamed `examples.greeting` conventionally lives in\n`examples/greeting/greeting.factor` under a vocabulary root:\n\n```\nUSING: io ;\nIN: examples.greeting\n\n: greet ( -- ) greeting print ;\nMAIN: greet\n```\n[``](https://docs.factorcode.org/content/word-__lt__PRIVATE%2Csyntax.html) places helper definitions in the vocabulary’s\nprivate namespace. Import public definitions with `USE: examples.greeting`\nor include it in a [`USING:`](https://docs.factorcode.org/content/word-USING__colon__%2Csyntax.html) list. Run the entry point with\n`./factor -run=examples.greeting` once its directory is in a vocabulary\n[root](https://docs.factorcode.org/content/article-vocabs.roots.html), such as your installation’s `work` directory. Dots organize vocabulary\nnames; importing a parent does not automatically import its children.\n\nSource files need explicit imports. If a word is missing, its documentation\nshows which vocabulary provides it. The listener may offer to import a word\nautomatically; include that vocabulary in [`USING:`](https://docs.factorcode.org/content/word-USING__colon__%2Csyntax.html) when saving the code.\nFor [ambiguous names](https://docs.factorcode.org/content/article-word-search.html),\nuse a vocabulary prefix or select a word with [`FROM:`](https://docs.factorcode.org/content/word-FROM__colon__%2Csyntax.html):\n\n```\nUSING: math prettyprint ;\n2 3 math:+ . ! 5\nFROM: math => + ;\n2 3 + . ! 5\n```\n### Editing and reloading\n\nFactor’s listener runs in a live image containing loaded definitions and\nobjects. You can redefine a word and try it again in the same session.\nFor code saved in a vocabulary, load it once with [`USE:`](https://docs.factorcode.org/content/word-USE__colon__%2Csyntax.html), then\n[reload changes](https://docs.factorcode.org/content/article-vocabs.refresh.html)\nafter editing its source:\n\n```\nUSING: vocabs.loader vocabs.refresh ;\nUSE: examples.greeting\n\"examples.greeting\" reload ! Reload this vocabulary\nrefresh-all ! Reload changed files in loaded vocabularies\n```\nThis assumes you saved `examples.greeting` in a vocabulary root as above.\nThe [scaffold tool](https://docs.factorcode.org/content/article-tools.scaffold.html)\ncan create source, documentation, and test files for a new vocabulary.\n\n### Code as data, macros, and parsing words\n\nWords are objects too. A backslash obtains a word without executing it:\n\n```\nUSING: accessors math prettyprint words ;\n\\ + name>> . ! \"+\"\n```\nQuotations are built out of objects and words.\n[Macros](https://docs.factorcode.org/content/article-macros.html) compute quotations\nthat the compiler expands at call sites:\n\n```\nUSING: kernel macros math prettyprint ;\nIN: scratchpad\nMACRO: add-constant ( n -- quot ) [ + ] curry ;\n5 10 add-constant . ! 15\n```\nHere `10` is the macro input, and the expansion adds it to the runtime\nvalue `5`. Macro inputs must be known at compile time.\n\nSyntax is extensible through [*parsing words*](https://docs.factorcode.org/content/article-parsing-words.html), which execute while source\nis being read. `:`, [`TUPLE:`](https://docs.factorcode.org/content/word-TUPLE__colon__%2Csyntax.html), and literal openers are examples. Libraries\ncan add their own syntax, such as `R/ ... /` for regular expressions.\n\n### Memoization\n\n[`MEMO:`](https://docs.factorcode.org/content/article-memoize.html) defines a word whose results are cached by its inputs:\n\n```\nUSING: kernel math memoize prettyprint ;\nIN: scratchpad\nMEMO: fibonacci ( n -- m )\n dup 1 <= [ ] [\n [ 1 - fibonacci ] [ 2 - fibonacci ] bi +\n ] if ;\n10 fibonacci . ! 55\n```\nThis is useful for pure computations. Cached mutable results are shared objects, so memoization needs care when callers mutate those results.\n\n### Files and formatted output\n\n```\nUSING: formatting io io.encodings.utf8 io.files prettyprint ;\n\"Ada\" 36 \"%s is %d years old.\\n\" printf\n\"Hello, world!\\n\" \"hello.txt\" utf8 set-file-contents\n\"hello.txt\" utf8 file-contents print\n\"hello.txt\" utf8 [\n readln .\n] with-file-reader\n```\nThe [file examples](https://docs.factorcode.org/content/article-io.files.html) create `hello.txt` in the current directory.\n[`formatting`](https://docs.factorcode.org/content/article-formatting.html) provides [`printf`](https://docs.factorcode.org/content/word-printf%2Cformatting.html) for formatted output.\n[`with-file-reader`](https://docs.factorcode.org/content/word-with-file-reader%2Cio.files.html) binds the current input stream and closes it after the\nquotation finishes. [`with-file-writer`](https://docs.factorcode.org/content/word-with-file-writer%2Cio.files.html) does the same for output.\n\n### JSON, regular expressions, and HTTP\n\nThe [`json` vocabulary](https://docs.factorcode.org/content/article-json.html) converts between JSON text and Factor objects:\n\n```\nUSING: assocs json kernel prettyprint ;\n\"{\\\"name\\\":\\\"Ada\\\",\\\"age\\\":36}\" json>\n\"name\" swap at . ! \"Ada\"\nH{ { \"name\" \"Ada\" } } >json . ! \"{\\\"name\\\":\\\"Ada\\\"}\"\n```\n[Regular expressions](https://docs.factorcode.org/content/article-regexp.html) use their own literal syntax:\n\n```\nUSING: prettyprint regexp ;\n\"12345\" R/ [0-9]+/ matches? . ! t\n\"hello\" R/ [0-9]+/ matches? . ! f\n```\nThe [HTTP client](https://docs.factorcode.org/content/article-http.client.html) returns both a response object and the downloaded content:\n\n```\nUSING: http.client kernel ;\n\"https://factorcode.org\" http-get\nnip ! Leave only the content\n```\n### Dates and calendars\n\n[`calendar`](https://docs.factorcode.org/content/article-calendar.html) provides timestamps and durations and computations on them.\n\n```\nUSING: calendar prettyprint ;\nnow . ! Current local timestamp\n10 months duration>minutes ! Lots of minutes\ntoday next-monday ! The next monday after today\n```\n### Random\n\n[`random`](https://docs.factorcode.org/content/article-random.html) selects random numbers or collection elements:\n\n```\nUSING: prettyprint random ;\n10 random . ! Random integer from 0 through 9\n{ \"red\" \"green\" \"blue\" } random . ! Random element\n```\nWe also have various [random distributions](../../2024/07/random-distributions.html) available.\n\n### Threads\n\nFactor [threads](https://docs.factorcode.org/content/article-threads.html) are cooperatively scheduled. [`yield`](https://docs.factorcode.org/content/word-yield%2Cthreads.html) lets another runnable\nthread execute, and blocking I/O integrates with the scheduler:\n\n```\nUSING: kernel math prettyprint threads ;\n42 [ 1 + . ] curry \"worker\" spawn drop\nyield ! Worker prints 43\n```\nThe worker starts with an empty data stack; `curry` explicitly carries the\ninput into its quotation. The `concurrency` vocabularies provide additional\ntools such as mailboxes and promises.\n\n### Calling C\n\nThe [foreign function interface](https://docs.factorcode.org/content/article-alien-invoke.html) declares C functions as Factor words.\nFor example, this binds `strlen` from the C library:\n\n```\nUSING: alien.c-types alien.syntax prettyprint ;\nIN: scratchpad\nLIBRARY: libc\nFUNCTION: size_t strlen ( c-string str )\n\"hello\" strlen . ! 5\n```\nThe [`c-string`](https://docs.factorcode.org/content/word-c-string%2Calien.c-types.html) argument converts a Factor string for the C call. The FFI\nalso supports structures, pointers, callbacks, and arrays. Unlike the\nmanaged objects used above, foreign allocations can require explicit\nlifetime management.\n\n### Testing and exploring\n\n[`tools.test`](https://docs.factorcode.org/content/article-tools.test.html) expresses expected stack results as an array:\n\n```\nUSING: kernel math tools.test ;\n{ 5 } [ 2 3 + ] unit-test\n{ 25 } [ 5 dup * ] unit-test\n[ 1 0 / ] must-fail\n```\nTests for a vocabulary conventionally live alongside its source in a\n`*-tests.factor` file. After saving tests for `examples.greeting`, run them\nwith `\"examples.greeting\" test` in the listener. This also runs tests in\nits child vocabularies.\n\nThe development environment also lets you inspect definitions, look up documentation, and time quotations:\n\n```\nUSING: help kernel math see sequences tools.time ;\n\\ map help ! Open documentation for map\n\\ + describe ! Describe the object ``+``\n\\ square see ! Show the earlier definition\n[ 1000000 [ ] times ] time ! Time a quotation\n```\nThe [Factor handbook](https://docs.factorcode.org/content/article-handbook.html)\nis the next stop for more detail. For a project walkthrough, the\n[first-program tutorial](https://docs.factorcode.org/content/article-first-program.html)\ncovers creating a vocabulary, editing and reloading it, and extending it\nwith tests. The\n[vocabulary index](https://docs.factorcode.org/content/article-vocab-index.html) covers\nthe libraries, and the source distribution includes documentation and tests\nnext to the code. Start with small words, follow their stack effects, and\nuse combinators to make the flow of values clear.\n","body_html":"

Factor Overview

\n

I highly recommend reading the guided tour of Factor.\nIt provides a great introduction to the language and libraries of Factor.\nEven still, I sometimes have also wanted to have more code-forward examples of everyday syntax,\ncontrol flow, combinators, and some of the main libraries. This is that overview. It assumes you have programmed before, but have not necessarily used a\nstack-based language.

\n

Hello, world

\n

The simplest Hello, world is just:

\n
"Hello, world!" print
\n

You can run that from the listener:

\n
IN: scratchpad "Hello, world!" print\nHello, world!
\n

And you can run it from the command-line:

\n
$ ./factor -e="\\"Hello, world!\\" print"\nHello, world!
\n

Of course, you can also make this a file named hello.factor, which\ndefines a hello vocabulary (something you learn about in the\nyour first program tutorial).

\n
USING: io ;\nIN: hello\n: main ( -- )\n    "Hello, world!" print ;\nMAIN: main
\n

The syntax used above includes:

\n
  • USING: imports vocabularies (named collections of words)
  • IN: selects the vocabulary for definitions, and
  • MAIN: sets an entry point.
\n

And then you can run it either as a script:

\n
$ ./factor hello.factor\nHello, world!
\n

Or, if this is available in the vocabulary roots\nsearch path, run the vocabulary’s main word:

\n
$ ./factor -run=hello\nHello, world!
\n

For the rest of this overview, try the examples in the listener, Factor’s\ninteractive REPL.\nStart the terminal listener with ./factor -run=listener,\nor use the graphical listener in the development environment. Each example\nincludes its imports; examples that build on a definition assume you have\nentered that definition too. IN: scratchpad puts experimental definitions\nin the listener’s usual working vocabulary. Feel free to paste the code\ndirectly, to see what it does. Comments beginning with ! are part of\nvalid Factor source.

\n

For a quick start, work through the stack, word definitions, quotations, control flow, and sequences. The later sections introduce objects, metaprogramming, and libraries that you can return to as you need them.

\n

Values and the stack

\n

Literals push values onto the data stack. Words consume inputs from the top\nof that stack and push their outputs. Code runs from left to right:

\n
USING: math prettyprint ;\n2 3 + .                         ! 5\n10 4 - .                        ! 6\n2 3 + 4 * .                     ! 20
\n

. consumes and prints an object. print consumes and prints a string.\nThe comments beside examples show the output. Because printing removes the\nvalue, these examples leave the stack empty unless stated otherwise.\nThere are no parentheses around function arguments: put the arguments on\nthe stack, then invoke the word. Below, the top of the stack is on the right:

\n
Code       Stack\n2          2\n3          2 3\n+          5\n4          5 4\n*          20\n.          (empty)
\n

Spaces matter. 2 3 + is three tokens; 2+3 is a single token, which would\nneed to be the name of a word. Names like number>string, empty?, and\nset-at are ordinary word names. A trailing ? conventionally marks a\npredicate; > often appears in conversion names. Those characters are part\nof the name, not separate operators. A trailing ! often marks a mutating\nvariant, such as append!; * usually marks an alternative form. There are some\nconventions useful\nfor learning word and type naming.

\n

Comments and literals

\n
USING: math multiline prettyprint ;\n! A comment runs to the end of the line.\n/* A block comment can span\n   several lines. */\n42 .                            ! Integer\n-17 .                           ! Negative integer\n0xff .                          ! 255, hexadecimal\n0b1010 .                        ! 10, binary\n3/4 .                           ! Exact rational\n1.25 .                          ! Floating point\nC{ 2 3 } .                      ! Complex number: 2 + 3i\nt .                             ! True\nf .                             ! False\n"hello\\nworld" .                ! String with an escape\nCHAR: A .                       ! 65, a character code point\n{ 1 2 3 } .                     ! Array\nV{ 1 2 3 } .                    ! Growable vector\nB{ 0 127 255 } .                ! Byte array\nH{ { "name" "Ada" } } .         ! Hashtable\n[ 1 + ] .                       ! Quotation: code as a value
\n

Arrays and quotations contain objects without executing them. Collection\nliterals are useful for fixed data; when mutating one inside a word, use\nclone to obtain a fresh copy rather than changing a shared literal.\nThis is a shallow copy: objects inside the collection are still shared.

\n

Block comments come from the multiline vocabulary.

\n

CHAR: produces an integer code point; Factor has no separate character\ntype. { ... } is an array, while [ ... ] is executable code held as a\nvalue called a quotation.\nSpaces separate the literal openers, their contents, and the closing\ndelimiters, as in { 1 2 3 } and [ 1 + ].

\n

Strings and escape characters

\n

String literals use double quotes. A backslash introduces a\ncharacter escape:

\n
EscapeMeaning
\\"Double quote
\\\\Backslash
\\aBell (code point 7)
\\bBackspace (8)
\\eEscape (27)
\\fForm feed (12)
\\nNewline (10)
\\rCarriage return (13)
\\sSpace (32)
\\tTab (9)
\\vVertical tab (11)
\\0Null (0)
\\oooCode point given by one to three octal digits
\\xHHCode point given by exactly two hexadecimal digits
\\uHHHHHHCode point given by exactly six hexadecimal digits
\\u{H...}Code point given by hexadecimal digits inside braces
\\u{name}Named Unicode character, with Unicode support loaded
\n

For example:

\n
USING: io prettyprint sequences unicode ;\n"She said \\"hello\\"." print        ! She said "hello".\n"C:\\\\Users\\\\Ada" print             ! C:\\Users\\Ada\n"\\x41\\u000042\\u{43}" print         ! ABC\n"\\u{greek-small-letter-pi}" print  ! π\n"first\\nsecond" print              ! Prints two lines\n"\\t" length .                      ! 1: the escape represents one character\n"hello" length .                   ! 5\n"hello" >upper .                   ! "HELLO"\n"a,b,c" "," split .                ! { "a" "b" "c" }\n{ "a" "b" "c" } ", " join .        ! "a, b, c"\n"42" string>number .               ! 42\n42 number>string .                 ! "42"\n"oops" string>number .             ! f
\n

The six-digit \\u form differs from languages that use four digits; the\nbraced form is often easier to read. Unknown escapes are errors. Strings\ncan also span source lines directly: an actual newline becomes part of the\nstring. A backslash immediately before a source newline continues the\nstring without including that newline. A backslash followed by a literal\nspace also represents a space, like \\s.

\n

*Note: the length of a string\nis the number of code points, not the number of visible glyphs. You can learn a bit more\nby reading about Factor’s Unicode support.*

\n

Stack shuffling

\n

Typical of concatenative languages,\nthe stack is a data structure with it’s own access patterns that we often call\nstack shuffling.

\n
USING: kernel prettyprint ;\n10 dup . .                      ! Prints 10, then 10\n10 20 swap . .                  ! Prints 10, then 20\n10 20 over . . .                ! Prints 10, then 20, then 10\n10 20 nip .                     ! 20: discard the second item\n10 20 drop .                    ! 10: discard the top item
\n

The usual stack shuffling words have these effects:

\n
! dup   ( x -- x x )\n! drop  ( x -- )\n! swap  ( x y -- y x )\n! over  ( x y -- x y x )\n! nip   ( x y -- y )\n! rot   ( x y z -- y z x )
\n

Most Factor code uses short definitions and combinators to keep explicit shuffling to a minimum.

\n

In a stack effect, inputs and outputs run from left to right, with the\ntopmost value last. swap therefore changes a stack ending in x y into\none ending in y x; values below those inputs are untouched. Repeated\n. calls print the topmost result first.

\n

Defining words

\n

You can create words that\ncontain code that is executed when called:

\n
USING: kernel math prettyprint ;\nIN: scratchpad\n: square ( n -- n-squared ) dup * ;\n: neighbors ( n -- below above )\n    dup 1 - swap 1 + ;\n5 square .                      ! 25\n5 neighbors . .                 ! Prints 6, then 4\nCONSTANT: answer 42\nanswer .                        ! 42
\n

: begins a definition and ; ends it. The stack effect ( inputs -- outputs ) documents how many values the word consumes and produces. Its\nnames describe the values; they do not bind variables or specify types.\nThe compiler checks stack effects, including compatible effects for branches.\nWords can return several values simply by leaving them on the stack.\nThere is no explicit return: execution finishes at the end of the word.

\n

ALIAS: new-name existing-word defines another name for a word.

\n

Arithmetic and comparisons

\n

Lots of arithmetic is\navailable for computing with numbers:

\n
USING: kernel math math.functions math.order prettyprint ;\n7 2 / .                         ! 3+1/2, an exact rational\n7 2 /i .                        ! 3, integer division\n7 2 mod .                       ! 1\n2 10 ^ .                        ! 1024\n9 sqrt .                        ! 3.0\n-5 abs .                        ! 5\n3 8 min .                       ! 3\n3 8 max .                       ! 8\n2 3 < .                         ! t\n2 3 >= .                        ! f\n"hello" "hello" = .             ! t, value equality
\n

Integers grow beyond machine size automatically, and division of integers\ncan produce exact ratios. Use floating-point inputs when you want\nfloating-point arithmetic.

\n

Bitwise operations have their own names, separate from boolean logic:

\n
USING: math prettyprint ;\n0b1100 0b1010 bitand .          ! 8\n0b1100 0b1010 bitor .           ! 14\n0b1100 0b1010 bitxor .          ! 6\n1 3 shift .                     ! 8: shift left\n8 -1 shift .                    ! 4: shift right
\n

Quotations

\n

Square brackets produce a quotation. call executes it:

\n
USING: kernel math prettyprint sequences ;\n5 [ 1 + ] call .                ! 6\n{ 1 2 3 } [ 2 * ] map .         ! { 2 4 6 }
\n

Quotations can be passed to words, returned from words, and stored in\ncollections. Words that take quotations are called\ncombinators.

\n

Booleans and conditionals

\n

In boolean tests, only f is false. Zero, an empty string, and an empty array are all true.

\n
USING: kernel math prettyprint ;\nt f and .                        ! f\nt f or .                         ! t\nf not .                          ! t\n3 2 > [ "yes" ] [ "no" ] if .    ! "yes"\n0 [ "truthy" ] [ "false" ] if .  ! "truthy"\nt [ "runs" . ] when\nf [ "runs too" . ] unless
\n

if consumes a condition and two quotations. It calls the first quotation\nfor a true condition and the second for f. when and unless take one\nquotation. These are words that operate on code values, just like +\noperates on numbers.

\n

For several alternatives, use cond or case:

\n
USING: combinators kernel math prettyprint ;\nIN: scratchpad\n: sign-name ( n -- string )\n    {\n        { [ dup 0 < ] [ drop "negative" ] }\n        { [ dup 0 = ] [ drop "zero" ] }\n        [ drop "positive" ]\n    } cond ;\n-3 sign-name .                  ! "negative"\n: color-name ( color -- string )\n    {\n        { "r" [ "red" ] }\n        { "g" [ "green" ] }\n        [ drop "unknown" ]\n    } case ;\n"g" color-name .                ! "green"
\n

cond tries predicate quotations in order. case compares an input with\neach key; a matching branch consumes the key automatically, while the\ndefault branch receives the unmatched input.

\n

and and or combine values that have already been computed. For\nshort-circuit evaluation, pass predicate quotations instead:

\n
USING: combinators.short-circuit kernel math prettyprint ;\n5 { [ 0 > ] [ 10 < ] } 1&& .    ! t: positive and less than ten\n-5 { [ 0 < ] [ 10 > ] } 1|| .   ! t: negative or greater than ten
\n

Each predicate receives the same input. 1&& stops at the first false\nresult; 1|| stops at the first true result. The leading number is the\nnumber of inputs passed to each predicate.

\n

Keeping and hiding values

\n

The dip word temporarily hides a value while a quotation works on the stack below\nit. keep gives a quotation a value and also preserves that value:

\n
USING: kernel math prettyprint ;\n10 20 [ 1 + ] dip + .           ! 31: increment 10, then restore 20\n5 [ 1 + ] keep . .              ! Prints 5, then 6
\n
! dip   ( ..a x quot -- ..b x )\n! keep  ( ..a x quot -- ..b x )
\n

The overall shapes look alike, but dip hides x from the quotation and\nkeep passes it in. 2dip hides two values; 2keep preserves two inputs.

\n

Applying several quotations

\n

The bi family covers several common ways to distribute inputs:

\n
USING: kernel math prettyprint ;\n! Apply two quotations to the same input.\n5 [ 1 + ] [ 2 * ] bi . .        ! Prints 10, then 6\n! Apply one quotation to each of two inputs.\n3 4 [ 2 * ] bi@ . .             ! Prints 8, then 6\n! Apply separate quotations to separate inputs.\n3 4 [ 1 + ] [ 2 * ] bi* . .     ! Prints 8, then 4\n! Apply two quotations to the same pair of inputs.\n3 4 [ + ] [ * ] 2bi . .         ! Prints 12, then 7
\n

For example, 2bi lets a word calculate two results from the same inputs:

\n
USING: kernel math prettyprint ;\nIN: scratchpad\n: sum-and-product ( a b -- sum product )\n    [ + ] [ * ] 2bi ;\n3 4 sum-and-product . .         ! Prints 12, then 7
\n

Then tri, tri@, and tri* extend these patterns to three quotations or\ninputs.

\n

You can find cleave, napply and spread as the generalizations\nof those patterns.

\n

Partial application and composition

\n

The curry word binds a value to the beginning of a quotation.\ncompose joins two\nquotations so that one runs after the other:

\n
USING: kernel math prettyprint sequences ;\n{ 1 2 3 } 10 [ + ] curry map .    ! { 11 12 13 }\n5 [ 1 + ] [ 2 * ] compose call .  ! 12
\n

10 [ + ] curry behaves like [ 10 + ]. This is a convenient way to build\na quotation using a value computed at runtime.

\n

The fry vocabulary provides quotation templates. _ inserts a value;\n@ inserts a call to a supplied quotation:

\n
USING: fry kernel math prettyprint sequences ;\n{ 1 2 3 } 10 '[ _ + ] map .     ! { 11 12 13 }\n5 [ 1 + ] '[ @ 2 * ] call .     ! 12
\n

The apostrophe in '[ ... ] makes this a template rather than an ordinary\nquotation. Its placeholders consume their values when the template is\nconstructed, not when the resulting quotation is called.

\n

Defining combinators

\n

A combinator can be an ordinary word with quotation inputs. Give those\ninputs their own stack effects and declare the word inline so the\ncompiler can infer the effects at its call sites:

\n
USING: kernel math prettyprint ;\nIN: scratchpad\n: twice ( ... quot: ( ... -- ... ) -- ... )\n    dup [ call ] dip call ; inline\n3 [ 2 * ] twice .               ! 12
\n

The ... represents values carried through the combinator. Here, the\nsupplied quotation must preserve stack height, and twice calls it twice.

\n

Loops and recursion

\n
USING: kernel math prettyprint sequences ;\n3 [ "hello" . ] times           ! Print three times\n{ "Ada" "Grace" } [ . ] each    ! Visit each element\n5 <iota> [ . ] each             ! Print 0 through 4\n0 [ dup 3 < ] [ dup . 1 + ] while drop\n! Print 0, 1, 2; keep the counter on the stack
\n

The looping combinator while calls its predicate before each iteration. The predicate leaves\na condition; the body updates the loop’s values. until reverses the\ncondition. Often each, map, or reduce expresses the loop directly.

\n

Recursion uses an ordinary call to the word being defined:

\n
USING: kernel math prettyprint ;\nIN: scratchpad\n: factorial ( n -- n! )\n    dup 1 <=\n    [ drop 1 ]\n    [ dup 1 - factorial * ] if ;\n5 factorial .                   ! 120
\n

Definitions are read in order: define helper words before words that use\nthem. DEFER:\ndeclares a word before its implementation, allowing mutual recursion:

\n
USING: kernel math prettyprint ;\nIN: scratchpad\nDEFER: odd-count?\n: even-count? ( n -- ? )\n    dup 0 = [ drop t ] [ 1 - odd-count? ] if ;\n: odd-count? ( n -- ? )\n    dup 0 = [ drop f ] [ 1 - even-count? ] if ;\n6 even-count? .                 ! t\n7 odd-count? .                  ! t
\n

These examples accept nonnegative integers. Factor guarantees\ntail-call optimization,\nso a final call such as the one to odd-count? can continue without growing\nthe call stack.

\n

Local variables and closures

\n

When names make an algorithm easier to read, import\nlocals and define\na word with ::. Inputs become lexical variables:

\n
USING: kernel locals math prettyprint sequences ;\nIN: scratchpad\n:: rectangle-area ( width height -- area )\n    width height * ;\n:: add-offset ( seq offset -- newseq )\n    seq [| n | n offset + ] map ;\n3 4 rectangle-area .            ! 12\n{ 1 2 3 } 10 add-offset .       ! { 11 12 13 }\n:: hypotenuse-squared ( a b -- n )\n    a a * :> a-squared\n    b b * :> b-squared\n    a-squared b-squared + ;
\n

:> binds a computed value. \\[| n | ... \\] names quotation inputs and can\ncapture enclosing variables, as offset does above. Output names in ::\nstill describe stack results; there is no implicit return variable.

\n

Mutable locals have an exclamation point in their declaration and an\nassociated setter:

\n
USING: kernel locals math prettyprint ;\n[let\n    0 :> total!\n    5 [ total 1 + total! ] times\n    total .                     ! 5\n]
\n

\\[let ... \\] establishes a lexical scope, including in the listener.

\n

Sequences

\n

Arrays, vectors, strings, and several other types share the sequence\nprotocol. Most sequence words work across these types:

\n
USING: kernel math prettyprint sequences sorting ;\n{ 10 20 30 } length .               ! 3\n{ 10 20 30 } first .                ! 10\n1 { 10 20 30 } nth .                ! 20, zero-based indexing\n{ 1 2 } { 3 4 } append .            ! { 1 2 3 4 }\n{ 1 2 3 } reverse .                 ! { 3 2 1 }\n{ 1 2 3 4 } [ dup * ] map .         ! { 1 4 9 16 }\n{ 1 2 3 4 } [ 2 mod 0 = ] filter .  ! { 2 4 }\n{ 1 2 3 4 } 0 [ + ] reduce .        ! 10\n{ 1 2 3 } [ 0 > ] all? .            ! t\n{ 1 2 3 } [ 2 = ] any? .            ! t\n{ 3 1 2 } natural-sort .            ! { 1 2 3 }\nV{ 1 2 } clone\n3 over push .                       ! V{ 1 2 3 }
\n

The sequence combinator map collects quotation results; each is for side effects. reduce\nthreads an accumulator through the sequence. push mutates a growable\nsequence and consumes both the new element and the sequence.

\n

For incremental construction, make\ncollects values produced inside a quotation. , adds one element and %\nadds the elements of a sequence:

\n
USING: make prettyprint ;\n[ 1 , { 2 3 } % 4 , ] { } make .            ! { 1 2 3 4 }\n[ "Hello" % CHAR: \\s , "Ada" % ] "" make .  ! "Hello Ada"
\n

The final exemplar ({ } or "") chooses the result type. Prefer map,\nfilter, or append when one of those directly expresses the operation.

\n

Specialized arrays\nstore elements as C numeric types in contiguous memory while supporting\nthe sequence protocol:

\n
USING: alien.c-types prettyprint sequences specialized-arrays ;\nSPECIALIZED-ARRAY: double\ndouble-array{ 1.0 2.0 3.0 } length .  ! 3
\n

Hashtables and sets

\n

Associative collections use the assocs protocol:

\n
USING: assocs kernel prettyprint ;\n"Ada" H{ { "Ada" 36 } { "Grace" 85 } } at .  ! 36\n"missing" H{ { "Ada" 36 } } at .             ! f\n"enabled" H{ { "enabled" f } } at* . .       ! Prints t, then f\nH{ { "Ada" 36 } } clone\n37 "Ada" pick set-at\n"Ada" swap at .                              ! 37
\n

at* returns a presence flag as well as a value, distinguishing a missing\nkey from a key whose value is f. set-at takes a value, key, and assoc.

\n

Sets also have a protocol, with useful operations on ordinary sequences:

\n
USING: prettyprint sets ;\n{ 1 2 2 3 } members .           ! { 1 2 3 }\n2 { 1 2 3 } in? .               ! t\n{ 1 2 } { 2 3 } union .         ! { 1 2 3 }\n{ 1 2 } { 2 3 } intersect .     ! { 2 }\n{ 1 2 } { 2 3 } diff .          ! { 1 }
\n

For repeated membership checks, use a hash set rather than scanning a sequence:

\n
USING: hash-sets prettyprint sets ;\n2 HS{ 1 2 3 } in? .             ! t
\n

Tuples and accessors

\n

Tuples define classes with named slots. boa constructs a tuple from\nslot values in declaration order:

\n
USING: accessors kernel prettyprint ;\nIN: scratchpad\nTUPLE: person name age ;\nC: <person> person\n"Ada" 36 <person>\ndup name>> .                    ! "Ada"\n37 >>age\nage>> .                         ! 37
\n

C: defines a constructor using boa. name>> reads a slot; >>age\nwrites a slot and returns the tuple, allowing chained updates. You can also\nconstruct an instance with person new and set its slots explicitly.\nNames such as <person> conventionally denote constructors; the angle\nbrackets are part of the word’s name.

\n

Tuple literals use T{ ... }. Slots can also declare a class, an initial\nvalue, or the read-only attribute:

\n
USING: accessors kernel math prettyprint ;\nIN: scratchpad\nT{ person { name "Grace" } { age 85 } } name>> .  ! "Grace"\nTUPLE: counter { value integer initial: 0 } ;\ncounter new\n[ 1 + ] change-value\nvalue>> .                                         ! 1
\n

Slot declarations\nconstrain stored values. { name string read-only }, for example, declares\na string slot that is initialized at construction and has no generated\nsetter. change-value applies a quotation to the current slot value,\nstores the result, and returns the tuple.

\n

Structs and C layouts

\n

STRUCT:\ndefines a record backed by a C memory layout. Every field declares a C\ntype, and the usual slot accessors work on struct instances:

\n
USING: accessors alien.c-types classes.struct kernel prettyprint ;\nIN: scratchpad\nSTRUCT: c-point\n    { x double }\n    { y double } ;\n3.0 4.0 c-point boa\ndup x>> .                       ! 3.0\ny>> .                           ! 4.0\nPACKED-STRUCT: packet-header\n    { kind uint8_t }\n    { length uint32_t } ;\npacket-header heap-size .       ! 5
\n

boa initializes fields from stack values; c-point <struct> creates an\ninstance with its declared initial field values. These constructors use\ngarbage-collected storage. STRUCT: includes alignment padding according\nto the platform’s C layout rules. PACKED-STRUCT: removes padding between\nfields and at the end, for layouts that explicitly require packed storage.\nIt does not choose byte order.

\n

UNION-STRUCT: defines overlapping C fields that share the same storage.\nIt serves a different purpose from UNION:, which groups Factor classes.\nUse tuples for ordinary Factor records and structs when you need C-compatible\nmemory or an explicitly specified binary layout.

\n

Generic words and classes

\n

A generic word chooses a method based on the class of its topmost input.\nThis example reuses person and <person> from “Tuples and accessors”:

\n
USING: accessors kernel math math.parser prettyprint ;\nIN: scratchpad\nGENERIC: description ( obj -- string )\nM: person description name>> ;\nM: integer description number>string ;\n"Ada" 36 <person> description .  ! "Ada"\n42 description .                 ! "42"
\n

A tuple subclass\ninherits its parent’s slots and can add its own. An overriding method can\nreuse the next less-specific method with\ncall-next-method:

\n
USING: accessors kernel prettyprint sequences ;\nIN: scratchpad\nTUPLE: employee < person role ;\nC: <employee> employee\nM: employee description\n    [ call-next-method ] [ role>> ] bi " - " glue ;\n"Ada" 36 "programmer" <employee> description .\n! "Ada - programmer"
\n

The constructor takes inherited slots first (name, age), then role.\nHere call-next-method receives the employee, calls the person method,\nand returns "Ada"; the override combines that with the employee’s role.\nIt must appear inside a method definition and receives its inputs from the\nstack, just like an ordinary call.

\n

M: defines a method. This is how protocols such as sequences and assocs\nprovide common operations for many concrete types. Classes also have\npredicate words, and you can define narrower predicate classes or unions:

\n
USING: kernel math prettyprint strings ;\nIN: scratchpad\nPREDICATE: positive-integer < integer 0 > ;\nUNION: text-or-integer string integer ;\n3 positive-integer? .           ! t\n-3 positive-integer? .          ! f\n"hello" text-or-integer? .      ! t
\n

Mixin classes\nare open groups of classes: INSTANCE: adds a member, including after the\nmixin was defined. They are useful for protocols spanning unrelated types:

\n
USING: prettyprint ;\nIN: scratchpad\nMIXIN: named\nINSTANCE: person named\n"Ada" 36 <person> named? .      ! t
\n

Singleton classes\neach have one stateless instance, useful as distinct states or options.\nUnlike a plain symbol, each can have its own generic methods:

\n
USING: prettyprint ;\nIN: scratchpad\nSINGLETONS: pending running finished ;\nUNION: job-state pending running finished ;\npending job-state? .            ! t
\n

UNION: accepts instances of any listed class. INTERSECTION: requires\nmembership in all listed classes. For named numeric values,\nENUMERATION:\nis available in classes.enumeration:

\n
USING: classes.enumeration prettyprint ;\nIN: scratchpad\nENUMERATION: priority low medium high ;\npriority.low .                  ! 0\npriority.high .                 ! 2
\n

Symbols and dynamic variables

\n

Lexical locals are scoped by source structure. namespaces provides\nvariables scoped dynamically around a quotation:

\n
USING: namespaces prettyprint ;\nIN: scratchpad\nSYMBOL: current-user\n"Ada" current-user [\n    current-user get .          ! "Ada"\n] with-variable
\n

Called words inside the quotation see the binding too. with-variable\nrestores the previous binding on exit. set changes a binding in the\ncurrent namespace; set-global sets a global binding. A symbol is itself\na value, so symbols also work as distinct markers and hashtable keys.

\n

Errors and cleanup

\n
USING: continuations kernel prettyprint ;\nIN: scratchpad\nERROR: invalid-age age ;\n[ -1 invalid-age ] [ drop "handled" ] recover .  ! "handled"\n[ "work" . ] [ "cleanup" . ] finally\n! Prints "work", then "cleanup"
\n

The exception handling form ERROR: defines an error class and a word that throws an instance.\nrecover calls a handler with the thrown object. The data stack is restored\nto its state before the protected quotation, then the error is pushed.\nfinally runs cleanup on either normal completion or an error.

\n

Factor also exposes continuations,\nwhich capture execution state and can later resume it. They underpin error\nhandling and cooperative threads; most everyday code uses those higher-level\nfacilities directly.

\n

Resource disposal

\n

Ordinary objects are garbage collected. Resources such as open streams\nalso need deterministic disposal.\ndispose releases a resource explicitly. with-disposal passes a resource\nto a quotation and disposes it when the quotation finishes or throws:

\n
USING: destructors io io.encodings.utf8 io.files prettyprint ;\n"Hello!\\n" "disposal.txt" utf8 set-file-contents\n"disposal.txt" utf8 <file-reader>\n[ stream-readln . ] with-disposal  ! "Hello!"
\n

This example creates disposal.txt in the current directory. The reader\nis closed after reading the line. For several resources, use\nwith-destructors\nand register each one for cleanup:

\n
USING: destructors io io.encodings.utf8 io.files prettyprint ;\n[\n    "disposal.txt" utf8 <file-reader> &dispose\n    stream-readln .             ! "Hello!"\n] with-destructors
\n

Both registration words leave the resource on the stack so you can use it:

\n
WordWhen the resource is disposed
&disposeWhen the enclosing with-destructors scope finishes, on success or error
|disposeWhen the enclosing with-destructors scope exits with an error
\n

&dispose is for resources used within a scope. |dispose is useful when\nbuilding a result that owns resources: if construction fails, clean up;\nif it succeeds, return the resources to the caller. For example:

\n
USING: destructors io.encodings.utf8 io.files kernel ;\nIN: scratchpad\n: open-two-readers ( path1 path2 -- reader1 reader2 )\n    [ [ utf8 <file-reader> |dispose ] bi@ ] with-destructors ;\n"disposal.txt" "disposal.txt" open-two-readers\n[ dispose ] bi@                 ! Caller closes both readers
\n

If opening the second reader throws, the first reader is disposed. On\nsuccess, both readers remain open and the caller owns their cleanup.\nWithin each registration group, destructors run in reverse registration\norder. The with-file-reader and with-file-writer combinators shown below\nmanage stream cleanup automatically.

\n

Vocabularies

\n

A vocabulary is a namespace and a unit of source organization. A vocabulary\nnamed examples.greeting conventionally lives in\nexamples/greeting/greeting.factor under a vocabulary root:

\n
USING: io ;\nIN: examples.greeting\n<PRIVATE\n: greeting ( -- string ) "Hello, world!" ;\nPRIVATE>\n: greet ( -- ) greeting print ;\nMAIN: greet
\n

<PRIVATE ... PRIVATE> places helper definitions in the vocabulary’s\nprivate namespace. Import public definitions with USE: examples.greeting\nor include it in a USING: list. Run the entry point with\n./factor -run=examples.greeting once its directory is in a vocabulary\nroot, such as your installation’s work directory. Dots organize vocabulary\nnames; importing a parent does not automatically import its children.

\n

Source files need explicit imports. If a word is missing, its documentation\nshows which vocabulary provides it. The listener may offer to import a word\nautomatically; include that vocabulary in USING: when saving the code.\nFor ambiguous names,\nuse a vocabulary prefix or select a word with FROM::

\n
USING: math prettyprint ;\n2 3 math:+ .                    ! 5\nFROM: math => + ;\n2 3 + .                         ! 5
\n

Editing and reloading

\n

Factor’s listener runs in a live image containing loaded definitions and\nobjects. You can redefine a word and try it again in the same session.\nFor code saved in a vocabulary, load it once with USE:, then\nreload changes\nafter editing its source:

\n
USING: vocabs.loader vocabs.refresh ;\nUSE: examples.greeting\n"examples.greeting" reload      ! Reload this vocabulary\nrefresh-all                     ! Reload changed files in loaded vocabularies
\n

This assumes you saved examples.greeting in a vocabulary root as above.\nThe scaffold tool\ncan create source, documentation, and test files for a new vocabulary.

\n

Code as data, macros, and parsing words

\n

Words are objects too. A backslash obtains a word without executing it:

\n
USING: accessors math prettyprint words ;\n\\ + name>> .                    ! "+"
\n

Quotations are built out of objects and words.\nMacros compute quotations\nthat the compiler expands at call sites:

\n
USING: kernel macros math prettyprint ;\nIN: scratchpad\nMACRO: add-constant ( n -- quot ) [ + ] curry ;\n5 10 add-constant .             ! 15
\n

Here 10 is the macro input, and the expansion adds it to the runtime\nvalue 5. Macro inputs must be known at compile time.

\n

Syntax is extensible through parsing words, which execute while source\nis being read. :, TUPLE:, and literal openers are examples. Libraries\ncan add their own syntax, such as R/ ... / for regular expressions.

\n

Memoization

\n

MEMO: defines a word whose results are cached by its inputs:

\n
USING: kernel math memoize prettyprint ;\nIN: scratchpad\nMEMO: fibonacci ( n -- m )\n    dup 1 <= [ ] [\n        [ 1 - fibonacci ] [ 2 - fibonacci ] bi +\n    ] if ;\n10 fibonacci .                  ! 55
\n

This is useful for pure computations. Cached mutable results are shared objects, so memoization needs care when callers mutate those results.

\n

Files and formatted output

\n
USING: formatting io io.encodings.utf8 io.files prettyprint ;\n"Ada" 36 "%s is %d years old.\\n" printf\n"Hello, world!\\n" "hello.txt" utf8 set-file-contents\n"hello.txt" utf8 file-contents print\n"hello.txt" utf8 [\n    readln .\n] with-file-reader
\n

The file examples create hello.txt in the current directory.\nformatting provides printf for formatted output.\nwith-file-reader binds the current input stream and closes it after the\nquotation finishes. with-file-writer does the same for output.

\n

JSON, regular expressions, and HTTP

\n

The json vocabulary converts between JSON text and Factor objects:

\n
USING: assocs json kernel prettyprint ;\n"{\\"name\\":\\"Ada\\",\\"age\\":36}" json>\n"name" swap at .                ! "Ada"\nH{ { "name" "Ada" } } >json .   ! "{\\"name\\":\\"Ada\\"}"
\n

Regular expressions use their own literal syntax:

\n
USING: prettyprint regexp ;\n"12345" R/ [0-9]+/ matches? .   ! t\n"hello" R/ [0-9]+/ matches? .   ! f
\n

The HTTP client returns both a response object and the downloaded content:

\n
USING: http.client kernel ;\n"https://factorcode.org" http-get\nnip                             ! Leave only the content
\n

Dates and calendars

\n

calendar provides timestamps and durations and computations on them.

\n
USING: calendar prettyprint ;\nnow .                              ! Current local timestamp\n10 months duration>minutes         ! Lots of minutes\ntoday next-monday                  ! The next monday after today
\n

Random

\n

random selects random numbers or collection elements:

\n
USING: prettyprint random ;\n10 random .                        ! Random integer from 0 through 9\n{ "red" "green" "blue" } random .  ! Random element
\n

We also have various random distributions available.

\n

Threads

\n

Factor threads are cooperatively scheduled. yield lets another runnable\nthread execute, and blocking I/O integrates with the scheduler:

\n
USING: kernel math prettyprint threads ;\n42 [ 1 + . ] curry "worker" spawn drop\nyield                           ! Worker prints 43
\n

The worker starts with an empty data stack; curry explicitly carries the\ninput into its quotation. The concurrency vocabularies provide additional\ntools such as mailboxes and promises.

\n

Calling C

\n

The foreign function interface declares C functions as Factor words.\nFor example, this binds strlen from the C library:

\n
USING: alien.c-types alien.syntax prettyprint ;\nIN: scratchpad\nLIBRARY: libc\nFUNCTION: size_t strlen ( c-string str )\n"hello" strlen .                ! 5
\n

The c-string argument converts a Factor string for the C call. The FFI\nalso supports structures, pointers, callbacks, and arrays. Unlike the\nmanaged objects used above, foreign allocations can require explicit\nlifetime management.

\n

Testing and exploring

\n

tools.test expresses expected stack results as an array:

\n
USING: kernel math tools.test ;\n{ 5 } [ 2 3 + ] unit-test\n{ 25 } [ 5 dup * ] unit-test\n[ 1 0 / ] must-fail
\n

Tests for a vocabulary conventionally live alongside its source in a\n*-tests.factor file. After saving tests for examples.greeting, run them\nwith "examples.greeting" test in the listener. This also runs tests in\nits child vocabularies.

\n

The development environment also lets you inspect definitions, look up documentation, and time quotations:

\n
USING: help kernel math see sequences tools.time ;\n\\ map help                      ! Open documentation for map\n\\ + describe                    ! Describe the object ``+``\n\\ square see                    ! Show the earlier definition\n[ 1000000 [ ] times ] time      ! Time a quotation
\n

The Factor handbook\nis the next stop for more detail. For a project walkthrough, the\nfirst-program tutorial\ncovers creating a vocabulary, editing and reloading it, and extending it\nwith tests. The\nvocabulary index covers\nthe libraries, and the source distribution includes documentation and tests\nnext to the code. Start with small words, follow their stack effects, and\nuse combinators to make the flow of values clear.

","headings":[{"level":1,"text":"Factor Overview","id":"factor-overview"},{"level":3,"text":"Hello, world","id":"hello-world"},{"level":3,"text":"Values and the stack","id":"values-and-the-stack"},{"level":3,"text":"Comments and literals","id":"comments-and-literals"},{"level":3,"text":"Strings and escape characters","id":"strings-and-escape-characters"},{"level":3,"text":"Stack shuffling","id":"stack-shuffling"},{"level":3,"text":"Defining words","id":"defining-words"},{"level":3,"text":"Arithmetic and comparisons","id":"arithmetic-and-comparisons"},{"level":3,"text":"Quotations","id":"quotations"},{"level":3,"text":"Booleans and conditionals","id":"booleans-and-conditionals"},{"level":3,"text":"Keeping and hiding values","id":"keeping-and-hiding-values"},{"level":3,"text":"Applying several quotations","id":"applying-several-quotations"},{"level":3,"text":"Partial application and composition","id":"partial-application-and-composition"},{"level":3,"text":"Defining combinators","id":"defining-combinators"},{"level":3,"text":"Loops and recursion","id":"loops-and-recursion"},{"level":3,"text":"Local variables and closures","id":"local-variables-and-closures"},{"level":3,"text":"Sequences","id":"sequences"},{"level":3,"text":"Hashtables and sets","id":"hashtables-and-sets"},{"level":3,"text":"Tuples and accessors","id":"tuples-and-accessors"},{"level":3,"text":"Structs and C layouts","id":"structs-and-c-layouts"},{"level":3,"text":"Generic words and classes","id":"generic-words-and-classes"},{"level":3,"text":"Symbols and dynamic variables","id":"symbols-and-dynamic-variables"},{"level":3,"text":"Errors and cleanup","id":"errors-and-cleanup"},{"level":3,"text":"Resource disposal","id":"resource-disposal"},{"level":3,"text":"Vocabularies","id":"vocabularies"},{"level":3,"text":"Editing and reloading","id":"editing-and-reloading"},{"level":3,"text":"Code as data, macros, and parsing words","id":"code-as-data-macros-and-parsing-words"},{"level":3,"text":"Memoization","id":"memoization"},{"level":3,"text":"Files and formatted output","id":"files-and-formatted-output"},{"level":3,"text":"JSON, regular expressions, and HTTP","id":"json-regular-expressions-and-http"},{"level":3,"text":"Dates and calendars","id":"dates-and-calendars"},{"level":3,"text":"Random","id":"random"},{"level":3,"text":"Threads","id":"threads"},{"level":3,"text":"Calling C","id":"calling-c"},{"level":3,"text":"Testing and exploring","id":"testing-and-exploring"}]}}