path: root/gemtext_decode.3

.Dd 2020-10-22
.Dt gemtext 3
.Os
.Sh NAME
.Nm gemtext_decode ,
.Nm gemtext_decode_fd ,
.Nm gemtext_decode_file ,
.Nm gemtext_list_decode ,
.Nm gemtext_list_decode_fd ,
.Nm gemtext_list_decode_file
.Nd Gemini text parsing functions
.Sh SYNOPSIS
.In gemtext.h
.Ft struct gemtext *
.Fn gemtext_decode "char *text"
.Ft struct gemtext *
.Fn gemtext_decode_fd "int fd"
.Ft struct gemtext *
.Fn gemtext_decode_file "const char *path"
.Ft struct gemtext **
.Fn gemtext_list_decode "char *text"
.Ft struct gemtext **
.Fn gemtext_list_decode_fd "int fd"
.Ft struct gemtext **
.Fn gemtext_list_decode_file "const char *path"
.Sh DESCRIPTION
.Fn gemtext_decode
takes string consisting of a single line specified in
.Em text
and converts it to
.Em struct gemtext*
returned.
.Pp
.Fn gemtext_decode_fd
and
.Fn gemtext_decode_file
are wrappers for
.Fn gemtext_decode
where the former takes input from file descriptor specified int
.Em fd ,
and the latter reads input from file specified in
.Em file .
.Pp
.Fn gemtext_list_decode ,
.Fn gemtext_list_decode_fd
and
.Fn gemtext_list_decode_file
behave similar to
.Fn gemtext_decode
family of functions except text specified in
.Em text
can consist of multiple lines and the returned value would be a list of
.Em struct gemtext*
terminated by a NULL pointer.
.Sh RETURN VALUES
.Fn gemtext_decode ,
.Fn gemtext_decode_fd
and
.Fn gemtext_decode_file
return a valid pointer to
.Em struct gemtext
consisting of the parsed text on success, or NULL on error.
.Pp
.Fn gemtext_list_decode ,
.Fn gemtext_list_decode_fd
and
.Fn gemtext_list_decode_file
return a list of
.Em struct gemtext*
terminated by NULL pointer, or NULL on error.
.Pp
Pointers returned by
.Fn gemtext_decode
and it's wrappers should be freed using
.Xr gemtext_free(3) .
.Pp
Pointers returned by
.Fn gemtext_list_decode
and it's wrappers should be freed using
.Xr gemtext_list_free(3) .
.Sh SEE ALSO
.Xr gemtext_encode 3 ,
.Xr gemtext_text_new 3 ,
.Xr gemtext_type 3 ,
.Xr gemtext_text_string 3 ,
.Xr gemtext_text_strlen 3 ,
.Xr gemtext_list_append 3 ,
.Xr gemtext_free 3
.Sh AUTHORS
.An Ali Fardan Aq Mt raiz@stellarbound.space