extra/roles/roles-docs.factor

   1 ! Copyright (C) 2009 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: classes.mixin help.markup help.syntax kernel roles ;
   4 IN: roles
   5
   6 HELP: ROLE:
   7 { $syntax "ROLE: name slots... ;
   8 ROLE: name < role slots... ;
   9 ROLE: name <{ roles... } slots... ;" }
  10 { $description "Defines a new " { $link role } ". " { $link tuple } " classes which inherit this role will contain the specified " { $snippet "slots" } " as well as the slots associated with the optional inherited " { $snippet "roles" } "."
  11 $nl
  12 "Slot specifiers take one of the following three forms:"
  13 { $list
  14     { { $snippet "name" } " - a slot which can hold any object, with no attributes" }
  15     { { $snippet "{ name attributes... }" } " - a slot which can hold any object, with optional attributes" }
  16     { { $snippet "{ name class attributes... }" } " - a slot specialized to a specific class, with optional attributes" }
  17 }
  18 "Slot attributes are lists of slot attribute specifiers followed by values; a slot attribute specifier is one of " { $link initial: } " or " { $link read-only } ". See " { $link "tuple-declarations" } " for details." } ;
  19
  20 HELP: ROLE-TUPLE:
  21 { $syntax "ROLE-TUPLE: name slots ;
  22 ROLE-TUPLE: name < estate slots ;
  23 ROLE-TUPLE: name <{ estates... } slots... ;" }
  24 { $description "Defines a new " { $link tuple } " class."
  25 $nl
  26 "The list of inherited " { $snippet "estates" } " is optional; a single tuple superclass and/or a set of " { $link role } "s can be specified. If no superclass is provided, it defaults to " { $link tuple } "."
  27 $nl
  28 "Slot specifiers take one of the following three forms:"
  29 { $list
  30     { { $snippet "name" } " - a slot which can hold any object, with no attributes" }
  31     { { $snippet "{ name attributes... }" } " - a slot which can hold any object, with optional attributes" }
  32     { { $snippet "{ name class attributes... }" } " - a slot specialized to a specific class, with optional attributes" }
  33 }
  34 "Slot attributes are lists of slot attribute specifiers followed by values; a slot attribute specifier is one of " { $link initial: } " or " { $link read-only } ". See " { $link "tuple-declarations" } " for details." } ;
  35
  36 {
  37     POSTPONE: ROLE:
  38     POSTPONE: ROLE-TUPLE:
  39 } related-words
  40
  41 HELP: role
  42 { $class-description "The superclass of all role classes. A " { $snippet "role" } " is a " { $link mixin-class } " that includes a set of slot definitions that can be added to " { $link tuple } " classes alongside other " { $snippet "role" } "s." } ;
  43
  44 HELP: multiple-inheritance-attempted
  45 { $class-description "This error is thrown if a " { $link POSTPONE: ROLE-TUPLE: } " definition attempts to inherit more than one " { $link tuple } " class." } ;
  46
  47 HELP: role-slot-overlap
  48 { $class-description "This error is thrown if a " { $link POSTPONE: ROLE-TUPLE: } " or " { $link POSTPONE: ROLE: } " definition attempts to inherit a set of " { $link role } "s in which more than one attempts to define the same slot." } ;
  49
  50 ARTICLE: "roles" "Roles"
  51 "The " { $vocab-link "roles" } " vocabulary provides a form of tuple interface that can be implemented by concrete tuple classes. A " { $link role } " definition is a mixin class that also prescribes a set of tuple slots. Roles are not tuple classes by themselves and cannot be instantiated by " { $link new } ". The vocabulary extends " { $link POSTPONE: ROLE-TUPLE: } " syntax to allow concrete tuple types to declare membership to one or more roles, automatically including their prescribed slots." $nl
  52 "The role superclass:"
  53 { $subsections role }
  54 "Syntax for making a new role:"
  55 { $subsection POSTPONE: ROLE: }
  56 "Syntax for making tuples that use roles:"
  57 { $subsection POSTPONE: ROLE-TUPLE: }
  58 "Errors with roles:"
  59 { $subsections multiple-inheritance-attempted role-slot-overlap } ;
  60
  61 ABOUT: "roles"