Update Doku aus Driversourcen
Change-Id: I455f0813b970151089b3dc1b8d9407eea323cdd1
diff --git a/doc/concepts/erq b/doc/concepts/erq
index 378d59d..8db9216 100644
--- a/doc/concepts/erq
+++ b/doc/concepts/erq
@@ -5,11 +5,11 @@
Up to version 3.2.1@61, LPMud utilized two external programs
in an ad-hoc manner to solve problems: the 'hname' program to
resolve IP addresses into meaningful hostnames, and the
- 'indent' program to properly indent LPC files.
- In version 3.2.1@61 both functions were united in a
- generalized 'erq' process, to which additional functions may
- be attached. Unfortunately it was never documented by Amylaar,
- so the information presented here had to be reverse engineered
+ 'indent' program to properly indent LPC files. In version
+ 3.2.1@61 both functions were united in a generalized 'erq'
+ process, to which additional functions may be attached.
+ Unfortunately it was never documented by Amylaar, so the
+ information presented here had to be reverse engineered
from the sources - better take it with a grain of salt.
The erq feature is available if the driver is compiled with
@@ -34,10 +34,10 @@
an interactive object as argument, and takes the connection
away(!) from this object and stores it as the erq connection
to use (an old erq connection is closed first). The object
- (which now no longer is interactive) is then no longer needed,
- but may continue to exist.
- The erq attached this way of course has to use the sockets it
- opened to communicate with the driver.
+ (which is now no longer is interactive) is then no longer
+ needed, but may continue to exist. The erq attached this way
+ of course has to use the sockets it opened to communicate
+ with the driver.
Most of the communication between erq and driver is going to
be initiated by the driver (the erq has to look up the
@@ -97,6 +97,7 @@
identified by 'header.handle'. Normally, one request results
in just one response sent by the erq using struct from_erq_msg,
so the handle is recycled after this response.
+
Shall the erq send several responses (or break one response
into several parts), the struct from_erq_keep_msg has to be
used for all but the last response - this message with its
@@ -298,7 +299,7 @@
ERQ_E_UNKNOWN : Process terminated for unknown reason.
- Authentificate connection (see rfc 931):
+ Authenticate connection (see rfc 931):
request : ERQ_AUTH
data sent: struct sockaddr_in remote // the address to check
@@ -313,7 +314,7 @@
The erq attempts to connect the authd on the remote system
and to verify the connection between the remote port and the
mud port. The latter will normally be the port number of the
- socket on besides of the gamedriver, retrieveable by
+ socket on besides of the gamedriver, retrievable by
query_ip_number().
The answer from the authd (one line of text) if there is any
@@ -323,7 +324,7 @@
the xerq as alternative.
- Open an UPD port:
+ Open an UDP port:
request : ERQ_OPEN_UDP
data sent: char[2] port // the port number to open (network order)
@@ -342,7 +343,7 @@
of two bytes.
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
- ERQ_E_UNKNOWN : Error <info> occured in one of the system
+ ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
Once the port is open, it is treated as if is just another
@@ -398,7 +399,7 @@
the network from the sender at <addr>, reply port number <port>.
- Open an TCP to listen for connections:
+ Open a TCP port to listen for connections:
request : ERQ_LISTEN
data sent: struct addr.sin_port port // the port number to open
@@ -409,7 +410,7 @@
char rc = ERQ_OK
char[] ticket // the connection ticket.
- The erq opens an TCP-port on the host machine with the given
+ The erq opens a TCP-port on the host machine with the given
port number to listen for connections.
Possible exit codes are:
ERQ_OK : Operation succeeded.
@@ -417,14 +418,14 @@
of two bytes.
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
- ERQ_E_UNKNOWN : Error <info> occured in one of the system
+ ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
Once the port is open, it is treated as if is just another
spawned program.
- Open an TCP port:
+ Open a TCP port:
request : ERQ_OPEN_TCP
data sent: struct in_addr.s_addr ip // the ip to address
@@ -436,7 +437,7 @@
char rc = ERQ_OK
char[] ticket // the connection ticket.
- The erq opens an TCP-port on the host machine and tries to connect
+ The erq opens a TCP-port on the host machine and tries to connect
it to the address <ip>:<port>.
Possible exit codes are:
ERQ_OK : Operation succeeded.
@@ -444,7 +445,7 @@
of two bytes.
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
- ERQ_E_UNKNOWN : Error <info> occured in one of the system
+ ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
Once the port is open, it is treated as if is just another
@@ -529,7 +530,7 @@
char[] ticket // the new ticket.
The erq accepts a new connection on an accept-TCP-port, creates
- an child and ticket for it and returns its ticket together with
+ a child and ticket for it, and returns its ticket together with
the remote's side <ip>:<port> number (in network byte order).
Possible exit codes are:
ERQ_OK : Operation succeeded.
@@ -538,13 +539,12 @@
ERQ_E_NSLOTS : The max number of child processes (given
in <info>) is exhausted.
ERQ_E_TICKET : the ticket didn't match
- ERQ_E_UNKNOWN : Error <info> occured in one of the system
+ ERQ_E_UNKNOWN : Error <info> occurred in one of the system
calls done to open the port.
- Once the port is open, it is treated as if is just another
+ Once the port is open, it is treated as if it is just another
spawned program.
-
EXAMPLE
Assume you have a script 'welcome-mail' to send a welcome mail
to a new player. Put this script into the directory for the callable
@@ -563,7 +563,6 @@
, #'erq_response);
}
-
HISTORY
The erq was introduced with 3.2.1@61.
ERQ_AUTH was introduced with 3.2.1@81.
diff --git a/doc/concepts/hooks b/doc/concepts/hooks
index 108da08..aada84e 100644
--- a/doc/concepts/hooks
+++ b/doc/concepts/hooks
@@ -11,6 +11,7 @@
Some of the hooks are mandatory, some not. Most hooks accept
unbound lambda closures as values, some also lfun closures or
even strings.
+
The hooks are identified by an ordinal number, for which
symbolic names are defined in /sys/driverhooks.h.
@@ -30,7 +31,7 @@
H_CREATE_CLONE
Optional hooks to initialize an object after creation.
- H_CREATE_SUPER is called for blueprints implicitely loaded
+ H_CREATE_SUPER is called for blueprints implicitly loaded
by inheritance, H_CREATE_OB for explicitely loaded
blueprints/objects, and H_CREATE_CLONE for cloned objects.
@@ -104,9 +105,14 @@
the source of every compiled LPC object.
+ H_FILE_ENCODING
+ Optonal hook specifying the name of the encoding to be used
+ for decoding a file (default: "ascii").
+
+
H_TELNET_NEG
Optional hook to specifiy how to perform a single telnet
- negotiation. If not set, most telnet options are rejected (read:
+ negotiation. If not set, most telnet options are rejected (read:
only a very minimal negotiation takes place).
@@ -125,6 +131,10 @@
the erq demon.
+ H_MSG_DISCARDED
+ Optional hook to specify a message or take other measures
+ when a message had to be discarded.
+
HISTORY
The hooks concept was introduced in 3.2.1
H_MOVE_OBJECT0/1 were introduced in 3.2.1@1
diff --git a/doc/concepts/hsregexp b/doc/concepts/hsregexp
index 04266be..9905215 100644
--- a/doc/concepts/hsregexp
+++ b/doc/concepts/hsregexp
@@ -1,13 +1,11 @@
SYNOPSIS
Henry Spencer Regular Expressions
-
DESCRIPTION
This document describes the regular expressions supported by the
implementation by Henry Spencer (the traditional package for
LPMud).
-
OPTIONS
The following bitflag options modify the behaviour of the
regular expressions - both interpretation and actual matching.
@@ -20,7 +18,6 @@
editor would do it: () match literally, and the \( \) group
expressions.
-
REGULAR EXPRESSION DETAILS
A regular expression is a pattern that is matched against a
subject string from left to right. Most characters stand for
@@ -77,7 +74,6 @@
\c match character c even if it's one of the special
characters.
-
NOTES
The \< and \> metacharacters from Henry Spencers package
are not available in PCRE, but can be emulate with \b,
@@ -87,13 +83,11 @@
limit, to avoid freezing the driver with a match
like regexp(({"=XX==================="}), "X(.+)+X").
-
AUTHOR
Mark H. Colburn, NAPS International (mark@jhereg.mn.org)
Henry Spencer, University of Torronto (henry@utzoo.edu)
Joern Rennecke
Ian Phillipps
-
SEE ALSO
regexp(C), pcre(C)
diff --git a/doc/concepts/imp b/doc/concepts/imp
index 27d9ab9..5ac1259 100644
--- a/doc/concepts/imp
+++ b/doc/concepts/imp
@@ -3,7 +3,7 @@
LAST UPDATED
Deepthought, 10-Nov-92
- Pepel, 18-Nov-93
+ Pepel, 18-Nov-93
DESRIPTION
This document describes IMP, the intermud message protocol,
@@ -13,8 +13,8 @@
(unreliable datagram protocol) packets. Each mud provides
a connection endpoint which is given by the ip host address
and the UDP port number. Muds may then send messages to
- this port by using the efun send_udp(). The applied function
- receive_udp will be called by the driver in the master
+ this port by using the efun send_imp(). The applied function
+ receive_imp will be called by the driver in the master
object if a imp message arrives at the mud's UDP port.
Imp message packets have the following format:
@@ -48,8 +48,8 @@
NOTE
The above is only particularly correct nowadays. Recently a
- package name ``inetd'' was published, that is based on the IMP
- mechanism in the driver (send_udp() and receive_udp()), but
+ package name "inetd" was published, that is based on the IMP
+ mechanism in the driver (send_imp() and receive_imp()), but
it uses a different message format. That package seems to
enjoy much publicity and is installed in a number of muds. For
details look into the inetd description.
@@ -60,4 +60,4 @@
the connection to other muds.
SEE ALSO
- send_udp(E), receive_udp(M), intermud(C)
+ send_imp(E), receive_imp(M), intermud(C)
diff --git a/doc/concepts/inheritance b/doc/concepts/inheritance
index 46bf338..127b7e6 100644
--- a/doc/concepts/inheritance
+++ b/doc/concepts/inheritance
@@ -10,11 +10,11 @@
some special changes to it. That doesn't work by copying the
file.. Ouch! Don't replicate code! But by putting a tiny inherit
declaration
-
+
inherit "<model-class>";
-
+
at the beginning of your new file. This must come before any local
- ariables or functions. Once inherited your class will behave just
+ variables or functions. Once inherited your class will behave just
like the model class, because all the public methods are available
to the outside world. Now it is in your hands to change such an
inherited behaviour. You have the following tools to do so:
@@ -52,7 +52,6 @@
variant.
EXAMPLE
-
Let's imagine very simple food in a file called "/the/food.c":
// unless "modified" variables are accessible by inheritors
@@ -124,7 +123,6 @@
}
ADVANCED USAGE
-
* Doing multiple inheritance
While the Java(TM) language has so-called interfaces as a kludge,
@@ -137,16 +135,17 @@
* Wildcarded multiple inheritance
- LDMUD 3.2.1@117 introduces an advanced voodoo syntax which allows
- you to call several methods in model classes at once, but for some
- technical reasons it cannot pass any arguments. This works by
+ LDMud 3.2.1@117 introduces an advanced voodoo syntax which allows
+ you to call several methods in model classes at once. This works by
writing a glob type match ('*' and '?' wildcards) into the string
- in front of the double colon, as in "*"::create(). I wouldn't
- recommend you to use this, it's better to be clearly conscious of
- what you inherit and do. But if you're desperate, there you go.
+ in front of the double colon, as in "*"::create().
+ I wouldn't recommend you to use this, it's better to be clearly
+ conscious of what you inherit and do. But if you're desperate, there
+ you go.
+
+ Since LDMud 3.5.0 it is possible to pass arguments as well.
ADVANCED EXAMPLE
-
inherit "foo";
inherit "bar";
inherit "baz";
@@ -172,6 +171,6 @@
SEE ALSO
functions(LPC), initialisation(LPC), modifiers(LPC), pragma(LPC),
- overloading(C)
- function_exists(efun), functionlist(efun), inherit_list(efun),
- symbol_variable(efun), variable_exists(efun), variable_list(efun).
+ overloading(C),
+ function_exists(E), functionlist(E), inherit_list(E),
+ symbol_variable(E), variable_exists(E), variable_list(E)
diff --git a/doc/concepts/intermud b/doc/concepts/intermud
index abe2b4f..5db726b 100644
--- a/doc/concepts/intermud
+++ b/doc/concepts/intermud
@@ -8,7 +8,7 @@
implementations is limited.
This text is about the rather old widely spread 'Zebedee Intermud',
- which is also called 'Intermud 2' altough it differs quite a lot
+ which is also called 'Intermud 2' although it differs quite a lot
from the real Intermud 2 protocol.
Full information on the newer Intermud 3 could be found on the
diff --git a/doc/concepts/mccp b/doc/concepts/mccp
index f3e31fb..5cb605d 100644
--- a/doc/concepts/mccp
+++ b/doc/concepts/mccp
@@ -2,14 +2,14 @@
mccp - The Mud Client Compression Protocol
DESCRIPTION
- Informations and code taken from the MCCP Homepage
+ Information and code taken from the MCCP Homepage
http://www.randomly.org/projects/MCCP/
MCCP is implemented as a Telnet option [RFC854, RFC855]. The server
and client negotiate the use of MCCP as they would any other telnet
option. Once agreement has been reached on the use of the option,
option subnegotiation is used to determine acceptable compression
- methods to use, and to indicate the start of a compressed data stream.
+ methods to use, and to indicate the start of a compressed data stream.
If the driver is compiled with MCCP Support there is a
define __MCCP__.
@@ -24,7 +24,7 @@
Notice: when the client uses compressions all binary_message calls
are executed with flag=3. This is because writing to the
socket would disturb zlib stream.
-
+
mccp-efuns:
start_mccp_compress(int telopt) (only needed with H_NOECHO)
@@ -32,7 +32,7 @@
query_mccp(object player)
query_mccp_stats(object player)
- Initiating MCCP without H_NOECHO hook:
+ Initiating MCCP without H_NOECHO hook:
if(!query_mccp()){
binary_message(({ IAC, WILL, TELOPT_COMPRESS2 }),1)
@@ -41,42 +41,43 @@
the driver will parse the clients answers and start compression.
(The connection might already be compressed, because although the
- documentation says clients should not negotiate from themselfes,
+ documentation says clients should not negotiate from themselves,
zmud e.g. does.)
You can start and stop compression manually by efuns
when you are sure client supports compression :)
- Initiating MCCP compression with H_NOECHO hook:
+ Initiating MCCP compression with H_NOECHO hook:
If your mudlib uses the H_NOECHO driver-hook you decided to do
all the negotiation by yourself:
Server Commands
- IAC WILL COMPRESS indicates the sender supports version 1 of the
- protocol, and is willing to compress data it sends.
+ IAC WILL COMPRESS indicates the sender supports version 1 of the
+ protocol, and is willing to compress data it sends.
IAC WILL COMPRESS2 indicates the sender supports version 2, and is
- willing to compress data it sends.
+ willing to compress data it sends.
- IAC WONT COMPRESS indicates the sender refuses to compress data using
- version 1.
+ IAC WONT COMPRESS indicates the sender refuses to compress data using
+ version 1.
IAC WONT COMPRESS2 indicates the sender refuses to compress data
- using version 2.
+ using version 2.
Client Commands
- IAC DO COMPRESS indicates the sender supports version 1 of the
- protocol, and is willing to decompress data received.
+ IAC DO COMPRESS indicates the sender supports version 1 of the
+ protocol, and is willing to decompress data
+ received.
- IAC DO COMPRESS2 indicates the sender supports version 2 or above,
- and is willing to decompress data received.
+ IAC DO COMPRESS2 indicates the sender supports version 2 or above,
+ and is willing to decompress data received.
- IAC DONT COMPRESS indicates the sender refuses to support version 1.
- If compression was previously negotiated and is
- currently being used, the server should terminate
- compression.
+ IAC DONT COMPRESS indicates the sender refuses to support version 1.
+ If compression was previously negotiated and is
+ currently being used, the server should terminate
+ compression.
IAC DONT COMPRESS2 indicates the sender refuses to support version 2.
If compression was previously negotiated and is
@@ -96,5 +97,4 @@
SEE ALSO
start_mccp_compress(E), end_mccp_compress(E), query_mccp(E),
- query_mccp_stats(object player)
-
+ query_mccp_stats(E)
diff --git a/doc/concepts/memory b/doc/concepts/memory
index 9524eb3..95b0b2d 100644
--- a/doc/concepts/memory
+++ b/doc/concepts/memory
@@ -1,9 +1,7 @@
CONCEPT
- memory
- swapping
+ memory / swapping
DESCRIPTION
-
TODO: This is out of date. Also document the relation with reset
(Collected from the Changelogs of the driver source)
@@ -35,8 +33,8 @@
Any feedback of how to best tune these values are welcome. The
call of reset will be done once, and not yet again until the
object has been touched. This enables reset'ed objects to stay
- swapped out. If you have a mudlib that has no ojbects that
- defines 'clean_up', then you may better define this time as 0,
+ swapped out. If you have a mudlib that has no objects that
+ define 'clean_up', then you may better define this time as 0,
which means never call clean_up (and thus never swap the
object in needlessly). A well implemented usage of clean_up is
better than the swap algorithm, as even cloned objects can be
@@ -44,13 +42,14 @@
swapping (memory wise).
Changed mechanism of calling clean_up() slightly. Only objects
- that defines the function will be called. And, only clean_up()
+ that define the function will be called. And, only clean_up()
that returns non-zero will be called again. This will minimize
- calls of clean_up(), while still cost very litte to maintain.
+ calls of clean_up(), while still costing little to maintain.
clean_up() now gets a flag as argument, which will be non-zero
if the the program of this object is used for inheritance by
other objects.
SEE ALSO
- clean_up(A), slow_shut_down(M), quota_demon(M), malloc(D)
+ clean_up(A), slow_shut_down(M), quota_demon(M), low_memory(M)
+ malloc(D), garbage_collection(E)
diff --git a/doc/concepts/mysql b/doc/concepts/mysql
index 4fb6dee..66f4e7d 100644
--- a/doc/concepts/mysql
+++ b/doc/concepts/mysql
@@ -1,5 +1,5 @@
CONCEPT
- mysql - mySQL support
+ mysql - mySQL support
DESCRIPTION
On hosts with the mySQL package installed, the driver can be
@@ -12,9 +12,9 @@
Create a dedicated user in the mySQL database for the driver.
Enter this username and password in the file pkg-mysql.c, function
mysql_real_connect(), and compile the driver (the username and
- password are built into the driver for security reasons).
- If you chose to not create either a username and/or a password,
- leave the corresponding entry at 0.
+ password are built into the driver for security reasons). If you
+ choose to not create either a username and/or a password, leave the
+ corresponding entry at 0.
Use mysqladmin to create any databases you want to provide - the
names are later used in the efun db_connect() to connect to
@@ -32,7 +32,7 @@
To connect to your mySQL-server, use the efun db_connect(). It
takes only one argument which is the name of the database (which
- must exist). The return-value of db_connect() is an integer
+ must exist). The return-value of db_connect() is an integer
representing the unique handle to the database with which you will
identify your connection later.
@@ -94,6 +94,16 @@
db_conv_string()
+ -- Caveats --
+
+ The driver enables automatic reconnects on the database connections.
+ This means that if a connection is lost - the most common case for
+ this is timeouts, which by default happen after 28800 seconds of
+ inactivity - an attempt will be made to establish a new connection to
+ the database server. When that happens, all session state (temprary
+ tables and state changes from SET statements) will be lost. It's best
+ not to rely on such state.
+
EXAMPLE
A simple server to store aliases could be implemented like this:
diff --git a/doc/concepts/native b/doc/concepts/native
index 13cf008..49b9b38 100644
--- a/doc/concepts/native
+++ b/doc/concepts/native
@@ -97,7 +97,7 @@
These exist only in compat mode (creator() is
identical with getuid()).
- object_name(),function_exists()
+ object_name(), function_exists()
In !compat mode, the returned filenames start with a
leading '/', in compat mode they don't.
@@ -134,18 +134,21 @@
--- In Detail ---
Userids of the Master
- The masters (e)uid is determined by a call to
+ The master's (e)uid is determined by a call to
master->get_master_uid().
+
In strict-euids mode, the result has to be a string,
otherwise the driver won't start up at all. If the result is
- valid it is set as the masters uid and euid.
+ valid it is set as the master's uid and euid.
+
In !strict-euids mode, the result may be any value: 0 or a
string are treated as the uid to set, a non-zero integer
leads to the use of the uid set in the default 'global'
wizlist entry, and any other value defaults to 0.
The euid is either set to the returned string (if any),
or to 0.
- The masters uid is determined only on startup this way,
+
+ The master's uid is determined only on startup this way;
at runtime the uids of a reloaded master determined as
for every object by a call to the appropriate driver
hooks.
@@ -156,8 +159,10 @@
evaluated (H_LOAD_UIDS, H_CLONE_UIDS) and the result set
as (e)uid. The result may be a single value, in which case the
euid is set to 0, or an array ({ uid, euid }).
+
In strict-euids mode, both uid and euid must be 0 or a string,
any other value causes the load/clone to fail.
+
In !strict-euids mode, the uid (however returned) may also be
a non-zero integer to use the uid of the global
wizlist entry as uid. The euid is then
diff --git a/doc/concepts/negotiation b/doc/concepts/negotiation
index ed2318f..f00aba9 100644
--- a/doc/concepts/negotiation
+++ b/doc/concepts/negotiation
@@ -6,14 +6,14 @@
between a client (the 'telnet' program or a mud client) and a
server (the game driver). Most of the options offered by the
protocol are optional and need to be negotiated between the
- client and the server. Consequently, and due to their
+ client and the server. Consequently, and due to their
specialized nature, mud clients don't have to support the full
telnet option feature set.
For the server to find out if a client supports the telnet
- protocol at all, one good approach is to a simple, commonly
- used telnet command to the client. If the client reacts
- conform to the protocol (or sends telnet commands itself), the
+ protocol at all, one good approach is to issue a simple,
+ commonly used telnet command to the client. If the client reaction
+ conforms to the protocol (or sends telnet commands itself), the
mud can continue to negotiate further options. If the client
does not react, the mud can safely refrain from further
negotiations.
@@ -22,58 +22,58 @@
the telnet related RFCs (available for example on
http://www.faqs.org/rfcs):
- RFC Titel rel. Code
+ RFC Title rel. Code
- 495 TELNET Protocol Specification
- 513 Comments on the new TELNET specifications
- 559 Comments on the new TELNET Protocol and its Implem
- 595 Some Thoughts in Defense of the TELNET Go-Ahead
- 596 Second Thoughts on Telnet Go-Ahead
- 652 Telnet Output Carriage-Return Disposition Option NAOCRD 10
- 653 Telnet Output Horizontal Tabstops Option NAOHTS 11
- 654 Telnet Output Horizontal Tab Disposition Option NAOHTD 12
- 655 Telnet Output Formfeed Disposition Option NAOFFD 13
- 656 Telnet Output Vertical Tabstops Option NAOVTS 14
- 657 Telnet Output Vertical Tab Disposition Option NAOVTD 15
- 658 Telnet Output Linefeed Disposition NAOLFD 16
- 698 Telnet Extended Ascii Option X-ASCII 17
- 727 Telnet Logout Option LOGOUT 18
- 728 A Minor Pitfall in the Telnet Protocol
- 735 Revised TELNET Byte Macro Option BM 19
- 749 Telnet SUPDUP-OUTPUT Option SUPDUP 22
- 764 Telnet Protocol Specification
- 779 Telnet SEND-LOCATION Option SENDLOC 23
- 818 The Remote User Telnet Service
- 854 Telnet Protocol Specification
- 855 Telnet Option Specifications
- 856 Telnet Binary Transmission BINARY 0
- 857 Telnet Echo Option ECHO 1
- 858 Telnet Suppress Go Ahead Option SGA 3
- 859 Telnet Status Option STATUS 5
- 860 Telnet Timing Mark Option TM 6
- 861 Telnet Extended Options - List Option EXOPL 255
- 884 Telnet Terminal Type Option TTYPE 24
- 885 Telnet End of Record Option EOR 25
- 930 Telnet Terminal Type Option TTYPE 24
- 933 Output Marking Telnet Option OUTMRK 27
- 946 Telnet Terminal Location Number Option TTYLOC 28
- 1043 Telnet Data Entry Terminal Option DODIIS Implement DET 20
- 1053 Telnet X.3 PAD Option X.3-PAD 30
- 1073 Telnet Window Size Option NAWS 31
- 1079 Telnet Terminal Speed Option TSPEED 32
- 1080 Telnet Remote Flow Control Option FLOWCTRL 33
- 1091 Telnet Terminal-Type Option TTYPE 24
- 1096 Telnet X Display Location Option XDISPLOC 35
- 1116 Telnet Linemode Option LINEMODE 34
- 1143 The Q Method of Implementing TELNET Option Negotia
- 1184 Telnet Linemode Option LINEMODE 34
- 1372 Telnet Remote Flow Control Option FLOWCTRL 33
- 1408 Telnet Environment Option ENVIRON 36
- 1571 Telnet Environment Option Interoperability Issues
- 1572 Telnet Environment Option NEWENV 39
- 2066 Telnet Charset Option CHARSET 42
- 2217 Telnet Com Port Control Option COMPORT 44
- 2877 5250 Telnet Enhancements
+ 495 TELNET Protocol Specification
+ 513 Comments on the new TELNET specifications
+ 559 Comments on the new TELNET Protocol and its Implem
+ 595 Some Thoughts in Defense of the TELNET Go-Ahead
+ 596 Second Thoughts on Telnet Go-Ahead
+ 652 Telnet Output Carriage-Return Disposition Option NAOCRD 10
+ 653 Telnet Output Horizontal Tabstops Option NAOHTS 11
+ 654 Telnet Output Horizontal Tab Disposition Option NAOHTD 12
+ 655 Telnet Output Formfeed Disposition Option NAOFFD 13
+ 656 Telnet Output Vertical Tabstops Option NAOVTS 14
+ 657 Telnet Output Vertical Tab Disposition Option NAOVTD 15
+ 658 Telnet Output Linefeed Disposition NAOLFD 16
+ 698 Telnet Extended Ascii Option X-ASCII 17
+ 727 Telnet Logout Option LOGOUT 18
+ 728 A Minor Pitfall in the Telnet Protocol
+ 735 Revised TELNET Byte Macro Option BM 19
+ 749 Telnet SUPDUP-OUTPUT Option SUPDUP 22
+ 764 Telnet Protocol Specification
+ 779 Telnet SEND-LOCATION Option SENDLOC 23
+ 818 The Remote User Telnet Service
+ 854 Telnet Protocol Specification
+ 855 Telnet Option Specifications
+ 856 Telnet Binary Transmission BINARY 0
+ 857 Telnet Echo Option ECHO 1
+ 858 Telnet Suppress Go Ahead Option SGA 3
+ 859 Telnet Status Option STATUS 5
+ 860 Telnet Timing Mark Option TM 6
+ 861 Telnet Extended Options - List Option EXOPL 255
+ 884 Telnet Terminal Type Option TTYPE 24
+ 885 Telnet End of Record Option EOR 25
+ 930 Telnet Terminal Type Option TTYPE 24
+ 933 Output Marking Telnet Option OUTMRK 27
+ 946 Telnet Terminal Location Number Option TTYLOC 28
+ 1043 Telnet Data Entry Terminal Option DODIIS Implement DET 20
+ 1053 Telnet X.3 PAD Option X.3-PAD 30
+ 1073 Telnet Window Size Option NAWS 31
+ 1079 Telnet Terminal Speed Option TSPEED 32
+ 1080 Telnet Remote Flow Control Option FLOWCTRL 33
+ 1091 Telnet Terminal-Type Option TTYPE 24
+ 1096 Telnet X Display Location Option XDISPLOC 35
+ 1116 Telnet Linemode Option LINEMODE 34
+ 1143 The Q Method of Implementing TELNET Option Negotia
+ 1184 Telnet Linemode Option LINEMODE 34
+ 1372 Telnet Remote Flow Control Option FLOWCTRL 33
+ 1408 Telnet Environment Option ENVIRON 36
+ 1571 Telnet Environment Option Interoperability Issues
+ 1572 Telnet Environment Option NEWENV 39
+ 2066 Telnet Charset Option CHARSET 42
+ 2217 Telnet Com Port Control Option COMPORT 44
+ 2877 5250 Telnet Enhancements
All negotiations start with the special character IAC which is
defined in /usr/include/arpa/telnet.h (or in
@@ -81,8 +81,7 @@
255. Negotiations are based on different telnetoptions (their
values are defined in telnet.h too). Before a negotiation can
start the client and the server have to agree that they
- support the option.
- This works in the following way:
+ support the option. This works in the following way:
If a client wants to send something to the server it has to
send 'IAC WILL option' (For terminaltype negotation this would
@@ -100,17 +99,17 @@
sent a WILL or WONT it has to reply with either 'IAC WILL
option' if it supports the option or 'IAC WONT option' if not.
- A small example: Lets assume we want to negotiating
+ A small example: Lets assume we want to negotiate
terminaltype. (TELOPT_TTYPE with value 24). client is the
telnet executable on the playerside, the server is the
gamedriver.
client server
IAC WILL TTYPE
- IAC DO TTYPE
+ IAC DO TTYPE
Or:
- IAC DO TTYPE
+ IAC DO TTYPE
IAC WILL TTYPE
After this we are ready to transfer the terminaltype from the
@@ -137,18 +136,18 @@
Example: (we have exchanged WILL/DO already)
client server
- IAC SB TTYPE SEND IAC SE
+ IAC SB TTYPE SEND IAC SE
IAC SB TTYPE IS VT200 IAC SE
- IAC SB TTYPE SEND IAC SE
+ IAC SB TTYPE SEND IAC SE
IAC SB TTYPE IS VT100 IAC SE
- IAC SB TTYPE SEND IAC SE
+ IAC SB TTYPE SEND IAC SE
IAC SB TTYPE IS VT52 IAC SE
- IAC SB TTYPE SEND IAC SE
+ IAC SB TTYPE SEND IAC SE
IAC SB TTYPE IS VT52 IAC SE
/* this marks that we have all terminaltypes. We decide to use the
* vt200 mode so we have to skip to VT200
*/
- IAC SB TTYPE SEND IAC SE
+ IAC SB TTYPE SEND IAC SE
IAC SB TTYPE IS VT200 IAC SE
@@ -166,7 +165,7 @@
Example: (WILL/DO exchanged)
client server
IAC SB NAWS 0 80 0 24 IAC SE /* the standard vt100 windowsize */
- /* no reply */
+ /* no reply */
And, a bit less important but most complex, the LINEMODE (34)
option. It was implemented it due to the fact, that
@@ -178,7 +177,7 @@
commandline-editing for the client. If a client supports
LINEMODE it HAS to support this modechange. The client will
reply with IAC SB LINEMODE LM_MODE MODE_EDIT|MODE_ACK IAC SE
- (x|y is bitwise or). Thats it for linemode. (You will perhaps
+ (x|y is bitwise or). That's it for linemode. (You will perhaps
receive other IAC SB LINEMODEs with other LM_xxx ... you may
ignore them. (At least IRIX 5.x sends IAC SB LINEMODE LM_SLC
.... IAC SE which declares the local characterset.)).
@@ -191,9 +190,9 @@
IAC SB LINEMODE LM_MODE
MODE_EDIT|MODE_ACK IAC SE
- Note: The option is much more funnier as it looks here, it for
- example supports a mixed mode between linemode and
- charactermode... flushing the input at certain characters (at
+ Note: The option is more interesting than it looks here. For
+ example it supports a mixed mode between linemode and
+ charactermode, flushing the input at certain characters (at
ESC or TAB for shell-like commandline completition). We suggest
reading RFC 1184.
@@ -232,7 +231,7 @@
using binary_message() (appropiate meaning sending the
right DO/DONT/WILL/WONT if not sent before and using the SB
return values).
- 3.1. Sent IAC DO TTYPE IAC DO NAWS IAC DO LINEMODE at the
+ 3.1. Send IAC DO TTYPE IAC DO NAWS IAC DO LINEMODE at the
first time you can do it (before cat()ing /WELCOME perhaps).
3.2. Note all sent and received WILL/WONT/DO/DONT options for
conforming to the standard, avoiding endless loops and for
@@ -243,7 +242,7 @@
linkdead or quits. You won't need to save this data.
3.4. Lower_case() terminaltypes... ;)
3.5. Use reasonable defaultvalues if the client does not
- support one of the options. (columns 80,lines 24 if not
+ support one of the options. (columns 80, lines 24 if not
NAWS, unknown or vt100 for no terminaltype)
The WILL/WONT/DO/DONT data is best saved in a mapping looking
@@ -287,6 +286,7 @@
Tinyfugue and some other mudclients usually do not support
negotiations.
+
Except for TF, which supports the Telnet End-Of-Record option
as marker for the end of the prompt. So if you send IAC EOR
after every prompt, it will print the prompt always in the
@@ -306,7 +306,6 @@
For getting RFCs you can for example use
ftp://ftp.uni-erlangen.de/pub/doc/rfc/
-
BUGS
Not all aspects of the options are mentioned to keep this doc
at a reasonable size. Refer to the RFCs to get more confused.
diff --git a/doc/concepts/objects b/doc/concepts/objects
index b9c7eb9..bae3b30 100644
--- a/doc/concepts/objects
+++ b/doc/concepts/objects
@@ -10,10 +10,10 @@
The only way to manipulate the data contained in an object is
via one of the functions defined by the object.
- Every single thing in a mud is an object. Rooms are objects.
- Weapons are objects. Even your character is an object (a special
+ Every single thing in a mud is an object. Rooms are objects.
+ Weapons are objects. Even your character is an object (a special
kind of object called "interactive" but still an object in most
- every respect). Each object (except possibly virtual objects) in
+ every respect). Each object (except possibly virtual objects) in
the mud is associated with some file written in LPC (in the mud's
directory structure) that describes how the object is to interact
with the gamedriver and the rest of the objects in the mud.
diff --git a/doc/concepts/overloading b/doc/concepts/overloading
index 06209e9..70c3544 100644
--- a/doc/concepts/overloading
+++ b/doc/concepts/overloading
@@ -6,10 +6,12 @@
A function is called 'overloaded' if it is defined more than once
in an object. This can happen if the object inherits other objects
which have defined a function with the same name.
+
Usually the overloading is wanted and intended by the inheriting
object to change the behaviour of the function it overloads.
To call the overloaded functions from the overloading object the
::-operator is used.
+
From outside the object only one of the functions can be called
via call_other() or the like; this will be the topmost of all
overloaded functions.
@@ -37,12 +39,12 @@
foo() {
a::foo();
- b::foo();
- write("C");
- }
+ b::foo();
+ write("C");
+ }
- To call "players/alfe/c"->foo() will now result in the output of
- ABC.
+ To call "players/alfe/c"->foo() will now result in the output of
+ ABC.
SEE ALSO
modifiers(LPC), inheritance(C), functions(LPC)
diff --git a/doc/concepts/pcre b/doc/concepts/pcre
index f863ffd..4c4cc02 100644
--- a/doc/concepts/pcre
+++ b/doc/concepts/pcre
@@ -1,58 +1,54 @@
SYNOPSIS
PCRE - Perl-compatible regular expressions
-
DESCRIPTION
- This document describes the regular expressions supported by the
- PCRE package. When the package is compiled into the driver, the
- macro __PCRE__ is defined.
+ This document describes the regular expressions supported by the PCRE
+ package. When the package is compiled into the driver, the macro
+ __PCRE__ is defined.
- Most of this manpage is lifted directly from the original PCRE
- manpage (dated January 2003).
+ Most of this manpage is lifted directly from the original PCRE manpage
+ (dated January 2003).
- The PCRE library is a set of functions that implement regular
- expression pattern matching using the same syntax and semantics
- as Perl 5, with just a few differences (see below). The
- current implementation corresponds to Perl 5.005, with some
- additional features from later versions. This includes some
- experimental, incomplete support for UTF-8 encoded strings.
- Details of exactly what is and what is not supported are given
- below.
-
+ The PCRE library is a set of functions that implement regular
+ expression pattern matching using the same syntax and semantics as
+ Perl 5, with just a few differences (see below). The current
+ implementation corresponds to Perl 5.005, with some additional features
+ from later versions. This includes some experimental, incomplete
+ support for UTF-8 encoded strings. Details of exactly what is and what
+ is not supported are given below.
PCRE REGULAR EXPRESSION DETAILS
+ The syntax and semantics of the regular expressions supported by PCRE
+ are described below. Regular expressions are also described in the Perl
+ documentation and in a number of other books, some of which have
+ copious examples. Jeffrey Friedl's "Mastering Regular Expressions",
+ published by O'Reilly, covers them in great detail. The description
+ here is intended as reference documentation.
- The syntax and semantics of the regular expressions supported by PCRE
- are described below. Regular expressions are also described in the Perl
- documentation and in a number of other books, some of which have copi-
- ous examples. Jeffrey Friedl's "Mastering Regular Expressions", pub-
- lished by O'Reilly, covers them in great detail. The description here
- is intended as reference documentation.
+ The basic operation of PCRE is on strings of bytes. However, there is
+ also support for UTF-8 character strings. To use this support you must
+ build PCRE to include UTF-8 support, and then call pcre_compile() with
+ the PCRE_UTF8 option. How this affects the pattern matching is
+ mentioned in several places below. There is also a summary of UTF-8
+ features in the section on UTF-8 support in the main pcre page.
- The basic operation of PCRE is on strings of bytes. However, there is
- also support for UTF-8 character strings. To use this support you must
- build PCRE to include UTF-8 support, and then call pcre_compile() with
- the PCRE_UTF8 option. How this affects the pattern matching is men-
- tioned in several places below. There is also a summary of UTF-8 fea-
- tures in the section on UTF-8 support in the main pcre page.
-
- A regular expression is a pattern that is matched against a subject
- string from left to right. Most characters stand for themselves in a
- pattern, and match the corresponding characters in the subject. As a
- trivial example, the pattern
+ A regular expression is a pattern that is matched against a subject
+ string from left to right. Most characters stand for themselves in a
+ pattern, and match the corresponding characters in the subject. As a
+ trivial example, the pattern
The quick brown fox
- matches a portion of a subject string that is identical to itself. The
- power of regular expressions comes from the ability to include alterna-
- tives and repetitions in the pattern. These are encoded in the pattern
- by the use of meta-characters, which do not stand for themselves but
- instead are interpreted in some special way.
+ matches a portion of a subject string that is identical to itself. The
+ power of regular expressions comes from the ability to include
+ alternatives and repetitions in the pattern. These are encoded in the
+ pattern by the use of meta-characters, which do not stand for
+ themselves but instead are interpreted in some special way.
- There are two different sets of meta-characters: those that are recog-
- nized anywhere in the pattern except within square brackets, and those
- that are recognized in square brackets. Outside square brackets, the
- meta-characters are as follows:
+ There are two different sets of meta-characters: those that are
+ recognized anywhere in the pattern except within square brackets, and
+ those that are recognized in square brackets. Outside square brackets,
+ the meta-characters are as follows:
\ general escape character with several uses
^ assert start of string (or line, in multiline mode)
@@ -70,8 +66,8 @@
also "possessive quantifier"
{ start min/max quantifier
- Part of a pattern that is in square brackets is called a "character
- class". In a character class the only meta-characters are:
+ Part of a pattern that is in square brackets is called a "character
+ class". In a character class the only meta-characters are:
\ general escape character
^ negate the class, but only if the first character
@@ -80,34 +76,32 @@
syntax)
] terminates the character class
- The following sections describe the use of each of the meta-characters.
-
+ The following sections describe the use of each of the meta-characters.
BACKSLASH
+ The backslash character has several uses. Firstly, if it is followed by
+ a non-alphameric character, it takes away any special meaning that
+ character may have. This use of backslash as an escape character
+ applies both inside and outside character classes.
- The backslash character has several uses. Firstly, if it is followed by
- a non-alphameric character, it takes away any special meaning that
- character may have. This use of backslash as an escape character
- applies both inside and outside character classes.
+ For example, if you want to match a * character, you write \* in the
+ pattern. This escaping action applies whether or not the following
+ character would otherwise be interpreted as a meta-character, so it is
+ always safe to precede a non-alphameric with backslash to specify that
+ it stands for itself. In particular, if you want to match a backslash,
+ you write \\.
- For example, if you want to match a * character, you write \* in the
- pattern. This escaping action applies whether or not the following
- character would otherwise be interpreted as a meta-character, so it is
- always safe to precede a non-alphameric with backslash to specify that
- it stands for itself. In particular, if you want to match a backslash,
- you write \\.
+ If a pattern is compiled with the PCRE_EXTENDED option, whitespace in
+ the pattern (other than in a character class) and characters between a
+ # outside a character class and the next newline character are ignored.
+ An escaping backslash can be used to include a whitespace or #
+ character as part of the pattern.
- If a pattern is compiled with the PCRE_EXTENDED option, whitespace in
- the pattern (other than in a character class) and characters between a
- # outside a character class and the next newline character are ignored.
- An escaping backslash can be used to include a whitespace or # charac-
- ter as part of the pattern.
-
- If you want to remove the special meaning from a sequence of charac-
- ters, you can do so by putting them between \Q and \E. This is differ-
- ent from Perl in that $ and @ are handled as literals in \Q...\E
- sequences in PCRE, whereas in Perl, $ and @ cause variable interpola-
- tion. Note the following examples:
+ If you want to remove the special meaning from a sequence of
+ characters, you can do so by putting them between \Q and \E. This is
+ different from Perl in that $ and @ are handled as literals in \Q...\E
+ sequences in PCRE, whereas in Perl, $ and @ cause variable
+ interpolation. Note the following examples:
Pattern PCRE matches Perl matches
@@ -116,15 +110,15 @@
\Qabc\$xyz\E abc\$xyz abc\$xyz
\Qabc\E\$\Qxyz\E abc$xyz abc$xyz
- The \Q...\E sequence is recognized both inside and outside character
- classes.
+ The \Q...\E sequence is recognized both inside and outside character
+ classes.
- A second use of backslash provides a way of encoding non-printing char-
- acters in patterns in a visible manner. There is no restriction on the
- appearance of non-printing characters, apart from the binary zero that
- terminates a pattern, but when a pattern is being prepared by text
- editing, it is usually easier to use one of the following escape
- sequences than the binary character it represents:
+ A second use of backslash provides a way of encoding non-printing
+ characters in patterns in a visible manner. There is no restriction on
+ the appearance of non-printing characters, apart from the binary zero
+ that terminates a pattern, but when a pattern is being prepared by text
+ editing, it is usually easier to use one of the following escape
+ sequences than the binary character it represents:
\a alarm, that is, the BEL character (hex 07)
\cx "control-x", where x is any character
@@ -137,45 +131,45 @@
\xhh character with hex code hh
\x{hhh..} character with hex code hhh... (UTF-8 mode only)
- The precise effect of \cx is as follows: if x is a lower case letter,
- it is converted to upper case. Then bit 6 of the character (hex 40) is
- inverted. Thus \cz becomes hex 1A, but \c{ becomes hex 3B, while \c;
- becomes hex 7B.
+ The precise effect of \cx is as follows: if x is a lower case letter,
+ it is converted to upper case. Then bit 6 of the character (hex 40) is
+ inverted. Thus \cz becomes hex 1A, but \c{ becomes hex 3B, while \c;
+ becomes hex 7B.
- After \x, from zero to two hexadecimal digits are read (letters can be
- in upper or lower case). In UTF-8 mode, any number of hexadecimal dig-
- its may appear between \x{ and }, but the value of the character code
- must be less than 2**31 (that is, the maximum hexadecimal value is
- 7FFFFFFF). If characters other than hexadecimal digits appear between
- \x{ and }, or if there is no terminating }, this form of escape is not
- recognized. Instead, the initial \x will be interpreted as a basic hex-
- adecimal escape, with no following digits, giving a byte whose value is
- zero.
+ After \x, from zero to two hexadecimal digits are read (letters can be
+ in upper or lower case). In UTF-8 mode, any number of hexadecimal
+ dig-its may appear between \x{ and }, but the value of the character
+ code must be less than 2**31 (that is, the maximum hexadecimal value is
+ 7FFFFFFF). If characters other than hexadecimal digits appear between
+ \x{ and }, or if there is no terminating }, this form of escape is not
+ recognized. Instead, the initial \x will be interpreted as a basic
+ hexadecimal escape, with no following digits, giving a byte whose value
+ is zero.
- Characters whose value is less than 256 can be defined by either of the
- two syntaxes for \x when PCRE is in UTF-8 mode. There is no difference
- in the way they are handled. For example, \xdc is exactly the same as
- \x{dc}.
+ Characters whose value is less than 256 can be defined by either of the
+ two syntaxes for \x when PCRE is in UTF-8 mode. There is no difference
+ in the way they are handled. For example, \xdc is exactly the same as
+ \x{dc}.
- After \0 up to two further octal digits are read. In both cases, if
- there are fewer than two digits, just those that are present are used.
- Thus the sequence \0\x\07 specifies two binary zeros followed by a BEL
- character (code value 7). Make sure you supply two digits after the
- initial zero if the character that follows is itself an octal digit.
+ After \0 up to two further octal digits are read. In both cases, if
+ there are fewer than two digits, just those that are present are used.
+ Thus the sequence \0\x\07 specifies two binary zeros followed by a BEL
+ character (code value 7). Make sure you supply two digits after the
+ initial zero if the character that follows is itself an octal digit.
- The handling of a backslash followed by a digit other than 0 is compli-
- cated. Outside a character class, PCRE reads it and any following dig-
- its as a decimal number. If the number is less than 10, or if there
- have been at least that many previous capturing left parentheses in the
- expression, the entire sequence is taken as a back reference. A
- description of how this works is given later, following the discussion
- of parenthesized subpatterns.
+ The handling of a backslash followed by a digit other than 0 is
+ complicated. Outside a character class, PCRE reads it and any following
+ digits as a decimal number. If the number is less than 10, or if there
+ have been at least that many previous capturing left parentheses in the
+ expression, the entire sequence is taken as a back reference. A
+ description of how this works is given later, following the discussion
+ of parenthesized subpatterns.
- Inside a character class, or if the decimal number is greater than 9
- and there have not been that many capturing subpatterns, PCRE re-reads
- up to three octal digits following the backslash, and generates a sin-
- gle byte from the least significant 8 bits of the value. Any subsequent
- digits stand for themselves. For example:
+ Inside a character class, or if the decimal number is greater than 9
+ and there have not been that many capturing subpatterns, PCRE re-reads
+ up to three octal digits following the backslash, and generates a
+ single byte from the least significant 8 bits of the value. Any
+ subsequent digits stand for themselves. For example:
\040 is another way of writing a space
\40 is the same, provided there are fewer than 40
@@ -192,16 +186,16 @@
\81 is either a back reference, or a binary zero
followed by the two characters "8" and "1"
- Note that octal values of 100 or greater must not be introduced by a
- leading zero, because no more than three octal digits are ever read.
+ Note that octal values of 100 or greater must not be introduced by a
+ leading zero, because no more than three octal digits are ever read.
- All the sequences that define a single byte value or a single UTF-8
- character (in UTF-8 mode) can be used both inside and outside character
- classes. In addition, inside a character class, the sequence \b is
- interpreted as the backspace character (hex 08). Outside a character
- class it has a different meaning (see below).
+ All the sequences that define a single byte value or a single UTF-8
+ character (in UTF-8 mode) can be used both inside and outside character
+ classes. In addition, inside a character class, the sequence \b is
+ interpreted as the backspace character (hex 08). Outside a character
+ class it has a different meaning (see below).
- The third use of backslash is for specifying generic character types:
+ The third use of backslash is for specifying generic character types:
\d any decimal digit
\D any character that is not a decimal digit
@@ -210,35 +204,35 @@
\w any "word" character
\W any "non-word" character
- Each pair of escape sequences partitions the complete set of characters
- into two disjoint sets. Any given character matches one, and only one,
- of each pair.
+ Each pair of escape sequences partitions the complete set of characters
+ into two disjoint sets. Any given character matches one, and only one,
+ of each pair.
- In UTF-8 mode, characters with values greater than 255 never match \d,
- \s, or \w, and always match \D, \S, and \W.
+ In UTF-8 mode, characters with values greater than 255 never match \d,
+ \s, or \w, and always match \D, \S, and \W.
- For compatibility with Perl, \s does not match the VT character (code
- 11). This makes it different from the the POSIX "space" class. The \s
- characters are HT (9), LF (10), FF (12), CR (13), and space (32).
+ For compatibility with Perl, \s does not match the VT character (code
+ 11). This makes it different from the the POSIX "space" class. The \s
+ characters are HT (9), LF (10), FF (12), CR (13), and space (32).
- A "word" character is any letter or digit or the underscore character,
- that is, any character which can be part of a Perl "word". The defini-
- tion of letters and digits is controlled by PCRE's character tables,
- and may vary if locale- specific matching is taking place (see "Locale
- support" in the pcreapi page). For example, in the "fr" (French)
- locale, some character codes greater than 128 are used for accented
- letters, and these are matched by \w.
+ A "word" character is any letter or digit or the underscore character,
+ that is, any character which can be part of a Perl "word". The
+ definition of letters and digits is controlled by PCRE's character
+ tables, and may vary if locale-specific matching is taking place (see
+ "Locale support" in the pcreapi page). For example, in the "fr"
+ (French) locale, some character codes greater than 128 are used for
+ accented letters, and these are matched by \w.
- These character type sequences can appear both inside and outside char-
- acter classes. They each match one character of the appropriate type.
- If the current matching point is at the end of the subject string, all
- of them fail, since there is no character to match.
+ These character type sequences can appear both inside and outside
+ character classes. They each match one character of the appropriate
+ type. If the current matching point is at the end of the subject
+ string, all of them fail, since there is no character to match.
- The fourth use of backslash is for certain simple assertions. An asser-
- tion specifies a condition that has to be met at a particular point in
- a match, without consuming any characters from the subject string. The
- use of subpatterns for more complicated assertions is described below.
- The backslashed assertions are
+ The fourth use of backslash is for certain simple assertions. An
+ assertion specifies a condition that has to be met at a particular
+ point in a match, without consuming any characters from the subject
+ string. The use of subpatterns for more complicated assertions is
+ described below. The backslashed assertions are:
\b matches at a word boundary
\B matches when not at a word boundary
@@ -247,205 +241,196 @@
\z matches at end of subject
\G matches at first matching position in subject
- These assertions may not appear in character classes (but note that \b
- has a different meaning, namely the backspace character, inside a char-
- acter class).
+ These assertions may not appear in character classes (but note that \b
+ has a different meaning, namely the backspace character, inside a
+ character class).
- A word boundary is a position in the subject string where the current
- character and the previous character do not both match \w or \W (i.e.
- one matches \w and the other matches \W), or the start or end of the
- string if the first or last character matches \w, respectively.
+ A word boundary is a position in the subject string where the current
+ character and the previous character do not both match \w or \W (i.e.
+ one matches \w and the other matches \W), or the start or end of the
+ string if the first or last character matches \w, respectively.
- The \A, \Z, and \z assertions differ from the traditional circumflex
- and dollar (described below) in that they only ever match at the very
- start and end of the subject string, whatever options are set. Thus,
- they are independent of multiline mode.
+ The \A, \Z, and \z assertions differ from the traditional circumflex
+ and dollar (described below) in that they only ever match at the very
+ start and end of the subject string, whatever options are set. Thus,
+ they are independent of multiline mode.
- They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options. If the
- startoffset argument of pcre_exec() is non-zero, indicating that match-
- ing is to start at a point other than the beginning of the subject, \A
- can never match. The difference between \Z and \z is that \Z matches
- before a newline that is the last character of the string as well as at
- the end of the string, whereas \z matches only at the end.
+ They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options. If the
+ startoffset argument of pcre_exec() is non-zero, indicating that
+ matching is to start at a point other than the beginning of the
+ subject, \A can never match. The difference between \Z and \z is that
+ \Z matches before a newline that is the last character of the string as
+ well as at the end of the string, whereas \z matches only at the end.
- The \G assertion is true only when the current matching position is at
- the start point of the match, as specified by the startoffset argument
- of pcre_exec(). It differs from \A when the value of startoffset is
- non-zero. By calling pcre_exec() multiple times with appropriate argu-
- ments, you can mimic Perl's /g option, and it is in this kind of imple-
- mentation where \G can be useful.
+ The \G assertion is true only when the current matching position is at
+ the start point of the match, as specified by the startoffset argument
+ of pcre_exec(). It differs from \A when the value of startoffset is
+ non-zero. By calling pcre_exec() multiple times with appropriate
+ arguments, you can mimic Perl's /g option, and it is in this kind of
+ implementation where \G can be useful.
- Note, however, that PCRE's interpretation of \G, as the start of the
- current match, is subtly different from Perl's, which defines it as the
- end of the previous match. In Perl, these can be different when the
- previously matched string was empty. Because PCRE does just one match
- at a time, it cannot reproduce this behaviour.
+ Note, however, that PCRE's interpretation of \G, as the start of the
+ current match, is subtly different from Perl's, which defines it as the
+ end of the previous match. In Perl, these can be different when the
+ previously matched string was empty. Because PCRE does just one match
+ at a time, it cannot reproduce this behaviour.
- If all the alternatives of a pattern begin with \G, the expression is
- anchored to the starting match position, and the "anchored" flag is set
- in the compiled regular expression.
-
+ If all the alternatives of a pattern begin with \G, the expression is
+ anchored to the starting match position, and the "anchored" flag is set
+ in the compiled regular expression.
CIRCUMFLEX AND DOLLAR
+ Outside a character class, in the default matching mode, the circumflex
+ character is an assertion which is true only if the current matching
+ point is at the start of the subject string. If the startoffset
+ argument of pcre_exec() is non-zero, circumflex can never match if the
+ PCRE_MULTILINE option is unset. Inside a character class, circumflex
+ has an entirely different meaning (see below).
- Outside a character class, in the default matching mode, the circumflex
- character is an assertion which is true only if the current matching
- point is at the start of the subject string. If the startoffset argu-
- ment of pcre_exec() is non-zero, circumflex can never match if the
- PCRE_MULTILINE option is unset. Inside a character class, circumflex
- has an entirely different meaning (see below).
+ Circumflex need not be the first character of the pattern if a number
+ of alternatives are involved, but it should be the first thing in each
+ alternative in which it appears if the pattern is ever to match that
+ branch. If all possible alternatives start with a circumflex, that is,
+ if the pattern is constrained to match only at the start of the
+ subject, it is said to be an "anchored" pattern. (There are also other
+ constructs that can cause a pattern to be anchored.)
- Circumflex need not be the first character of the pattern if a number
- of alternatives are involved, but it should be the first thing in each
- alternative in which it appears if the pattern is ever to match that
- branch. If all possible alternatives start with a circumflex, that is,
- if the pattern is constrained to match only at the start of the sub-
- ject, it is said to be an "anchored" pattern. (There are also other
- constructs that can cause a pattern to be anchored.)
+ A dollar character is an assertion which is true only if the current
+ matching point is at the end of the subject string, or immediately
+ before a newline character that is the last character in the string (by
+ default). Dollar need not be the last character of the pattern if a
+ number of alternatives are involved, but it should be the last item in
+ any branch in which it appears. Dollar has no special meaning in a
+ character class.
- A dollar character is an assertion which is true only if the current
- matching point is at the end of the subject string, or immediately
- before a newline character that is the last character in the string (by
- default). Dollar need not be the last character of the pattern if a
- number of alternatives are involved, but it should be the last item in
- any branch in which it appears. Dollar has no special meaning in a
- character class.
+ The meaning of dollar can be changed so that it matches only at the
+ very end of the string, by setting the PCRE_DOLLAR_ENDONLY option at
+ compile time. This does not affect the \Z assertion.
- The meaning of dollar can be changed so that it matches only at the
- very end of the string, by setting the PCRE_DOLLAR_ENDONLY option at
- compile time. This does not affect the \Z assertion.
+ The meanings of the circumflex and dollar characters are changed if the
+ PCRE_MULTILINE option is set. When this is the case, they match
+ immediately after and immediately before an internal newline character,
+ respectively, in addition to matching at the start and end of the
+ subject string. For example, the pattern /^abc$/ matches the subject
+ string "def\nabc" in multiline mode, but not otherwise. Consequently,
+ patterns that are anchored in single line mode because all branches
+ start with ^ are not anchored in multiline mode, and a match for
+ circumflex is possible when the startoffset argument of pcre_exec() is
+ non-zero. The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE
+ is set.
- The meanings of the circumflex and dollar characters are changed if the
- PCRE_MULTILINE option is set. When this is the case, they match immedi-
- ately after and immediately before an internal newline character,
- respectively, in addition to matching at the start and end of the sub-
- ject string. For example, the pattern /^abc$/ matches the subject
- string "def\nabc" in multiline mode, but not otherwise. Consequently,
- patterns that are anchored in single line mode because all branches
- start with ^ are not anchored in multiline mode, and a match for cir-
- cumflex is possible when the startoffset argument of pcre_exec() is
- non-zero. The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE
- is set.
-
- Note that the sequences \A, \Z, and \z can be used to match the start
- and end of the subject in both modes, and if all branches of a pattern
- start with \A it is always anchored, whether PCRE_MULTILINE is set or
- not.
-
+ Note that the sequences \A, \Z, and \z can be used to match the start
+ and end of the subject in both modes, and if all branches of a pattern
+ start with \A it is always anchored, whether PCRE_MULTILINE is set or
+ not.
FULL STOP (PERIOD, DOT)
-
- Outside a character class, a dot in the pattern matches any one charac-
- ter in the subject, including a non-printing character, but not (by
- default) newline. In UTF-8 mode, a dot matches any UTF-8 character,
- which might be more than one byte long, except (by default) for new-
- line. If the PCRE_DOTALL option is set, dots match newlines as well.
- The handling of dot is entirely independent of the handling of circum-
- flex and dollar, the only relationship being that they both involve
- newline characters. Dot has no special meaning in a character class.
-
+ Outside a character class, a dot in the pattern matches any one
+ character in the subject, including a non-printing character, but not
+ (by default) newline. In UTF-8 mode, a dot matches any UTF-8 character,
+ which might be more than one byte long, except (by default) for
+ newline. If the PCRE_DOTALL option is set, dots match newlines as well.
+ The handling of dot is entirely independent of the handling of
+ circumflex and dollar, the only relationship being that they both
+ involve newline characters. Dot has no special meaning in a character
+ class.
MATCHING A SINGLE BYTE
+ Outside a character class, the escape sequence \C matches any one byte,
+ both in and out of UTF-8 mode. Unlike a dot, it always matches a
+ newline. The feature is provided in Perl in order to match individual
+ bytes in UTF-8 mode. Because it breaks up UTF-8 characters into
+ individual bytes, what remains in the string may be a malformed UTF-8
+ string. For this reason it is best avoided.
- Outside a character class, the escape sequence \C matches any one byte,
- both in and out of UTF-8 mode. Unlike a dot, it always matches a new-
- line. The feature is provided in Perl in order to match individual
- bytes in UTF-8 mode. Because it breaks up UTF-8 characters into indi-
- vidual bytes, what remains in the string may be a malformed UTF-8
- string. For this reason it is best avoided.
-
- PCRE does not allow \C to appear in lookbehind assertions (see below),
- because in UTF-8 mode it makes it impossible to calculate the length of
- the lookbehind.
-
+ PCRE does not allow \C to appear in lookbehind assertions (see below),
+ because in UTF-8 mode it makes it impossible to calculate the length of
+ the lookbehind.
SQUARE BRACKETS
+ An opening square bracket introduces a character class, terminated by a
+ closing square bracket. A closing square bracket on its own is not
+ special. If a closing square bracket is required as a member of the
+ class, it should be the first data character in the class (after an
+ initial circumflex, if present) or escaped with a backslash.
- An opening square bracket introduces a character class, terminated by a
- closing square bracket. A closing square bracket on its own is not spe-
- cial. If a closing square bracket is required as a member of the class,
- it should be the first data character in the class (after an initial
- circumflex, if present) or escaped with a backslash.
+ A character class matches a single character in the subject. In UTF-8
+ mode, the character may occupy more than one byte. A matched character
+ must be in the set of characters defined by the class, unless the first
+ character in the class definition is a circumflex, in which case the
+ subject character must not be in the set defined by the class. If a
+ circumflex is actually required as a member of the class, ensure it is
+ not the first character, or escape it with a backslash.
- A character class matches a single character in the subject. In UTF-8
- mode, the character may occupy more than one byte. A matched character
- must be in the set of characters defined by the class, unless the first
- character in the class definition is a circumflex, in which case the
- subject character must not be in the set defined by the class. If a
- circumflex is actually required as a member of the class, ensure it is
- not the first character, or escape it with a backslash.
+ For example, the character class [aeiou] matches any lower case vowel,
+ while [^aeiou] matches any character that is not a lower case vowel.
+ Note that a circumflex is just a convenient notation for specifying the
+ characters which are in the class by enumerating those that are not. It
+ is not an assertion: it still consumes a character from the subject
+ string, and fails if the current pointer is at the end of the string.
- For example, the character class [aeiou] matches any lower case vowel,
- while [^aeiou] matches any character that is not a lower case vowel.
- Note that a circumflex is just a convenient notation for specifying the
- characters which are in the class by enumerating those that are not. It
- is not an assertion: it still consumes a character from the subject
- string, and fails if the current pointer is at the end of the string.
+ In UTF-8 mode, characters with values greater than 255 can be included
+ in a class as a literal string of bytes, or by using the \x{ escaping
+ mechanism.
- In UTF-8 mode, characters with values greater than 255 can be included
- in a class as a literal string of bytes, or by using the \x{ escaping
- mechanism.
+ When caseless matching is set, any letters in a class represent both
+ their upper case and lower case versions, so for example, a caseless
+ [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not
+ match "A", whereas a caseful version would. PCRE does not support the
+ concept of case for characters with values greater than 255.
- When caseless matching is set, any letters in a class represent both
- their upper case and lower case versions, so for example, a caseless
- [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not
- match "A", whereas a caseful version would. PCRE does not support the
- concept of case for characters with values greater than 255.
+ The newline character is never treated in any special way in character
+ classes, whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE
+ options is. A class such as [^a] will always match a newline.
- The newline character is never treated in any special way in character
- classes, whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE
- options is. A class such as [^a] will always match a newline.
+ The minus (hyphen) character can be used to specify a range of
+ characters in a character class. For example, [d-m] matches any letter
+ between d and m, inclusive. If a minus character is required in a
+ class, it must be escaped with a backslash or appear in a position
+ where it cannot be interpreted as indicating a range, typically as the
+ first or last character in the class.
- The minus (hyphen) character can be used to specify a range of charac-
- ters in a character class. For example, [d-m] matches any letter
- between d and m, inclusive. If a minus character is required in a
- class, it must be escaped with a backslash or appear in a position
- where it cannot be interpreted as indicating a range, typically as the
- first or last character in the class.
+ It is not possible to have the literal character "]" as the end
+ character of a range. A pattern such as [W-]46] is interpreted as a
+ class of two characters ("W" and "-") followed by a literal string
+ "46]", so it would match "W46]" or "-46]". However, if the "]" is
+ escaped with a backslash it is interpreted as the end of range, so
+ [W-\]46] is interpreted as a single class containing a range followed
+ by two separate characters. The octal or hexadecimal representation of
+ "]" can also be used to end a range.
- It is not possible to have the literal character "]" as the end charac-
- ter of a range. A pattern such as [W-]46] is interpreted as a class of
- two characters ("W" and "-") followed by a literal string "46]", so it
- would match "W46]" or "-46]". However, if the "]" is escaped with a
- backslash it is interpreted as the end of range, so [W-\]46] is inter-
- preted as a single class containing a range followed by two separate
- characters. The octal or hexadecimal representation of "]" can also be
- used to end a range.
+ Ranges operate in the collating sequence of character values. They can
+ also be used for characters specified numerically, for example
+ [\000-\037]. In UTF-8 mode, ranges can include characters whose values
+ are greater than 255, for example [\x{100}-\x{2ff}].
- Ranges operate in the collating sequence of character values. They can
- also be used for characters specified numerically, for example
- [\000-\037]. In UTF-8 mode, ranges can include characters whose values
- are greater than 255, for example [\x{100}-\x{2ff}].
+ If a range that includes letters is used when caseless matching is set,
+ it matches the letters in either case. For example, [W-c] is equivalent
+ to [][\^_`wxyzabc], matched caselessly, and if character tables for the
+ "fr" locale are in use, [\xc8-\xcb] matches accented E characters in
+ both cases.
- If a range that includes letters is used when caseless matching is set,
- it matches the letters in either case. For example, [W-c] is equivalent
- to [][\^_`wxyzabc], matched caselessly, and if character tables for the
- "fr" locale are in use, [\xc8-\xcb] matches accented E characters in
- both cases.
+ The character types \d, \D, \s, \S, \w, and \W may also appear in a
+ character class, and add the characters that they match to the class.
+ For example, [\dABCDEF] matches any hexadecimal digit. A circumflex can
+ conveniently be used with the upper case character types to specify a
+ more restricted set of characters than the matching lower case type.
+ For example, the class [^\W_] matches any letter or digit, but not
+ underscore.
- The character types \d, \D, \s, \S, \w, and \W may also appear in a
- character class, and add the characters that they match to the class.
- For example, [\dABCDEF] matches any hexadecimal digit. A circumflex can
- conveniently be used with the upper case character types to specify a
- more restricted set of characters than the matching lower case type.
- For example, the class [^\W_] matches any letter or digit, but not
- underscore.
-
- All non-alphameric characters other than \, -, ^ (at the start) and the
- terminating ] are non-special in character classes, but it does no harm
- if they are escaped.
-
+ All non-alphameric characters other than \, -, ^ (at the start) and the
+ terminating ] are non-special in character classes, but it does no harm
+ if they are escaped.
POSIX CHARACTER CLASSES
-
- Perl supports the POSIX notation for character classes, which uses
- names enclosed by [: and :] within the enclosing square brackets. PCRE
- also supports this notation. For example,
+ Perl supports the POSIX notation for character classes, which uses
+ names enclosed by [: and :] within the enclosing square brackets. PCRE
+ also supports this notation. For example,
[01[:alpha:]%]
- matches "0", "1", any alphabetic character, or "%". The supported class
- names are
+ matches "0", "1", any alphabetic character, or "%". The supported class
+ names are
alnum letters and digits
alpha letters
@@ -462,168 +447,158 @@
word "word" characters (same as \w)
xdigit hexadecimal digits
- The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13),
- and space (32). Notice that this list includes the VT character (code
- 11). This makes "space" different to \s, which does not include VT (for
- Perl compatibility).
+ The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13),
+ and space (32). Notice that this list includes the VT character (code
+ 11). This makes "space" different to \s, which does not include VT (for
+ Perl compatibility).
- The name "word" is a Perl extension, and "blank" is a GNU extension
- from Perl 5.8. Another Perl extension is negation, which is indicated
- by a ^ character after the colon. For example,
+ The name "word" is a Perl extension, and "blank" is a GNU extension
+ from Perl 5.8. Another Perl extension is negation, which is indicated
+ by a ^ character after the colon. For example,
[12[:^digit:]]
- matches "1", "2", or any non-digit. PCRE (and Perl) also recognize the
- POSIX syntax [.ch.] and [=ch=] where "ch" is a "collating element", but
- these are not supported, and an error is given if they are encountered.
+ matches "1", "2", or any non-digit. PCRE (and Perl) also recognize the
+ POSIX syntax [.ch.] and [=ch=] where "ch" is a "collating element", but
+ these are not supported, and an error is given if they are encountered.
- In UTF-8 mode, characters with values greater than 255 do not match any
- of the POSIX character classes.
-
+ In UTF-8 mode, characters with values greater than 255 do not match any
+ of the POSIX character classes.
VERTICAL BAR
-
- Vertical bar characters are used to separate alternative patterns. For
- example, the pattern
+ Vertical bar characters are used to separate alternative patterns. For
+ example, the pattern
gilbert|sullivan
- matches either "gilbert" or "sullivan". Any number of alternatives may
- appear, and an empty alternative is permitted (matching the empty
- string). The matching process tries each alternative in turn, from
- left to right, and the first one that succeeds is used. If the alterna-
- tives are within a subpattern (defined below), "succeeds" means match-
- ing the rest of the main pattern as well as the alternative in the sub-
- pattern.
-
+ matches either "gilbert" or "sullivan". Any number of alternatives may
+ appear, and an empty alternative is permitted (matching the empty
+ string). The matching process tries each alternative in turn, from
+ left to right, and the first one that succeeds is used. If the
+ alternatives are within a subpattern (defined below), "succeeds" means
+ matching the rest of the main pattern as well as the alternative in the
+ subpattern.
INTERNAL OPTION SETTING
-
- The settings of the PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and
- PCRE_EXTENDED options can be changed from within the pattern by a
- sequence of Perl option letters enclosed between "(?" and ")". The
- option letters are
+ The settings of the PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and
+ PCRE_EXTENDED options can be changed from within the pattern by a
+ sequence of Perl option letters enclosed between "(?" and ")". The
+ option letters are
i for PCRE_CASELESS
m for PCRE_MULTILINE
s for PCRE_DOTALL
x for PCRE_EXTENDED
- For example, (?im) sets caseless, multiline matching. It is also possi-
- ble to unset these options by preceding the letter with a hyphen, and a
- combined setting and unsetting such as (?im-sx), which sets PCRE_CASE-
- LESS and PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED,
- is also permitted. If a letter appears both before and after the
- hyphen, the option is unset.
+ For example, (?im) sets caseless, multiline matching. It is also
+ possible to unset these options by preceding the letter with a hyphen,
+ and a combined setting and unsetting such as (?im-sx), which sets
+ PCRE_CASELESS and PCRE_MULTILINE while unsetting PCRE_DOTALL and
+ PCRE_EXTENDED, is also permitted. If a letter appears both before and
+ after the hyphen, the option is unset.
- When an option change occurs at top level (that is, not inside subpat-
- tern parentheses), the change applies to the remainder of the pattern
- that follows. If the change is placed right at the start of a pattern,
- PCRE extracts it into the global options (and it will therefore show up
- in data extracted by the pcre_fullinfo() function).
+ When an option change occurs at top level (that is, not inside
+ subpattern parentheses), the change applies to the remainder of the
+ pattern that follows. If the change is placed right at the start of a
+ pattern, PCRE extracts it into the global options (and it will
+ therefore show up in data extracted by the pcre_fullinfo() function).
- An option change within a subpattern affects only that part of the cur-
- rent pattern that follows it, so
+ An option change within a subpattern affects only that part of the
+ current pattern that follows it, so
(a(?i)b)c
- matches abc and aBc and no other strings (assuming PCRE_CASELESS is not
- used). By this means, options can be made to have different settings
- in different parts of the pattern. Any changes made in one alternative
- do carry on into subsequent branches within the same subpattern. For
- example,
+ matches abc and aBc and no other strings (assuming PCRE_CASELESS is not
+ used). By this means, options can be made to have different settings
+ in different parts of the pattern. Any changes made in one alternative
+ do carry on into subsequent branches within the same subpattern. For
+ example,
(a(?i)b|c)
- matches "ab", "aB", "c", and "C", even though when matching "C" the
- first branch is abandoned before the option setting. This is because
- the effects of option settings happen at compile time. There would be
- some very weird behaviour otherwise.
+ matches "ab", "aB", "c", and "C", even though when matching "C" the
+ first branch is abandoned before the option setting. This is because
+ the effects of option settings happen at compile time. There would be
+ some very weird behaviour otherwise.
- The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can be changed
- in the same way as the Perl-compatible options by using the characters
- U and X respectively. The (?X) flag setting is special in that it must
- always occur earlier in the pattern than any of the additional features
- it turns on, even when it is at top level. It is best put at the start.
-
+ The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can be changed
+ in the same way as the Perl-compatible options by using the characters
+ U and X respectively. The (?X) flag setting is special in that it must
+ always occur earlier in the pattern than any of the additional features
+ it turns on, even when it is at top level. It is best put at the start.
SUBPATTERNS
+ Subpatterns are delimited by parentheses (round brackets), which can be
+ nested. Marking part of a pattern as a subpattern does two things:
- Subpatterns are delimited by parentheses (round brackets), which can be
- nested. Marking part of a pattern as a subpattern does two things:
-
- 1. It localizes a set of alternatives. For example, the pattern
+ 1. It localizes a set of alternatives. For example, the pattern
cat(aract|erpillar|)
- matches one of the words "cat", "cataract", or "caterpillar". Without
- the parentheses, it would match "cataract", "erpillar" or the empty
- string.
+ matches one of the words "cat", "cataract", or "caterpillar". Without
+ the parentheses, it would match "cataract", "erpillar" or the empty
+ string.
- 2. It sets up the subpattern as a capturing subpattern (as defined
- above). When the whole pattern matches, that portion of the subject
- string that matched the subpattern is passed back to the caller via the
- ovector argument of pcre_exec(). Opening parentheses are counted from
- left to right (starting from 1) to obtain the numbers of the capturing
- subpatterns.
+ 2. It sets up the subpattern as a capturing subpattern (as defined
+ above). When the whole pattern matches, that portion of the subject
+ string that matched the subpattern is passed back to the caller via the
+ ovector argument of pcre_exec(). Opening parentheses are counted from
+ left to right (starting from 1) to obtain the numbers of the capturing
+ subpatterns.
- For example, if the string "the red king" is matched against the pat-
- tern
+ For example, if the string "the red king" is matched against the
+ pattern
the ((red|white) (king|queen))
- the captured substrings are "red king", "red", and "king", and are num-
- bered 1, 2, and 3, respectively.
+ the captured substrings are "red king", "red", and "king", and are
+ numbered 1, 2, and 3, respectively.
- The fact that plain parentheses fulfil two functions is not always
- helpful. There are often times when a grouping subpattern is required
- without a capturing requirement. If an opening parenthesis is followed
- by a question mark and a colon, the subpattern does not do any captur-
- ing, and is not counted when computing the number of any subsequent
- capturing subpatterns. For example, if the string "the white queen" is
- matched against the pattern
+ The fact that plain parentheses fulfil two functions is not always
+ helpful. There are often times when a grouping subpattern is required
+ without a capturing requirement. If an opening parenthesis is followed
+ by a question mark and a colon, the subpattern does not do any
+ capturing, and is not counted when computing the number of any
+ subsequent capturing subpatterns. For example, if the string "the white
+ queen" is matched against the pattern
the ((?:red|white) (king|queen))
- the captured substrings are "white queen" and "queen", and are numbered
- 1 and 2. The maximum number of capturing subpatterns is 65535, and the
- maximum depth of nesting of all subpatterns, both capturing and non-
- capturing, is 200.
+ the captured substrings are "white queen" and "queen", and are numbered
+ 1 and 2. The maximum number of capturing subpatterns is 65535, and the
+ maximum depth of nesting of all subpatterns, both capturing and
+ noncapturing, is 200.
- As a convenient shorthand, if any option settings are required at the
- start of a non-capturing subpattern, the option letters may appear
- between the "?" and the ":". Thus the two patterns
+ As a convenient shorthand, if any option settings are required at the
+ start of a non-capturing subpattern, the option letters may appear
+ between the "?" and the ":". Thus the two patterns
(?i:saturday|sunday)
(?:(?i)saturday|sunday)
- match exactly the same set of strings. Because alternative branches are
- tried from left to right, and options are not reset until the end of
- the subpattern is reached, an option setting in one branch does affect
- subsequent branches, so the above patterns match "SUNDAY" as well as
- "Saturday".
-
+ match exactly the same set of strings. Because alternative branches are
+ tried from left to right, and options are not reset until the end of
+ the subpattern is reached, an option setting in one branch does affect
+ subsequent branches, so the above patterns match "SUNDAY" as well as
+ "Saturday".
NAMED SUBPATTERNS
+ Identifying capturing parentheses by number is simple, but it can be
+ very hard to keep track of the numbers in complicated regular
+ expressions. Furthermore, if an expression is modified, the numbers may
+ change. To help with the difficulty, PCRE supports the naming of
+ subpatterns, something that Perl does not provide. The Python syntax
+ (?P<name>...) is used. Names consist of alphanumeric characters and
+ underscores, and must be unique within a pattern.
- Identifying capturing parentheses by number is simple, but it can be
- very hard to keep track of the numbers in complicated regular expres-
- sions. Furthermore, if an expression is modified, the numbers may
- change. To help with the difficulty, PCRE supports the naming of sub-
- patterns, something that Perl does not provide. The Python syntax
- (?P<name>...) is used. Names consist of alphanumeric characters and
- underscores, and must be unique within a pattern.
-
- Named capturing parentheses are still allocated numbers as well as
- names. The PCRE API provides function calls for extracting the name-to-
- number translation table from a compiled pattern. For further details
- see the pcreapi documentation.
-
+ Named capturing parentheses are still allocated numbers as well as
+ names. The PCRE API provides function calls for extracting the name-to-
+ number translation table from a compiled pattern. For further details
+ see the pcreapi documentation.
REPETITION
-
- Repetition is specified by quantifiers, which can follow any of the
- following items:
+ Repetition is specified by quantifiers, which can follow any of the
+ following items:
a literal data character
the . metacharacter
@@ -633,693 +608,681 @@
a back reference (see next section)
a parenthesized subpattern (unless it is an assertion)
- The general repetition quantifier specifies a minimum and maximum num-
- ber of permitted matches, by giving the two numbers in curly brackets
- (braces), separated by a comma. The numbers must be less than 65536,
- and the first must be less than or equal to the second. For example:
+ The general repetition quantifier specifies a minimum and maximum
+ number of permitted matches, by giving the two numbers in curly
+ brackets (braces), separated by a comma. The numbers must be less than
+ 65536, and the first must be less than or equal to the second. For
+ example:
z{2,4}
- matches "zz", "zzz", or "zzzz". A closing brace on its own is not a
- special character. If the second number is omitted, but the comma is
- present, there is no upper limit; if the second number and the comma
- are both omitted, the quantifier specifies an exact number of required
- matches. Thus
+ matches "zz", "zzz", or "zzzz". A closing brace on its own is not a
+ special character. If the second number is omitted, but the comma is
+ present, there is no upper limit; if the second number and the comma
+ are both omitted, the quantifier specifies an exact number of required
+ matches. Thus
[aeiou]{3,}
- matches at least 3 successive vowels, but may match many more, while
+ matches at least 3 successive vowels, but may match many more, while
\d{8}
- matches exactly 8 digits. An opening curly bracket that appears in a
- position where a quantifier is not allowed, or one that does not match
- the syntax of a quantifier, is taken as a literal character. For exam-
- ple, {,6} is not a quantifier, but a literal string of four characters.
+ matches exactly 8 digits. An opening curly bracket that appears in a
+ position where a quantifier is not allowed, or one that does not match
+ the syntax of a quantifier, is taken as a literal character. For
+ example, {,6} is not a quantifier, but a literal string of four
+ characters.
- In UTF-8 mode, quantifiers apply to UTF-8 characters rather than to
- individual bytes. Thus, for example, \x{100}{2} matches two UTF-8 char-
- acters, each of which is represented by a two-byte sequence.
+ In UTF-8 mode, quantifiers apply to UTF-8 characters rather than to
+ individual bytes. Thus, for example, \x{100}{2} matches two UTF-8
+ characters, each of which is represented by a two-byte sequence.
- The quantifier {0} is permitted, causing the expression to behave as if
- the previous item and the quantifier were not present.
+ The quantifier {0} is permitted, causing the expression to behave as if
+ the previous item and the quantifier were not present.
- For convenience (and historical compatibility) the three most common
- quantifiers have single-character abbreviations:
+ For convenience (and historical compatibility) the three most common
+ quantifiers have single-character abbreviations:
* is equivalent to {0,}
+ is equivalent to {1,}
? is equivalent to {0,1}
- It is possible to construct infinite loops by following a subpattern
- that can match no characters with a quantifier that has no upper limit,
- for example:
+ It is possible to construct infinite loops by following a subpattern
+ that can match no characters with a quantifier that has no upper limit,
+ for example:
(a?)*
- Earlier versions of Perl and PCRE used to give an error at compile time
- for such patterns. However, because there are cases where this can be
- useful, such patterns are now accepted, but if any repetition of the
- subpattern does in fact match no characters, the loop is forcibly bro-
- ken.
+ Earlier versions of Perl and PCRE used to give an error at compile time
+ for such patterns. However, because there are cases where this can be
+ useful, such patterns are now accepted, but if any repetition of the
+ subpattern does in fact match no characters, the loop is forcibly
+ broken.
- By default, the quantifiers are "greedy", that is, they match as much
- as possible (up to the maximum number of permitted times), without
- causing the rest of the pattern to fail. The classic example of where
- this gives problems is in trying to match comments in C programs. These
- appear between the sequences /* and */ and within the sequence, indi-
- vidual * and / characters may appear. An attempt to match C comments by
- applying the pattern
+ By default, the quantifiers are "greedy", that is, they match as much
+ as possible (up to the maximum number of permitted times), without
+ causing the rest of the pattern to fail. The classic example of where
+ this gives problems is in trying to match comments in C programs. These
+ appear between the sequences /* and */ and within the sequence,
+ individual * and / characters may appear. An attempt to match C
+ comments by applying the pattern
/\*.*\*/
- to the string
+ to the string
- /* first command */ not comment /* second comment */
+ /* first command */ not comment /* second comment */
- fails, because it matches the entire string owing to the greediness of
- the .* item.
+ fails, because it matches the entire string owing to the greediness of
+ the .* item.
- However, if a quantifier is followed by a question mark, it ceases to
- be greedy, and instead matches the minimum number of times possible, so
- the pattern
+ However, if a quantifier is followed by a question mark, it ceases to
+ be greedy, and instead matches the minimum number of times possible, so
+ the pattern
/\*.*?\*/
- does the right thing with the C comments. The meaning of the various
- quantifiers is not otherwise changed, just the preferred number of
- matches. Do not confuse this use of question mark with its use as a
- quantifier in its own right. Because it has two uses, it can sometimes
- appear doubled, as in
+ does the right thing with the C comments. The meaning of the various
+ quantifiers is not otherwise changed, just the preferred number of
+ matches. Do not confuse this use of question mark with its use as a
+ quantifier in its own right. Because it has two uses, it can sometimes
+ appear doubled, as in
\d??\d
- which matches one digit by preference, but can match two if that is the
- only way the rest of the pattern matches.
+ which matches one digit by preference, but can match two if that is the
+ only way the rest of the pattern matches.
- If the PCRE_UNGREEDY option is set (an option which is not available in
- Perl), the quantifiers are not greedy by default, but individual ones
- can be made greedy by following them with a question mark. In other
- words, it inverts the default behaviour.
+ If the PCRE_UNGREEDY option is set (an option which is not available in
+ Perl), the quantifiers are not greedy by default, but individual ones
+ can be made greedy by following them with a question mark. In other
+ words, it inverts the default behaviour.
- When a parenthesized subpattern is quantified with a minimum repeat
- count that is greater than 1 or with a limited maximum, more store is
- required for the compiled pattern, in proportion to the size of the
- minimum or maximum.
+ When a parenthesized subpattern is quantified with a minimum repeat
+ count that is greater than 1 or with a limited maximum, more store is
+ required for the compiled pattern, in proportion to the size of the
+ minimum or maximum.
- If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equiv-
- alent to Perl's /s) is set, thus allowing the . to match newlines, the
- pattern is implicitly anchored, because whatever follows will be tried
- against every character position in the subject string, so there is no
- point in retrying the overall match at any position after the first.
- PCRE normally treats such a pattern as though it were preceded by \A.
+ If a pattern starts with .* or .{0,} and the PCRE_DOTALL option
+ (equivalent to Perl's /s) is set, thus allowing the . to match
+ newlines, the pattern is implicitly anchored, because whatever follows
+ will be tried against every character position in the subject string,
+ so there is no point in retrying the overall match at any position
+ after the first. PCRE normally treats such a pattern as though it were
+ preceded by \A.
- In cases where it is known that the subject string contains no new-
- lines, it is worth setting PCRE_DOTALL in order to obtain this opti-
- mization, or alternatively using ^ to indicate anchoring explicitly.
+ In cases where it is known that the subject string contains no
+ newlines, it is worth setting PCRE_DOTALL in order to obtain this
+ optimization, or alternatively using ^ to indicate anchoring
+ explicitly.
- However, there is one situation where the optimization cannot be used.
- When .* is inside capturing parentheses that are the subject of a
- backreference elsewhere in the pattern, a match at the start may fail,
- and a later one succeed. Consider, for example:
+ However, there is one situation where the optimization cannot be used.
+ When .* is inside capturing parentheses that are the subject of a
+ backreference elsewhere in the pattern, a match at the start may fail,
+ and a later one succeed. Consider, for example:
(.*)abc\1
- If the subject is "xyz123abc123" the match point is the fourth charac-
- ter. For this reason, such a pattern is not implicitly anchored.
+ If the subject is "xyz123abc123" the match point is the fourth
+ character. For this reason, such a pattern is not implicitly anchored.
- When a capturing subpattern is repeated, the value captured is the sub-
- string that matched the final iteration. For example, after
+ When a capturing subpattern is repeated, the value captured is the
+ substring that matched the final iteration. For example, after
(tweedle[dume]{3}\s*)+
- has matched "tweedledum tweedledee" the value of the captured substring
- is "tweedledee". However, if there are nested capturing subpatterns,
- the corresponding captured values may have been set in previous itera-
- tions. For example, after
+ has matched "tweedledum tweedledee" the value of the captured substring
+ is "tweedledee". However, if there are nested capturing subpatterns,
+ the corresponding captured values may have been set in previous
+ iterations. For example, after
/(a|(b))+/
- matches "aba" the value of the second captured substring is "b".
-
+ matches "aba" the value of the second captured substring is "b".
ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS
+ With both maximizing and minimizing repetition, failure of what follows
+ normally causes the repeated item to be re-evaluated to see if a
+ different number of repeats allows the rest of the pattern to match.
+ Sometimes it is useful to prevent this, either to change the nature of
+ the match, or to cause it fail earlier than it otherwise might, when
+ the author of the pattern knows there is no point in carrying on.
- With both maximizing and minimizing repetition, failure of what follows
- normally causes the repeated item to be re-evaluated to see if a dif-
- ferent number of repeats allows the rest of the pattern to match. Some-
- times it is useful to prevent this, either to change the nature of the
- match, or to cause it fail earlier than it otherwise might, when the
- author of the pattern knows there is no point in carrying on.
-
- Consider, for example, the pattern \d+foo when applied to the subject
- line
+ Consider, for example, the pattern \d+foo when applied to the subject
+ line
123456bar
- After matching all 6 digits and then failing to match "foo", the normal
- action of the matcher is to try again with only 5 digits matching the
- \d+ item, and then with 4, and so on, before ultimately failing.
- "Atomic grouping" (a term taken from Jeffrey Friedl's book) provides
- the means for specifying that once a subpattern has matched, it is not
- to be re-evaluated in this way.
+ After matching all 6 digits and then failing to match "foo", the normal
+ action of the matcher is to try again with only 5 digits matching the
+ \d+ item, and then with 4, and so on, before ultimately failing.
+ "Atomic grouping" (a term taken from Jeffrey Friedl's book) provides
+ the means for specifying that once a subpattern has matched, it is not
+ to be re-evaluated in this way.
- If we use atomic grouping for the previous example, the matcher would
- give up immediately on failing to match "foo" the first time. The nota-
- tion is a kind of special parenthesis, starting with (?> as in this
- example:
+ If we use atomic grouping for the previous example, the matcher would
+ give up immediately on failing to match "foo" the first time. The
+ notation is a kind of special parenthesis, starting with (?> as in this
+ example:
(?>\d+)foo
- This kind of parenthesis "locks up" the part of the pattern it con-
- tains once it has matched, and a failure further into the pattern is
- prevented from backtracking into it. Backtracking past it to previous
- items, however, works as normal.
+ This kind of parenthesis "locks up" the part of the pattern it
+ contains once it has matched, and a failure further into the pattern is
+ prevented from backtracking into it. Backtracking past it to previous
+ items, however, works as normal.
- An alternative description is that a subpattern of this type matches
- the string of characters that an identical standalone pattern would
- match, if anchored at the current point in the subject string.
+ An alternative description is that a subpattern of this type matches
+ the string of characters that an identical standalone pattern would
+ match, if anchored at the current point in the subject string.
- Atomic grouping subpatterns are not capturing subpatterns. Simple cases
- such as the above example can be thought of as a maximizing repeat that
- must swallow everything it can. So, while both \d+ and \d+? are pre-
- pared to adjust the number of digits they match in order to make the
- rest of the pattern match, (?>\d+) can only match an entire sequence of
- digits.
+ Atomic grouping subpatterns are not capturing subpatterns. Simple cases
+ such as the above example can be thought of as a maximizing repeat that
+ must swallow everything it can. So, while both \d+ and \d+? are
+ prepared to adjust the number of digits they match in order to make the
+ rest of the pattern match, (?>\d+) can only match an entire sequence of
+ digits.
- Atomic groups in general can of course contain arbitrarily complicated
- subpatterns, and can be nested. However, when the subpattern for an
- atomic group is just a single repeated item, as in the example above, a
- simpler notation, called a "possessive quantifier" can be used. This
- consists of an additional + character following a quantifier. Using
- this notation, the previous example can be rewritten as
+ Atomic groups in general can of course contain arbitrarily complicated
+ subpatterns, and can be nested. However, when the subpattern for an
+ atomic group is just a single repeated item, as in the example above, a
+ simpler notation, called a "possessive quantifier" can be used. This
+ consists of an additional + character following a quantifier. Using
+ this notation, the previous example can be rewritten as
\d++bar
- Possessive quantifiers are always greedy; the setting of the
- PCRE_UNGREEDY option is ignored. They are a convenient notation for the
- simpler forms of atomic group. However, there is no difference in the
- meaning or processing of a possessive quantifier and the equivalent
- atomic group.
+ Possessive quantifiers are always greedy; the setting of the
+ PCRE_UNGREEDY option is ignored. They are a convenient notation for the
+ simpler forms of atomic group. However, there is no difference in the
+ meaning or processing of a possessive quantifier and the equivalent
+ atomic group.
- The possessive quantifier syntax is an extension to the Perl syntax. It
- originates in Sun's Java package.
+ The possessive quantifier syntax is an extension to the Perl syntax. It
+ originates in Sun's Java package.
- When a pattern contains an unlimited repeat inside a subpattern that
- can itself be repeated an unlimited number of times, the use of an
- atomic group is the only way to avoid some failing matches taking a
- very long time indeed. The pattern
+ When a pattern contains an unlimited repeat inside a subpattern that
+ can itself be repeated an unlimited number of times, the use of an
+ atomic group is the only way to avoid some failing matches taking a
+ very long time indeed. The pattern
(\D+|<\d+>)*[!?]
- matches an unlimited number of substrings that either consist of non-
- digits, or digits enclosed in <>, followed by either ! or ?. When it
- matches, it runs quickly. However, if it is applied to
+ matches an unlimited number of substrings that either consist of non-
+ digits, or digits enclosed in <>, followed by either ! or ?. When it
+ matches, it runs quickly. However, if it is applied to
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
- it takes a long time before reporting failure. This is because the
- string can be divided between the two repeats in a large number of
- ways, and all have to be tried. (The example used [!?] rather than a
- single character at the end, because both PCRE and Perl have an opti-
- mization that allows for fast failure when a single character is used.
- They remember the last single character that is required for a match,
- and fail early if it is not present in the string.) If the pattern is
- changed to
+ it takes a long time before reporting failure. This is because the
+ string can be divided between the two repeats in a large number of
+ ways, and all have to be tried. (The example used [!?] rather than a
+ single character at the end, because both PCRE and Perl have an
+ optimization that allows for fast failure when a single character is
+ used. They remember the last single character that is required for a
+ match, and fail early if it is not present in the string.) If the
+ pattern is changed to
((?>\D+)|<\d+>)*[!?]
- sequences of non-digits cannot be broken, and failure happens quickly.
-
+ sequences of non-digits cannot be broken, and failure happens quickly.
BACK REFERENCES
+ Outside a character class, a backslash followed by a digit greater than
+ 0 (and possibly further digits) is a back reference to a capturing
+ subpattern earlier (that is, to its left) in the pattern, provided
+ there have been that many previous capturing left parentheses.
- Outside a character class, a backslash followed by a digit greater than
- 0 (and possibly further digits) is a back reference to a capturing sub-
- pattern earlier (that is, to its left) in the pattern, provided there
- have been that many previous capturing left parentheses.
+ However, if the decimal number following the backslash is less than 10,
+ it is always taken as a back reference, and causes an error only if
+ there are not that many capturing left parentheses in the entire
+ pattern. In other words, the parentheses that are referenced need not
+ be to the left of the reference for numbers less than 10. See the
+ section entitled "Backslash" above for further details of the handling
+ of digits following a backslash.
- However, if the decimal number following the backslash is less than 10,
- it is always taken as a back reference, and causes an error only if
- there are not that many capturing left parentheses in the entire pat-
- tern. In other words, the parentheses that are referenced need not be
- to the left of the reference for numbers less than 10. See the section
- entitled "Backslash" above for further details of the handling of dig-
- its following a backslash.
-
- A back reference matches whatever actually matched the capturing sub-
- pattern in the current subject string, rather than anything matching
- the subpattern itself (see "Subpatterns as subroutines" below for a way
- of doing that). So the pattern
+ A back reference matches whatever actually matched the capturing
+ subpattern in the current subject string, rather than anything matching
+ the subpattern itself (see "Subpatterns as subroutines" below for a way
+ of doing that). So the pattern
(sens|respons)e and \1ibility
- matches "sense and sensibility" and "response and responsibility", but
- not "sense and responsibility". If caseful matching is in force at the
- time of the back reference, the case of letters is relevant. For exam-
- ple,
+ matches "sense and sensibility" and "response and responsibility", but
+ not "sense and responsibility". If caseful matching is in force at the
+ time of the back reference, the case of letters is relevant. For
+ example,
((?i)rah)\s+\1
- matches "rah rah" and "RAH RAH", but not "RAH rah", even though the
- original capturing subpattern is matched caselessly.
+ matches "rah rah" and "RAH RAH", but not "RAH rah", even though the
+ original capturing subpattern is matched caselessly.
- Back references to named subpatterns use the Python syntax (?P=name).
- We could rewrite the above example as follows:
+ Back references to named subpatterns use the Python syntax (?P=name).
+ We could rewrite the above example as follows:
(?<p1>(?i)rah)\s+(?P=p1)
- There may be more than one back reference to the same subpattern. If a
- subpattern has not actually been used in a particular match, any back
- references to it always fail. For example, the pattern
+ There may be more than one back reference to the same subpattern. If a
+ subpattern has not actually been used in a particular match, any back
+ references to it always fail. For example, the pattern
(a|(bc))\2
- always fails if it starts to match "a" rather than "bc". Because there
- may be many capturing parentheses in a pattern, all digits following
- the backslash are taken as part of a potential back reference number.
- If the pattern continues with a digit character, some delimiter must be
- used to terminate the back reference. If the PCRE_EXTENDED option is
- set, this can be whitespace. Otherwise an empty comment can be used.
+ always fails if it starts to match "a" rather than "bc". Because there
+ may be many capturing parentheses in a pattern, all digits following
+ the backslash are taken as part of a potential back reference number.
+ If the pattern continues with a digit character, some delimiter must be
+ used to terminate the back reference. If the PCRE_EXTENDED option is
+ set, this can be whitespace. Otherwise an empty comment can be used.
- A back reference that occurs inside the parentheses to which it refers
- fails when the subpattern is first used, so, for example, (a\1) never
- matches. However, such references can be useful inside repeated sub-
- patterns. For example, the pattern
+ A back reference that occurs inside the parentheses to which it refers
+ fails when the subpattern is first used, so, for example, (a\1) never
+ matches. However, such references can be useful inside repeated
+ subpatterns. For example, the pattern
(a|b\1)+
- matches any number of "a"s and also "aba", "ababbaa" etc. At each iter-
- ation of the subpattern, the back reference matches the character
- string corresponding to the previous iteration. In order for this to
- work, the pattern must be such that the first iteration does not need
- to match the back reference. This can be done using alternation, as in
- the example above, or by a quantifier with a minimum of zero.
-
+ matches any number of "a"s and also "aba", "ababbaa" etc. At each
+ iteration of the subpattern, the back reference matches the character
+ string corresponding to the previous iteration. In order for this to
+ work, the pattern must be such that the first iteration does not need
+ to match the back reference. This can be done using alternation, as in
+ the example above, or by a quantifier with a minimum of zero.
ASSERTIONS
+ An assertion is a test on the characters following or preceding the
+ current matching point that does not actually consume any characters.
+ The simple assertions coded as \b, \B, \A, \G, \Z, \z, ^ and $ are
+ described above. More complicated assertions are coded as subpatterns.
+ There are two kinds: those that look ahead of the current position in
+ the subject string, and those that look behind it.
- An assertion is a test on the characters following or preceding the
- current matching point that does not actually consume any characters.
- The simple assertions coded as \b, \B, \A, \G, \Z, \z, ^ and $ are
- described above. More complicated assertions are coded as subpatterns.
- There are two kinds: those that look ahead of the current position in
- the subject string, and those that look behind it.
-
- An assertion subpattern is matched in the normal way, except that it
- does not cause the current matching position to be changed. Lookahead
- assertions start with (?= for positive assertions and (?! for negative
- assertions. For example,
+ An assertion subpattern is matched in the normal way, except that it
+ does not cause the current matching position to be changed. Lookahead
+ assertions start with (?= for positive assertions and (?! for negative
+ assertions. For example,
\w+(?=;)
- matches a word followed by a semicolon, but does not include the semi-
- colon in the match, and
+ matches a word followed by a semicolon, but does not include the
+ semicolon in the match, and
foo(?!bar)
- matches any occurrence of "foo" that is not followed by "bar". Note
- that the apparently similar pattern
+ matches any occurrence of "foo" that is not followed by "bar". Note
+ that the apparently similar pattern
(?!foo)bar
- does not find an occurrence of "bar" that is preceded by something
- other than "foo"; it finds any occurrence of "bar" whatsoever, because
- the assertion (?!foo) is always true when the next three characters are
- "bar". A lookbehind assertion is needed to achieve this effect.
+ does not find an occurrence of "bar" that is preceded by something
+ other than "foo"; it finds any occurrence of "bar" whatsoever, because
+ the assertion (?!foo) is always true when the next three characters are
+ "bar". A lookbehind assertion is needed to achieve this effect.
- If you want to force a matching failure at some point in a pattern, the
- most convenient way to do it is with (?!) because an empty string
- always matches, so an assertion that requires there not to be an empty
- string must always fail.
+ If you want to force a matching failure at some point in a pattern, the
+ most convenient way to do it is with (?!) because an empty string
+ always matches, so an assertion that requires there not to be an empty
+ string must always fail.
- Lookbehind assertions start with (?<= for positive assertions and (?<!
- for negative assertions. For example,
+ Lookbehind assertions start with (?<= for positive assertions and (?<!
+ for negative assertions. For example,
(?<!foo)bar
- does find an occurrence of "bar" that is not preceded by "foo". The
- contents of a lookbehind assertion are restricted such that all the
- strings it matches must have a fixed length. However, if there are sev-
- eral alternatives, they do not all have to have the same fixed length.
- Thus
+ does find an occurrence of "bar" that is not preceded by "foo". The
+ contents of a lookbehind assertion are restricted such that all the
+ strings it matches must have a fixed length. However, if there are
+ several alternatives, they do not all have to have the same fixed
+ length. Thus
(?<=bullock|donkey)
- is permitted, but
+ is permitted, but
(?<!dogs?|cats?)
- causes an error at compile time. Branches that match different length
- strings are permitted only at the top level of a lookbehind assertion.
- This is an extension compared with Perl (at least for 5.8), which
- requires all branches to match the same length of string. An assertion
- such as
+ causes an error at compile time. Branches that match different length
+ strings are permitted only at the top level of a lookbehind assertion.
+ This is an extension compared with Perl (at least for 5.8), which
+ requires all branches to match the same length of string. An assertion
+ such as
(?<=ab(c|de))
- is not permitted, because its single top-level branch can match two
- different lengths, but it is acceptable if rewritten to use two top-
- level branches:
+ is not permitted, because its single top-level branch can match two
+ different lengths, but it is acceptable if rewritten to use two top-
+ level branches:
(?<=abc|abde)
- The implementation of lookbehind assertions is, for each alternative,
- to temporarily move the current position back by the fixed width and
- then try to match. If there are insufficient characters before the cur-
- rent position, the match is deemed to fail.
+ The implementation of lookbehind assertions is, for each alternative,
+ to temporarily move the current position back by the fixed width and
+ then try to match. If there are insufficient characters before the
+ current position, the match is deemed to fail.
- PCRE does not allow the \C escape (which matches a single byte in UTF-8
- mode) to appear in lookbehind assertions, because it makes it impossi-
- ble to calculate the length of the lookbehind.
+ PCRE does not allow the \C escape (which matches a single byte in UTF-8
+ mode) to appear in lookbehind assertions, because it makes it
+ impossible to calculate the length of the lookbehind.
- Atomic groups can be used in conjunction with lookbehind assertions to
- specify efficient matching at the end of the subject string. Consider a
- simple pattern such as
+ Atomic groups can be used in conjunction with lookbehind assertions to
+ specify efficient matching at the end of the subject string. Consider a
+ simple pattern such as
abcd$
- when applied to a long string that does not match. Because matching
- proceeds from left to right, PCRE will look for each "a" in the subject
- and then see if what follows matches the rest of the pattern. If the
- pattern is specified as
+ when applied to a long string that does not match. Because matching
+ proceeds from left to right, PCRE will look for each "a" in the subject
+ and then see if what follows matches the rest of the pattern. If the
+ pattern is specified as
^.*abcd$
- the initial .* matches the entire string at first, but when this fails
- (because there is no following "a"), it backtracks to match all but the
- last character, then all but the last two characters, and so on. Once
- again the search for "a" covers the entire string, from right to left,
- so we are no better off. However, if the pattern is written as
+ the initial .* matches the entire string at first, but when this fails
+ (because there is no following "a"), it backtracks to match all but the
+ last character, then all but the last two characters, and so on. Once
+ again the search for "a" covers the entire string, from right to left,
+ so we are no better off. However, if the pattern is written as
^(?>.*)(?<=abcd)
- or, equivalently,
+ or, equivalently,
^.*+(?<=abcd)
- there can be no backtracking for the .* item; it can match only the
- entire string. The subsequent lookbehind assertion does a single test
- on the last four characters. If it fails, the match fails immediately.
- For long strings, this approach makes a significant difference to the
- processing time.
+ there can be no backtracking for the .* item; it can match only the
+ entire string. The subsequent lookbehind assertion does a single test
+ on the last four characters. If it fails, the match fails immediately.
+ For long strings, this approach makes a significant difference to the
+ processing time.
- Several assertions (of any sort) may occur in succession. For example,
+ Several assertions (of any sort) may occur in succession. For example,
(?<=\d{3})(?<!999)foo
- matches "foo" preceded by three digits that are not "999". Notice that
- each of the assertions is applied independently at the same point in
- the subject string. First there is a check that the previous three
- characters are all digits, and then there is a check that the same
- three characters are not "999". This pattern does not match "foo" pre-
- ceded by six characters, the first of which are digits and the last
- three of which are not "999". For example, it doesn't match "123abc-
- foo". A pattern to do that is
+ matches "foo" preceded by three digits that are not "999". Notice that
+ each of the assertions is applied independently at the same point in
+ the subject string. First there is a check that the previous three
+ characters are all digits, and then there is a check that the same
+ three characters are not "999". This pattern does not match "foo"
+ preceded by six characters, the first of which are digits and the last
+ three of which are not "999". For example, it doesn't match
+ "123abcfoo". A pattern to do that is
(?<=\d{3}...)(?<!999)foo
- This time the first assertion looks at the preceding six characters,
- checking that the first three are digits, and then the second assertion
- checks that the preceding three characters are not "999".
+ This time the first assertion looks at the preceding six characters,
+ checking that the first three are digits, and then the second assertion
+ checks that the preceding three characters are not "999".
- Assertions can be nested in any combination. For example,
+ Assertions can be nested in any combination. For example,
(?<=(?<!foo)bar)baz
- matches an occurrence of "baz" that is preceded by "bar" which in turn
- is not preceded by "foo", while
+ matches an occurrence of "baz" that is preceded by "bar" which in turn
+ is not preceded by "foo", while
(?<=\d{3}(?!999)...)foo
- is another pattern which matches "foo" preceded by three digits and any
- three characters that are not "999".
+ is another pattern which matches "foo" preceded by three digits and any
+ three characters that are not "999".
- Assertion subpatterns are not capturing subpatterns, and may not be
- repeated, because it makes no sense to assert the same thing several
- times. If any kind of assertion contains capturing subpatterns within
- it, these are counted for the purposes of numbering the capturing sub-
- patterns in the whole pattern. However, substring capturing is carried
- out only for positive assertions, because it does not make sense for
- negative assertions.
-
+ Assertion subpatterns are not capturing subpatterns, and may not be
+ repeated, because it makes no sense to assert the same thing several
+ times. If any kind of assertion contains capturing subpatterns within
+ it, these are counted for the purposes of numbering the capturing
+ subpatterns in the whole pattern. However, substring capturing is
+ carried out only for positive assertions, because it does not make
+ sense for negative assertions.
CONDITIONAL SUBPATTERNS
-
- It is possible to cause the matching process to obey a subpattern con-
- ditionally or to choose between two alternative subpatterns, depending
- on the result of an assertion, or whether a previous capturing
- subpattern matched or not. The two possible forms of conditional sub-
- pattern are
+ It is possible to cause the matching process to obey a subpattern
+ conditionally or to choose between two alternative subpatterns,
+ depending on the result of an assertion, or whether a previous
+ capturing subpattern matched or not. The two possible forms of
+ conditional subpattern are
(?(condition)yes-pattern)
(?(condition)yes-pattern|no-pattern)
- If the condition is satisfied, the yes-pattern is used; otherwise the
- no-pattern (if present) is used. If there are more than two alterna-
- tives in the subpattern, a compile-time error occurs.
+ If the condition is satisfied, the yes-pattern is used; otherwise the
+ no-pattern (if present) is used. If there are more than two
+ alternatives in the subpattern, a compile-time error occurs.
- There are three kinds of condition. If the text between the parentheses
- consists of a sequence of digits, the condition is satisfied if the
- capturing subpattern of that number has previously matched. The number
- must be greater than zero. Consider the following pattern, which con-
- tains non-significant white space to make it more readable (assume the
- PCRE_EXTENDED option) and to divide it into three parts for ease of
- discussion:
+ There are three kinds of condition. If the text between the parentheses
+ consists of a sequence of digits, the condition is satisfied if the
+ capturing subpattern of that number has previously matched. The number
+ must be greater than zero. Consider the following pattern, which
+ contains non-significant white space to make it more readable (assume
+ the PCRE_EXTENDED option) and to divide it into three parts for ease of
+ discussion:
- ( \( )? [^()]+ (?(1) \) )
+ ( \( )? [^()]+ (?(1) \) )
- The first part matches an optional opening parenthesis, and if that
- character is present, sets it as the first captured substring. The sec-
- ond part matches one or more characters that are not parentheses. The
- third part is a conditional subpattern that tests whether the first set
- of parentheses matched or not. If they did, that is, if subject started
- with an opening parenthesis, the condition is true, and so the yes-pat-
- tern is executed and a closing parenthesis is required. Otherwise,
- since no-pattern is not present, the subpattern matches nothing. In
- other words, this pattern matches a sequence of non-parentheses,
- optionally enclosed in parentheses.
+ The first part matches an optional opening parenthesis, and if that
+ character is present, sets it as the first captured substring. The
+ second part matches one or more characters that are not parentheses.
+ The third part is a conditional subpattern that tests whether the first
+ set of parentheses matched or not. If they did, that is, if subject
+ started with an opening parenthesis, the condition is true, and so the
+ yes-pattern is executed and a closing parenthesis is required.
+ Otherwise, since no-pattern is not present, the subpattern matches
+ nothing. In other words, this pattern matches a sequence of
+ non-parentheses, optionally enclosed in parentheses.
- If the condition is the string (R), it is satisfied if a recursive call
- to the pattern or subpattern has been made. At "top level", the condi-
- tion is false. This is a PCRE extension. Recursive patterns are
- described in the next section.
+ If the condition is the string (R), it is satisfied if a recursive call
+ to the pattern or subpattern has been made. At "top level", the
+ condition is false. This is a PCRE extension. Recursive patterns are
+ described in the next section.
- If the condition is not a sequence of digits or (R), it must be an
- assertion. This may be a positive or negative lookahead or lookbehind
- assertion. Consider this pattern, again containing non-significant
- white space, and with the two alternatives on the second line:
+ If the condition is not a sequence of digits or (R), it must be an
+ assertion. This may be a positive or negative lookahead or lookbehind
+ assertion. Consider this pattern, again containing non-significant
+ white space, and with the two alternatives on the second line:
(?(?=[^a-z]*[a-z])
\d{2}-[a-z]{3}-\d{2} | \d{2}-\d{2}-\d{2} )
- The condition is a positive lookahead assertion that matches an
- optional sequence of non-letters followed by a letter. In other words,
- it tests for the presence of at least one letter in the subject. If a
- letter is found, the subject is matched against the first alternative;
- otherwise it is matched against the second. This pattern matches
- strings in one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are
- letters and dd are digits.
-
+ The condition is a positive lookahead assertion that matches an
+ optional sequence of non-letters followed by a letter. In other words,
+ it tests for the presence of at least one letter in the subject. If a
+ letter is found, the subject is matched against the first alternative;
+ otherwise it is matched against the second. This pattern matches
+ strings in one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are
+ letters and dd are digits.
COMMENTS
+ The sequence (?# marks the start of a comment which continues up to the
+ next closing parenthesis. Nested parentheses are not permitted. The
+ characters that make up a comment play no part in the pattern matching
+ at all.
- The sequence (?# marks the start of a comment which continues up to the
- next closing parenthesis. Nested parentheses are not permitted. The
- characters that make up a comment play no part in the pattern matching
- at all.
-
- If the PCRE_EXTENDED option is set, an unescaped # character outside a
- character class introduces a comment that continues up to the next new-
- line character in the pattern.
-
+ If the PCRE_EXTENDED option is set, an unescaped # character outside a
+ character class introduces a comment that continues up to the next
+ newline character in the pattern.
RECURSIVE PATTERNS
-
- Consider the problem of matching a string in parentheses, allowing for
- unlimited nested parentheses. Without the use of recursion, the best
- that can be done is to use a pattern that matches up to some fixed
- depth of nesting. It is not possible to handle an arbitrary nesting
- depth. Perl has provided an experimental facility that allows regular
- expressions to recurse (amongst other things). It does this by interpo-
- lating Perl code in the expression at run time, and the code can refer
- to the expression itself. A Perl pattern to solve the parentheses prob-
- lem can be created like this:
+ Consider the problem of matching a string in parentheses, allowing for
+ unlimited nested parentheses. Without the use of recursion, the best
+ that can be done is to use a pattern that matches up to some fixed
+ depth of nesting. It is not possible to handle an arbitrary nesting
+ depth. Perl has provided an experimental facility that allows regular
+ expressions to recurse (amongst other things). It does this by
+ interpolating Perl code in the expression at run time, and the code can
+ refer to the expression itself. A Perl pattern to solve the parentheses
+ problem can be created like this:
$re = qr{\( (?: (?>[^()]+) | (?p{$re}) )* \)}x;
- The (?p{...}) item interpolates Perl code at run time, and in this case
- refers recursively to the pattern in which it appears. Obviously, PCRE
- cannot support the interpolation of Perl code. Instead, it supports
- some special syntax for recursion of the entire pattern, and also for
- individual subpattern recursion.
+ The (?p{...}) item interpolates Perl code at run time, and in this case
+ refers recursively to the pattern in which it appears. Obviously, PCRE
+ cannot support the interpolation of Perl code. Instead, it supports
+ some special syntax for recursion of the entire pattern, and also for
+ individual subpattern recursion.
- The special item that consists of (? followed by a number greater than
- zero and a closing parenthesis is a recursive call of the subpattern of
- the given number, provided that it occurs inside that subpattern. (If
- not, it is a "subroutine" call, which is described in the next sec-
- tion.) The special item (?R) is a recursive call of the entire regular
- expression.
+ The special item that consists of (? followed by a number greater than
+ zero and a closing parenthesis is a recursive call of the subpattern of
+ the given number, provided that it occurs inside that subpattern. (If
+ not, it is a "subroutine" call, which is described in the next
+ section.) The special item (?R) is a recursive call of the entire
+ regular expression.
- For example, this PCRE pattern solves the nested parentheses problem
- (assume the PCRE_EXTENDED option is set so that white space is
- ignored):
+ For example, this PCRE pattern solves the nested parentheses problem
+ (assume the PCRE_EXTENDED option is set so that white space is
+ ignored):
\( ( (?>[^()]+) | (?R) )* \)
- First it matches an opening parenthesis. Then it matches any number of
- substrings which can either be a sequence of non-parentheses, or a
- recursive match of the pattern itself (that is a correctly parenthe-
- sized substring). Finally there is a closing parenthesis.
+ First it matches an opening parenthesis. Then it matches any number of
+ substrings which can either be a sequence of non-parentheses, or a
+ recursive match of the pattern itself (that is a correctly
+ parenthesized substring). Finally there is a closing parenthesis.
- If this were part of a larger pattern, you would not want to recurse
- the entire pattern, so instead you could use this:
+ If this were part of a larger pattern, you would not want to recurse
+ the entire pattern, so instead you could use this:
( \( ( (?>[^()]+) | (?1) )* \) )
- We have put the pattern into parentheses, and caused the recursion to
- refer to them instead of the whole pattern. In a larger pattern, keep-
- ing track of parenthesis numbers can be tricky. It may be more conve-
- nient to use named parentheses instead. For this, PCRE uses (?P>name),
- which is an extension to the Python syntax that PCRE uses for named
- parentheses (Perl does not provide named parentheses). We could rewrite
- the above example as follows:
+ We have put the pattern into parentheses, and caused the recursion to
+ refer to them instead of the whole pattern. In a larger pattern,
+ keeping track of parenthesis numbers can be tricky. It may be more
+ convenient to use named parentheses instead. For this, PCRE uses
+ (?P>name), which is an extension to the Python syntax that PCRE uses
+ for named parentheses (Perl does not provide named parentheses). We
+ could rewrite the above example as follows:
(?P<pn> \( ( (?>[^()]+) | (?P>pn) )* \) )
- This particular example pattern contains nested unlimited repeats, and
- so the use of atomic grouping for matching strings of non-parentheses
- is important when applying the pattern to strings that do not match.
- For example, when this pattern is applied to
+ This particular example pattern contains nested unlimited repeats, and
+ so the use of atomic grouping for matching strings of non-parentheses
+ is important when applying the pattern to strings that do not match.
+ For example, when this pattern is applied to
(aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()
- it yields "no match" quickly. However, if atomic grouping is not used,
- the match runs for a very long time indeed because there are so many
- different ways the + and * repeats can carve up the subject, and all
- have to be tested before failure can be reported.
+ it yields "no match" quickly. However, if atomic grouping is not used,
+ the match runs for a very long time indeed because there are so many
+ different ways the + and * repeats can carve up the subject, and all
+ have to be tested before failure can be reported.
- At the end of a match, the values set for any capturing subpatterns are
- those from the outermost level of the recursion at which the subpattern
- value is set. If you want to obtain intermediate values, a callout
- function can be used (see below and the pcrecallout documentation). If
- the pattern above is matched against
+ At the end of a match, the values set for any capturing subpatterns are
+ those from the outermost level of the recursion at which the subpattern
+ value is set. If you want to obtain intermediate values, a callout
+ function can be used (see below and the pcrecallout documentation). If
+ the pattern above is matched against
(ab(cd)ef)
- the value for the capturing parentheses is "ef", which is the last
- value taken on at the top level. If additional parentheses are added,
- giving
+ the value for the capturing parentheses is "ef", which is the last
+ value taken on at the top level. If additional parentheses are added,
+ giving
\( ( ( (?>[^()]+) | (?R) )* ) \)
^ ^
^ ^
- the string they capture is "ab(cd)ef", the contents of the top level
- parentheses. If there are more than 15 capturing parentheses in a pat-
- tern, PCRE has to obtain extra memory to store data during a recursion,
- which it does by using pcre_malloc, freeing it via pcre_free after-
- wards. If no memory can be obtained, the match fails with the
- PCRE_ERROR_NOMEMORY error.
+ the string they capture is "ab(cd)ef", the contents of the top level
+ parentheses. If there are more than 15 capturing parentheses in a
+ pattern, PCRE has to obtain extra memory to store data during a
+ recursion, which it does by using pcre_malloc, freeing it via pcre_free
+ afterwards. If no memory can be obtained, the match fails with the
+ PCRE_ERROR_NOMEMORY error.
- Do not confuse the (?R) item with the condition (R), which tests for
- recursion. Consider this pattern, which matches text in angle brack-
- ets, allowing for arbitrary nesting. Only digits are allowed in nested
- brackets (that is, when recursing), whereas any characters are permit-
- ted at the outer level.
+ Do not confuse the (?R) item with the condition (R), which tests for
+ recursion. Consider this pattern, which matches text in angle
+ brackets, allowing for arbitrary nesting. Only digits are allowed in
+ nested brackets (that is, when recursing), whereas any characters are
+ permitted at the outer level.
< (?: (?(R) \d++ | [^<>]*+) | (?R)) * >
- In this pattern, (?(R) is the start of a conditional subpattern, with
- two different alternatives for the recursive and non-recursive cases.
- The (?R) item is the actual recursive call.
-
+ In this pattern, (?(R) is the start of a conditional subpattern, with
+ two different alternatives for the recursive and non-recursive cases.
+ The (?R) item is the actual recursive call.
SUBPATTERNS AS SUBROUTINES
-
- If the syntax for a recursive subpattern reference (either by number or
- by name) is used outside the parentheses to which it refers, it oper-
- ates like a subroutine in a programming language. An earlier example
- pointed out that the pattern
+ If the syntax for a recursive subpattern reference (either by number or
+ by name) is used outside the parentheses to which it refers, it
+ operates like a subroutine in a programming language. An earlier
+ example pointed out that the pattern
(sens|respons)e and \1ibility
- matches "sense and sensibility" and "response and responsibility", but
- not "sense and responsibility". If instead the pattern
+ matches "sense and sensibility" and "response and responsibility", but
+ not "sense and responsibility". If instead the pattern
(sens|respons)e and (?1)ibility
- is used, it does match "sense and responsibility" as well as the other
- two strings. Such references must, however, follow the subpattern to
- which they refer.
-
+ is used, it does match "sense and responsibility" as well as the other
+ two strings. Such references must, however, follow the subpattern to
+ which they refer.
CALLOUTS
+ Perl has a feature whereby using the sequence (?{...}) causes arbitrary
+ Perl code to be obeyed in the middle of matching a regular expression.
+ This makes it possible, amongst other things, to extract different
+ substrings that match the same pair of parentheses when there is a
+ repetition.
- Perl has a feature whereby using the sequence (?{...}) causes arbitrary
- Perl code to be obeyed in the middle of matching a regular expression.
- This makes it possible, amongst other things, to extract different sub-
- strings that match the same pair of parentheses when there is a repeti-
- tion.
+ PCRE provides a similar feature, but of course it cannot obey arbitrary
+ Perl code. The feature is called "callout". The caller of PCRE provides
+ an external function by putting its entry point in the global variable
+ pcre_callout. By default, this variable contains NULL, which disables
+ all calling out.
- PCRE provides a similar feature, but of course it cannot obey arbitrary
- Perl code. The feature is called "callout". The caller of PCRE provides
- an external function by putting its entry point in the global variable
- pcre_callout. By default, this variable contains NULL, which disables
- all calling out.
-
- Within a regular expression, (?C) indicates the points at which the
- external function is to be called. If you want to identify different
- callout points, you can put a number less than 256 after the letter C.
- The default value is zero. For example, this pattern has two callout
- points:
+ Within a regular expression, (?C) indicates the points at which the
+ external function is to be called. If you want to identify different
+ callout points, you can put a number less than 256 after the letter C.
+ The default value is zero. For example, this pattern has two callout
+ points:
(?C1)abc(?C2)def
- During matching, when PCRE reaches a callout point (and pcre_callout is
- set), the external function is called. It is provided with the number
- of the callout, and, optionally, one item of data originally supplied
- by the caller of pcre_exec(). The callout function may cause matching
- to backtrack, or to fail altogether. A complete description of the
- interface to the callout function is given in the pcrecallout documen-
- tation.
-
+ During matching, when PCRE reaches a callout point (and pcre_callout is
+ set), the external function is called. It is provided with the number
+ of the callout, and, optionally, one item of data originally supplied
+ by the caller of pcre_exec(). The callout function may cause matching
+ to backtrack, or to fail altogether. A complete description of the
+ interface to the callout function is given in the pcrecallout
+ documentation.
DIFFERENCES FROM PERL
- This section escribes the differences in the ways that PCRE and Perl
- handle regular expressions. The differences described here are with
- respect to Perl 5.8.
+ This section escribes the differences in the ways that PCRE and Perl
+ handle regular expressions. The differences described here are with
+ respect to Perl 5.8.
- 1. PCRE does not have full UTF-8 support. Details of what it does have
- are given in the section on UTF-8 support in the main pcre page.
+ 1. PCRE does not have full UTF-8 support. Details of what it does have
+ are given in the section on UTF-8 support in the main pcre page.
- 2. PCRE does not allow repeat quantifiers on lookahead assertions. Perl
- permits them, but they do not mean what you might think. For example,
- (?!a){3} does not assert that the next three characters are not "a". It
- just asserts that the next character is not "a" three times.
+ 2. PCRE does not allow repeat quantifiers on lookahead assertions.
+ Perl permits them, but they do not mean what you might think. For
+ example, (?!a){3} does not assert that the next three characters are
+ not "a". It just asserts that the next character is not "a" three
+ times.
- 3. Capturing subpatterns that occur inside negative lookahead asser-
- tions are counted, but their entries in the offsets vector are never
- set. Perl sets its numerical variables from any such patterns that are
- matched before the assertion fails to match something (thereby succeed-
- ing), but only if the negative lookahead assertion contains just one
- branch.
+ 3. Capturing subpatterns that occur inside negative lookahead
+ assertions are counted, but their entries in the offsets vector are
+ never set. Perl sets its numerical variables from any such patterns
+ that are matched before the assertion fails to match something
+ (thereby succeeding), but only if the negative lookahead assertion
+ contains just one branch.
- 4. Though binary zero characters are supported in the subject string,
- they are not allowed in a pattern string because it is passed as a nor-
- mal C string, terminated by zero. The escape sequence "\0" can be used
- in the pattern to represent a binary zero.
+ 4. Though binary zero characters are supported in the subject string,
+ they are not allowed in a pattern string because it is passed as a
+ normal C string, terminated by zero. The escape sequence "\0" can be
+ used in the pattern to represent a binary zero.
- 5. The following Perl escape sequences are not supported: \l, \u, \L,
- \U, \P, \p, \N, and \X. In fact these are implemented by Perl's general
- string-handling and are not part of its pattern matching engine. If any
- of these are encountered by PCRE, an error is generated.
+ 5. The following Perl escape sequences are not supported: \l, \u, \L,
+ \U, \P, \p, \N, and \X. In fact these are implemented by Perl's general
+ string-handling and are not part of its pattern matching engine. If any
+ of these are encountered by PCRE, an error is generated.
- 6. PCRE does support the \Q...\E escape for quoting substrings. Charac-
- ters in between are treated as literals. This is slightly different
- from Perl in that $ and @ are also handled as literals inside the
- quotes. In Perl, they cause variable interpolation (but of course PCRE
- does not have variables). Note the following examples:
+ 6. PCRE does support the \Q...\E escape for quoting substrings.
+ Characters in between are treated as literals. This is slightly
+ different from Perl in that $ and @ are also handled as literals inside
+ the quotes. In Perl, they cause variable interpolation (but of course
+ PCRE does not have variables). Note the following examples:
Pattern PCRE matches Perl matches
@@ -1328,61 +1291,59 @@
\Qabc\$xyz\E abc\$xyz abc\$xyz
\Qabc\E\$\Qxyz\E abc$xyz abc$xyz
- The \Q...\E sequence is recognized both inside and outside character
- classes.
+ The \Q...\E sequence is recognized both inside and outside character
+ classes.
- 7. Fairly obviously, PCRE does not support the (?{code}) and (?p{code})
- constructions. However, there is some experimental support for recur-
- sive patterns using the non-Perl items (?R), (?number) and (?P>name).
- Also, the PCRE "callout" feature allows an external function to be
- called during pattern matching.
+ 7. Fairly obviously, PCRE does not support the (?{code}) and
+ (?p{code}) constructions. However, there is some experimental support
+ for recursive patterns using the non-Perl items (?R), (?number) and
+ (?P>name). Also, the PCRE "callout" feature allows an external function
+ to be called during pattern matching.
- 8. There are some differences that are concerned with the settings of
- captured strings when part of a pattern is repeated. For example,
- matching "aba" against the pattern /^(a(b)?)+$/ in Perl leaves $2
- unset, but in PCRE it is set to "b".
+ 8. There are some differences that are concerned with the settings of
+ captured strings when part of a pattern is repeated. For example,
+ matching "aba" against the pattern /^(a(b)?)+$/ in Perl leaves $2
+ unset, but in PCRE it is set to "b".
- 9. PCRE provides some extensions to the Perl regular expression
- facilities:
+ 9. PCRE provides some extensions to the Perl regular expression
+ facilities:
- (a) Although lookbehind assertions must match fixed length strings,
- each alternative branch of a lookbehind assertion can match a different
- length of string. Perl requires them all to have the same length.
+ (a) Although lookbehind assertions must match fixed length strings,
+ each alternative branch of a lookbehind assertion can match a different
+ length of string. Perl requires them all to have the same length.
- (b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $
- meta-character matches only at the very end of the string.
+ (b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $
+ meta-character matches only at the very end of the string.
- (c) If PCRE_EXTRA is set, a backslash followed by a letter with no spe-
- cial meaning is faulted.
+ (c) If PCRE_EXTRA is set, a backslash followed by a letter with no
+ special meaning is faulted.
- (d) If PCRE_UNGREEDY is set, the greediness of the repetition quanti-
- fiers is inverted, that is, by default they are not greedy, but if fol-
- lowed by a question mark they are.
+ (d) If PCRE_UNGREEDY is set, the greediness of the repetition
+ quantifiers is inverted, that is, by default they are not greedy, but
+ if followed by a question mark they are.
- (e) PCRE_ANCHORED can be used to force a pattern to be tried only at
- the first matching position in the subject string.
+ (e) PCRE_ANCHORED can be used to force a pattern to be tried only at
+ the first matching position in the subject string.
- (f) The PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and PCRE_NO_AUTO_CAP-
- TURE options for pcre_exec() have no Perl equivalents.
+ (f) The PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and
+ PCRE_NO_AUTO_CAPTURE options for pcre_exec() have no Perl equivalents.
- (g) The (?R), (?number), and (?P>name) constructs allows for recursive
- pattern matching (Perl can do this using the (?p{code}) construct,
- which PCRE cannot support.)
+ (g) The (?R), (?number), and (?P>name) constructs allows for recursive
+ pattern matching (Perl can do this using the (?p{code}) construct,
+ which PCRE cannot support.)
- (h) PCRE supports named capturing substrings, using the Python syntax.
+ (h) PCRE supports named capturing substrings, using the Python syntax.
- (i) PCRE supports the possessive quantifier "++" syntax, taken from
- Sun's Java package.
+ (i) PCRE supports the possessive quantifier "++" syntax, taken from
+ Sun's Java package.
- (j) The (R) condition, for testing recursion, is a PCRE extension.
+ (j) The (R) condition, for testing recursion, is a PCRE extension.
- (k) The callout facility is PCRE-specific.
-
-
+ (k) The callout facility is PCRE-specific.
NOTES
The \< and \> metacharacters from Henry Spencers package
- are not available in PCRE, but can be emulate with \b,
+ are not available in PCRE, but can be emulated with \b,
as required, also in conjunction with \W or \w.
In LDMud, backtracks are limited by the EVAL_COST runtime
@@ -1391,25 +1352,23 @@
LDMud doesn't support PCRE callouts.
-
LIMITATIONS
There are some size limitations in PCRE but it is hoped that
- they will never in practice be relevant. The maximum length
- of a compiled pattern is 65539 (sic) bytes. All values in
- repeating quantifiers must be less than 65536. There max-
- imum number of capturing subpatterns is 65535. There is no
- limit to the number of non-capturing subpatterns, but the
- maximum depth of nesting of all kinds of parenthesized sub-
- pattern, including capturing subpatterns, assertions, and
- other types of subpattern, is 200.
+ they will never in practice be relevant. The maximum length
+ of a compiled pattern is 65539 (sic) bytes. All values in
+ repeating quantifiers must be less than 65536. There
+ maximum number of capturing subpatterns is 65535. There is no
+ limit to the number of non-capturing subpatterns, but the
+ maximum depth of nesting of all kinds of parenthesized
+ subpattern, including capturing subpatterns, assertions,
+ and other types of subpattern, is 200.
- The maximum length of a subject string is the largest posi-
- tive number that an integer variable can hold. However, PCRE
- uses recursion to handle subpatterns and indefinite repeti-
- tion. This means that the available stack space may limit
- the size of a subject string that can be processed by cer-
- tain patterns.
-
+ The maximum length of a subject string is the largest
+ positive number that an integer variable can hold. However,
+ PCRE uses recursion to handle subpatterns and indefinite
+ repetition. This means that the available stack space may
+ limit the size of a subject string that can be processed by
+ certain patterns.
AUTHOR
Philip Hazel <ph10@cam.ac.uk>
diff --git a/doc/concepts/pgsql b/doc/concepts/pgsql
index 12f2cc4..0249ed0 100644
--- a/doc/concepts/pgsql
+++ b/doc/concepts/pgsql
@@ -40,7 +40,7 @@
row).
PGRES_COMMAND_OK: <ret> is a string which contains the
- server response (e.g. on INSERT or DELETE)
+ server response (e.g. on INSERT or DELETE)
PGRES_BAD_RESPONSE,
PGRES_NONFATAL_ERROR,
@@ -49,7 +49,7 @@
void <callback>(int type, mixed ret [, mixed extra...])
- <type> is the type of the call, which is not related a
+ <type> is the type of the call, which is not related to a
specific query:
PGCONN_SUCCESS: The database-connection was established,
@@ -65,7 +65,7 @@
we try to re-establish (reset) it. If the
reset fails, the connection is closed and
this value is returned. Consider the
- connection gone and don't try to close or
+ connection gone and don't try to close or
otherwise operate further on it.
<ret> is a dummy string.
diff --git a/doc/concepts/python b/doc/concepts/python
new file mode 100644
index 0000000..0fe48b7
--- /dev/null
+++ b/doc/concepts/python
@@ -0,0 +1,191 @@
+PRELIMINARY
+CONCEPT
+ python
+
+DESCRIPTION
+ Python can be used to extend the LDMud driver. At the startup
+ of LDMud a python script will be called that can register
+ additional efuns. The python script can either be given
+ on the command line using the --python-script option,
+ or at compile time with the --with-python-script configuration
+ option.
+
+ The python script can import the builtin ldmud module.
+ This module provides the following functions:
+
+ - register_efun(name, function) -> None
+ Registers a new efun name. This is not allowed during
+ compilation of an LPC object.
+
+ If the Python function has type annotations for its
+ arguments and return value, the type is checked
+ at compile and runtime. Union types can be specified
+ as tuples of types.
+
+ - unregister_efun(name) -> None
+ Removes a python efun from registration. This is not
+ allowed during compilation of an LPC object. The
+ removal will only affect newly compiled code,
+ already compiled code will produce errors when
+ calling this efun.
+
+ - register_socket(fd, function [,eventmask]) -> None
+ Registers a socket <fd> to watch for events (like
+ poll/select). The socket must be either given as
+ an integer or an object with a fileno() method
+ returning an integer. The function must be a callable
+ accepting one argument, the actual event mask.
+ <eventmask> may be an combination of select.POLLIN,
+ select.POLLOUT and select.POLLPRI or a callable
+ returning such a combination.
+
+ - unregister_socket(fd) -> None
+ Removes a previously registered socket from the
+ watch list.
+
+ - register_hook(hook, function) -> None
+ Register a hook. The python function will be called
+ whenever <hook> happens. <hook> can be one of the
+ following:
+
+ ON_HEARTBEAT
+ Called without arguments for every backend loop
+
+ ON_OBJECT_CREATED
+ Called whenever an object was created, with the
+ object as its first and only argument. This call
+ happens before any LPC code of the object ran.
+
+ ON_OBJECT_DESTRUCTED
+ Called just before an object will be destructed,
+ with the object as its first and only argument.
+
+ - unregister_hook(hook, function) -> None
+ Removes a hook function.
+
+ - get_master() - > Object
+ Returns the current master object.
+ Returns None, if there is no master object (yet).
+
+ - get_simul_efun() - > Object
+ Returns the current simul-efun object
+ (or None if there is none).
+
+
+ This module provides the following types:
+
+ - Object(filename)
+ Corresponds to the LPC object type.
+ On instantiation a filename for an object
+ to search or load is required.
+
+ - Array([values | size])
+ Corresponds to an LPC array.
+ Can either be initialized with a list of values
+ or to a given size.
+
+ Supports element access with [], len() and __contains__.
+
+ - Mapping([values | width])
+ Corresponds to an LPC mapping.
+ Can either be initialized with a dict, a list of tuples
+ or as an empty mapping with a given width.
+
+ Supports element access with [], len(), __contains__
+ and has a width member.
+
+ - Struct(object, name [, values])
+ Corresponds to an LPC struct.
+ On initialization the name of the struct definition and
+ the correspopnding object is required. It can be initialized
+ with a list of values or dict.
+
+ Supports member access as regular python members.
+
+ - Closure(object [,name [, lfun_object]])
+ Corresponds to an LPC closure.
+ On initialization a closure bound to <object> will be created,
+ like a call to symbol_function(<name> [, <lfun_object>]).
+
+ Supports function calls.
+
+ - Symbol(name [, quotes])
+ Corresponds to an LPC symbol.
+ On initialization the name of the symbol is required.
+ Optionally the number of quotes (at least 1) can be specified.
+
+ Has two members: name and quotes.
+
+ - QuotedArray(array [, quotes])
+ Corresponds to an LPC quoted array.
+ On initialization an array is required.
+ Optionally the number of quotes (at least 1) can be specified.
+
+ Has two members: array and quotes.
+
+
+ This module contains the following sub-namespaces:
+
+ - efuns
+ This namespace contains all original efuns (without any
+ registered python efuns or simul-efuns). These can be called
+ as a regular function.
+
+
+EXAMPLE
+ import ldmud
+
+ def hello_world(name: str) -> int:
+ print("Hello, world, %s!\n" % (name,))
+ return 1
+
+ ldmud.register_efun("hello", hello_world)
+
+NOTES
+ Just like simul-efuns python efuns can shadow real efuns. The
+ original efun is then inaccessible for LPC code (except for code
+ that was compiled before the efun was registered). Python efuns are
+ nearly indistinguishable from real efuns, they also use the efun::
+ prefix. However they can be detected with
+ CLOSURE_IS_PYTHON_EFUN(get_type_info(#'efun,1))
+
+ Without the prefix the order of name resolution for function calls is:
+ 1. lfuns
+ 2. simul-efuns
+ 3. python efuns
+ 4. real efuns
+
+ Also just like simul-efuns python-registered efuns are called
+ from LPC code that was compiled after the registration. LPC code
+ that was compiled before the registration will still call the
+ original efuns (or throw a compile error if that efun doesn't exist).
+ Therefore such efuns should be registered in the python startup
+ script.
+
+ When a python efun is unregistered, code that was compiled while the
+ registration was in effect will throw a runtime error. (Regardless
+ of whether a driver efun with the same name exists or not.)
+
+ There is a limit of 2048 python efuns. Not only registered, but also
+ formerly registered - but now unregistered - efuns count toward that
+ limit. Re-registering the same efun name again won't count a second
+ time. (LPC code that was compiled during the previous registration
+ will also call the new efun after the re-registration.)
+
+ As LDMud is single-threaded, the python code will run in the same
+ thread as the LPC machine. So any long-running python function will
+ halt the MUD for all players. Hence python functions should return
+ promptly and source out any lengthy tasks to another process. If
+ other threads are spawned from python, then these threads are not
+ allowed to access any LDMud functions or objects.
+
+ Finally a note of caution: Don't change the meaning of base efuns
+ fundamentally as it furthers confusion and hinders exchange of LPC
+ code and knowledge between mudlibs.
+
+HISTORY
+ LDMud 3.5 implemented the python functionality.
+ LDMud 3.6 added type checks.
+
+SEE ALSO
+ simul_efun(C)
diff --git a/doc/concepts/regexp b/doc/concepts/regexp
index 9a9d70e..b04ca1b 100644
--- a/doc/concepts/regexp
+++ b/doc/concepts/regexp
@@ -1,16 +1,18 @@
SYNOPSIS
Regular Expressions
-
DESCRIPTION
LDMud supports both the traditional regular expressions as
- implemented by Henry Spencer ("HS" or "traditional"), and the
- Perl-compatible regular expressions by Philip Hazel ("PCRE").
+ implemented by Henry Spencer ("HS" or "traditional"), and
+ optionally the Perl-compatible regular expressions by Philip
+ Hazel ("PCRE").
Both packages can be used concurrently, with the selection
being made through extra option flags argument to the efuns.
One of the two packages can be selected at compile time, by
commandline argument, and by driver hook to be the default
package.
+ If the host system does not supply PCREs at compile-time, they
+ will not be availablea in the driver.
The packages differ in the expressivity of their expressions
(PCRE offering more options that Henry Spencer's package),
@@ -25,7 +27,6 @@
For details, refer to the detailed manpages: hsregexp(C) for
the Henry Spencer package, pcre(C) for the PCRE package.
-
REGULAR EXPRESSION DETAILS
A regular expression is a pattern that is matched against a
subject string from left to right. Most characters stand for
@@ -84,7 +85,6 @@
\< HS: Match begin of word.
\> HS: Match end of word.
-
OPTIONS
The package is selected with these option flags:
diff --git a/doc/concepts/simul_efun b/doc/concepts/simul_efun
index 8c4a2a0..d42c957 100644
--- a/doc/concepts/simul_efun
+++ b/doc/concepts/simul_efun
@@ -8,7 +8,7 @@
object (except the master object). To get access to efuns that
are overloaded by the simul_efun object, you can use the
efun::function() to bypass the simul_efun (unless the
- simul_efun object has defined the function as ``nomask'').
+ simul_efun object has defined the function as "nomask").
SEE ALSO
get_simul_efun(M), inheritance(LPC), operators(LPC)
diff --git a/doc/concepts/tls b/doc/concepts/tls
index 25946a2..d42d8de 100644
--- a/doc/concepts/tls
+++ b/doc/concepts/tls
@@ -3,53 +3,55 @@
tls (transport layer security)
DESCRIPTION
- TLS stands for Transport Layer Security which is the successor
- of the well known SSL (Secure Socket Layer). Both techniques
- provide a way to authenticate and encrypt the data send through
- a network connection.
- By enabling TLS during compilation of the driver you can provide
- a secure channel into the mud to your players.
- In difference to other solutions as "sslwrap" or "stunnel" the
- driver integrated approach has the advantage that the mud sees
- the real IP of the player, not the IP of the local mud host.
+ TLS stands for Transport Layer Security which is the successor
+ of the well known SSL (Secure Socket Layer). Both techniques
+ provide a way to authenticate and encrypt the data send through
+ a network connection.
+
+ By enabling TLS during compilation of the driver you can provide
+ a secure channel into the mud to your players.
+
+ In difference to other solutions as "sslwrap" or "stunnel" the
+ driver integrated approach has the advantage that the mud sees
+ the real IP of the player, not the IP of the local mud host.
USAGE
- To use TLS configure your driver with --enable-tls option.
- After starting your driver you have five new efuns
- (tls_init_connection(), tls_deinit_connection(), tls_error(),
- tls_query_connection_info(), tls_query_connection_state()).
+ To use TLS configure your driver with --enable-tls option.
+ After starting your driver you have five new efuns
+ (tls_init_connection(), tls_deinit_connection(), tls_error(),
+ tls_query_connection_info(), tls_query_connection_state()).
- You can switch on TLS by calling tls_init_connection().
- This can happen in three ways:
+ You can switch on TLS by calling tls_init_connection().
+ This can happen in three ways:
- 1) in telnet_neg()
+ 1) in telnet_neg()
- Advantage of this method is that you can offer TLS on a normal
- mud port. If you have a limited number of ports this can
- become important. The TLS connection will be started by
+ Advantage of this method is that you can offer TLS on a normal
+ mud port. If you have a limited number of ports this can
+ become important. The TLS connection will be started by
the client with help of telnet option STARTTLS. Currently
there are no mudclients that support this method.
-
+
You will have to implement the telnet option STARTTLS (46) for
this method. The draft for this can be found here:
http://www.ietf.org/proceedings/99mar/I-D/draft-ietf-tn3270e-telnet-tls-01.txt
Call tls_init_connection() to initiate the TLS handshake.
- 2) in master_ob->connect()
+ 2) in master_ob->connect()
Advantage of this method is that your users can connect with
any program that supports TLS/SSL. Examples are telnet-ssl,
sslwrap or stunnel. Disadvantage is that you have to spend
a dedicated port for this.
-
+
You have to call tls_init_connection() as first command
after the player connected (normally in master_ob->connect())
3) in an interactive object using a callback.
This method is similar to method (1), but not limited to
- telnet: it is useful for implementing protocols thta use
+ telnet: it is useful for implementing protocols that use
STARTTLS like SMTP or IMAP. tls_init_connection() can be
called at any time by the interactive object.
diff --git a/doc/concepts/uids b/doc/concepts/uids
index 724a7af..26a94e9 100644
--- a/doc/concepts/uids
+++ b/doc/concepts/uids
@@ -28,11 +28,9 @@
As uids, euids are assigned at an objects creation through
the two aformentioned driverhooks. They can be queried with
- the efun geteuid() and changed with the efun seteuid(). Calls
- to the latter are verified by the master lfun valid_seteuid().
-
- Additionally objects can impose their uid onto an other objects
- euid with the efun export_uid().
+ the efun geteuid() and changed with the efun configure_object
+ (using the OC_EUID option). Calls to the latter are verified by
+ the master lfun privilege_violation().
If the driver is run in 'strict euids' mode, euids are taken
@@ -51,9 +49,11 @@
When an object is newly loaded, the H_LOAD_UIDS hook is
called with the object name as argument.
+
When an object is cloned, the H_CLONE_UIDS hook is called
with the blueprint object as first and the clone's designated
name as second argument.
+
In both cases the new object already exists, but has 0 uids.
For the result, the following possibilities exist (<num> is
@@ -71,9 +71,8 @@
({ <num>, <no-string> }) -> uid = 'default', euid = 0
-
Slightly different rules apply to the (e)uid of the master.
- The masters (e)uid is determined by a call to
+ The master's (e)uid is determined by a call to
master->get_master_uid():
"<uid"> -> uid = "<uid>", euid = "<uid>"
@@ -92,5 +91,6 @@
the appropriate driver hooks.
SEE ALSO
- native(C), get_root_uid(M), valid_seteuid(M),
- objects(C), clone_object(E), geteuid(E), getuid(E), seteuid(E)
+ native(C), get_root_uid(M), privilege_violation(M),
+ objects(C), clone_object(E), geteuid(E), getuid(E),
+ configure_object(E)
diff --git a/doc/concepts/unicode b/doc/concepts/unicode
new file mode 100644
index 0000000..5c22ecc
--- /dev/null
+++ b/doc/concepts/unicode
@@ -0,0 +1,56 @@
+CONCEPT
+ unicode
+
+DESCRIPTION
+ LPC strings come in two flavors: As byte sequences and as unicode
+ strings. For both types almost the full range of string operations
+ is available, but the types are not to be mixed. So for example
+ you cannot add a byte sequence to an unicode string or vice versa.
+
+ Byte sequences can store only bytes (values from 0 to 255),
+ but unicode strings can store the full unicode character set
+ (values from 0 to 1114111).
+
+ There are two conversion functions to convert between byte sequences
+ and unicode strings: to_text() which will return a unicode string,
+ and to_bytes() which returns a byte sequence. Both take either
+ a string or an array, and when converting between bytes and unicode
+ also the name of the encoding (to be) used for the byte sequence.
+
+ -- File handling --
+
+ When a file is accessed either by compiling, read_file(), write_file()
+ (not read_bytes() or write_bytes(), or when an explicit encoding was
+ given), the master is asked via the driver hook H_FILE_ENCODING for
+ the encoding of the file. If none is given, 7 bit ASCII is assumed.
+ Whenever codes are encounted that are not valid in the given encoding
+ a compile or runtime error will be raised.
+
+ -- File names --
+
+ The filesystem encoding can be set with a call to
+ configure_driver(DC_FILESYSTEM_ENCODING, <encoding>). The default
+ encoding is derived from the LC_CTYPE environment setting.
+ If there is no environment setting (or it is set to the default
+ "C" locale), then UTF-8 is used.
+
+ -- Interactives --
+
+ Each interactive has its own encoding. It can be set with
+ configure_interactive(IC_ENCODING, <encoding>). The default is
+ "ISO-8859-1//TRANSLIT" which maps each incoming byte to the
+ first 256 unicode characters and uses transliteration to encode
+ characters that are not in this character set. If an input or
+ output character can not be converted to/from the configured
+ encoding it will be silently discarded.
+
+ -- ERQ / UDP --
+
+ Only byte sequences can be sent to the ERQ or via UDP,
+ and only byte sequences can be received from them.
+
+HISTORY
+ Introduced in LDMud 3.6.
+
+SEE ALSO
+ to_text(E), to_bytes(E), configure_driver(E)