Function trace

This function is used internally with debug mode. Given a parser and a debug name for it, when the parser is called, trace will:

1. Print a line when the parser starts
2. print a line when the parser ends, indicating success or failure.
3. If the parser returns any captures, print the captures.
4. Count the number of times this parser has been run.
5. Track the total time this parser has taken.
6. Track the total number of steps your parser has taken (a step equals one parser invocation). So, for example, you may find out that your parser to parse Markdown has taken 50 steps to parse that file.

All this happens only if debug mode is on, which you can turn on by using parserDebug, or setting the env var DEBUG to 1.

Caveat: If you have debug mode on through an environment variable, trace will capture counts and times for all parsers across your entire application. If you want to profile just a particular section of code, use parserDebug instead. If you do want to track constant times for all parsers, don't use parserDebug as it will reset those.

trace works with tarsec's built-in parsers out of the box. You can easily set it up to work with your custom parser too.

For example, if your parser looks like this:

const myParser = (input:string) => {
  if (input === "hello") {
   return { success: true, result: "hello", rest: "" };
 }
return { success: false, message: "expected hello", rest: input };
}
Copy

You can wrap it in trace like this:

const myParser = trace("myParser", (input:string) => {
 if (input === "hello") {
  return { success: true, result: "hello", rest: "" };
}
return { success: false, message: "expected hello", rest: input };
});
Copy

Now, when you run myParser("hello") with debug mode on, you will see the debug output.

Some parsers, like seq, are very general. You might have a few parser that use seq. So when you see seq debug output, you might not know which seq parser that means. ou can pass seq a debug name as an optional third argument to be used in the debug output. This name is used to track count and time, so using this name will also mean this seq parser's count and time are tracked separately from the other seq parsers, which might be useful.