Add new User-aware utility functions

Right now neither are used (get_participants does not have any event listeners anywhere), however in the future it will be easier to convert code that uses the old, nick-based functions.

src/functions.py

@@ -1,8 +1,9 @@
 from src.messages import messages
+from src.events import Event
 from src import settings as var
 from src import users
 
-__all__ = ["get_players", "get_target"]
+__all__ = ["get_players", "get_participants", "get_target", "get_role"]
 
 def get_players(roles=None, *, mainroles=None):
     if mainroles is None:
@@ -20,6 +21,11 @@ def get_players(roles=None, *, mainroles=None):
         return list(pl)
     return [p for p in var.ALL_PLAYERS if p in pl]
 
+def get_participants():
+    """List all players who are still able to participate in the game."""
+    evt = Event("get_participants", {"players": get_players()})
+    evt.dispatch(var)
+    return evt.data["players"]
 
 def get_target(var, wrapper, message, *, allow_self=False, allow_bot=False):
     if not message:
@@ -41,3 +47,16 @@ def get_target(var, wrapper, message, *, allow_self=False, allow_bot=False):
         return
 
     return match
+
+def get_role(user):
+    role = var.MAIN_ROLES.get(user)
+    if role is not None:
+        return role
+    # not found in player list, see if they're a special participant
+    if user in get_participants():
+        evt = Event("get_participant_role", {"role": None})
+        evt.dispatch(var, user)
+        role = evt.data["role"]
+    if role is None:
+        raise ValueError("User {0} isn't playing and has no defined participant role".format(user))
+    return role