extra/python/syntax/syntax-docs.factor

   1 IN: python.syntax
   2 USING: hashtables python.syntax help.markup help.syntax ;
   3
   4 HELP: PY-FROM:
   5 { $syntax "PY-FROM: module => name-effects ;" }
   6 { $values
   7   { "module" "fully qualified name of a python module" }
   8   { "name-effects" "pairs of names and effect declarations of bindings to import" }
   9 }
  10 { $description
  11   "Creates factor words that maps to the given python objects."
  12 }
  13 { $examples
  14   { $code
  15     "PY-FROM: os.path => isfile ( path -- ? ) splitext ( path -- root ext ) ;"
  16   }
  17 } ;
  18
  19 HELP: PY-QUALIFIED-FROM:
  20 { $syntax "PY-QUALIFIED-FROM: module => name-effects ;" }
  21 { $values
  22   { "module" "fully qualified name of a python module" }
  23   { "name-effects" "pairs of names and effect declarations of bindings to import" }
  24 }
  25 { $description
  26   "Like " { $link \ PY-FROM: } " except all words are created with module as the given prefix."
  27 } ;
  28
  29 HELP: PY-METHODS:
  30 { $syntax "PY-METHODS: class => name-effects ;" }
  31 { $values
  32   { "class" "name of a class to associate the bindings with" }
  33   { "name-effects" "pairs of names and effect declarations of methods to create" }
  34 }
  35 { $description
  36   "Creates factor words that acts as properties and getters and can work on any python object."
  37 }
  38 { $examples
  39   { $code
  40     "PY-FROM: zipfile => ZipFile ( name mode -- file ) ;"
  41     "PY-METHODS: ZipFile => namelist ( self -- names ) ;"
  42     "! Then use the declarations like this"
  43     "\"name-of-zip.zip\" >py \"r\" >py ZipFile namelist py>"
  44   }
  45 } ;
  46
  47 ARTICLE: "python.syntax" "Syntax for python calls from factor"
  48 "The " { $vocab-link "python.syntax" } " vocab adds syntax to factor to make calls from factor to python natural and intuitive."
  49 { $subsections \ PY-FROM: \ PY-QUALIFIED-FROM: \ PY-METHODS: }
  50 $nl
  51 { $examples "Here is how you bind and call a method namelist on a ZipFile instance created by importing the zipfile module:"
  52   { $code
  53     "PY-FROM: zipfile => ZipFile ( name mode -- file ) ;"
  54     "PY-METHODS: ZipFile => namelist ( self -- names ) ;"
  55     "! Then use the declarations like this"
  56     "\"name-of-zip.zip\" >py \"r\" >py ZipFile namelist py>"
  57   }
  58   "In python, a method or function takes keyword arguments if its last parameter starts with \"**\". If the name of the last argument to a declared function is \"**\" then a " { $link hashtable } " can be sent to the function:"
  59   { $code
  60     "PY-FROM: datetime => timedelta ( ** -- timedelta ) ;"
  61     "PY-METHODS: timedelta => seconds ( self -- n ) ;"
  62     "H{ { \"hours\" 99 } { \"minutes\" 33 } } >py timedelta $seconds py> ."
  63     "12780"
  64     }
  65 } ;