add support for code block execution options

README.md

@@ -8,20 +8,22 @@ nudoc is inspired by [R Markdown](https://bookdown.org/yihui/rmarkdown/basics.ht
 
 ```
 git clone https://github.com/nushell101/nudoc; cd nudoc
+# nupm install --force --path . # optionally you can install this module via nupm
 use nudoc
 nudoc run --quiet README.md
 ```
-
-🗒 The code above isn't executed and updated by nudoc, as it lacks an opening ` ```nushell ` language idnetifier in the opening code fence tag.
+> **Note**
+> The code above isn't executed and updated by nudoc, as it lacks an opening ` ```nushell ` language idnetifier in the opening code fence tag.
 
 ## How it works
 
-1. The `nudoc run` command opens a file from the first argument.
-2. It looks for ` ```nushell ` code chunks.
+`nudoc run` parses the initial file, generates a script to execute the found commands, executes this script in a new nushell instance, parses the results, updates the initial document accordingly and output the resulting document into terminal.
+
+### Details of parsing
+
+2. `nudoc` looks for ` ```nushell ` or ` ```nu ` code chunks.
 3. In the code chunks, that entirely don't have lines starting with the `>` symbol, nudoc executes the whole code chunks as they are, and if they produce any output (like in `print 'this'`), then the output is written in the ` ```nudoc-output ` chunks, next to the executed code chunks.
 4. In the code chunks that contain one or more lines starting with `>` symbol, nudoc filters only lines that start with the `>` or `#` symbol, executes those lines one by one and output their results just after the executed line.
-5. nudoc outputs results code chunks and results of their execution into the terminal (if the `--quiet` flag is not used).
-6. nudoc updates results in the file, which was provided as the first argument (user needs to confirm overwriting the file, if the `--overwrite` flag wasn't used).
 
 ```nushell
 # Eventually, the script updates nushell code chunks.
@@ -46,7 +48,7 @@ Sun, 18 Feb 2024 15:32:52 +0000 (now)
 ## Examples
 
 ```
-nudoc run examples/types_of_data.md  examples/types_of_data_out.md --overwrite --intermid_script examples/types_of_data_intermid.nu
+nudoc run examples/types_of_data.md  examples/types_of_data_out.md --overwrite --intermid_script examples/types_of_data.md_intermid.nu
 ```
 
 The results of the command above are provided in the files of the example folder.

examples/types_of_data.md

@@ -492,7 +492,7 @@ git checkout featurebranch | null
 
 `null` is not the same as the absence of a value! It is possible for a table to be produced that has holes in some of its rows. Attempting to access this value will not produce `null`, but instead cause an error:
 
-```nushell
+```nushell try,new-instance
 > [{a:1 b:2} {b:1}]
 ╭───┬────┬───╮
 │ # │ a  │ b │

examples/types_of_data.md_intermid.nu

@@ -1,141 +1,169 @@
-# this script was generated automatically using nudochttps://github.com/nushell-prophet/nudoc
-
-print `###nudoc-block-1`
+# this script was generated automatically using nudoc
+# https://github.com/nushell-prophet/nudoc
+print "###nudoc-block-1"
+print "```nushell"
 print ("> 42 | describe" | nu-highlight)
-do {nu -c "42 | describe"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+42 | describe | echo $in
 
-print `###nudoc-block-4`
+print "###nudoc-block-4"
+print "```nushell"
 print ("> \"-5\" | into int" | nu-highlight)
-do {nu -c "\"-5\" | into int"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+"-5" | into int | echo $in
 
-print `###nudoc-block-7`
+print "###nudoc-block-7"
+print "```nushell"
 print ("> \"1.2\" | into float" | nu-highlight)
-do {nu -c "\"1.2\" | into float"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+"1.2" | into float | echo $in
 
-print `###nudoc-block-10`
+print "###nudoc-block-10"
+print "```nushell"
 print ("> let mybool = 2 > 1" | nu-highlight)
 let mybool = 2 > 1
 
 print ("> $mybool" | nu-highlight)
-try {$mybool} catch {|e| $e} | echo $in
+$mybool | echo $in
 
 print ("> let mybool = ($env.HOME | path exists)" | nu-highlight)
 let mybool = ($env.HOME | path exists)
 
 print ("> $mybool" | nu-highlight)
-try {$mybool} catch {|e| $e} | echo $in
+$mybool | echo $in
 
-print `###nudoc-block-13`
+print "###nudoc-block-13"
+print "```nushell"
 print ("> 3.14day" | nu-highlight)
-do {nu -c "3.14day"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+3.14day | echo $in
 
-print `###nudoc-block-16`
+print "###nudoc-block-16"
+print "```nushell"
 print ("> 30day / 1sec  # How many seconds in 30 days?" | nu-highlight)
-do {nu -c "30day / 1sec"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+30day / 1sec | echo $in
 
-print `###nudoc-block-19`
+print "###nudoc-block-19"
+print "```nushell"
 print ("> 1Gb / 1b" | nu-highlight)
-do {nu -c "1Gb / 1b"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+1Gb / 1b | echo $in
 
 print ("> 1Gib / 1b" | nu-highlight)
-do {nu -c "1Gib / 1b"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+1Gib / 1b | echo $in
 
 print ("> (1Gib / 1b) == 2 ** 30" | nu-highlight)
-do {nu -c "(1Gib / 1b) == 2 ** 30"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+(1Gib / 1b) == 2 ** 30 | echo $in
 
-print `###nudoc-block-22`
+print "###nudoc-block-22"
+print "```nushell"
 print ("> 0x[1F FF]  # Hexadecimal" | nu-highlight)
-do {nu -c "0x[1F FF]"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+0x[1F FF] | echo $in
 
 print ("> 0b[1 1010] # Binary" | nu-highlight)
-do {nu -c "0b[1 1010]"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+0b[1 1010] | echo $in
 
 print ("> 0o[377]    # Octal" | nu-highlight)
-do {nu -c "0o[377]"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+0o[377] | echo $in
 
-print `###nudoc-block-25`
+print "###nudoc-block-25"
+print "```nushell"
 print ("> {name: sam rank: 10}" | nu-highlight)
-do {nu -c "{name: sam rank: 10}"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+{name: sam rank: 10} | echo $in
 
-print `###nudoc-block-28`
+print "###nudoc-block-28"
+print "```nushell"
 print ("> {x:3 y:1} | insert z 0" | nu-highlight)
-do {nu -c "{x:3 y:1} | insert z 0"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+{x:3 y:1} | insert z 0 | echo $in
 
-print `###nudoc-block-31`
+print "###nudoc-block-31"
+print "```nushell"
 print ("> {name: sam, rank: 10} | transpose key value" | nu-highlight)
-do {nu -c "{name: sam, rank: 10} | transpose key value"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+{name: sam, rank: 10} | transpose key value | echo $in
 
-print `###nudoc-block-34`
+print "###nudoc-block-34"
+print "```nushell"
 print ("> {x:12 y:4}.x" | nu-highlight)
-do {nu -c "{x:12 y:4}.x"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+{x:12 y:4}.x | echo $in
 
-print `###nudoc-block-37`
+print "###nudoc-block-37"
+print "```nushell"
 print ("> {\"1\":true \" \":false}.\" \"" | nu-highlight)
-do {nu -c "{\"1\":true \" \":false}.\" \""} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+{"1":true " ":false}." " | echo $in
 
-print `###nudoc-block-40`
+print "###nudoc-block-40"
+print "```nushell"
 print ("> let data = { name: alice, age: 50 }" | nu-highlight)
 let data = { name: alice, age: 50 }
 
 print ("> { ...$data, hobby: cricket }" | nu-highlight)
-try {{ ...$data, hobby: cricket }} catch {|e| $e} | echo $in
+{ ...$data, hobby: cricket } | echo $in
 
-print `###nudoc-block-43`
+print "###nudoc-block-43"
+print "```nushell"
 print ("> [sam fred george]" | nu-highlight)
-do {nu -c "[sam fred george]"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+[sam fred george] | echo $in
 
-print `###nudoc-block-46`
+print "###nudoc-block-46"
+print "```nushell"
 print ("> [bell book candle] | where ($it =~ 'b')" | nu-highlight)
-try {[bell book candle] | where ($it =~ 'b')} catch {|e| $e} | echo $in
+[bell book candle] | where ($it =~ 'b') | echo $in
 
-print `###nudoc-block-49`
+print "###nudoc-block-49"
+print "```nushell"
 print ("> [a b c].1" | nu-highlight)
-do {nu -c "[a b c].1"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+[a b c].1 | echo $in
 
-print `###nudoc-block-52`
+print "###nudoc-block-52"
+print "```nushell"
 print ("> [a b c d e f] | range 1..3" | nu-highlight)
-do {nu -c "[a b c d e f] | range 1..3"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+[a b c d e f] | range 1..3 | echo $in
 
-print `###nudoc-block-55`
+print "###nudoc-block-55"
+print "```nushell"
 print ("> let x = [1 2]" | nu-highlight)
 let x = [1 2]
 
 print ("> [...$x 3 ...(4..7 | take 2)]" | nu-highlight)
-try {[...$x 3 ...(4..7 | take 2)]} catch {|e| $e} | echo $in
+[...$x 3 ...(4..7 | take 2)] | echo $in
 
-print `###nudoc-block-58`
+print "###nudoc-block-58"
+print "```nushell"
 print ("> [[column1, column2]; [Value1, Value2] [Value3, Value4]]" | nu-highlight)
-do {nu -c "[[column1, column2]; [Value1, Value2] [Value3, Value4]]"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+[[column1, column2]; [Value1, Value2] [Value3, Value4]] | echo $in
 
-print `###nudoc-block-61`
+print "###nudoc-block-61"
+print "```nushell"
 print ("> [{name: sam, rank: 10}, {name: bob, rank: 7}]" | nu-highlight)
-do {nu -c "[{name: sam, rank: 10}, {name: bob, rank: 7}]"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+[{name: sam, rank: 10}, {name: bob, rank: 7}] | echo $in
 
-print `###nudoc-block-64`
+print "###nudoc-block-64"
+print "```nushell"
 print ("> [{x:12, y:5}, {x:3, y:6}] | get 0" | nu-highlight)
-do {nu -c "[{x:12, y:5}, {x:3, y:6}] | get 0"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+[{x:12, y:5}, {x:3, y:6}] | get 0 | echo $in
 
-print `###nudoc-block-67`
+print "###nudoc-block-67"
+print "```nushell"
 print ("> [[x,y];[12,5],[3,6]] | get 0" | nu-highlight)
-do {nu -c "[[x,y];[12,5],[3,6]] | get 0"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+[[x,y];[12,5],[3,6]] | get 0 | echo $in
 
-print `###nudoc-block-70`
+print "###nudoc-block-70"
+print "```nushell"
 print ("> [{x:12 y:5} {x:4 y:7} {x:2 y:2}].x" | nu-highlight)
-do {nu -c "[{x:12 y:5} {x:4 y:7} {x:2 y:2}].x"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+[{x:12 y:5} {x:4 y:7} {x:2 y:2}].x | echo $in
 
-print `###nudoc-block-73`
+print "###nudoc-block-73"
+print "```nushell"
 print ("> [{x:0 y:5 z:1} {x:4 y:7 z:3} {x:2 y:2 z:0}] | select y z" | nu-highlight)
-do {nu -c "[{x:0 y:5 z:1} {x:4 y:7 z:3} {x:2 y:2 z:0}] | select y z"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+[{x:0 y:5 z:1} {x:4 y:7 z:3} {x:2 y:2 z:0}] | select y z | echo $in
 
-print `###nudoc-block-76`
+print "###nudoc-block-76"
+print "```nushell"
 print ("> [{x:0 y:5 z:1} {x:4 y:7 z:3} {x:2 y:2 z:0}] | select 1 2" | nu-highlight)
-do {nu -c "[{x:0 y:5 z:1} {x:4 y:7 z:3} {x:2 y:2 z:0}] | select 1 2"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+[{x:0 y:5 z:1} {x:4 y:7 z:3} {x:2 y:2 z:0}] | select 1 2 | echo $in
 
-print `###nudoc-block-79`
+print "###nudoc-block-79"
+print "```nushell"
 print ("> [{foo: 123}, {}].foo?" | nu-highlight)
-do {nu -c "[{foo: 123}, {}].foo?"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
+[{foo: 123}, {}].foo? | echo $in
 
-print `###nudoc-block-82`
+print "###nudoc-block-82"
+print "```nushell"
 print ("# Assign a closure to a variable
 let greet = { |name| print $\"Hello ($name)\"}
 do $greet \"Julian\"" | nu-highlight)
@@ -145,7 +173,8 @@ print '```
 let greet = { |name| print $"Hello ($name)"}
 do $greet "Julian" | echo $in
 
-print `###nudoc-block-85`
+print "###nudoc-block-85"
+print "```nushell"
 print ("mut x = 1
 if true {
     $x += 1000
@@ -159,13 +188,15 @@ if true {
 }
 print $x | echo $in
 
-print `###nudoc-block-88`
+print "###nudoc-block-88"
+print "```nushell"
 print ("git checkout featurebranch | null" | nu-highlight)
 print '```
 ```nudoc-output'
-git checkout featurebranch | null | echo $in
+git checkout featurebranch | null
 
-print `###nudoc-block-91`
+print "###nudoc-block-91"
+print "```nushell try,new-instance"
 print ("> [{a:1 b:2} {b:1}]" | nu-highlight)
 do {nu -c "[{a:1 b:2} {b:1}]"} | complete | if ($in.exit_code != 0) {get stderr} else {get stdout} | echo $in
 

examples/types_of_data_out.md

@@ -150,10 +150,8 @@ As with durations, you can make fractional file sizes, and do calculations:
 ```nushell
 > 1Gb / 1b
 1000000000
-
 > 1Gib / 1b
 1073741824
-
 > (1Gib / 1b) == 2 ** 30
 true
 ```
@@ -511,7 +509,7 @@ git checkout featurebranch | null
 
 `null` is not the same as the absence of a value! It is possible for a table to be produced that has holes in some of its rows. Attempting to access this value will not produce `null`, but instead cause an error:
 
-```nushell
+```nushell try,new-instance
 > [{a:1 b:2} {b:1}]
 ╭───┬────┬───╮
 │ # │ a  │ b │
@@ -524,7 +522,7 @@ git checkout featurebranch | null
 Error: nu::shell::column_not_found
 
   × Cannot find column
-   ╭─[source:1:1]
+   ╭─[source:1:12]
  1 │ [{a:1 b:2} {b:1}].1.a
    ·            ──┬──    ┬
    ·              │      ╰── cannot find column 'a'