basis/mirrors/mirrors-docs.factor

   1 USING: help.markup help.syntax slots kernel assocs sequences ;
   2 IN: mirrors
   3
   4 ARTICLE: "mirrors" "Mirrors"
   5 "The " { $vocab-link "mirrors" } " vocabulary defines data types which present an object's slots and slot values as an associative structure. This enables idioms such as iteration over all slots in a tuple, or editing of tuples, sequences and assocs in a generic fashion. This functionality is used by developer tools and meta-programming utilities."
   6 $nl
   7 "A mirror provides such a view of a tuple:"
   8 { $subsections
   9     mirror
  10     <mirror>
  11 }
  12 "Utility word used by developer tools which inspect objects:"
  13 { $subsections make-mirror }
  14 { $see-also "slots" } ;
  15
  16 ABOUT: "mirrors"
  17
  18 HELP: mirror
  19 { $class-description "An associative structure which wraps an object and presents itself as a mapping from slot names to the object's slot values. Mirrors are used to build reflective developer tools."
  20 $nl
  21 "Mirrors are mutable, however new keys cannot be inserted, only values of existing keys can be changed. Deleting a key has the effect of setting its value to " { $link f } "."
  22 $nl
  23 "Mirrors are created by calling " { $link <mirror> } " or " { $link make-mirror } "." } ;
  24
  25 HELP: <mirror>
  26 { $values { "object" object } { "mirror" mirror } }
  27 { $description "Creates a " { $link mirror } " reflecting an object." }
  28 { $examples
  29     { $example
  30         "USING: assocs mirrors prettyprint ;"
  31         "IN: scratchpad"
  32         "TUPLE: circle center radius ;"
  33         "C: <circle> circle"
  34         "{ 100 50 } 15 <circle> <mirror> >alist ."
  35         "{ { \"center\" { 100 50 } } { \"radius\" 15 } }"
  36     }
  37 } ;
  38
  39 HELP: make-mirror
  40 { $values { "obj" object } { "assoc" assoc } }
  41 { $description "Creates an assoc which reflects the internal structure of the object." } ;