30 ms·

I have to ask about http://craftinginterpreters.com/introduction.html#snippets http://craftinginterpreters.com/introduction.html#snippets > In the center, you

by gwern 7y ago

I have to ask about http://craftinginterpreters.com/introduction.html#snippets http://craftinginterpreters.com/introduction.html#snippets > In the center, you have the new code being added in this snippet. It may have a few faded out lines above or below to show you where to insert it in the existing code. There is also a little blurb telling you which file and where in the file it goes. If it says “replace _ lines”, there was some previous code between the faded lines that you need to remove and replace with this snippet. > ...lox/Scanner.java in scanToken() replace 1 line How are these done? Are they compiled from actual diffs, or what? I looked at the source but the CSS/HTML just puts `source-code-narrow` in a class and doesn't tell me anything about them.

munificent 7y ago
The build system figures out all of this location information automatically based on the snippet markers in the code. The code is pretty hairy since it's a pile of Python that sort of accreted organically as I was writing the book. I have been sorely tempted to rewrite the whole thing but abstained because I wanted to focus on writing. The basic idea is that the build system walks every line of code. As it steps through, it keeps track of: * What is the current source file. This is pretty easy to track. :) * What is the current stack of snippet markers? The marker comments support nesting because it makes it easier to, say, introduce a function in one chapter and then insert a couple of lines into the middle later. The topmost snippet on the stack indicates which snippet owns the current line of code. * What is the current surrounding declaration? Using some fairly hacky regexes, it tracks whether it is inside a class, method, struct, etc. Given that, the build system knows for every line of code which snippet it first appears in, which snippet it disappears in if it's one that gets replaced, and the surrounding declaration if any. When compiling a chapter, when it inserts a snippet, it finds all of the lines owned by that snippet. It also grabs some of the preceding and following lines (which is made trickier by the fact that some of the surrounding lines that may be textually present in the actual source file may not exist in the code as it is at the point in time that that snippet is inserted). And it looks for any lines that are removed by that snippet so that it knows what number to put in the "replace _" annotation. From that, it can create the HTML that shows the code for the snippet, some surrounding lines if needed, and a location annotation describing the file, declaration, and number of replaced lines. It's a pretty neat tool, though the implementation is fairly hacky. It's just good enough to produce the correct output for this one book and this book only. :)
- gwern 7y ago
  Wow. Overall, I wonder if it wouldn't've been easier to write the code samples as diffs, and then compile them appropriately to a regular code sample + summary?

by gwern 7y ago

munificent 7y ago

The build system figures out all of this location information automatically based on the snippet markers in the code. The code is pretty hairy since it's a pile of Python that sort of accreted organically as I was writing the book. I have been sorely tempted to rewrite the whole thing but abstained because I wanted to focus on writing. The basic idea is that the build system walks every line of code. As it steps through, it keeps track of: * What is the current source file. This is pretty easy to track. :) * What is the current stack of snippet markers? The marker comments support nesting because it makes it easier to, say, introduce a function in one chapter and then insert a couple of lines into the middle later. The topmost snippet on the stack indicates which snippet owns the current line of code. * What is the current surrounding declaration? Using some fairly hacky regexes, it tracks whether it is inside a class, method, struct, etc. Given that, the build system knows for every line of code which snippet it first appears in, which snippet it disappears in if it's one that gets replaced, and the surrounding declaration if any. When compiling a chapter, when it inserts a snippet, it finds all of the lines owned by that snippet. It also grabs some of the preceding and following lines (which is made trickier by the fact that some of the surrounding lines that may be textually present in the actual source file may not exist in the code as it is at the point in time that that snippet is inserted). And it looks for any lines that are removed by that snippet so that it knows what number to put in the "replace _" annotation. From that, it can create the HTML that shows the code for the snippet, some surrounding lines if needed, and a location annotation describing the file, declaration, and number of replaced lines. It's a pretty neat tool, though the implementation is fairly hacky. It's just good enough to produce the correct output for this one book and this book only. :)

gwern 7y ago
Wow. Overall, I wonder if it wouldn't've been easier to write the code samples as diffs, and then compile them appropriately to a regular code sample + summary?