basis/typed/typed-docs.factor

   1 ! Copyright (C) 2009 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: arrays effects help.markup help.syntax locals math quotations words ;
   4 IN: typed
   5
   6 HELP: TYPED:
   7 { $syntax
   8 "TYPED: word ( a b: class ... -- x: class y ... )
   9     body ;" }
  10 { $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." }
  11 { $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." }
  12 { $examples
  13 "A version of " { $link + } " specialized for floats, converting other real number types:"
  14 { $example
  15 "USING: math prettyprint typed ;
  16 IN: scratchpad
  17
  18 TYPED: add-floats ( a: float b: float -- c: float )
  19     + ;
  20
  21 1 2+1/2 add-floats ."
  22 "3.5" } } ;
  23
  24 HELP: TYPED::
  25 { $syntax
  26 "TYPED:: word ( a b: class ... -- x: class y ... )
  27     body ;" }
  28 { $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." }
  29 { $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." }
  30 { $examples
  31 "A version of the quadratic formula specialized for floats, converting other real number types:"
  32 { $example
  33 "USING: kernel math math.libm prettyprint typed ;
  34 IN: scratchpad
  35
  36 TYPED:: quadratic-roots ( a: float b: float c: float -- q1: float q2: float )
  37     b neg
  38     b sq 4.0 a * c * - fsqrt
  39     [ + ] [ - ] 2bi
  40     [ 2.0 a * / ] bi@ ;
  41
  42 1 0 -9/4 quadratic-roots [ . ] bi@"
  43 "1.5
  44 -1.5" } } ;
  45
  46 HELP: define-typed
  47 { $values { "word" word } { "def" quotation } { "effect" effect } }
  48 { $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." } ;
  49
  50 HELP: input-mismatch-error
  51 { $values { "word" word } { "expected-types" array } }
  52 { $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." } ;
  53
  54 HELP: output-mismatch-error
  55 { $values { "word" word } { "expected-types" array } }
  56 { $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." } ;
  57
  58 { POSTPONE: TYPED: POSTPONE: TYPED:: define-typed } related-words
  59
  60 ARTICLE: "typed" "Strongly-typed word definitions"
  61 "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."
  62 $nl
  63 "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."
  64 { $subsections
  65     POSTPONE: TYPED:
  66     POSTPONE: TYPED::
  67 }
  68 "Defining typed words at run time:"
  69 { $subsections
  70     define-typed
  71 }
  72 "Errors:"
  73 { $subsections
  74     input-mismatch-error
  75     output-mismatch-error
  76 } ;
  77
  78 ABOUT: "typed"