rofi/include/helper.h

434 lines
13 KiB
C
Raw Normal View History

/*
* rofi
*
* MIT/X11 License
2023-01-14 12:02:35 +00:00
* Copyright © 2013-2023 Qball Cow <qball@gmpclient.org>
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files (the
* "Software"), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to
* the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*
*/
2015-07-27 08:17:12 +00:00
#ifndef ROFI_HELPER_H
#define ROFI_HELPER_H
#include "rofi-types.h"
2021-08-17 23:16:45 +00:00
#include <cairo.h>
G_BEGIN_DECLS
2016-01-07 07:54:24 +00:00
/**
* @defgroup HELPERS Helpers
*/
/**
* @defgroup HELPER Helper
* @ingroup HELPERS
*
* @{
*/
2014-11-24 19:22:44 +00:00
/**
* @param string The input string.
* @param output Pointer to 2 dimensional array with parsed string.
* @param length Length of 2 dimensional array.
* @param ... Key, value parse. Replaces the string Key with value.
*
* Parses a string into arguments. While replacing keys with values.
*
* @returns TRUE when successful, FALSE when failed.
2014-11-24 19:35:28 +00:00
*/
2021-08-17 23:16:45 +00:00
int helper_parse_setup(char *string, char ***output, int *length, ...);
2014-11-24 19:22:44 +00:00
/**
* @param input The input string.
2015-01-12 13:13:46 +00:00
* @param case_sensitive Whether case is significant.
2014-11-24 19:22:44 +00:00
*
* Tokenize the string on spaces.
*
2017-10-01 08:51:02 +00:00
* @returns a newly allocated array of matching objects
2014-11-24 19:22:44 +00:00
*/
2021-08-17 23:16:45 +00:00
rofi_int_matcher **helper_tokenize(const char *input, int case_sensitive);
/**
2016-10-14 14:46:54 +00:00
* @param tokens Array of regex objects
*
2017-10-01 08:51:02 +00:00
* Frees the array of matching objects.
*/
2021-08-17 23:16:45 +00:00
void helper_tokenize_free(rofi_int_matcher **tokens);
2014-11-15 15:26:55 +00:00
2014-11-24 19:22:44 +00:00
/**
* @param key The key to search for
* @param val Pointer to the string to set to the key value (if found)
*
* Parse command line argument 'key' to character.
* This one supports character escaping.
*
2014-11-24 19:35:28 +00:00
* @returns TRUE if key was found and val was set.
2014-11-24 19:22:44 +00:00
*/
2021-08-17 23:16:45 +00:00
int find_arg_char(const char *const key, char *val);
2014-11-15 15:26:55 +00:00
2014-11-24 19:22:44 +00:00
/**
* @param key The key to search for
* @param val Pointer to the string to set to the key value (if found)
*
* Parse command line argument 'key' to unsigned int.
*
2014-11-24 19:35:28 +00:00
* @returns TRUE if key was found and val was set.
2014-11-24 19:22:44 +00:00
*/
2021-08-17 23:16:45 +00:00
int find_arg_uint(const char *const key, unsigned int *val);
2014-11-15 15:26:55 +00:00
2014-11-24 19:22:44 +00:00
/**
* @param key The key to search for
* @param val Pointer to the string to set to the key value (if found)
*
* Parse command line argument 'key' to int.
*
2014-11-24 19:35:28 +00:00
* @returns TRUE if key was found and val was set.
2014-11-24 19:22:44 +00:00
*/
2021-08-17 23:16:45 +00:00
int find_arg_int(const char *const key, int *val);
2014-11-15 15:26:55 +00:00
2014-11-24 19:22:44 +00:00
/**
* @param key The key to search for
* @param val Pointer to the string to set to the key value (if found)
*
* Parse command line argument 'key' to string.
*
2014-11-24 19:35:28 +00:00
* @returns TRUE if key was found and val was set.
2014-11-24 19:22:44 +00:00
*/
2021-08-17 23:16:45 +00:00
int find_arg_str(const char *const key, char **val);
2014-11-15 15:26:55 +00:00
/**
* @param key The key to search for
*
* Parse all command line options 'key' to string vector.
*
* @returns str vector. user should free array.
*/
2021-08-17 23:16:45 +00:00
const char **find_arg_strv(const char *const key);
2014-11-24 19:22:44 +00:00
/**
* @param key The key to search for
*
* Check if key is passed as argument.
*
2014-11-24 19:35:28 +00:00
* @returns return position of string or -1 if not found.
2014-11-24 19:22:44 +00:00
*/
2021-08-17 23:16:45 +00:00
int find_arg(const char *const key);
2014-11-15 15:26:55 +00:00
2014-12-02 08:09:20 +00:00
/**
* @param tokens List of (input) tokens to match.
* @param input The entry to match against.
*
* Tokenized match, match tokens to line input.
*
2016-07-29 06:32:34 +00:00
* @returns TRUE when matches, FALSE otherwise
2014-12-02 08:09:20 +00:00
*/
2021-08-17 23:16:45 +00:00
int helper_token_match(rofi_int_matcher *const *tokens, const char *input);
2015-01-05 20:53:50 +00:00
/**
* @param cmd The command to execute.
*
2021-08-17 23:16:45 +00:00
* Execute cmd using config.run_command and outputs the result (stdout) to the
* opened file descriptor.
2015-01-05 20:53:50 +00:00
*
* @returns a valid file descriptor on success, or -1 on failure.
*/
2021-08-17 23:16:45 +00:00
int execute_generator(const char *cmd) __attribute__((nonnull));
/**
* @param pidfile The pidfile to create.
2022-03-15 00:00:56 +00:00
* @param kill_running Try killing running instance.
*
* returns file descriptor (or -1 when failed)
*/
2022-03-15 00:00:56 +00:00
int create_pid_file(const char *pidfile, gboolean kill_running);
/**
* Remove pid file
*/
2021-08-17 23:16:45 +00:00
void remove_pid_file(int fd);
2015-02-03 07:21:59 +00:00
/**
* Do some input validation, especially the first few could break things.
* It is good to catch them beforehand.
*
2021-08-17 23:16:45 +00:00
* This functions exits the program with 1 when it finds an invalid
* configuration.
2015-02-03 07:21:59 +00:00
*/
2021-08-17 23:16:45 +00:00
int config_sanity_check(void);
2015-03-17 19:05:37 +00:00
/**
* @param arg string to parse.
*
* Parses a string into an character.
*
* @returns character.
*/
2021-08-17 23:16:45 +00:00
char helper_parse_char(const char *arg);
2015-03-17 19:05:37 +00:00
/**
* @param argc number of arguments.
* @param argv Array of arguments.
*
* Set the application arguments.
*/
2021-08-17 23:16:45 +00:00
void cmd_set_arguments(int argc, char **argv);
2015-12-02 16:56:25 +00:00
/**
* @param input The path to expand
*
* Expand path, both `~` and `~<user>`
*
* @returns path
*/
2021-08-17 23:16:45 +00:00
char *rofi_expand_path(const char *input);
/**
* @param needle The string to find match weight off
* @param needlelen The length of the needle
* @param haystack The string to match against
* @param haystacklen The length of the haystack
*
* UTF-8 aware levenshtein distance calculation
*
* @returns the levenshtein distance between needle and haystack
*/
2021-08-17 23:16:45 +00:00
unsigned int levenshtein(const char *needle, const glong needlelen,
const char *haystack, const glong haystacklen);
2016-01-07 07:54:24 +00:00
/**
* @param data the unvalidated character array holding possible UTF-8 data
* @param length the length of the data array
*
2021-08-17 23:16:45 +00:00
* Convert string to valid utf-8, replacing invalid parts with replacement
* character.
*
* @returns the converted UTF-8 string
*/
2021-08-17 23:16:45 +00:00
char *rofi_force_utf8(const gchar *data, ssize_t length);
/**
2016-11-15 20:54:31 +00:00
* @param input the char array holding latin text
* @param length the length of the data array
*
* Converts latin to UTF-8.
*
* @return the UTF-8 representation of data
*/
2021-08-17 23:16:45 +00:00
char *rofi_latin_to_utf8_strdup(const char *input, gssize length);
2017-01-11 08:20:19 +00:00
/**
* @param pattern The user input to match against.
* @param plen Pattern length.
* @param str The input to match against pattern.
2017-11-23 17:41:52 +00:00
* @param slen Length of str.
2017-01-11 08:20:19 +00:00
*
2021-08-17 23:16:45 +00:00
* rofi_scorer_fuzzy_evaluate implements a global sequence alignment algorithm
* to find the maximum accumulated score by aligning `pattern` to `str`. It
* applies when `pattern` is a subsequence of `str`.
*
* Scoring criteria
2021-08-17 23:16:45 +00:00
* - Prefer matches at the start of a word, or the start of subwords in
* CamelCase/camelCase/camel123 words. See WORD_START_SCORE/CAMEL_SCORE.
* - Non-word characters matter. See NON_WORD_SCORE.
2021-08-17 23:16:45 +00:00
* - The first characters of words of `pattern` receive bonus because they
* usually have more significance than the rest. See
* PATTERN_START_MULTIPLIER/PATTERN_NON_START_MULTIPLIER.
* - Superfluous characters in `str` will reduce the score (gap penalty). See
* GAP_SCORE.
* - Prefer early occurrence of the first character. See
* LEADING_GAP_SCORE/GAP_SCORE.
*
* The recurrence of the dynamic programming:
* dp[i][j]: maximum accumulated score by aligning pattern[0..i] to str[0..j]
* dp[0][j] = leading_gap_penalty(0, j) + score[j]
2021-08-17 23:16:45 +00:00
* dp[i][j] = max(dp[i-1][j-1] + CONSECUTIVE_SCORE, max(dp[i-1][k] +
* gap_penalty(k+1, j) + score[j] : k < j))
*
2021-08-17 23:16:45 +00:00
* The first dimension can be suppressed since we do not need a matching
* scheme, which reduces the space complexity from O(N*M) to O(M)
2017-01-11 08:20:19 +00:00
*
* @returns the sorting weight.
*/
2021-08-17 23:16:45 +00:00
int rofi_scorer_fuzzy_evaluate(const char *pattern, glong plen, const char *str,
glong slen);
2016-01-07 07:54:24 +00:00
/*@}*/
/**
* @param a UTF-8 string to compare
* @param b UTF-8 string to compare
* @param n Maximum number of characters to compare
*
* Compares the `G_NORMALIZE_ALL_COMPOSE` forms of the two strings.
*
2021-08-17 23:16:45 +00:00
* @returns less than, equal to, or greater than zero if the first `n`
* characters (not bytes) of `a` are found, respectively, to be less than, to
* match, or be greater than the first `n` characters (not bytes) of `b`.
*/
2021-08-17 23:16:45 +00:00
int utf8_strncmp(const char *a, const char *b, size_t n)
__attribute__((nonnull(1, 2)));
/**
* The startup notification context of the application to launch
*/
2021-08-17 23:16:45 +00:00
typedef struct {
/** The name of the application */
const gchar *name;
/** The binary name of the application */
const gchar *binary;
/** The description of the launch */
const gchar *description;
/** The icon name of the application */
const gchar *icon;
/** The application id (desktop file with the .desktop suffix) */
const gchar *app_id;
/** The window manager class of the application */
const gchar *wmclass;
/** The command we run */
const gchar *command;
} RofiHelperExecuteContext;
/**
2017-06-03 14:27:11 +00:00
* @param wd The working directory.
* @param args The arguments of the command to exec.
* @param error_precmd Prefix to error message command.
* @param error_cmd Error message command
* @param context The startup notification context, if any
*
* Executes the command
*
* @returns TRUE when successful, FALSE when failed.
*/
2021-08-17 23:16:45 +00:00
gboolean helper_execute(const char *wd, char **args, const char *error_precmd,
const char *error_cmd,
RofiHelperExecuteContext *context);
/**
* @param wd The work directory (optional)
* @param cmd The cmd to execute
* @param run_in_term Indicate if command should be run in a terminal
* @param context The startup notification context, if any
*
* Execute command.
2020-10-12 19:39:36 +00:00
* If needed members of context are NULL, they will be filled.
*
* @returns FALSE On failure, TRUE on success
*/
2021-08-17 23:16:45 +00:00
gboolean helper_execute_command(const char *wd, const char *cmd,
gboolean run_in_term,
RofiHelperExecuteContext *context);
/**
* @param file The file path
* @param height The wanted height
* Gets a surface from an svg path
*
* @returns a cairo surface from an svg path
*/
2021-08-17 23:16:45 +00:00
cairo_surface_t *cairo_image_surface_create_from_svg(const gchar *file,
int height);
/**
* Ranges.
*/
/**
* @param input String to parse
* @param list List of ranges
* @param length Length of list.
*
* ranges
*/
2021-08-17 23:16:45 +00:00
void parse_ranges(char *input, rofi_range_pair **list, unsigned int *length);
/**
* @param format The format string used. See below for possible syntax.
* @param string The selected entry.
* @param selected_line The selected line index.
* @param filter The entered filter.
*
* Function that outputs the selected line in the user-specified format.
* Currently the following formats are supported:
* * i: Print the index (0-(N-1))
* * d: Print the index (1-N)
* * s: Print input string.
* * q: Print quoted input string.
* * f: Print the entered filter.
* * F: Print the entered filter, quoted
2020-10-12 19:39:36 +00:00
*
2021-08-17 23:16:45 +00:00
* This functions outputs the formatted string to stdout, appends a newline (\n)
* character and calls flush on the file descriptor.
*/
2021-08-17 23:16:45 +00:00
void rofi_output_formatted_line(const char *format, const char *string,
int selected_line, const char *filter);
/**
* @param string The string with elements to be replaced
2021-08-17 23:16:45 +00:00
* @param ... Set of {key}, value that will be replaced, terminated by a
* NULL
*
2021-08-17 23:16:45 +00:00
* Items {key} are replaced by the value if '{key}' is passed as key/value pair,
* otherwise removed from string. If the {key} is in between [] all the text
* between [] are removed if {key} is not found. Otherwise key is replaced and [
* & ] removed.
*
* This allows for optional replacement, f.e. '{ssh-client} [-t {title}] -e
* "{cmd}"' the '-t {title}' is only there if {title} is set.
*
* @returns a new string with the keys replaced.
*/
2021-08-17 23:16:45 +00:00
char *helper_string_replace_if_exists(char *string, ...);
/**
* @param file File name passed to option.
* @param ext NULL terminated array of file extension passed to option.
*
* @returns path to theme or copy of filename if not found.
*/
2023-03-26 11:19:58 +00:00
char *helper_get_theme_path(const char *file, const char **ext)
__attribute__((nonnull));
/**
* @param name The name of the element to find.
* @param state The state of the element.
* @param exact If the match should be exact, or parent can be included.
*
* Find the configuration element. If not exact, the closest specified element
* is returned.
*
* @returns the ThemeWidget if found, otherwise NULL.
*/
ConfigEntry *rofi_config_find_widget(const char *name, const char *state,
gboolean exact);
/**
* @param widget The widget to find the property on.
* @param type The %PropertyType to find.
* @param property The property to find.
* @param exact If the property should only be found on this widget, or on
* parents if not found.
*
* Find the property on the widget. If not exact, the parents are searched
* recursively until match is found.
*
* @returns the Property if found, otherwise NULL.
*/
Property *rofi_theme_find_property(ConfigEntry *widget, PropertyType type,
const char *property, gboolean exact);
G_END_DECLS
2020-10-12 19:39:36 +00:00
/**@} */
2015-07-27 08:17:12 +00:00
#endif // ROFI_HELPER_H