new nbSomething apis to evaluate

[pietroppeter]

trying to list possible new apis that might be useful. Will need to decide if I want to really do them and write example that actually use them before implementing.

nbSkip:

• show code in the document but do not run it (if other code later needs it, there will be an error)
• use case: when you just need to show a piece of code but you do not need to run the computation
• use case: also useful during development to skip long computations, test different approaches, ...

nbOff:

• run the code but do not add it to the document, nor create a block (nor capture stdout). It acts as if nimib is off
• it is the empty template with trivial implementation: template nbNot(body: untyped) = body
• use case: during development you want to debug stuff that has to do with nimib or you do not want currently to add it to documentation (but you want to run the code, since you might need it).
• it could be useful in conjuction with a compile time define (nbAllOff) in which basically all features of nimib are turned off (unless you use nimib feature outside of nb blocks, in which case you need to wrap them with when not defined(nbAllOff)

nbDisc:

• discard the code
• use case: another way to comment, without commenting when experimenting stuff. also useful in conjunction with nbLib (see below)

nbLib:

• normally it is the same of nbCode, but when nbAsModule is defined then nbLib work as nbOff and all the others work as nbDisc. In this way you can import a file with nimib as if it were a "clean" module.

nbNimFile(name: string, body: untyped):

• write body to file with given name and nim extension (should I also import it automatically? should I check that it compiles in a separate block?).
• I would expect the presentation layer to show file name.

nbWriteFile(name: string, text: untyped):

• write text to file with given name (should include extension).

nbTimeIt

• as nbCode but time the code and report duration (use timeit module?)

nbNextAssign(ident: untyped, eval: untyped):

• kind of magic: when running replace this line of code (should be just one line) in source file with: ident = eval(ident), where expression is the ident evaluated in a way that you can reassign (for string the case would be to use repr).
• names comes from the fact that next time you run the code has changed
• example: nbNext(nbBlock.output)
• use case: use in conjunction with nbSkip. you are done running (possibly long) computations and you want only to work on presentation aspects. then change all code blocks to nbSkip and add nbNext magic to recreate the outputs. rerunning code you will still see the outputs but

nbNextReplace(nbThis: untyped, nbThat: untyped):

• replace nbThis with nbThat
• use case: nbNextReplace(nbCode, nbSkip)

[pietroppeter]

another use case for nbNext magics: support a document that containes different outputs according to different compile switches!

this is a very nice use case (e.g. benchmarking different compilation options). In this use case although it would be even nicer if I am able to make next magics reproducible. mmh, it could be probably done with more next magics (e.g. a nbNextAdd; the content of Add might need to be protected behind a compiler switch; multiple compilations in a specific order should result in the same document after hysteresis sets in).

[pietroppeter]

nbFold: same as nbCode but code should not be shown (possibility to add a button to unfold?)

[pietroppeter]

use case from adventofnim:

• I want a number of blocks to be put into a div container. for example to hide long explanations for adventofnim.
• api?:

nbDiv(class="hide"):
  nbText:
    ...
  nbCode:
    ...
  ...

[pietroppeter]

related also to #4:

nbTest: to but code that might also be extracted for a test file.

for example (see #5) I want to do a small utility package for paths. I could have a single file that provides: documentation, testing and library (3 different outputs: 1 html and 2 nim files, heck I could add also md...).

[pietroppeter]

Edit opened a specific issue (#34) for the following two:

• nbFile to write to a file (with the possibility of executing the file)
• nbShell to run commands from terminal