addresses issue #310

[timbray]

add a prettyprinter for NFAs

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 97.95918% with 2 lines in your changes missing coverage. Please review.

Project coverage is 96.39%. Comparing base (b74612e) to head (7c5c99d).

Files	Patch %	Lines
prettyprinter.go	97.40%	1 Missing and 1 partial ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #311      +/-   ##
==========================================
+ Coverage   96.32%   96.39%   +0.06%     
==========================================
  Files          17       18       +1     
  Lines        1634     1718      +84     
==========================================
+ Hits         1574     1656      +82     
- Misses         34       35       +1     
- Partials       26       27       +1     

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

[timbray]

Once again, deep NFA twiddling, will push it myself if nobody wants to review. However, have a glance at TestPP() in prettyerinter_test.go to see what the prettyprinter output looks like for the wildcard pattern "x*9". I found this output absolutely essential in debugging the transition from DFA to NFA. In that output, the abbreviation gS stands for "glob state", i.e. when you arrive at * and loop back on anything but a particular byte value. The state you reach when you see that particular value and exit the glob has a name including gX for "glob exit".

If you have an idea for an improvement in the prettyerinter output, feel free to comment.

[embano1]

Left a comment regarding potential performance (allocation) issues. You should also update the README if you think this could be useful. For example, would it be good to enable printing behavior (for users) using an environment variable like Q_DEBUG_NFA to enable the printer?

Regarding printing output, might also be worth explaining that in README unless you want users/developers to only send a printer output file to you so you can debug?

[embano1]

I'd suggest following what Google did when they developed the slog logging package. Instead of going with an interface type, they used a concrete struct with a specific interface handler type to avoid allocations: https://youtu.be/8rnI2xLrdeM?feature=shared&t=1336 (starts at that conversation)

[embano1]

tl;dr

// inspired by https://pkg.go.dev/golang.org/x/exp/slog#Logger
type Handler interface {
  Enabled() bool
  Handle(...)
}

type Printer struct {
  handler handler
}

func New() *Printer {...}

[timbray]

Hmm, looking at this. Unless you're actively testing/debugging and using newPrettyPrinter() the only allocation currently in production code is in value_matcher:

		case shellStyleType:
			newFA, nextField = makeShellStyleAutomaton(valBytes, &nullPrinter{})

It dawns on me that if I put a global variable in pretty_printer.go like this:

var sharedNullPrinter = &nullPrinter{}

Then that line in value_matcher becomes:

		case shellStyleType:
			newFA, nextField = makeShellStyleAutomaton(valBytes, sharedNullPrinter)

Then there would be no allocations ever outside of when you're testing/debugging. Would that address your concern?

[timbray]

Also, I agree about documenting this stuff. Probably best to create a DEVELOPING.md or some such; is there a standard name for this kind of thing?

[embano1]

If this implementation is purely for developing, CONTRIBUTING.md might be common

[embano1]

Left a comment in the place where I think alloc might happen? Ideally, we'd have a benchmark which shows the before/after here?

[embano1]

Can't see alloc changes in this though: https://github.com/timbray/quamina/actions/runs/9324906941?pr=311

[timbray]

Yes, CONTRIBUTING is the place.

[timbray]

I added a description to CONTRIBUTING in the latest commit. If that's OK I think we can resolve this conversation?

[embano1]

Great section! Since we talked about OS env vars, how would a dev enable the pretty printer easily? Would be nice to explain this here too.

[timbray]

Good idea. CONTRIBUTING now contains a mini developer's user guide.

[embano1]

LGTM, perhaps squash before merging

[timbray]

LGTM, perhaps squash before merging

Thanks! Your input really improved this one. I'll let GitHub do the squashing, that seems to work OK with the CI.