.\"	$Id: lowdown_doc_parse.3,v 1.16 2021/01/16 14:01:09 kristaps Exp $
.\"
.\" Copyright (c) 2017, 2020 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: January 16 2021 $
.Dt LOWDOWN_DOC_PARSE 3
.Os
.Sh NAME
.Nm lowdown_doc_parse
.Nd parse a Markdown document into an AST
.Sh LIBRARY
.Lb liblowdown
.Sh SYNOPSIS
.In sys/queue.h
.In stdio.h
.In lowdown.h
.Ft "struct lowdown_node *"
.Fo lowdown_doc_parse
.Fa "struct lowdown_doc *doc"
.Fa "size_t *maxn"
.Fa "const char *input"
.Fa "size_t inputsz"
.Fc
.Sh DESCRIPTION
Parse a
.Xr lowdown 5
document
.Fa input
of length
.Fa inputsz
into an AST with the parser
.Fa doc .
The
.Fa maxn
argument, if not
.Dv NULL ,
is set to one greater than the highest node identifier.
Its value is undefined if the function returns
.Dv NULL .
.Pp
This function may be invoked multiple times with a single
.Fa doc
and different input.
.Sh RETURN VALUES
Returns the root of the parse tree or
.Dv NULL
on memory allocation failure.
If not
.Dv NULL ,
the returned node is always of type
.Dv LOWDOWN_ROOT .
.Sh EXAMPLES
The following parsers the NUL-terminated string
.Va data .
It first allocates the parser, then the document, then the renderer
(HTML is used in this case).
Then it passes output to the renderer, prints it, and cleans up
resources.
On any memory errors, it exits with
.Xr err 3 .
.Bd -literal -offset indent
struct lowdown_doc *doc;
struct lowdown_node *n;
struct lowdown_buf *ob;
void *rndr;

doc = lowdown_doc_new(NULL);
if (doc == NULL)
  err(1, NULL);

n = lowdown_doc_parse(doc, NULL, data, strlen(data));
if (n == NULL)
  err(1, NULL);

rndr = lowdown_html_new(NULL);
if (rndr == NULL)
  err(1, NULL);

ob = lowdown_buf_new(1024);

if (!lowdown_html_rndr(ob, NULL, rndr, n))
  err(1, NULL);

fwrite(stdout, 1, ob->size, ob->data);

lowdown_buf_free(ob);
lowdown_html_rndr_free(rndr);
lowdown_node_free(n);
lowdown_doc_free(doc);
.Ed
.Sh SEE ALSO
.Xr lowdown 3