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 "" } ;
  11
  12 HELP: (set-os-envs)
  13 { $values
  14      { "seq" sequence } }
  15 { $description "" } ;
  16
  17
  18 HELP: os-env ( key -- value )
  19 { $values { "key" string } { "value" string } }
  20 { $description "Looks up the value of a shell environment variable." }
  21 { $examples
  22     "This is an operating system-specific feature. On Unix, you can do:"
  23     { $unchecked-example "\"USER\" os-env print" "jane" }
  24 } ;
  25
  26 HELP: os-envs
  27 { $values { "assoc" "an association mapping strings to strings" } }
  28 { $description "Outputs the current set of environment variables." }
  29 { $notes
  30     "Names and values of environment variables are operating system-specific."
  31 } ;
  32
  33 HELP: set-os-envs
  34 { $values { "assoc" "an association mapping strings to strings" } }
  35 { $description "Replaces the current set of environment variables." }
  36 { $notes
  37     "Names and values of environment variables are operating system-specific. Windows NT allows values up to 32766 characters in length."
  38 } ;
  39
  40 HELP: set-os-env ( value key -- )
  41 { $values { "value" string } { "key" string } }
  42 { $description "Set an environment variable." }
  43 { $notes
  44     "Names and values of environment variables are operating system-specific."
  45 } ;
  46
  47 HELP: unset-os-env ( key -- )
  48 { $values { "key" string } }
  49 { $description "Unset an environment variable." }
  50 { $notes
  51     "Names and values of environment variables are operating system-specific."
  52 } ;
  53
  54 { os-env os-envs set-os-env unset-os-env set-os-envs } related-words
  55
  56
  57 ARTICLE: "environment" "Environment variables"
  58 "The " { $vocab-link "environment" } " vocabulary interfaces to the platform-dependent mechanism for setting environment variables." $nl
  59 "Windows CE has no concept of environment variables, so these words are undefined on that platform." $nl
  60 "Reading environment variables:"
  61 { $subsection os-env }
  62 { $subsection os-envs }
  63 "Writing environment variables:"
  64 { $subsection set-os-env }
  65 { $subsection unset-os-env }
  66 { $subsection set-os-envs } ;
  67
  68 ABOUT: "environment"