basis/documents/documents-docs.factor

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