basis/documents/documents-docs.factor

   1 USING: help.markup help.syntax kernel math models sequences
   2 strings ;
   3 IN: documents
   4
   5 HELP: +col
   6 { $values { "loc" "a pair of integers" } { "n" integer } { "newloc" "a pair of integers" } }
   7 { $description "Adds an integer to the column number of a line/column pair." } ;
   8
   9 { +col +line =col =line } related-words
  10
  11 HELP: +line
  12 { $values { "loc" "a pair of integers" } { "n" integer } { "newloc" "a pair of integers" } }
  13 { $description "Adds an integer to the line number of a line/column pair." } ;
  14
  15 HELP: =col
  16 { $values { "n" integer } { "loc" "a pair of integers" } { "newloc" "a pair of integers" } }
  17 { $description "Sets the column number of a line/column pair." } ;
  18
  19 HELP: =line
  20 { $values { "n" integer } { "loc" "a pair of integers" } { "newloc" "a pair of integers" } }
  21 { $description "Sets the line number of a line/column pair." } ;
  22
  23 HELP: lines-equal?
  24 { $values { "loc1" "a pair of integers" } { "loc2" "a pair of integers" } { "?" boolean } }
  25 { $description "Tests if both line/column pairs have the same line number." } ;
  26
  27 HELP: document
  28 { $class-description "A document is a " { $link model } " containing editable text, stored as an array of lines. Documents are created by calling " { $link <document> } ". Documents can be edited with editor gadgets; see " { $vocab-link "ui.gadgets.editors" } "." } ;
  29
  30 HELP: <document>
  31 { $values { "document" "a new " { $link document } } }
  32 { $description "Creates a new, empty " { $link document } "." } ;
  33
  34 HELP: doc-line
  35 { $values { "n" "a non-negative integer" } { "document" document } { "string" string } }
  36 { $description "Outputs the " { $snippet "n" } "th line of the document." }
  37 { $errors "Throws an error if " { $snippet "n" } " is out of bounds." } ;
  38
  39 HELP: doc-lines
  40 { $values { "from" "a non-negative integer" } { "to" "a non-negative integer" } { "document" document } { "slice" slice } }
  41 { $description "Outputs a range of lines from the document." }
  42 { $notes "The range is created by calling " { $link <slice> } "." }
  43 { $errors "Throws an error if " { $snippet "from" } " or " { $snippet "to" } " is out of bounds." } ;
  44
  45 HELP: each-doc-line
  46 { $values { "from" "a non-negative integer" } { "to" "a non-negative integer" } { "quot" { $quotation ( ... line -- ... ) } } }
  47 { $description "Applies the quotation to each line in the range." }
  48 { $notes "The range is created by calling " { $link <slice> } "." }
  49 { $errors "Throws an error if " { $snippet "from" } " or " { $snippet "to" } " is out of bounds." } ;
  50
  51 HELP: doc-range
  52 { $values { "from" "a pair of integers" } { "to" "a pair of integers" } { "document" document } { "string" "a new " { $link string } } }
  53 { $description "Outputs all text in between two line/column number pairs. Lines are separated by " { $snippet "\\n" } "." }
  54 { $errors "Throws an error if " { $snippet "from" } " or " { $snippet "to" } " is out of bounds." } ;
  55
  56 HELP: set-doc-range
  57 { $values { "string" string } { "from" "a pair of integers" } { "to" "a pair of integers" } { "document" document } }
  58 { $description "Replaces all text between two line/column number pairs with " { $snippet "string" } ". The string may use either " { $snippet "\\n" } ", " { $snippet "\\r\\n" } " or " { $snippet "\\r" } " line separators." }
  59 { $errors "Throws an error if " { $snippet "from" } " or " { $snippet "to" } " is out of bounds." }
  60 { $side-effects "document" } ;
  61
  62 HELP: set-doc-range*
  63 { $values { "string" string } { "from" "a pair of integers" } { "to" "a pair of integers" } { "document" document } }
  64 { $description "Replaces all text between two line/column number pairs with " { $snippet "string" } ". The string may use either " { $snippet "\\n" } ", " { $snippet "\\r\\n" } " or " { $snippet "\\r" } " line separators.\n\nThis word differs from " { $link set-doc-range } " in that it does not include changes in the Undo and Redo actions." }
  65 { $errors "Throws an error if " { $snippet "from" } " or " { $snippet "to" } " is out of bounds." }
  66 { $side-effects "document" } ;
  67
  68 HELP: remove-doc-range
  69 { $values { "from" "a pair of integers" } { "to" "a pair of integers" } { "document" document } }
  70 { $description "Removes all text between two line/column number pairs." }
  71 { $errors "Throws an error if " { $snippet "from" } " or " { $snippet "to" } " is out of bounds." }
  72 { $side-effects "document" } ;
  73
  74 HELP: validate-loc
  75 { $values { "loc" "a pair of integers" } { "document" document } { "newloc" "a pair of integers" } }
  76 { $description "Ensures that the line and column numbers in " { $snippet "loc" } " are valid, clamping them to the permitted range if they are not." } ;
  77
  78 HELP: line-end
  79 { $values { "line#" "a non-negative integer" } { "document" document } { "loc" "a pair of integers" } }
  80 { $description "Outputs the location where " { $snippet "line#" } " ends." }
  81 { $errors "Throws an error if " { $snippet "line#" } " is out of bounds." } ;
  82
  83 HELP: doc-end
  84 { $values { "document" document } { "loc" "a pair of integers" } }
  85 { $description "Outputs the location of the end of the document." } ;
  86
  87 HELP: doc-string
  88 { $values { "document" document } { "str" "a new " { $link string } } }
  89 { $description "Outputs the contents of the document as a string. Lines are separated by " { $snippet "\\n" } "." } ;
  90
  91 HELP: set-doc-string
  92 { $values { "string" string } { "document" document } }
  93 { $description "Sets the contents of the document to a string, which may use either " { $snippet "\\n" } ", " { $snippet "\\r\\n" } " or " { $snippet "\\r" } " line separators." }
  94 { $side-effects "document" } ;
  95
  96 HELP: clear-doc
  97 { $values { "document" document } }
  98 { $description "Removes all text from the document." }
  99 { $side-effects "document" } ;
 100
 101 ARTICLE: "documents" "Documents"
 102 "The " { $vocab-link "documents" } " vocabulary implements " { $emphasis "documents" } ", which are models storing a passage of text as a sequence of lines. Operations are defined for operating on subranges of the text, and " { $link "ui.gadgets.editors" } " can display these models."
 103 { $subsections
 104     document
 105     <document>
 106 }
 107 "Getting and setting the contents of the entire document:"
 108 { $subsections
 109     doc-string
 110     set-doc-string
 111     clear-doc
 112 }
 113 "Getting and setting subranges:"
 114 { $subsections
 115     doc-line
 116     doc-lines
 117     doc-range
 118     set-doc-range
 119     remove-doc-range
 120 }
 121 "A combinator:"
 122 { $subsections
 123     each-doc-line
 124     map-doc-lines
 125 }
 126 "More info:"
 127 { $subsections
 128     "document-locs"
 129     "documents.elements"
 130 }
 131 { $see-also "ui.gadgets.editors" } ;
 132
 133 ARTICLE: "document-locs" "Document locations"
 134 "Locations in the document are represented as a line/column number pair, with both indices being zero-based. There are some words for manipulating locations:"
 135 { $subsections
 136     +col
 137     +line
 138     =col
 139     =line
 140 }
 141 "Miscellaneous words for working with locations:"
 142 { $subsections
 143     lines-equal?
 144     validate-loc
 145 } ;
 146
 147 ABOUT: "documents"