Merge pull request #110 from nushell-prophet/parse-md

Add parse-md command for semantic markdown parsing

Author: maxim-uvarov

README.md

@@ -113,7 +113,7 @@ numd run $path --ignore-git-check
 Use the `--eval` option to prepend Nushell code to the intermediate script. This lets you set visual settings and other configuration before your code runs.
 
 ```nushell
-let path = $nu.temp-path | path join simple_nu_table.md
+let path = $nu.temp-dir | path join simple_nu_table.md
 
 # let's generate some markdown and save it to the `simple_nu_table.md` file in the temp directory
 "```nushell\n[[a b c]; [1 2 3]]\n```\n" | save -f $path
@@ -209,6 +209,33 @@ numd capture stop --help
 # =>
 ```
 
+### `numd parse-md`
+
+Parse markdown into a table of semantic blocks (headers, paragraphs, code blocks, lists, blockquotes, frontmatter) with extracted content and metadata.
+
+```nushell
+numd parse-md --help
+# => Parse markdown into semantic blocks
+# =>
+# => Usage:
+# =>   > parse-md (file)
+# =>
+# => Flags:
+# =>   -h, --help: Display the help message for this command
+# =>
+# => Parameters:
+# =>   file <path>: optional path to markdown file (can also pipe content) (optional)
+# =>
+# => Input/output types:
+# =>   ╭───┬─────────┬────────╮
+# =>   │ # │  input  │ output │
+# =>   ├───┼─────────┼────────┤
+# =>   │ 0 │ string  │ table  │
+# =>   │ 1 │ nothing │ table  │
+# =>   ╰───┴─────────┴────────╯
+# =>
+```
+
 ### Some random familiar examples
 
 ```nushell
@@ -234,7 +261,7 @@ ls z_examples | sort-by name | reject modified size
 # => 4
 
 git tag | lines | sort -n | last
-# => 0.2.2
+# => 0.3.0
 ```
 
 ## Real fight examples to try

numd/commands.nu

@@ -432,7 +432,7 @@ export def list-fence-options []: nothing -> table {
 # Expand short options for code block execution to their long forms.
 @example "expand short option to long form" {
     convert-short-options 'O'
-} --result 'no-output'
+} --result "no-output"
 export def convert-short-options [
     option: string
 ]: nothing -> string {
@@ -449,7 +449,7 @@ export def convert-short-options [
 # Escape symbols to be printed unchanged inside a `print "something"` statement.
 @example "escape quotes for print statement" {
     'abcd"dfdaf" "' | quote-for-print
-} --result '"abcd\"dfdaf\" \""'
+} --result "\"abcd\\\"dfdaf\\\" \\\"\""
 export def quote-for-print []: string -> string {
     # `to json` might give similar results, yet it replaces new lines
     # which spoils readability of intermediate scripts
@@ -517,7 +517,9 @@ export def code-block-marker [
 # Generate a command to highlight code using Nushell syntax highlighting.
 @example "generate syntax highlighting command" {
     'ls' | generate-highlight-print
-} --result "\"ls\" | nu-highlight | print\n\n"
+} --result "\"ls\" | nu-highlight | print
+
+"
 export def generate-highlight-print []: string -> string {
     quote-for-print
     | pipe-to { nu-highlight | print }
@@ -531,12 +533,12 @@ export def trim-trailing-comments []: string -> string {
 }
 
 # Extract the last span from a command to determine if `| print` can be appended.
-@example "pipeline ending with command" { get-last-span 'let a = 1..10; $a | length' } --result 'length'
-@example "pipeline ending with assignment" { get-last-span 'let a = 1..10; let b = $a | length' } --result 'let b = $a | length'
-@example "statement ending with semicolon" { get-last-span 'let a = 1..10; ($a | length);' } --result 'let a = 1..10; ($a | length);'
-@example "expression in parentheses" { get-last-span 'let a = 1..10; ($a | length)' } --result '($a | length)'
-@example "single assignment" { get-last-span 'let a = 1..10' } --result 'let a = 1..10'
-@example "string literal" { get-last-span '"abc"' } --result '"abc"'
+@example "pipeline ending with command" { get-last-span 'let a = 1..10; $a | length' } --result "length"
+@example "pipeline ending with assignment" { get-last-span 'let a = 1..10; let b = $a | length' } --result "let b = $a | length"
+@example "statement ending with semicolon" { get-last-span 'let a = 1..10; ($a | length);' } --result "let a = 1..10; ($a | length);"
+@example "expression in parentheses" { get-last-span 'let a = 1..10; ($a | length)' } --result "($a | length)"
+@example "single assignment" { get-last-span 'let a = 1..10' } --result "let a = 1..10"
+@example "string literal" { get-last-span '"abc"' } --result "\"abc\""
 export def get-last-span [
     command: string
 ]: nothing -> string {
@@ -582,7 +584,7 @@ export def can-append-print [
 # Generate a pipeline that captures command output with `# =>` prefix for inline display.
 @example "generate inline output capture pipeline" {
     'ls' | generate-inline-output-pipeline
-} --result "ls | table --width 120 | default '' | into string | lines | each {$'# => ($in)' | str trim --right} | str join (char nl) | str replace -r '\\s*$' (char nl)"
+} --result "ls | table --width ($env.numd?.table-width? | default 120) | default '' | into string | lines | each { $'# => ($in)' | str trim --right } | str join (char nl) | str replace -r '\\s*$' (char nl)"
 export def generate-inline-output-pipeline []: string -> string {
     generate-table-statement
     | pipe-to {
@@ -597,13 +599,13 @@ export def generate-print-statement []: string -> string {
 }
 
 # Generate a table statement with width evaluated at runtime from $env.numd.table-width.
-@example "default table width" { 'ls' | generate-table-statement } --result 'ls | table --width ($env.numd?.table-width? | default 120)'
+@example "default table width" { 'ls' | generate-table-statement } --result "ls | table --width ($env.numd?.table-width? | default 120)"
 export def generate-table-statement []: string -> string {
     pipe-to { table --width ($env.numd?.table-width? | default 120) }
 }
 
 # Wrap code in a try-catch block to handle errors gracefully.
-@example "wrap command in try-catch" { 'ls' | wrap-in-try-catch } --result 'try {ls} catch {|error| $error}'
+@example "wrap command in try-catch" { 'ls' | wrap-in-try-catch } --result "try {ls} catch {|error| $error}"
 export def wrap-in-try-catch [
     --new-instance # execute in a separate Nushell instance to get formatted error messages
 ]: string -> string {
@@ -646,7 +648,7 @@ export def generate-block-markers [
 }
 
 # Parse options from a code fence and return them as a list.
-@example "parse fence options with short forms" { '```nu no-run, t' | extract-fence-options } --result ['no-run' 'try']
+@example "parse fence options with short forms" { '```nu no-run, t' | extract-fence-options } --result [no-run, try]
 export def extract-fence-options []: string -> list<string> {
     str replace -r '```nu(shell)?\s*' ''
     | split row ','
@@ -658,7 +660,7 @@ export def extract-fence-options []: string -> list<string> {
 # Modify a path by adding a prefix, suffix, extension, or parent directory.
 @example "build path with all modifiers" {
     'numd/capture.nu' | build-modified-path --extension '.md' --prefix 'pref_' --suffix '_suf' --parent_dir abc
-} --result 'numd/abc/pref_capture_suf.nu.md'
+} --result "numd/abc/pref_capture_suf.nu.md"
 export def build-modified-path [
     --prefix: string
     --suffix: string

numd/live.nu

@@ -0,0 +1,131 @@
+export def 'filename-set' [
+    file = 'numdlive.md'
+] {
+    $env.numd.live-filename = $file
+}
+
+export def 'file-name' [] {
+    $env.numd?.live-filename?
+    | default 'numdlive.md'
+}
+
+export def 'append-block' [] {
+    if $env.numd?.live-print? == true {
+        print --no-newline
+    } else {
+        save --append (file-name)
+    }
+}
+
+export def 'h' [
+    $index
+    $header
+] {
+    seq 1 $index
+    | each { '#' }
+    | append ' '
+    | append $header
+    | str join
+    | str replace -ar "\n*$" "\n\n"
+    | append-block
+}
+
+export def 'h1' [
+    $text: string
+] {
+    h 1 $text
+}
+
+export def 'h2' [
+    $text: string
+] {
+    h 2 $text
+}
+
+export def 'h3' [
+    $text: string
+] {
+    h 3 $text
+}
+
+export def 'h4' [
+    $text: string
+] {
+    h 4 $text
+}
+
+export def 'h5' [
+    $text: string
+] {
+    h 5 $text
+}
+
+export def 'h6' [
+    $text: string
+] {
+    h 6 $text
+}
+
+# > numd list-code-options | values | each {$'--($in)'} | to text
+
+export def 'code' [
+    $code_block
+    --indent-output
+    --inline
+    --no-output
+    --no-run
+    --try
+    --new-instance
+    --comment: string = '' # add comment to the code
+] {
+    let $comment = $comment
+    | if $in != '' {
+        lines
+        | compact --empty
+        | str replace -r '^#? ?' '# '
+        | $"($in)\n"
+    } else { '' }
+
+    let $code = $code_block
+    | if $inline {
+        str replace -r '^(> )?' '> '
+    } else { }
+    | $'($comment)($in)'
+
+    let $code_fence_with_options = [
+        (if $indent_output { 'indent-output' })
+        (if $no_output { 'no-output' })
+        (if $no_run { 'no-run' })
+        (if $try { 'try' })
+        (if $new_instance { 'new-instance' })
+    ]
+    | compact
+    | if $in == [] { } else { sort | str join ',' | $' ($in)' }
+    | $'```nushell($in)'
+
+    [
+        $code_fence_with_options
+        $code
+        '```'
+        ''
+    ]
+    | to text
+    | append-block
+}
+
+# add a paragraph
+export def 'p' [
+    $text
+] {
+    $text
+    | str replace -r "\\s*$" "\n\n"
+    | append-block
+}
+
+export def 'pseudo-xml' [
+    tag: string
+    --close
+] {
+    if not $close { $'<($tag)>' } else { $'</($tag)>' }
+    | append-block
+}