From: Doug Coleman <doug.coleman@gmail.com>
Date: Sun, 23 Jan 2022 05:12:33 +0000 (-0600)
Subject: syntax: Add some more docs for syntax words.
X-Git-Tag: 0.99~1698
X-Git-Url: https://gitweb.factorcode.org/gitweb.cgi?p=factor.git;a=commitdiff_plain;h=1249d293d069b3ced06b48f836931984a49d0412

syntax: Add some more docs for syntax words.
---

diff --git a/core/syntax/syntax-docs.factor b/core/syntax/syntax-docs.factor
index a73d80f362..bbca72ea4f 100644
--- a/core/syntax/syntax-docs.factor
+++ b/core/syntax/syntax-docs.factor
@@ -1,7 +1,8 @@
-USING: arrays assocs classes.algebra.private classes.tuple combinators
-command-line effects generic generic.math generic.single help.markup
-help.syntax io.pathnames kernel math parser sequences vocabs.loader
-vocabs.parser words words.alias words.constant words.symbol ;
+USING: arrays assocs classes.algebra.private classes.maybe
+classes.tuple combinators command-line effects generic
+generic.math generic.single help.markup help.syntax io.pathnames
+kernel math parser sequences vocabs.loader vocabs.parser words
+words.alias words.constant words.symbol ;
 IN: syntax
 
 ARTICLE: "parser-algorithm" "Parser algorithm"
@@ -219,11 +220,12 @@ ARTICLE: "syntax-vectors" "Vector syntax"
 
 ARTICLE: "syntax-hashtables" "Hashtable syntax"
 { $subsections POSTPONE: H{ }
-"Hashtables are documented in " { $link "hashtables" } "." ;
+{ $subsections POSTPONE: IH{ }
+"Hashtables are documented in " { $link "hashtables" } " and " { $vocab-link "hashtables.identity" } "." ;
 
 ARTICLE: "syntax-hash-sets" "Hash set syntax"
 { $subsections POSTPONE: HS{ }
-"Hashtables are documented in " { $link "hash-sets" } "." ;
+"Hash sets are documented in " { $link "hash-sets" } " and " { $vocab-link "hash-sets.identity" } "." ;
 
 ARTICLE: "syntax-tuples" "Tuple syntax"
 { $subsections POSTPONE: T{ }
@@ -391,6 +393,23 @@ HELP: intersection{
 { $values { "elements" "a list of classoids" } }
 { $description "Marks the beginning of a literal " { $link anonymous-intersection } " class." } ;
 
+HELP: maybe{
+{ $syntax "maybe{ elements... }" }
+{ $values { "elements" "a list of classoids" } }
+{ $description "Marks the beginning of a literal " { $link maybe } " class." } ;
+
+HELP: not{
+{ $syntax "not{ elements... }" }
+{ $values { "elements" "a list of classoids" } }
+{ $description "Marks the beginning of a literal " { $link anonymous-complement } " class." } ;
+
+HELP: union{
+{ $syntax "union{ elements... }" }
+{ $values { "elements" "a list of classoids" } }
+{ $description "Marks the beginning of a literal " { $link anonymous-union } " class." } ;
+
+{ POSTPONE: intersection{ POSTPONE: union{ POSTPONE: not{ POSTPONE: maybe{ } related-words
+
 HELP: H{
 { $syntax "H{ { key value }... }" }
 { $values { "key" object } { "value" object } }
@@ -403,6 +422,12 @@ HELP: HS{
 { $description "Marks the beginning of a literal hash set, given as a list of its members. Literal hashtables are terminated by " { $link POSTPONE: } } "." }
 { $examples { $code "HS{ 3 \"foo\" }" } } ;
 
+HELP: IH{
+{ $syntax "IH{ { key value }... }" }
+{ $values { "key" object } { "value" object } }
+{ $description "Marks the beginning of a literal identity hashtable, given as a list of two-element arrays holding key/value pairs. Literal identity hashtables are terminated by " { $link POSTPONE: } } "." }
+{ $examples { $code "IH{ { \"tuna\" \"fish\" } { \"jalapeno\" \"vegetable\" } }" } } ;
+
 HELP: C{
 { $syntax "C{ real-part imaginary-part }" }
 { $values { "real-part" "a real number" } { "imaginary-part" "a real number" } }
@@ -960,3 +985,27 @@ HELP: execute(
 } ;
 
 { POSTPONE: call( POSTPONE: execute( } related-words
+
+HELP: BUILTIN:
+{ $syntax "BUILTIN: class slots ... ;" }
+{ $values { "class" "a builtin class" } { "definition" "a word definition" } }
+{ $description "A representation of a builtin class from the VM. This word cannot define new builtins but is meant to provide a paper trail to which vocabularies define the builtins. To define new builtins requires adding them to the VM." } ;
+
+HELP: PRIMITIVE:
+{ $syntax "PRIMITIVE: word ( stack -- effect )" }
+{ $description "A reference to a primitive word of from the VM. This word cannot define new primitives but is meant to provide a paper trail to which vocabularies define the primitives. To define new primitves requires adding them to the VM." } ;
+
+HELP: MEMO:
+{ $syntax "MEMO: word ( stack -- effect ) definition... ;" }
+{ $values { "word" "a new word to define" } { "definition" "a word definition" } }
+{ $description "Defines the given word at parse time as one which memoizes its output given a particular input. The stack effect is mandatory." } ;
+
+HELP: IDENTITY-MEMO:
+{ $syntax "IDENTITY-MEMO: word ( stack -- effect ) definition... ;" }
+{ $values { "word" "a new word to define" } { "definition" "a word definition" } }
+{ $description "Defines the given word at parse time as one which memoizes its output given a particular input which is identical to another input. The stack effect is mandatory." } ;
+
+HELP: IDENTITY-MEMO::
+{ $syntax "IDENTITY-MEMO:: word ( stack -- effect ) definition... ;" }
+{ $values { "word" "a new word to define" } { "definition" "a word definition" } }
+{ $description "Defines the given word at parse time as one which memoizes its output given a particular input with locals which is identical to another input. The stack effect is mandatory." } ;