basis/typed/typed-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: arrays effects help.markup help.syntax locals math quotations words ;
   3 IN: typed
   4
   5 HELP: TYPED:
   6 { $syntax
   7 "TYPED: word ( a b: class ... -- x: class y ... )
   8     body ;" }
   9 { $description "Like " { $link POSTPONE: : } ", defines a new word with a given stack effect in the current vocabulary. The inputs and outputs of the stack effect can additionally be given type annotations in the form " { $snippet "a: class" } ". When invoked, the word will attempt to coerce its input values to the declared input types before executing the body, throwing an " { $link input-mismatch-error } " if the types cannot be made to match. The word will likewise attempt to coerce its outputs to their declared types and throw an " { $link output-mismatch-error } " if the types cannot be made to match." }
  10 { $notes "The aforementioned type conversions and checks are structured in such a way that they will be eliminated by the compiler if it can statically determine that the types of the inputs at a call site or of the outputs in the word definition are always correct." }
  11 { $examples
  12 "A version of " { $link + } " specialized for floats, converting other real number types:"
  13 { $example
  14 "USING: math prettyprint typed ;
  15 IN: scratchpad
  16
  17 TYPED: add-floats ( a: float b: float -- c: float )
  18     + ;
  19
  20 1 2+1/2 add-floats ."
  21 "3.5" } } ;
  22
  23 HELP: TYPED::
  24 { $syntax
  25 "TYPED:: word ( a b: class ... -- x: class y ... )
  26     body ;" }
  27 { $description "Like " { $link POSTPONE: :: } ", defines a new word with named inputs in the current vocabulary. The inputs and outputs of the stack effect can additionally be given type annotations in the form " { $snippet "a: class" } ". When invoked, the word will attempt to coerce its input values to the declared input types before executing the body, throwing an " { $link input-mismatch-error } " if the types cannot be made to match. The word will likewise attempt to coerce its outputs to their declared types and throw an " { $link output-mismatch-error } " if the types cannot be made to match." }
  28 { $notes "The aforementioned type conversions and checks are structured in such a way that they will be eliminated by the compiler if it can statically determine that the types of the inputs at a call site or of the outputs in the word definition are always correct." }
  29 { $examples
  30 "A version of the quadratic formula specialized for floats, converting other real number types:"
  31 { $example
  32 "USING: kernel math math.libm prettyprint typed ;
  33 IN: scratchpad
  34
  35 TYPED:: quadratic-roots ( a: float b: float c: float -- q1: float q2: float )
  36     b neg
  37     b sq 4.0 a * c * - fsqrt
  38     [ + ] [ - ] 2bi
  39     [ 2.0 a * / ] bi@ ;
  40
  41 1 0 -9/4 quadratic-roots [ . ] bi@"
  42 "1.5
  43 -1.5" } } ;
  44
  45 HELP: define-typed
  46 { $values { "word" word } { "def" quotation } { "effect" effect } }
  47 { $description "The runtime equivalent to " { $link POSTPONE: TYPED: } " and " { $link POSTPONE: TYPED:: } ". Defines " { $snippet "word" } " with " { $snippet "def" } " as its body and " { $snippet "effect" } " as its stack effect. The word will check that its inputs and outputs correspond to the types specified in " { $snippet "effect" } " as described in the " { $link POSTPONE: TYPED: } " documentation." } ;
  48
  49 HELP: input-mismatch-error
  50 { $values { "word" word } { "expected-types" array } }
  51 { $class-description "Errors of this class are raised at runtime by " { $link POSTPONE: TYPED: } " words when they are invoked with input values that do not match their type annotations. The " { $snippet "word" } " slot indicates the word that failed, and the " { $snippet "expected-types" } " slot specifies the input types expected." } ;
  52
  53 HELP: output-mismatch-error
  54 { $values { "word" word } { "expected-types" array } }
  55 { $class-description "Errors of this class are raised at runtime by " { $link POSTPONE: TYPED: } " words when they attempt to output values that do not match their type annotations. The " { $snippet "word" } " slot indicates the word that failed, and the " { $snippet "expected-types" } " slot specifies the output types expected." } ;
  56
  57 { POSTPONE: TYPED: POSTPONE: TYPED:: define-typed } related-words
  58
  59 ARTICLE: "typed" "Strongly-typed word definitions"
  60 "The Factor compiler supports advanced compiler optimizations that take advantage of the type information it can glean from source code. The " { $vocab-link "typed" } " vocabulary provides syntax that allows words to provide checked type information about their inputs and outputs and improve the performance of compiled code."
  61 $nl
  62 "Parameters and return values of typed words where the type is declared to be a " { $link POSTPONE: final } " tuple class with all slots " { $link read-only } " are passed by value."
  63 { $subsections
  64     POSTPONE: TYPED:
  65     POSTPONE: TYPED::
  66 }
  67 "Defining typed words at run time:"
  68 { $subsections
  69     define-typed
  70 }
  71 "Errors:"
  72 { $subsections
  73     input-mismatch-error
  74     output-mismatch-error
  75 } ;
  76
  77 ABOUT: "typed"