basis/cocoa/subclassing/subclassing-docs.factor

   1 USING: help.markup help.syntax strings alien hashtables ;
   2 IN: cocoa.subclassing
   3
   4 HELP: define-objc-class
   5 { $values { "hash" hashtable } { "imeth" "a sequence of instance method definitions" } }
   6 { $description "Defines a new Objective C class. The hashtable can contain the following keys:"
   7     { $list
   8         { { $link +name+ } " - a string naming the new class. Required." }
   9         { { $link +superclass+ } " - a string naming the superclass. Required." }
  10         { { $link +protocols+ } " - an array of strings naming protocols implemented by the superclass. Optional." }
  11     }
  12 "Every element of " { $snippet "imeth" } " defines an instance method, and is an array having the shape "
  13 { $snippet "{ name return args quot }" }
  14 ".:"
  15 { $table
  16     { "name" { "a selector name" } }
  17     { "name" { "a C type name; see " { $link "c-data" } } }
  18     { "args" { "a sequence of C type names; see " { $link "c-data" } } }
  19     { "quot" { "a quotation to be run as a callback when the method is invoked; see " { $link alien-callback } } }
  20 }
  21 "The quotation is run with the following values on the stack:"
  22 { $list
  23     { "the receiver of the message; an " { $link alien } " pointing to an instance of this class" }
  24     { "the selector naming the message; in most cases this value can be ignored" }
  25     "arguments passed to the message, if any"
  26 }
  27 "There is no way to define instance variables or class methods using this mechanism. However, instance variables can be simulated by using the receiver to key into a hashtable." } ;
  28
  29 HELP: CLASS:
  30 { $syntax "CLASS: spec imeth... ;" }
  31 { $values { "spec" "an array of pairs" } { "name" "a new class name" } { "imeth" "instance method definitions" } }
  32 { $description "A sugared form of the following:"
  33     { $code "{ imeth... } \"spec\" define-objc-class" }
  34 "This word is preferred to calling " { $link define-objc-class } ", because it creates a class word in the " { $vocab-link "cocoa.classes" } " vocabulary at parse time, allowing code to refer to the class word in the same source file where the class is defined." } ;
  35
  36 { define-objc-class POSTPONE: CLASS: } related-words
  37
  38 ARTICLE: "objc-subclassing" "Subclassing Objective C classes"
  39 "Objective C classes can be subclassed, with new methods defined in Factor, using a parsing word:"
  40 { $subsection POSTPONE: CLASS: }
  41 "This word is actually syntax sugar for an ordinary word:"
  42 { $subsection define-objc-class }
  43 "Objective C class definitions are saved in the image. If the image is saved and Factor is restarted with the saved image, custom class definitions are made available to the Objective C runtime when they are first accessed from within Factor." ;
  44
  45 IN: cocoa.subclassing
  46 ABOUT: "objc-subclassing"