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-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: remove-doc-range
  63 { $values { "from" "a pair of integers" } { "to" "a pair of integers" } { "document" document } }
  64 { $description "Removes all text between two line/column number pairs." }
  65 { $errors "Throws an error if " { $snippet "from" } " or " { $snippet "to" } " is out of bounds." }
  66 { $side-effects "document" } ;
  67
  68 HELP: validate-loc
  69 { $values { "loc" "a pair of integers" } { "document" document } { "newloc" "a pair of integers" } }
  70 { $description "Ensures that the line and column numbers in " { $snippet "loc" } " are valid, clamping them to the permitted range if they are not." } ;
  71
  72 HELP: line-end
  73 { $values { "line#" "a non-negative integer" } { "document" document } { "loc" "a pair of integers" } }
  74 { $description "Outputs the location where " { $snippet "line#" } " ends." }
  75 { $errors "Throws an error if " { $snippet "line#" } " is out of bounds." } ;
  76
  77 HELP: doc-end
  78 { $values { "document" document } { "loc" "a pair of integers" } }
  79 { $description "Outputs the location of the end of the document." } ;
  80
  81 HELP: doc-string
  82 { $values { "document" document } { "str" "a new " { $link string } } }
  83 { $description "Outputs the contents of the document as a string. Lines are separated by " { $snippet "\\n" } "." } ;
  84
  85 HELP: set-doc-string
  86 { $values { "string" string } { "document" document } }
  87 { $description "Sets the contents of the document to a string, which may use either " { $snippet "\\n" } ", " { $snippet "\\r\\n" } " or " { $snippet "\\r" } " line separators." }
  88 { $side-effects "document" } ;
  89
  90 HELP: clear-doc
  91 { $values { "document" document } }
  92 { $description "Removes all text from the document." }
  93 { $side-effects "document" } ;
  94
  95 ARTICLE: "documents" "Documents"
  96 "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."
  97 { $subsections
  98     document
  99     <document>
 100 }
 101 "Getting and setting the contents of the entire document:"
 102 { $subsections
 103     doc-string
 104     set-doc-string
 105     clear-doc
 106 }
 107 "Getting and setting subranges:"
 108 { $subsections
 109     doc-line
 110     doc-lines
 111     doc-range
 112     set-doc-range
 113     remove-doc-range
 114 }
 115 "A combinator:"
 116 { $subsections each-line }
 117 "More info:"
 118 { $subsections
 119     "document-locs"
 120     "documents.elements"
 121 }
 122 { $see-also "ui.gadgets.editors" } ;
 123
 124 ARTICLE: "document-locs" "Document locations"
 125 "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:"
 126 { $subsections
 127     +col
 128     +line
 129     =col
 130     =line
 131 }
 132 "Miscellaneous words for working with locations:"
 133 { $subsections
 134     lines-equal?
 135     validate-loc
 136 } ;
 137
 138 ABOUT: "documents"