nagbalae/dunst
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add doxygen docs for markup and utils files

Browse Source
This commit is contained in:
Benedikt Heine 2018-11-11 15:05:44 +01:00
parent 413c0d68af
commit 2d2a9c893c
4 changed files with 115 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
src/markup.c
View File

@ -12,6 +12,10 @@
#include "settings.h"
#include "utils.h"
/**
* Convert all HTML special symbols to HTML entities.
* @param str (nullable)
*/
static char *markup_quote(char *str)
{
if (!str)
@ -26,6 +30,10 @@ static char *markup_quote(char *str)
return str;
}
/**
* Convert all HTML special entities to their actual char.
* @param str (nullable)
*/
static char *markup_unquote(char *str)
{
if (!str)
@ -40,6 +48,10 @@ static char *markup_unquote(char *str)
return str;
}
/**
* Convert all HTML linebreak tags to a newline character
* @param str (nullable)
*/
static char *markup_br2nl(char *str)
{
if (!str)
@ -51,13 +63,7 @@ static char *markup_br2nl(char *str)
return str;
}
/*
* Remove HTML hyperlinks of a string.
*
* @str: The string to replace a tags
* @urls: (nullable): If any href-attributes found, an '\n' concatenated
* string of the URLs in format '[<text between tags>] <href>'
*/
/* see markup.h */
void markup_strip_a(char **str, char **urls)
{
assert(*str);
@ -132,13 +138,7 @@ void markup_strip_a(char **str, char **urls)
}
}
/*
* Remove img-tags of a string. If alt attribute given, use this as replacement.
*
* @str: The string to replace img tags
* @urls: (nullable): If any src-attributes found, an '\n' concatenated string of
* the URLs in format '[<alt>] <src>'
*/
/* see markup.h */
void markup_strip_img(char **str, char **urls)
{
const char *start;
@ -221,18 +221,7 @@ void markup_strip_img(char **str, char **urls)
}
}
/*
* Strip any markup from text; turn it in to plain text.
*
* For well-formed markup, the following two commands should be
* roughly equivalent:
*
* out = markup_strip(in);
* pango_parse_markup(in, -1, 0, NULL, &out, NULL, NULL);
*
* However, `pango_parse_markup()` balks at invalid markup;
* `markup_strip()` shouldn't care if there is invalid markup.
*/
/* see markup.h */
char *markup_strip(char *str)
{
if (!str)
@ -321,10 +310,7 @@ static char *markup_escape_unsupported(char *str)
return str;
}
/*
* Transform the string in accordance with `markup_mode` and
* `settings.ignore_newline`
*/
/* see markup.h */
char *markup_transform(char *str, enum markup_mode markup_mode)
{
if (!str)

31
src/markup.h
View File

@ -4,11 +4,42 @@
#include "settings.h"
/**
* Strip any markup from text; turn it in to plain text.
*
* For well-formed markup, the following two commands should be
* roughly equivalent:
*
* out = markup_strip(in);
* pango_parse_markup(in, -1, 0, NULL, &out, NULL, NULL);
*
* However, `pango_parse_markup()` balks at invalid markup;
* `markup_strip()` shouldn't care if there is invalid markup.
*/
char *markup_strip(char *str);
/**
* Remove HTML hyperlinks of a string.
*
* @param str The string to replace a tags
* @param urls (nullable) If any href-attributes found, an `\n` concatenated
* string of the URLs in format `[<text between tags>] <href>`
*/
void markup_strip_a(char **str, char **urls);
/**
* Remove img-tags of a string. If alt attribute given, use this as replacement.
*
* @param str The string to replace img tags
* @param urls (nullable) If any src-attributes found, an `\n` concatenated string of
* the URLs in format `[<alt>] <src>`
*/
void markup_strip_img(char **str, char **urls);
/**
* Transform the string in accordance with `markup_mode` and
* `settings.ignore_newline`
*/
char *markup_transform(char *str, enum markup_mode markup_mode);
#endif

8
src/utils.c
View File

@ -11,6 +11,7 @@
#include "log.h"
/* see utils.h */
char *string_replace_char(char needle, char replacement, char *haystack)
{
if (!haystack)
@ -22,6 +23,7 @@ char *string_replace_char(char needle, char replacement, char *haystack)
return haystack;
}
/* see utils.h */
char *string_replace_at(char *buf, int pos, int len, const char *repl)
{
assert(buf);
@ -51,6 +53,7 @@ char *string_replace_at(char *buf, int pos, int len, const char *repl)
return tmp;
}
/* see utils.h */
char *string_replace_all(const char *needle, const char *replacement, char *haystack)
{
if (!haystack)
@ -78,6 +81,7 @@ char *string_replace_all(const char *needle, const char *replacement, char *hays
return haystack;
}
/* see utils.h */
char *string_append(char *a, const char *b, const char *sep)
{
if (STR_EMPTY(a)) {
@ -95,7 +99,6 @@ char *string_append(char *a, const char *b, const char *sep)
g_free(a);
return new;
}
/* see utils.h */
@ -115,6 +118,7 @@ char *string_strip_quotes(const char *value)
return s;
}
/* see utils.h */
void string_strip_delimited(char *str, char a, char b)
{
assert(str);
@ -132,6 +136,7 @@ void string_strip_delimited(char *str, char a, char b)
str[iwrite] = 0;
}
/* see utils.h */
char *string_to_path(char *string)
{
@ -146,6 +151,7 @@ char *string_to_path(char *string)
return string;
}
/* see utils.h */
gint64 string_to_time(const char *string)
{
assert(string);

71
src/utils.h
View File

@ -16,19 +16,48 @@
//! Test if string a and b are the same case-insensitively
#define STR_CASEQ(a, b) (strcasecmp(a, b) == 0)
/* replace all occurrences of the character needle with the character replacement in haystack */
/**
* Replaces all occurrences of the char \p needle with the char \p replacement in \p haystack.
*
* Does not allocate a new string.
*
* @param needle The char to replace with replacement
* @param replacement The char which is the new one
* @param haystack (nullable) The string to replace
*
* @returns The exact value of the haystack paramater (to allow nesting)
*/
char *string_replace_char(char needle, char replacement, char *haystack);
/* replace all occurrences of needle with replacement in haystack */
char *string_replace_all(const char *needle, const char *replacement, char *haystack);
/* replace <len> characters with <repl> at position <pos> of the string <buf> */
/**
* Replace a substring inside a string with another string.
*
* May reallocate memory. Free the result with `g_free`.
*
* @param buf The string to replace
* @param pos The position of the substring to replace
* @param len The length of the substring to replace
* @param repl The new contents of the substring.
*/
char *string_replace_at(char *buf, int pos, int len, const char *repl);
char *string_append(char *a, const char *b, const char *sep);
/**
* Replace all occurences of a substring.
*
* @param needle The substring to search
* @param replacement The substring to replace
* @param haystack (nullable) The string to search the substring for
*/
char *string_replace_all(const char *needle, const char *replacement, char *haystack);
/* strip content between two delimiter characters (inplace) */
void string_strip_delimited(char *str, char a, char b);
/**
* Append \p b to string \p a. And concatenate both strings with \p concat, if both are non-empty.
*
* @param a (nullable) The left side of the string
* @param b (nullable) The right side of the string
* @param sep (nullable) The concatenator to concatenate if a and b given
*/
char *string_append(char *a, const char *b, const char *sep);
/**
* Strip quotes from a string. Won't touch inner quotes.
@ -38,10 +67,32 @@ void string_strip_delimited(char *str, char a, char b);
*/
char *string_strip_quotes(const char *value);
/* replace tilde and path-specific values with its equivalents */
/**
* Strip content between two delimiter characters
*
* @param str The string to operate in place
* @param a Starting delimiter
* @param b Ending delimiter
*/
void string_strip_delimited(char *str, char a, char b);
/**
* Replace tilde and path-specific values with its equivalents
*
* The string gets invalidated. The new valid representation is the return value.
*
* @param string (nullable) The string to convert to a path.
* @returns The tilde-replaced string.
*/
char *string_to_path(char *string);
/* convert time units (ms, s, m) to internal gint64 microseconds */
/**
* Convert time units (ms, s, m) to the internal `gint64` microseconds format
*
* If no unit is given, 's' (seconds) is assumed by default.
*
* @param string The string to parse the time format from.
*/
gint64 string_to_time(const char *string);
/**