// Copyright 2026 The V Language. All rights reserved.
// Use of this source code is governed by an MIT license
// that can be found in the LICENSE file.
//
// Module markdown provides CommonMark-compliant markdown parsing and HTML
// rendering with support for GitHub Flavored Markdown and additional
// extensions. It is designed for feature parity with github.com/yuin/goldmark.
//
// Basic usage:
//
//     import x.markdown
//
//     html := markdown.to_html('# Hello\n\nWorld')
//
// With GFM extensions:
//
//     md := markdown.new(extensions: markdown.gfm())
//     html := md.convert('| a | b |\n|---|---|\n| 1 | 2 |')
//
// With fine-grained options:
//
//     md := markdown.new(
//         extensions: [markdown.Extension(markdown.footnote()), markdown.typographer()],
//         parser_opts: markdown.ParserOptions{ auto_heading_id: true },
//         renderer_opts: markdown.RendererOptions{ unsafe_: true, xhtml: true },
//     )
//     html := md.convert(source)
//
// Parse to AST and walk:
//
//     doc := md.parse(source)
//     doc.walk(fn (node &markdown.Node) bool {
//         println(node.kind)
//         return true
//     })
module markdown

// ParserOptions configures parser behaviour.
@[params]
pub struct ParserOptions {
pub mut:
	// auto_heading_id generates an id attribute for every heading node
	// derived from the heading text content (goldmark WithAutoHeadingID).
	auto_heading_id bool
}

// RendererOptions configures HTML renderer behaviour.
@[params]
pub struct RendererOptions {
pub mut:
	// unsafe_ allows raw HTML from the source to be included in the output.
	// When false (the default) raw HTML is replaced with an HTML comment.
	unsafe_ bool
	// hard_wraps converts every newline inside a paragraph to a <br> tag.
	hard_wraps bool
	// xhtml outputs XHTML-style self-closing tags (e.g. <br />).
	xhtml bool
}

// Options configures a Markdown processor.
// Extension flags in the mut section are normally set by calling new() with
// an extensions slice; they can also be set directly.
@[params]
pub struct Options {
pub mut:
	// extensions is the list of extensions applied when new() is called.
	extensions []Extension
	// parser_opts configures the parser.
	parser_opts ParserOptions
	// renderer_opts configures the renderer.
	renderer_opts RendererOptions
	// --- feature flags set by extensions ---
	tables          bool
	strikethrough   bool
	linkify         bool
	task_list       bool
	footnotes       bool
	typographer     bool
	definition_list bool
}

// LinkRef holds a collected link reference definition (url + optional title).
struct LinkRef {
	dest  string
	title string
}

// Markdown is the main markdown processor.  Create one with new() and reuse it
// across multiple convert/parse calls; link reference definitions are cached.
pub struct Markdown {
pub mut:
	opts    Options
	ref_map map[string]LinkRef
}

// Markdown.new creates a Markdown processor with the given options.
// All extensions in opts.extensions are applied immediately.
pub fn Markdown.new(opts Options) Markdown {
	mut m := Markdown{
		opts:    opts
		ref_map: map[string]LinkRef{}
	}
	for ext in opts.extensions {
		ext.extend(mut m)
	}
	return m
}

// to_html converts the markdown source to HTML with the given options.
pub fn to_html(src string, opts Options) string {
	mut md := Markdown.new(opts)
	return md.convert(src)
}

// to_plaintext converts the markdown source to UTF-8 plain text with the given options.
pub fn to_plaintext(src string, opts Options) string {
	mut md := Markdown.new(opts)
	return md.convert_plaintext(src)
}

// convert parses the markdown source and renders it to an HTML string.
pub fn (mut m Markdown) convert(src string) string {
	doc := m.parse(src)
	mut r := HTMLRenderer{
		opts:    m.opts
		ref_map: m.ref_map // Use the updated ref_map after parse()
	}
	return r.render(doc)
}

// convert_plaintext parses the markdown source and renders it to UTF-8 plain text.
pub fn (mut m Markdown) convert_plaintext(src string) string {
	doc := m.parse(src)
	mut r := PlainTextRenderer{
		opts:    m.opts
		ref_map: m.ref_map
	}
	return r.render(doc)
}

// parse parses the markdown source into an AST and returns the document root.
// Link reference definitions collected during parsing are cached so that
// subsequent parse/convert calls on the same Markdown instance share them.
pub fn (mut m Markdown) parse(src string) &Node {
	mut p := BlockParser.new(src, m.opts, m.ref_map)
	doc := p.parse()
	for k, v in p.ref_map {
		m.ref_map[k] = v
	}
	return doc
}