home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / comm / Mail+News / UMS11 / Doc / english / vars.txt < prev    next >
Text File  |  1995-06-10  |  6KB  |  212 lines
  1.  
  2.   UMS config strings
  3.   ~~~~~~~~~~~~~~~~~~
  4.  
  5.   Config strings are defined by lists of words.
  6.  
  7.   Words are seperated by whitespace (blanks, tabs, linefeeds).
  8.  
  9.   They  can  optionally be quoted (with double-quotes, "). Quoting
  10. is  required for including whitespace or control-chars in strings.
  11.   Within  quoted  strings,  the  backspace char (\) can be used to
  12. create  certain control-chars: "\n", "\t", "\b", "\r", "\f", "\e",
  13. "\[",  "\xHH"  yield  the  newline-,  tab-,  backsapce-,  return-,
  14. formfeed-, escape-, CSI- or any hexadecimally coded character.
  15.  
  16.   The  first  word in the list is the name of the config-string to
  17. define. Note that it can be quoted, too.
  18.  
  19.  
  20.   References
  21.   ~~~~~~~~~~
  22.  
  23.   All  other words (i.e. all except the name of the config-string)
  24. can now also contain references to other config strings.
  25.  
  26.   Purpose
  27.   ~~~~~~~
  28.  
  29.   References in config-strings offer a lot of additional power and
  30. flexibility  to  your  UMS  configuration.  The idea is relatively
  31. simple but when wisely used can reach a lot of goals:
  32.  
  33.  - allow to create various hierarchies of newsgroups and other
  34. access-rights
  35.  
  36.  - reduce size of the ums-configuration (and thus memory
  37. requirement of umsserver)
  38.    - by avoid needless copying of strings
  39.    - by using hierarchies of access rights which can be shared by
  40. many users
  41.  
  42.  - provide the possibility to create "classes" of users
  43.  
  44.  - give a better structure to the config, greatly simplifying its
  45. maintenance
  46.  
  47.  - obsolete the need for complicated AmigaDOS patterns. Just
  48. combine simple "*-only" patterns
  49.  
  50.  - allow future optimization of umsserver speed
  51.  
  52.  
  53.   Syntax
  54.   ~~~~~~
  55.  
  56.   References  are indicated by the dollar character ($), which may
  57. optionally be preceeded by an exclamation mark (!). Thus, whenever
  58. a  word  starts with "$" or "!$", the rest of the word constitutes
  59. the  name of another config-string which is to be inserted at that
  60. place.
  61.   References may also be quoted, but only after the dollar-char. A
  62. dollar-char within double-quotes will, of course, will be inserted
  63. literally.
  64.  
  65.  
  66.   References in patterns
  67.   ~~~~~~~~~~~~~~~~~~~~~~
  68.  
  69.   References in patterns are processed in a special way: as though
  70. they were a single pattern.
  71.  
  72.   This  is  completely  different  from matching the config-string
  73. after reading it as text!
  74.  
  75.   Not  only  in  the sense of not requiring a linefeed to separate
  76. single  patterns,  but  also  in  the  way  all  the  patterns are
  77. logically linked.
  78.  
  79.   References  introduced  with  "$"  constitute positive patterns,
  80. those introduced with "!$" are negative pattern. Positive patterns
  81. yield a logical OR operation of the result of previous matches and
  82. the  overall  result  of referred config-string. Negative patterns
  83. lead to a logical "AND NOT" operation.
  84.  
  85.  
  86.   Scope
  87.   ~~~~~
  88.  
  89.   Server  special  config-strings  only  try to resolve references
  90. from  global  strings.  E.g.  a  user's  READACCESS  could contain
  91. references,  but  the  user cannot sneak into disallowed groups by
  92. locally creating suitable config-strings. READACCESS only resolves
  93. its references from global config-strings.
  94.  
  95.   User-strings  use  login-local  and user-strings prior to global
  96. strings  for  resolving  references.  This is also true for global
  97. user-strings,  as  long  as  they are normally requested (i.e. not
  98. "global-only"). See in the examples below how this can be used.
  99.  
  100.  
  101.   Caveats
  102.   ~~~~~~~
  103.  
  104. Beware of the follwing possible mistakes:
  105.  
  106.  -  unresolvable  references.  Only  refer  to strings that really
  107. exist  in  the  scope  to  be  used!  When  UMS fails to resolve a
  108. reference  it will simply insert a dollar-char and the name of the
  109. reference and generate an error. This is not what you want.
  110.  
  111.  -   using   negative  references  as  text.  Negative  references
  112. (indicated   by   "!$")   are   only  useful  for  patterns,  e.g.
  113. access-patterns. They are not useful to be read as text.
  114.  
  115.  -  in  any  case:  strings with references designed to be used as
  116. patterns or not useful to be read as text.
  117.  
  118.  -  editing strings with references as unquoted text is dangerous.
  119. Especially when they were designed as patterns, unqoutedly reading
  120. and   rewriting   config-strings  will  completely  destroy  their
  121. original meaning.
  122.  
  123.  - cyclic dependencies. When trying to resolve strings with cyclic
  124. dependencies, like ( a.b $a.b ), a stack overflow will occur. This
  125. is handled, but an error will be generated, the result will be
  126. unpredictable and unusable, and you risk running out of memory. So
  127. be sure not to create cyclic dependencies.
  128.  
  129.  
  130.   Examples
  131.   ~~~~~~~~
  132.  
  133. ( Sysname foo.bar.com )
  134.  
  135. # define hierarchies of groups for two networks
  136. ( groups.public.all $groups.public.anet $groups.public.bnet )
  137. ( groups.public.anet
  138.     "anet.*\n"
  139.     "!anet.sysop*\n"
  140. )
  141. ( groups.sysop.anet
  142.     "anet.sysop*\n"
  143. )
  144. ( groups.public.bnet
  145.     "bnet.*\n"
  146.     "!bnet.sysop*\n"
  147. )
  148.  
  149. # define hostnames for exporting mail
  150. ( hosts.anet "*.anet" )
  151. ( hosts.bnet 
  152.      "*.bnet\n"
  153.      "*.b.net\n"
  154.      "*.bnet.com\n"
  155. )
  156.  
  157. # a universal signature
  158. #   with personal URL, assuming local system has a http-server
  159. ( Intuinews.signature
  160.     "--\n " $name " <" $rfc.username @ $sysname ">\n"
  161.     "WWW: http://" $sysname "/~" $rfc.username "/home.html\n"
  162. )
  163.  
  164. # simple anet-user
  165. ( User
  166.     ( Name "Alfred Ameise" )
  167.     ( Alias alam "Alfred Ant" )
  168.     ( rfc.username "alam" )
  169.     ( Readaccess $groups.public.anet )
  170.     [..]
  171. )
  172.  
  173. # simple bnet-user
  174. ( User
  175.     ( Name "Berta Biene" )
  176.     ( Alias bebi "Bertha Bee" )
  177.     ( rfc.username "bebi" )
  178.     ( Readaccess $groups.public.bnet )
  179.     [..]
  180. )
  181.  
  182. # advanced user with special rights in anet
  183. ( User
  184.     ( Name "Camilla Chamäleon" )
  185.     ( Alias caca "Camilla Chameleon" )
  186.     ( rfc.username "caca" )
  187.     ( Readaccess $groups.sysop.anet $groups.public.all )
  188.     [..]
  189. )
  190.  
  191. # exporter for anet mail
  192. ( Exporter
  193.     ( Name export.anet )
  194.     ( Export $hosts.anet )
  195.     [..]
  196. )
  197.  
  198. # exporter for bnet mail
  199. ( Exporter
  200.     ( Name export.bnet )
  201.     ( Export $hosts.bnet )
  202.     [..]
  203. )
  204.  
  205. # exporter for all other mail
  206. ( Exporter
  207.     ( Name export.anet )
  208.     ( Export "*" !$hosts.anet !$hosts.bnet )
  209.     [..]
  210. )
  211.  
  212.