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