basis/environment/environment-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: assocs help.markup help.syntax io.streams.string sequences strings ;
   4 IN: environment
   5
   6 HELP: (os-envs)
   7 { $values
   8
   9      { "seq" sequence } }
  10 { $description "Returns a sequence of key/value pairs from the operating system." }
  11 { $notes "In most cases, use " { $link os-envs } " instead." } ;
  12
  13 HELP: (set-os-envs)
  14 { $values
  15      { "seq" sequence } }
  16 { $description "Low-level word for replacing the current set of environment variables." }
  17 { $notes "In most cases, use " { $link set-os-envs } " instead." } ;
  18
  19
  20 HELP: os-env
  21 { $values { "key" string } { "value" string } }
  22 { $description "Looks up the value of a shell environment variable." }
  23 { $examples
  24     "This is an operating system-specific feature. On Unix, you can do:"
  25     { $unchecked-example
  26         "USING: environment io ;"
  27         "\"USER\" os-env print"
  28         "jane"
  29     }
  30 } ;
  31
  32 HELP: change-os-env
  33 { $values { "key" string } { "quot" { $quotation "( old -- new )" } } }
  34 { $description "Applies a quotation to change the value stored in an environment variable." }
  35 { $examples
  36     "This is an operating system-specific feature. On Unix, you can do:"
  37     { $unchecked-example
  38         "USING: environment io ;"
  39         "\"USER\" os-env print"
  40         "\"USER\" [ \"-doe\" append ] change-os-env"
  41         "\"USER\" os-env print"
  42         "jane\njane-doe"
  43     }
  44 }
  45 { $side-effects "key" } ;
  46
  47 HELP: os-envs
  48 { $values { "assoc" "an association mapping strings to strings" } }
  49 { $description "Outputs the current set of environment variables." }
  50 { $notes
  51     "Names and values of environment variables are operating system-specific."
  52 } ;
  53
  54 HELP: set-os-envs
  55 { $values { "assoc" "an association mapping strings to strings" } }
  56 { $description "Replaces the current set of environment variables." }
  57 { $warning "Leaks memory on Unix. If your program calls this function repeatedly, call " { $link set-os-envs-pointer } " with a malloced pointer and manage your memory instead." }
  58 { $notes
  59     "Names and values of environment variables are operating system-specific. Windows NT allows values up to 32766 characters in length."
  60 } ;
  61
  62 HELP: set-os-envs-pointer
  63 { $values { "malloc" "a pointer to memory from the heap obtained through " { $link malloc } " or similar" } }
  64 { $description "Set then " { $link environ } " pointer. Factor must retain a pointer to this memory until exiting the program." }
  65 { $notes
  66     "Names and values of environment variables are operating system-specific."
  67 } ;
  68
  69 HELP: set-os-env
  70 { $values { "value" string } { "key" string } }
  71 { $description "Set an environment variable." }
  72 { $notes
  73     "Names and values of environment variables are operating system-specific."
  74 } ;
  75
  76 HELP: unset-os-env
  77 { $values { "key" string } }
  78 { $description "Unset an environment variable." }
  79 { $notes
  80     "Names and values of environment variables are operating system-specific."
  81 } ;
  82
  83 { os-env os-envs set-os-env unset-os-env set-os-envs set-os-envs-pointer change-os-env } related-words
  84
  85
  86 ARTICLE: "environment" "Environment variables"
  87 "The " { $vocab-link "environment" } " vocabulary interfaces to the platform-dependent mechanism for setting environment variables." $nl
  88 "Reading environment variables:"
  89 { $subsections
  90     os-env
  91     os-envs
  92 }
  93 "Writing environment variables:"
  94 { $subsections
  95     set-os-env
  96     unset-os-env
  97     set-os-envs
  98     change-os-env
  99 }
 100 "Leak-free setting of all environment variables on Unix:"
 101 { $subsections
 102     set-os-envs-pointer
 103 } ;
 104
 105 ABOUT: "environment"