basis/english/english-docs.factor

   1 ! Copyright (C) 2018 Cat Stevens
   2 USING: arrays assocs help.markup help.syntax kernel math
   3 sequences strings ;
   4 IN: english
   5
   6 <PRIVATE
   7 : $0-plurality ( children -- )
   8     drop {
   9         "Due to the unique way in which the English language is structured, the number "
  10         { $snippet "0" }
  11         " is considered plural; "
  12         { $snippet "1" }
  13         " is the only singular quantity."
  14     } print-element ;
  15
  16 : $keep-case ( children -- )
  17     drop
  18     "This word attempts to preserve the letter case style of the input." print-element ;
  19 PRIVATE>
  20
  21 ABOUT: "english"
  22
  23 ARTICLE: "english" "English natural language transformations"
  24
  25 "The " { $vocab-link "english" } " vocabulary implements a few simple ways of interacting with text in the English language, for improving generated text."
  26 $nl
  27 "Plural and singular forms:"
  28 { $subsections plural? pluralize ?pluralize count-of-things singular? singularize }
  29
  30 "Toy grammatical words:"
  31 { $subsections a/an ?plural-article a10n comma-list }
  32
  33 "An example application:"
  34 { $subsections or-markup-example $or-markup-example } ;
  35
  36 { pluralize ?pluralize plural? count-of-things singularize singular? } related-words
  37 { a/an ?plural-article a10n comma-list $or-markup-example or-markup-example } related-words
  38
  39 HELP: singularize
  40 { $values { "word" string } { "singular" string } }
  41 { $description "Determine the singular form of the input English word. If the input is already singular, it is returned unchanged." }
  42 { $notes $keep-case  }
  43 { $examples
  44     { $example
  45         "USING: english io ;"
  46         "\"CATS\" singularize print"
  47         "CAT"
  48     }
  49     { $example
  50         "USING: english io ;"
  51         "\"Octopi\" singularize print"
  52         "Octopus"
  53     }
  54 } ;
  55
  56 HELP: singular?
  57 { $values { "word" string } { "?" boolean } }
  58 { $description "Attempt to determine whether the word is in singular form." }
  59 { $examples
  60     { $example
  61         "USING: english prettyprint ;"
  62         "\"octopi\" plural? ."
  63         "t"
  64     }
  65 } ;
  66
  67 HELP: pluralize
  68 { $values { "word" string } { "plural" string } }
  69 { $description "Determine the plural form of the input English word. If the input is already plural, it " { $emphasis "might" } " be returned unchanged." }
  70 { $notes { $list { "If the input is already in plural form, an invaid construct such as " { $emphasis "friendses" } " may be generated. This is difficult to avoid due to the unpredictable structure of the English language." } $keep-case } }
  71 { $examples
  72     { $example
  73         "USING: english io ;"
  74         "\"CAT\" pluralize print"
  75         "CATS"
  76     }
  77     { $example
  78         "USING: english io ;"
  79         "\"Octopus\" pluralize print"
  80         "Octopi"
  81     }
  82 } ;
  83
  84 HELP: plural?
  85 { $values { "word" string } { "?" boolean } }
  86 { $description "Attempt to determine whether the word is in plural form." }
  87 { $examples
  88     { $example
  89         "USING: english prettyprint ;"
  90         "\"octopus\" singular? ."
  91         "t"
  92     }
  93 } ;
  94
  95 HELP: count-of-things
  96 { $values { "count" number } { "word" string } { "str" string } }
  97 { $description "Transform a quantity and a word into a construct consisting of the quantity, and the correct plural or singular form of the word. " { $snippet "word" } " is expected to be in singular form." }
  98 { $notes { $list $keep-case $0-plurality } }
  99 { $examples
 100     { $example
 101         "USING: english io ;"
 102         "10 \"baby\" count-of-things print"
 103         "10 babies"
 104     }
 105     { $example
 106         "USING: english io ;"
 107         "2.5 \"FISH\" count-of-things print"
 108         "2.5 FISH"
 109     }
 110 } ;
 111
 112 HELP: ?pluralize
 113 { $values { "count" number } { "singular" string } { "singular/plural" string } }
 114 { $description "A simpler variant of " { $link count-of-things } " which omits its input value from the output. As with " { $link count-of-things } ", " { $snippet "word" } " is expected to be in singular form." }
 115 { $notes { $list $keep-case $0-plurality } }
 116 { $examples
 117     { $example
 118         "USING: english io ;"
 119         "14 \"criterion\" ?pluralize print"
 120         "criteria"
 121     }
 122 } ;
 123
 124 HELP: a10n
 125 { $values { "word" string } { "numeronym" string } }
 126 { $description "Abbreviates a word of more than three characters, by replacing the inner part of the word with the number of omitted letters. The result is an abbreviation (called a " { $emphasis "numeronym" } ") which is pronounced like the original word." }
 127 { $notes { $list
 128     $keep-case
 129     "When the input is too short, it is returned unchanged."
 130     { "The name of this word is " { $snippet "abbreviation" } ", abbreviated by its own strategy." }
 131     { "This style of abbreviation originated with " { $snippet "i18n" } " (the word " { $emphasis "internationalization" } ") in the 1980s." }
 132 } }
 133 { $examples
 134     { $example
 135         "USING: english io ;"
 136         "\"dup\" a10n print"
 137         "dup"
 138     }
 139     { $example
 140         "USING: english io ;"
 141         "\"abbreviationalism\" a10n print"
 142         "a15m"
 143     }
 144 } ;
 145
 146 HELP: a/an
 147 { $values { "word" string } { "article" { $or-markup-example "\"a\"" "\"an\"" } } }
 148 { $description "Gives the proper indefinite singular article (" { $emphasis "a" } " or " { $emphasis "an" } ") for the word. For words which begin with a vowel sound, " { $emphasis "an" } " is used, whereas " { $emphasis "a" } " is used for words which begin with a consonant sound." }
 149 { $notes "The output does not contain the input. The output of this word is always a singular article, regardless of the plurality of the input." }
 150 { $examples
 151     { $example
 152         "USING: english kernel combinators sequences io ;"
 153         "\"object\" [ a/an ] keep \" \" glue print"
 154         "an object"
 155     }
 156 } ;
 157
 158 HELP: ?plural-article
 159 { $values { "word" string } { "article" { $or-markup-example "\"a\"" "\"an\"" "\"the\"" } } }
 160 { $description "Output the proper article given the plurality and first letter of the input. Unlike " { $link a/an } " this word handles plural inputs by outputting the definite " { $emphasis "\"the\"" } ". If the input is singular as determined by " { $link singular? } " this word operates like " { $link a/an } "." }
 161 { $notes { $list "English lacks a plural indefinite article, so the plural definite is used here instead." $keep-case $0-plurality } }
 162 { $examples
 163     { $example
 164         "USING: english sequences kernel io ;"
 165         "\"cat\" [ ?plural-article ] keep \" \" glue print"
 166         "a cat"
 167     }
 168     { $example
 169         "USING: english sequences kernel io ;"
 170         "\"cats\" [ ?plural-article ] keep \" \" glue print"
 171         "the cats"
 172     }
 173 } ;
 174
 175 HELP: comma-list
 176 { $values
 177     { "parts" sequence }
 178     { "conjunction" string }
 179     { "clause-seq" sequence }
 180 }
 181 { $description "Generate a comma-separated list of things, emplacing " { $snippet "conjunction" } " before the last " { $snippet "part" } " if there are two or more elements in " { $snippet "parts" } "." }
 182 { $notes $keep-case }
 183 { $examples
 184     { $example
 185         "USING: english io sequences ;"
 186         "{ \"a cat\" \"a peach\" \"an object\" } \"or\" comma-list concat print"
 187         "a cat, a peach, or an object"
 188     }
 189 } ;
 190
 191 HELP: or-markup-example
 192 { $values { "classes" "a sequence of words" } { "markup" "a sequence of markup elements" } }
 193 { $description "Used to implement " { $link $or-markup-example } " and demonstrate " { $link comma-list } "." }
 194 { $examples { "See the examples in " { $link $or-markup-example } "." } } ;
 195
 196 HELP: $or-markup-example
 197 { $values { "classes" "a sequence of words" } }
 198 { $description "An example to demonstrate a use-case for " { $link comma-list } ". Works like the " { $link $or } " and " { $link ($instance) } " words from " { $vocab-link "help.markup" } "." }
 199 { $examples
 200     { $markup-example
 201         { $or-markup-example "cat" "octopus" "animal" object pair number array string sequence assoc "bird" } print-element
 202     }
 203 } ;