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.markup help.syntax math math.functions ;
   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     POSTPONE: INFIX::
  33 }
  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 ^ } "." }
  41     { { $snippet "%" } ", which is the infix operator for " { $link mod } "." }
  42 }
  43 "The standard precedence rules apply: Grouping with parentheses before " { $snippet "*" } ", " { $snippet "/" } "and " { $snippet "%" } " before " { $snippet "+" } " and " { $snippet "-" } "."
  44 { $example
  45     "USE: infix"
  46     "[infix 5-40/10*2 infix] ."
  47     "-3"
  48 }
  49 $nl
  50 "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:"
  51 { $list
  52     "The word must return exactly one value."
  53     "The word name must consist of the letters a-z, A-Z, _ or 0-9, and the first character can't be a number."
  54 }
  55 { $example
  56     "USING: infix locals math.functions ;"
  57     ":: binary_entropy ( p -- h )"
  58     "    [infix -(p*log(p) + (1-p)*log(1-p)) / log(2) infix] ;"
  59     "[infix binary_entropy( sqrt(0.25) ) infix] ."
  60     "1.0"
  61 }
  62 $nl
  63 "You can access " { $vocab-link "sequences" } " inside infix expressions with the familiar " { $snippet "seq[index]" } " notation."
  64 { $example
  65     "USING: arrays locals infix ;"
  66     "[let { 1 2 3 4 } :> myarr [infix myarr[4/2]*3 infix] ] ."
  67     "9"
  68 }
  69 $nl
  70 "You can create sub-" { $vocab-link "sequences" } " inside infix expressions using " { $snippet "seq[from:to]" } " notation."
  71 { $example
  72     "USING: arrays locals infix ;"
  73     "[let \"foobar\" :> s [infix s[0:3] infix] ] ."
  74     "\"foo\""
  75 }
  76 $nl
  77 "Additionally, you can step through " { $vocab-link "sequences" } " with " { $snippet "seq[from:to:step]" } " notation."
  78 { $example
  79     "USING: arrays locals infix ;"
  80     "[let \"reverse\" :> s [infix s[::-1] infix] ] ."
  81     "\"esrever\""
  82 }
  83 { $example
  84     "USING: arrays locals infix ;"
  85     "[let \"0123456789\" :> s [infix s[::2] infix] ] ."
  86     "\"02468\""
  87 }
  88 ;
  89
  90 ABOUT: "infix"