basis/unix/groups/groups-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax io.streams.string kernel quotations sequences strings math ;
   4 IN: unix.groups
   5
   6 HELP: all-groups
   7 { $values { "seq" sequence } }
   8 { $description "Returns a sequence of " { $link group } " tuples that are platform-dependent and field for field complete with the Unix " { $link group } " structure." } ;
   9
  10 HELP: effective-group-id
  11 { $values { "string" string } }
  12 { $description "Returns the effective group id for the current user." } ;
  13
  14 HELP: effective-group-name
  15 { $values { "string" string } }
  16 { $description "Returns the effective group name for the current user." } ;
  17
  18 HELP: group
  19 { $description "A platform-specific tuple corresponding to every field from the Unix group struct including the group name, the group id, the group passwd, and a list of users in each group." } ;
  20
  21 HELP: group-cache
  22 { $description "A symbol containing a cache of groups returned from " { $link all-groups } " and indexed by group id. Can be more efficient than using the system call words for many group lookups." } ;
  23
  24 HELP: group-id
  25 { $values
  26      { "string" string }
  27      { "id/f" "an integer or f" } }
  28 { $description "Returns the group id given a group name. Returns " { $link f } " if the group does not exist." } ;
  29
  30 HELP: group-name
  31 { $values
  32      { "id" integer }
  33      { "string" string } }
  34 { $description "Returns the group name given a group id." } ;
  35
  36 HELP: group-struct
  37 { $values
  38      { "obj" object }
  39      { "group/f" "a group struct or f" } }
  40 { $description "Returns an alien group struct to be turned into a group tuple by calling subsequent words." } ;
  41
  42 HELP: real-group-id
  43 { $values { "id" integer } }
  44 { $description "Returns the real group id for the current user." } ;
  45
  46 HELP: real-group-name
  47 { $values { "string" string } }
  48 { $description "Returns the real group name for the current user." } ;
  49
  50 HELP: set-effective-group
  51 { $values
  52      { "obj" object } }
  53 { $description "Sets the effective group id for the current user." } ;
  54
  55 HELP: set-real-group
  56 { $values
  57      { "obj" object } }
  58 { $description "Sets the real group id for the current user." } ;
  59
  60 HELP: user-groups
  61 { $values
  62      { "string/id" "a string or a group id" }
  63      { "seq" sequence } }
  64 { $description "Returns the sequence of groups to which the user belongs." } ;
  65
  66 HELP: with-effective-group
  67 { $values
  68      { "string/id/f" "a string, a group id, or f" } { "quot" quotation } }
  69 { $description "Sets the effective group name and calls the quotation. Restores the effective group name on success or on error after the call. If the first parameter is " { $link f } ", the quotation is called as the current user." } ;
  70
  71 HELP: with-group-cache
  72 { $values
  73      { "quot" quotation } }
  74 { $description "Iterates over the group file using library calls and creates a cache in the " { $link group-cache } " symbol. The cache is a hashtable indexed by group id. When looking up many groups, this approach is much faster than calling system calls." } ;
  75
  76 HELP: with-real-group
  77 { $values
  78      { "string/id/f" "a string or a group id" } { "quot" quotation } }
  79 { $description "Sets the real group name and calls the quotation. Restores the current group name on success or on error after the call. If the first parameter is " { $link f } ", the quotation is called as the current user." } ;
  80
  81 HELP: ?group-id
  82 { $values
  83     { "string" string }
  84     { "id" "a group id" }
  85 }
  86 { $description "Returns a group id or throws an exception." } ;
  87
  88 HELP: all-group-names
  89 { $values
  90
  91     { "seq" sequence }
  92 }
  93 { $description "Returns a sequence of group names as strings." } ;
  94
  95 HELP: group-exists?
  96 { $values
  97     { "name/id" "a name or a group id" }
  98     { "?" boolean }
  99 }
 100 { $description "Returns a boolean representing the group's existence." } ;
 101
 102 ARTICLE: "unix.groups" "Unix groups"
 103 "The " { $vocab-link "unix.groups" } " vocabulary contains words that return information about Unix groups."
 104 $nl
 105 "Listing all group structures:"
 106 { $subsections all-groups }
 107 "Listing all group names:"
 108 { $subsections all-group-names }
 109 "Checking if a group exists:"
 110 { $subsections group-exists? }
 111 "Querying/setting the current real group:"
 112 { $subsections
 113     real-group-name
 114     real-group-id
 115     set-real-group
 116 }
 117 "Querying/setting the current effective group:"
 118 { $subsections
 119     effective-group-name
 120     effective-group-id
 121     set-effective-group
 122 }
 123 "Getting a group id from a group name or id:"
 124 { $subsections
 125     ?group-id
 126 }
 127 "Combinators to change groups:"
 128 { $subsections
 129     with-real-group
 130     with-effective-group
 131 } ;
 132
 133 ABOUT: "unix.groups"