il2fb-events-parser 0.11.0

Basic usage

If you need to be able to parse all events this library knows about, use parse_string():

from il2fb.parsers.events import parse_string
event = parse_string("[8:33:05 PM] User0 has connected")
print(event)
# <Event 'HumanHasConnected'>
event.time
# datetime.time(20, 33, 5)
event.callsign
# 'User0'
import pprint
pprint.pprint(event.to_primitive())
# {'callsign': 'User0',
#  'name': 'HumanHasConnected',
#  'time': '20:33:05',
#  'verbose_name': u'Human has connected'}

Possible exceptions

Certain errors may be raised if you will try to parse unknown event or known event with invalid data:

parse_string("foo bar")
# Traceback (most recent call last):
# ...
# EventParsingError: No grammar was found for string "foo bar"
parse_string("[99:99:99 PM] Mission BEGIN")
# Traceback (most recent call last):
# ...
# ValueError: time data '99:99:99 PM' does not match format '%I:%M:%S %p'

Current list of supported events is rather full, but EventParsingError is quite possible, because server’s events are undocumented and this library may do not know all of them.

In case you need to catch this error, its full name is il2fb.parsers.events.exceptions.EventParsingError.

Other errors such as ValueError are quite impossible if you are parsing log created by dedicated server.

Safe usage

You may use parse_string_safely() if you don’t care about any exceptions:

from il2fb.parsers.events import parse_string_safely
event = parse_string_safely("foo bar")
event is None
# True

Any error (except SystemExit and KeyboardInterrupt) will be muted and None will be returned.

Explicitly tell which events you are interested in

You may explicitly tell which events you are interested in, if you are not interested in the vast majority of events supported by this library.

To do so, you will need to use InclusiveEventsParser:

from il2fb.parsers.events import InclusiveEventsParser
from il2fb.parsers.events import HumanHasConnected, HumanHasSelectedAirfield
parser = InclusiveEventsParser([
    HumanHasConnected, HumanHasSelectedAirfield,
])
parser.parse_string("[8:33:05 PM] User0 has connected")
# <Event 'HumanHasConnected'>
parser.parse_string("[8:33:05 PM] User0 selected army Red at 100.0 200.99")
# <Event 'HumanHasSelectedAirfield'>
parser.parse_string("[8:33:05 PM] User0 has disconnected")
# None

Here, parse_string() method of our parser will work same way as parse_string_safely() function.

Explicitly tell which events you are NOT interested in

If you are not interested only in some events, you can exclude them using ExclusiveEventsParser:

from il2fb.parsers.events import ExclusiveEventsParser
from il2fb.parsers.events import (
    TreeWasDestroyed, TreeWasDestroyedByAIAircraft,
    TreeWasDestroyedByHumanAircraft, TreeWasDestroyedByStatic,
)
parser = ExclusiveEventsParser([
    TreeWasDestroyed, TreeWasDestroyedByAIAircraft,
    TreeWasDestroyedByHumanAircraft, TreeWasDestroyedByStatic,
])
parser.parse_string("[8:33:05 PM] User0 has connected")
# <Event 'HumanHasConnected'>
parser.parse_string("[8:33:05 PM] 3do/Tree/Line_W/live.sim destroyed by User0:Pe-8 at 100.0 200.99")
# None

Just like in case of InclusiveEventsParser, parse_string() will work same way as parse_string_safely() function.

Ideas for future

Another way to speed up parsing is to use LRU cache for grammar rules.

Here, the key idea is that some types of events usually may come in sequence during game flow. For example, user destroys a group of objects with bombs, user changes seat in his aircraft rapidly, the whole crew bails out, etc.

It seems to be OK to use collections.deque to implement cache for such situations.

The problem is that we need to preserve order of rules for events of similar types. To do so, first of all, we need to group all existing rules. Then we will need combine a group of rules into a single rule. This must be done during instantiation of parser, because list of events we are interested in may vary (see InclusiveEventsParser and ExclusiveEventsParser).

This idea seems to be nice and useful, but maybe it’s just a premature optimization.