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 { $subsection mirror }
   9 { $subsection <mirror> }
  10 "Utility word used by developer tools which inspect objects:"
  11 { $subsection make-mirror }
  12 { $see-also "slots" } ;
  13
  14 ABOUT: "mirrors"
  15
  16 HELP: mirror
  17 { $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."
  18 $nl
  19 "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 } "."
  20 $nl
  21 "Mirrors are created by calling " { $link <mirror> } " or " { $link make-mirror } "." } ;
  22
  23 HELP: <mirror> ( object -- mirror )
  24 { $values { "object" object } { "mirror" mirror } }
  25 { $description "Creates a " { $link mirror } " reflecting an object." }
  26 { $examples
  27     { $example
  28         "USING: assocs mirrors prettyprint ;"
  29         "IN: scratchpad"
  30         "TUPLE: circle center radius ;"
  31         "C: <circle> circle"
  32         "{ 100 50 } 15 <circle> <mirror> >alist ."
  33         "{ { \"center\" { 100 50 } } { \"radius\" 15 } }"
  34     }
  35 } ;
  36
  37 HELP: make-mirror
  38 { $values { "obj" object } { "assoc" assoc } }
  39 { $description "Creates an assoc which reflects the internal structure of the object." } ;