Documentation of how pug runtime and compileClient work

[PythonLinks]

Pug Version: your version number here
I am reading the current version of this repository.

Additional Comments

First thank you for all of this great free software.
I am editing PUG with the ace editor, and generating the Javascript in the browser.
That gives the user instant feedback on whether their edits are legal or not.
This is for an application for those who do not know how to use the
Unix Shell, Git, emacs, and Node.js and want to
develop completely in the browser.

Next I want to run a function to generate the HTML.
While the instructions as to what to do are quite clear,
what is going on under the hood is not at all clear.

First comment. It took me a while to even find this page. The main PUG github page does not provide clear instructions for those who want to generate stuff in the browser. In fact it is discouraged. Fine to discourage, but please leave some breadcrumbs so that those of us who wish to follow, can follow. Specifically I could not find an architectural document to tell me
what to look for. The API docs are brilliant, but I need more than that.

Second Comment. It is not at all clear what is going on here. One guy said if you do not understand an api, ask the developers what constraints they were operating under for this design. I would have expected

//First I could generate the javascript

javascriptSrc = pug.compile ( pugSrc, options)

//Then I could eval it.

evan (javascriptSrc)

But that is not the case. There is all the complexity described on this page on how to do it.
What is going on here? What is the motivation for this api design?
Rather than just a how-to, could you give an explanation, some reasoning.
An architecture.

So what is pug_escape(e)?
I would have expected the function to be called pug_render(). Why the word
escape? What is being escaped?

Take this line for example.

assert(runtime.attr('foo', 'bar', true, true) === ' foo="bar"');

I know what assert is.
I know what runtime is.
What is attr?
What are the 4 arguments?
Why should this hold true?
What is going on here?

// By default compileClient automatically embeds the needed runtime functions,
// rendering this module useless.

Which module is useless? Is the following command useless? If it is useless, how to
I compile it for the browser, without the runtime included?

And finally:

When testing code compiled for the browser in Node.js, it is necessary to make the runtime available. To do >so, one can use require('pug-runtime/wrap'):

I think you mean "When generating Javascript code to be run in the browser, it is necessary to make the runtime available..."

Rather than just complaining, let me try to contribute. I will describe what the wrap function does.

The Pug CompileClient Function

When I ran Pug Compile, it generated 3 functions.
pug_escape, pug_rethrow and template.
The template function is the one that generates your html.

The wrap function

Pug generates javascript, but that javascript cannot run on its own. It needs
access to the PUG runtime. The wrap function 'binds' the runtime to the Pug generted javascript.
The wrap function takes two arguments. The first argument is the generated javascript.
The second argument is the optional name of the function to be created. If there is
no second argument, the new function is called 'template'.
You can see the code here:
https://github.com/pugjs/pug/blob/master/packages/pug-runtime/wrap.js

So how do I summarize? The documentation for the PUG api is excellent.
I could not find any documentation of the architecture of PUG. How does it work under the hood. If I am doing mainstream stuff, I just need the api docs. If I am trying to do something
innovative, I need a bit more information than is provide.

Hope that helps.
Thanks for all of the great free software.

[ForbesLindesay]

To answer your specific questions first:

1. The separation of compile and render is all about performance. The primary use case of pug is templates with dynamic data. It's ok for us to take a little time to compile and optimise the template, so that repeatedly rendering the same template with different data is fast. pug.compile generates a function that can be directly called. pug.compileClient generates a string of JavaScript that can be evaled to get a reference to the template function that would be returned by pug.compile. This is so that you can compile the template on a server/at build time and then just use the compiled template at runtime.
2. as to what pug_escape and runtime.attr are, these are functions from pug-runtime. They're for rendering isolated parts of the template. pug_escape is responsible for escaping user input to prevent XSS vulnerabilities. pug_attr is responsible for rendering a given attribute, given it's name, value, whether it should be escaped etc.
3. "By default compileClient automatically embeds the needed runtime functions" - you can tell pug not to inline runtime functions in the compiled templates. If you do this, you have to provide them yourself by requiring the pug-runtime package and making that available. This is a performance optimisation for client side rendering when you have lots of templates that have been pre-compiled on the server.

If you could submit pull requests to improve any comments you have found to be out of date and improve/update README files in this repository, that would be awesome. That's where the documentation is supposed to live for pug's architecture.