FUNKTION: escape_string
DEKLARATION: varargs string escape_string(string str, int mode)
BESCHREIBUNG:
Die Funktion fuegt Escape-Zeichen (\) nach verschiedenen Regeln in
den Eingabestring 'str' ein und liefert das Ergebnis zurueck. Die
verwendeten Regeln haengen von 'mode' ab.

Mit dieser Funktion lassen sich beliebige Strings in Regular Expressions
einbauen, auch wenn diese Sonderzeichen enthalten. Damit eignet sich diese
Funktion zum Beispiel auch fuer beliebige Spielereingaben.

Die Bestandteile des Bitflags 'mode' fuer Regular Expressions:

   ESCAPE_REGEXP:       (Default)
       Der zurueckgelieferte String ist ein regexp-Muster, das auf
       den Eingabestring 'str' passt.

   ESCAPE_PCRE:
       Anstelle von ESCAPE_REGEXP fuer PCRE-kompatible Patterns.

   ESCAPE_ANY:          (Default)
       Das zurueckgelieferte Muster passt auf beliebige Teilstrings.

   ESCAPE_EXACT:
       Das zurueckgelieferte Muster muss auf den kompletten String passen.

   ESCAPE_WORD:
       Das zurueckgelieferte Muster muss auf ein Wort passen.

   ESCAPE_CASE:         (Default)
       Das zurueckgelieferte Muster beachtet Gross- und Kleinschreibung.

   ESCAPE_NOCASE:
       Das zurueckgelieferte Muster ignoriert Gross- und Kleinschreibung.

   ESCAPE_LISTE:
       Das zurueckgelieferte Muster beachtet durch Kommata getrennte Listen.
       Wenn man sich selbst um die Trennung kuemmern moechte, kann man statt
       einem String auch ein String-Array uebergeben.

   ESCAPE_WILDCARD:
       Das zurueckgelieferte Muster beachtet einfache Wildcards:

           ?   steht fuer ein beliebiges einzelnes Zeichen
           *   steht fuer beliebig viele (oder keine) Zeichen

       Die Wildcards duerfen im Eingabestring selbst escaped werden.

          \?   steht fuer ?
          \*   steht fuer *

Weitere Werte fuer 'mode', die nicht kombinierbar sind:

   ESCAPE_REPLACE:
       Es wird kein Muster, sondern ein Replacepattern zurueckgeliefert.
       Damit setzt regreplace() genau den Eingabestring ein, auch wenn
       dieser Sonderzeichen enthaelt.

   ESCAPE_GETDIR:
       Der zurueckgelieferte String matcht Dateien bei get_dir()
       exakt der Eingabe, Wildcards und Escapes werden ignoriert.

BEISPIELE:
    escape_string("(foo|bar)")
        -> Das Muster passt auf "(foo|bar)", "bla (foo|bar) bla"

    escape_string("(foo|bar)", ESCAPE_PCRE)
        -> Dasselbe, jedoch fuer PCRE.

    escape_string("(foo|bar)", ESCAPE_EXACT)
        -> Das Muster passt ausschliesslich auf "(foo|bar)".

    escape_string("bla*", ESCAPE_WILDCARD)
        -> Das Muster passt auf "bla", "blafasel", "/pfad/zum/blablubb"

    escape_string("bla*", ESCAPE_WILDCARD|ESCAPE_EXACT)
        -> Jetzt passt das Muster nicht mehr auf "/pfad/zum/blablubb"

    escape_string("\\1&\\2&\\3", ESCAPE_REPLACE)
        -> Als replacepattern verwendet, wird \1&\2&\3 eingesetzt.

    escape_string("tisch, stuhl, sofa", ESCAPE_LISTE)
        -> Das Muster passt auf tisch oder stuhl oder sofa,
           aber auch auf holztisch, stuhlbein und ledersofa.

    escape_string("tisch, stuhl, sofa", ESCAPE_LISTE|ESCAPE_CASE|ESCAPE_WORD)
        -> Das Muster passt auf Tisch oder Stuhl oder Sofa,
           jedoch nicht mehr auf Holztisch, Stuhlbein und dergleichen.
           Zudem ist die Gross- und Kleinschreibung in diesem Beispiel egal.

    escape_string("", ESCAPE_LISTE)
    escape_string(" ", ESCAPE_LISTE)
    escape_string(" , ,,,", ESCAPE_LISTE)
        -> Es handelt sich um leere Listen, der Rueckgabewert ist 0.

VERWEISE: regexp, regreplace, get_dir
GRUPPEN: string, simul_efun
SOURCE: /secure/simul_efun/string.inc