1#!/usr/bin/env python
2# -*- coding: utf-8 -*-
3
4#
5# Copyright 2017, Data61
6# Commonwealth Scientific and Industrial Research Organisation (CSIRO)
7# ABN 41 687 119 230.
8#
9# This software may be distributed and modified according to the terms of
10# the BSD 2-Clause license. Note that NO WARRANTY is provided.
11# See "LICENSE_BSD2.txt" for details.
12#
13# @TAG(DATA61_BSD)
14#
15
16'''
17Context types for use with `ASTObject.postorder`.
18
19Traversal of an AST with `postorder`, accepts an optional context that receives
20enter and exit events each time a level of the AST is descended or ascended,
21respectively. See its usage in `postorder` for the exact way in which it is
22called. Any contexts provided by callers should be a descendent of
23`TraversalContext`.
24'''
25
26from __future__ import absolute_import, division, print_function, \
27    unicode_literals
28from camkes.internal.seven import cmp, filter, map, zip
29
30import abc, six
31
32class TraversalAction(six.with_metaclass(abc.ABCMeta, object)):
33    '''
34    Generic traversal action.
35    '''
36
37    @abc.abstractmethod
38    def __call__(self, item):
39        raise NotImplementedError
40
41class TraversalContext(six.with_metaclass(abc.ABCMeta, object)):
42    '''
43    Generic AST traversal context.
44    '''
45
46    @abc.abstractmethod
47    def __enter__(self):
48        raise NotImplementedError
49
50    @abc.abstractmethod
51    def __exit__(self, type, value, traceback):
52        raise NotImplementedError
53
54    @abc.abstractmethod
55    def __call__(self, f):
56        assert isinstance(f, TraversalAction)
57        raise NotImplementedError
58
59class SimpleTraversalContext(six.with_metaclass(abc.ABCMeta, TraversalContext)):
60    '''
61    A traversal context that does not need to interact with the traversal
62    action.
63    '''
64
65    def __call__(self, _):
66        return self
67
68class NullContext(SimpleTraversalContext):
69    '''
70    The default context if none is provided by the caller.
71    '''
72
73    def __enter__(self):
74        pass
75
76    def __exit__(self, *_):
77        pass
78