--- deliantra/server/lib/cf/match.pm 2009/10/10 19:11:50 1.8
+++ deliantra/server/lib/cf/match.pm 2010/03/20 20:26:18 1.25
@@ -1,3 +1,25 @@
+#
+# This file is part of Deliantra, the Roguelike Realtime MMORPG.
+#
+# Copyright (©) 2009 Marc Alexander Lehmann / Robin Redeker / the Deliantra team
+#
+# Deliantra is free software: you can redistribute it and/or modify it under
+# the terms of the Affero GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the Affero GNU General Public License
+# and the GNU General Public License along with this program. If not, see
+# .
+#
+# The authors can be reached via e-mail to
+#
+
=head1 NAME
cf::match - object matching language
@@ -5,7 +27,8 @@
=head1 DESCRIPTION
This module implements a simple object matching language. It can be asked
-to find any (boolean context), or all (list context), matching objects.
+to find any ("check for a match"), or all ("find all objects") matching
+objects.
=head1 MATCH EXAMPLES
@@ -26,91 +49,91 @@
type=SPELL in type=POTION in inv
-Find all potions inside someones inventory, or inside applied containers:
+Find all scrolls inside someones inventory, or inside applied scroll
+containers:
- type=POTION also in type=CONTAINER and applied in inv
+ type=SCROLL also in applied type=CONTAINER race="scroll" in inv
-=head1 LANGUAGE
+Find all unpaid items, anywhere, even deeply nested inside other items, in
+the originator:
- # object selection
+ unpaid also deep in inv of originator
- select = set
- | select also rep 'in' set
- also = nothing | 'also'
- rep = nothing | 'rep' | 'repeatedly'
+=head1 MATCH EXPRESSIONS
- set = 'inv' | 'env' | 'map'
+=head2 STRUCTURE
- empty =
+The two main structures are the C, which selects objects matching
+various criteria, and the C receives a set of "context objects" that it is applied
+to. This is initially just one object - by default, for altars, it is the
+object dropped on it, for pedestals, the object on top of it and so on.
- # object matching
+This set of context objects can be modified in various ways, for example
+by replacing it with the inventories of all objects, or all items on the
+same mapspace, and so on, by using the C operator:
- match = factor
- | factor 'and'? match
- | factor 'or' match
+ condition in inv
+ condition in map
- factor = 'not' factor
- | '(' match ')'
- | expr
- | expr operator constant
+Also, besides the default root object where all this begins, you can start
+elsewhere, for example in the I (usually the player):
- operator = '=' | '==' | '!=' | '<' | '<=' | '>' | '>='
+ condition in inv of originator
- expr = flag
- | sattr
- | aattr '[' ']'
- | special
- | func '(' args ')'
- | '{' perl code block '}'
+Once the final set of context objects has been established, each object
+is matched against the C.
- func =
- sattr =
- aattr =
- flag =
- special =
+It is possible to chain modifiers from right-to-left, so this example
+would start with the originator, take it's inventory, find all inventory
+items which are potions, looks into their inventory, and then finds all
+spells.
- constant = | '"' '"' |
- args =
+ type=SPELL in type=POTION in inv of originator
- TODO: repeatedly, env, contains, possbly matches
+Sometimes the server is only interested in knowing whether I
+matches, and sometimes the server is interested in I objects that
+match.
-=head2 STRUCTURE
+=head2 OPERATORS
-The two main structures are the C