core/generic/standard/standard-docs.factor

   1 USING: generic help.markup help.syntax sequences math
   2 math.parser ;
   3 IN: generic.standard
   4
   5 HELP: no-method
   6 { $values { "object" "an object" } { "generic" "a generic word" } }
   7 { $description "Throws a " { $link no-method } " error." }
   8 { $error-description "Thrown by the " { $snippet "generic" } " word to indicate it does not have a method for the class of " { $snippet "object" } "." } ;
   9
  10 HELP: standard-combination
  11 { $class-description
  12     "Performs standard method combination."
  13     $nl
  14     "Generic words using the standard method combination dispatch on the class of the object at the given stack position, where 0 is the top of the stack, 1 is the object underneath, and 2 is the next one under that. A " { $link no-method } " error is thrown if no suitable method is defined on the class."
  15 }
  16 { $examples
  17     "A generic word for append strings and characters to a sequence, dispatching on the object underneath the top of the stack:"
  18     { $code
  19         "GENERIC# build-string 1 ( elt str -- )"
  20         "M: string build-string swap push-all ;"
  21         "M: integer build-string push ;"
  22     }
  23 } ;
  24
  25 HELP: hook-combination
  26 { $class-description
  27     "Performs hook method combination . See " { $link POSTPONE: HOOK: } "."
  28 } ;
  29
  30 HELP: define-simple-generic
  31 { $values { "word" "a word" } }
  32 { $description "Defines a generic word with the " { $link standard-combination } " method combination and a dispatch position of 0." } ;
  33
  34 { standard-combination hook-combination } related-words
  35
  36 HELP: inconsistent-next-method
  37 { $error-description "Thrown by " { $link POSTPONE: call-next-method } " if the values on the stack are not compatible with the current method." }
  38 { $examples
  39     "The following code throws this error:"
  40     { $code
  41         "GENERIC: error-test ( object -- )"
  42         ""
  43         "M: string error-test print ;"
  44         ""
  45         "M: integer error-test number>string call-next-method ;"
  46         ""
  47         "123 error-test"
  48     }
  49     "This results in the method on " { $link integer } " being called, which then passes a string to " { $link POSTPONE: call-next-method } ". However, this fails because the string is not compatible with the current method."
  50     $nl
  51     "This usually indicates programmer error; if the intention above was to call the string method on the result of " { $link number>string } ", the code should be rewritten as follows:"
  52     { $code "M: integer error-test number>string error-test ;" }
  53 } ;