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 "\"USER\" os-env print" "jane" }
  26 } ;
  27
  28 HELP: os-envs
  29 { $values { "assoc" "an association mapping strings to strings" } }
  30 { $description "Outputs the current set of environment variables." }
  31 { $notes
  32     "Names and values of environment variables are operating system-specific."
  33 } ;
  34
  35 HELP: set-os-envs
  36 { $values { "assoc" "an association mapping strings to strings" } }
  37 { $description "Replaces the current set of environment variables." }
  38 { $notes
  39     "Names and values of environment variables are operating system-specific. Windows NT allows values up to 32766 characters in length."
  40 } ;
  41
  42 HELP: set-os-env
  43 { $values { "value" string } { "key" string } }
  44 { $description "Set an environment variable." }
  45 { $notes
  46     "Names and values of environment variables are operating system-specific."
  47 } ;
  48
  49 HELP: unset-os-env
  50 { $values { "key" string } }
  51 { $description "Unset an environment variable." }
  52 { $notes
  53     "Names and values of environment variables are operating system-specific."
  54 } ;
  55
  56 { os-env os-envs set-os-env unset-os-env set-os-envs } related-words
  57
  58
  59 ARTICLE: "environment" "Environment variables"
  60 "The " { $vocab-link "environment" } " vocabulary interfaces to the platform-dependent mechanism for setting environment variables." $nl
  61 "Windows CE has no concept of environment variables, so these words are undefined on that platform." $nl
  62 "Reading environment variables:"
  63 { $subsections
  64     os-env
  65     os-envs
  66 }
  67 "Writing environment variables:"
  68 { $subsections
  69     set-os-env
  70     unset-os-env
  71     set-os-envs
  72 } ;
  73
  74 ABOUT: "environment"