extra/infix/infix-docs.factor

   1 ! Copyright (C) 2009 Philipp Brüschweiler
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.syntax help.markup math prettyprint locals sequences ;
   4 IN: infix
   5
   6 HELP: [infix
   7 { $syntax "[infix ... infix]" }
   8 { $description "Parses the infix code inside the brackets, converts it to stack code and executes it." }
   9 { $examples
  10     { $example
  11         "USING: infix prettyprint ;"
  12         "IN: scratchpad"
  13         "[infix 8+2*3 infix] ."
  14         "14"
  15     } $nl
  16     { $link POSTPONE: [infix } " isn't that useful by itself, as it can only access literal numbers and no variables. It is designed to be used together with locals; for example with " { $link POSTPONE: :: } " :"
  17     { $example
  18         "USING: infix locals math.functions prettyprint ;"
  19         "IN: scratchpad"
  20         ":: quadratic-equation ( a b c -- z- z+ )"
  21         "    [infix (-b-sqrt(b*b-4*a*c)) / (2*a) infix]"
  22         "    [infix (-b+sqrt(b*b-4*a*c)) / (2*a) infix] ;"
  23         "1 0 -1 quadratic-equation . ."
  24         "1.0\n-1.0"
  25     }
  26 } ;
  27
  28 ARTICLE: "infix" "Infix notation"
  29 "The " { $vocab-link "infix" } " vocabulary implements support for infix notation in Factor source code."
  30 { $subsections
  31     POSTPONE: [infix
  32 }
  33 $nl
  34 "The usual infix math operators are supported:"
  35 { $list
  36     { $link + }
  37     { $link - }
  38     { $link * }
  39     { $link / }
  40     { { $snippet "%" } ", which is the infix operator for " { $link mod } "." }
  41 }
  42 "The standard precedence rules apply: Grouping with parentheses before " { $snippet "*" } ", " { $snippet "/" } "and " { $snippet "%" } " before " { $snippet "+" } " and " { $snippet "-" } "."
  43 { $example
  44     "USE: infix"
  45     "[infix 5-40/10*2 infix] ."
  46     "-3"
  47 }
  48 $nl
  49 "You can call Factor words in infix expressions just as you would in C. There are some restrictions on which words are legal to use though:"
  50 { $list
  51     "The word must return exactly one value."
  52     "The word name must consist of the letters a-z, A-Z, _ or 0-9, and the first character can't be a number."
  53 }
  54 { $example
  55     "USING: infix locals math.functions ;"
  56     ":: binary_entropy ( p -- h )"
  57     "    [infix -(p*log(p) + (1-p)*log(1-p)) / log(2) infix] ;"
  58     "[infix binary_entropy( sqrt(0.25) ) infix] ."
  59     "1.0"
  60 }
  61 $nl
  62 "You can access " { $vocab-link "sequences" } " inside infix expressions with the familiar " { $snippet "arr[index]" } " notation."
  63 { $example
  64     "USING: arrays locals infix ;"
  65     "[let { 1 2 3 4 } :> myarr [infix myarr[4/2]*3 infix] ] ."
  66     "9"
  67 }
  68 "Please note: in Factor " { $emphasis "fixnums are sequences too." } " If you are not careful with sequence accesses you may introduce subtle bugs:"
  69 { $example
  70     "USING: arrays infix locals ;"
  71     ":: add-2nd-elements ( x y -- res )"
  72     "    [infix x[1] + y[1] infix] ;"
  73     "{ 1 2 3 } { 0 1 2 3 } add-2nd-elements ."
  74     "3"
  75 }
  76 ;
  77
  78 ABOUT: "infix"