SmartFoxServer 2X JavaScript server API

Class: MatchExpression

MatchExpression


The MatchExpression class represents a Match Expression, a querying system to search for Rooms or Users using custom criteria.

Match Expressions are built like "if" conditions in any common programming language. They work like queries in a database and can be used to search for Rooms or Users using custom criteria. These expressions are extremely easy to create and concatenate and they can be used for many different filtering operations within the SFS2X framework.

Overview

Match Expressions are made of three elements: a User/Room Variable name or property to query, a match operator expressing the required condition and the value to match the Variable or property against. Additionally, any number of expressions can be linked together with the logical operators AND and OR, just like in regular "if" expressions.

The search options are not just limited to User/Room Variables names: the Match Expressions engine provides two extra classes, RoomProperties and UserProperties, where many specific attributes of the Room and User classes can be accessed.

Advanced features

The Match Expressions offer advanced capabilities of searching through nested data structures such as SFSObject and SFSArray. This is done via a very simple dot-syntax as shown in a couple of the examples below.

The power of Match Expression doesn't end here. You can run multiple passes of matching if you need complex searches to be performed. For example you can run a first match and obtain a list of filtered Rooms and then use it to apply another expression to further refine your search, and so on and so forth.

Notes

See also

new MatchExpression(varName, condition, value)

Creates a new MatchExpression instance.
Parameters:
Name Type Description
varName string The name of the User/Room Variable or one of the properties listed in RoomProperties or UserProperties enums.
condition BoolMatch | NumberMatch | StringMatch A matching condition among those provided by the BoolMatch, NumberMatch and StringMatch enums.
value boolean | number | string The value to compare against the User/Room Variable or property during the matching.
Examples

In this example we create an expression that will look for users from Italy with a rank greater than 5.
Both "rank" and "country" are User Variables set in our game.

var exp = new MatchExpression('rank', NumberMatch.GREATER_THAN, 5).and('country', StringMatch.EQUALS, 'Italy');

In this example, using some Room properties and a Room Variable name, we retrieve a list of Rooms that a user could join to play chess.

// Prepare a Match Expression
var exp = new MatchExpression(RoomProperties.IS_GAME, BoolMatch.EQUALS, true)
			 .and(RoomProperties.HAS_FREE_PLAYER_SLOTS, BoolMatch.EQUALS, true)
			 .and("isGameStarted", BoolMatch.EQUALS, false);
// Search Rooms
var joinableRooms = getApi().findRooms(getParentZone().getRoomListFromGroup("chess"), exp, 0);

In this example we traverse a Room Variable of type SFSObject via a very simple dot-syntax.
The expression goes down deep into an SFSObject called "europe", taking the "italy" object (another SFSObject) and finally reading its "capital" field and matching it with another string.

var exp = new MatchExpression("europe.italy.capital", StringMatch.EQUALS, "Rome");

The following is another example involving SFSObject and SFSArray type Variables.
From the "italy" SFSObject we obtain a "majorCities" SFSArray and we grab the third item in it (the ".3" expression means "give me the element at index == 3"). The item is again a SFSObject whose "name" property we finally compare to a the passed string.

var exp = new MatchExpression("europe.italy.majorCities.3.name", StringMatch.EQUALS, "Milan");