Add parser level hooks support with Parser2

[Argmaster]

This pull request introduces brand new Parser2 class which can be used in cooperation with old Tokenizer class and provides hooks interface based on visitor pattern.

Note

It was preferable to introduce new Parser class, as it was not possible to effectively implement hook interface for existing Parser class. Additionally this approach smooths transition between those two for any possible users, as they should be able to keep using old parser. When time will be right we will deprecate and remove old parser. Currently exisiting drawing backend interface is also not compatible with Parser2 and will have to be recreated following similar principles as parser.

We can customize parser hooks by creating new hook class inheriting from IHooks or Parser2Hooks and providing it to Parser2 constructor via Parser2Options. Difference between those two is that all IHooks hooks are NOOP while Parser2Hooks actually implement Gerber AST parser logic.

For example if we were to implement a parser only to print all comments from Gerber file we could do it following way:

from pygerber.gerberx3.parser2.context2 import Parser2Context
from pygerber.gerberx3.parser2.ihooks import IHooks
from pygerber.gerberx3.parser2.parser2 import Parser2, Parser2Options
from pygerber.gerberx3.tokenizer.tokens.g04_comment import Comment

class PrintComments(IHooks):

    class CommentTokenHooks(IHooks.CommentTokenHooks):
        
        def on_parser_visit_token(self, token: Comment, context: Parser2Context) -> None:
            print(token.content)
            return super().on_parser_visit_token(token, context)

All operations except visiting Comment tokens will be NOOP.

As you might notice we are creating class within a class body. This nesting mechanism allows us to reduce amount of boilderplate required to define hooks and simplify process of adding new hooks in the future.

All hooks specific to some particular token are defined as classes within a class inheriting from IHooks. They must follow particular naming scheme, for now please refer to source code in pygerber.gerberx3.parser2.ihooks module.

There are also hooks which are not tied to tokens, eg. for error handling, on_parser_error(self, context: Parser2Context, error: Parser2Error) which are then defined directly within master hook class.

It should be possible to extend hook interface in the future to add tokenizer level hooks and possibly others if needed.

[codecov]

Codecov Report

Attention: 384 lines in your changes are missing coverage. Please review.

Comparison is base (c81a9c1) 85.23% compared to head (5b6c61a) 84.48%.

Files	Patch %	Lines
src/pygerber/gerberx3/revisions.py	0.00%	256 Missing ⚠️
src/pygerber/gerberx3/parser2/attributes2.py	89.04%	16 Missing ⚠️
src/pygerber/gerberx3/parser2/parser2hooks.py	94.88%	16 Missing ⚠️
src/pygerber/gerberx3/parser2/context2.py	94.39%	13 Missing ⚠️
src/pygerber/gerberx3/tokenizer/decorators.py	0.00%	13 Missing ⚠️
src/pygerber/gerberx3/parser2/commands2/arc2.py	73.07%	7 Missing ⚠️
src/pygerber/gerberx3/parser2/parser2.py	90.00%	7 Missing ⚠️
src/pygerber/common/immutable_map_model.py	80.76%	5 Missing ⚠️
src/pygerber/gerberx3/parser2/command_buffer2.py	87.17%	5 Missing ⚠️
src/pygerber/common/general_model.py	0.00%	4 Missing ⚠️
... and 18 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #108      +/-   ##
==========================================
- Coverage   85.23%   84.48%   -0.75%     
==========================================
  Files         126      154      +28     
  Lines        3765     5860    +2095     
==========================================
+ Hits         3209     4951    +1742     
- Misses        556      909     +353     

Flag	Coverage Δ
unittests	84.48% <82.48%> (-0.75%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.