search

maciejhirsz / logos

Create ridiculously fast Lexers
https://logos.maciej.codes
Apache License 2.0
2.71k stars 105 forks source link

chore(docs): Adds graph debug documentation to book #379

Closed afreeland closed 3 weeks ago

afreeland commented 4 months ago

I ran across this comment while having some issues with regex support. Thought this was beneficial information and wanted to try and include it in the book so it was a little more visible to people that may be trying to debug and understand how things are working

afreeland commented 4 months ago

Yeah, sorry for the kind of rushed PR...trying to sneak this in-between family time lol

Made some improvements to language and file structure based off of your recommendations. Hopefully, a little less jarring to someone reading it.

As for the enable debugging part, I totally agree, I am new to rust but I can try to put something together that properly uses a debug-mode kind of flag. Will keep it as a separate commit or could be a follow up PR if I get a chance. Would make life much nicer if something was an easy feature bit to flip.

jeertmans commented 4 months ago

Yeah, sorry for the kind of rushed PR...trying to sneak this in-between family time lol

Made some improvements to language and file structure based off of your recommendations. Hopefully, a little less jarring to someone reading it.

As for the enable debugging part, I totally agree, I am new to rust but I can try to put something together that properly uses a debug-mode kind of flag. Will keep it as a separate commit or could be a follow up PR if I get a chance. Would make life much nicer if something was an easy feature bit to flip.

No issue, I did it myself since this was an easy fix. The issue you had was that you needed to declare a debug feature in sub-crates. See #382 for more details :-)

abhillman commented 1 month ago

Users wishing to use this functionality may do so, pending this patch making it upstream to crates.io, with the following:

logos = { git = "https://github.com/maciejhirsz/logos.git#afreeland:debug-graph", features = ["debug"]}
abhillman commented 1 month ago

I haven't had a chance to dive in yet, but does logos have a runtime-accessible public API for fetching, manipulating, and constructing graphs exist besides using macros? Some reasons I can think of why those APIs would be useful:

fetching [related to this PR]

manipulating/construction [out of scope for this PR, yet topically related]:

What this PR might look like if there is/were a fetch API

The documentation would mention something like this:

let graph = Token::graph();
println!("{:#?}", graph)

Continuing to use a feature flag to enable ::graph() (if something like it doesn't already exist) would still also probably make sense.

Thoughts?

jeertmans commented 1 month ago

I haven't had a chance to dive in yet, but does logos have a runtime-accessible public API for fetching, manipulating, and constructing graphs exist besides using macros? Some reasons I can think of why those APIs would be useful:

fetching [related to this PR]

  • if a project contains multiple lexers, being able to fetch a graph and print could be easier for users than printing all graphs, as is done in this PR
  • in many cases, such an API would enable a developer to easily use the logos macro DSL to produce a lexer file for other tools (flex and its many derivations, for example)

manipulating/construction [out of scope for this PR, yet topically related]:

  • although this may require additional changes, this would allow for producing lexers at runtime

What this PR might look like if there is/were a fetch API

The documentation would mention something like this:

let graph = Token::graph();
println!("{:#?}", graph)

Continuing to use a feature flag to enable ::graph() (if something like it doesn't already exist) would still also probably make sense.

Thoughts?

This is true that is might be nice to expose that as part of the public API. Would you mind creating an issue for that feature request?