NAME

stropt, stroptx, stropt2buf, stropt2str - Parse options from a string (it supports quotation, option arguments)

SYNOPSIS

#include <stropt.h>

int stropt(const char *input, char **tags, char **args, char *buf);

int stroptx(const char *input, char *features, char *sep, int flags, char **tags, char **args, char *buf);

char *stropt2buf(void *buf, size_t size, char **tags, char **args, char sep, char eq);

char *stropt2str(char **tags, char **args, char sep, char eq);

DESCRIPTION

This small library parses a list of options from a string. Options can be separated by spaces, commas, semicolons, tabs or new line. (e.g. uppercase,bold,underlined ). Options may have arguments (e.g. ro,noatime,uid=0,gid=0 ). It is possible to protect symbols and spaces using quote, double quote and backslash (e.g. values='1,2,3,4',equal== )

stropt

This function parses a list of options from the string input. Options can be separated by commas, semicolons, tabs oe new lines. Options may have arguments in the form keyword=value. buf is a temporary buffer, it must have the same size of the input string (including the NULL terminator). tags and args are the resulting arrays of options and arguments respectively. Both tags and args have one NULL terminator element at the end. When an option has not an argument the corresponding args element is NULL. For example if input is "font=12,typeface=bodoni,italic", tags[0]="font", tags[1]="typeface", tags[2]="italic", tags[4]=NULL, args[0]="12", args[1]="bodoni", args[0]=NULL, args[4]=NULL.

When stropt is called with tags, args, and buf all NULL, it parses the input, counting the options. The return value can be used to allocate suitable arrays for tags and args.

It is possible to use the same variable as input and buffer. In this case the original value of input is overwritten.

stroptx

This is a more configurable extension of stropt. Arguments having the same names as in stropt have the same meaning as explained above.

The string features permits one to enable/disable some of the standard features. Each feature corresponds to a mnemonic character, when the character is in the features string the feature is enabled:

': single quoting,

": double quoting,

\: character escape,

\n:input in several lines,

=: allow arguments,

#: support comments.

If features is NULL all the features are enabled, when features is an empty string all features are disabled.

All the characters included in sep are considered as option separators. If sep is NULL, the default value is " \t;,".

The flag argument may include the bitwise OR of any of the following flag values:

STROPTX_KEEP_QUOTATION_MARKS_IN_TAGS: preserve the quotation marks in tags,

STROPTX_KEEP_QUOTATION_MARKS_IN_ARGS: preserve the quotation marks in args,

STROPTX_KEEP_QUOTATION_MARKS: shortcut for STROPTX_KEEP_QUOTATION_MARKS_IN_TAGS | STROPTX_KEEP_QUOTATION_MARKS_IN_ARGS

STROPTX_ALLOW_MULTIPLE_SEP: when it is not set, a sequence of separators is processed as a single separator, when it is set each sequence of two separators means an empty field in between.

STROPTX_NEWLINE_TAGS: when set each new line is encoded as a tag "\n".

stropt2buf

This function re-encodes an array of options (and an array of arguments) in a string. It is the inverse function of of stropt. Given a buffer buf of size size, the array of options tags with their corresponding values in the array args is encoded using the separator character sep and the assignment character eq.

Elements whose option tag (element of tags) value is STROPTX_DELETED_TAG are omitted in output.

stropt2str

This is the sibling function of stropt2buf. It uses dynamically allocated memory instead of a buffer provided by the caller. The resulting string must be deallocated using free(3).

RETURN VALUE

• stropt and stroptx return the number of options + 1.
• stropt2buf and stropt2str return the resulting string.

EXAMPLES

The following function lists the option tags and arguments (without modyfying the input string).

void parse_args(char *input) {


  int tagc = stropt(input, NULL, NULL, NULL);


  if(tagc > 0) {


    char buf[strlen(input)+1];


    char *tags[tagc];


    char *args[tagc];


    stropt(input, tags, args, buf);


    for (int i=0; i<tagc; i++)


      printf("%s = %s\n",tags[i], args[i]);


  }
}

it is possible to use the same input string as the buffer for parsing (the value of the input string gets lost in this way).

void parse_args(char *input) {


  int tagc = stropt(input, NULL, NULL, NULL);


  if(tagc > 0) {


    char *tags[tagc];


    char *args[tagc];


    stropt(input, tags, args, input);


    for (int i=0; i<tagc; i++)


      printf("%s = %s\n",tags[i], args[i]);


  }
}

when options to parse have no arguments, args can be set to NULL.

void parse_args(char *input) {


  int tagc = stropt(input, NULL, NULL, NULL);


  if(tagc > 0) {


    char buf[strlen(input)+1];


    char *tags[tagc];


    stropt(input, tags, NULL, buf);


    for (int i=0; i<tagc; i++)


      printf("%s \n",tags[i]);


  }
}

The following complete program parses and re-encode a string of comma separated arguments deleting those which begin by an uppercase letter.

#include <stdio.h>
#include <ctype.h>
#include <stdlib.h>
#include <string.h>
#include <stropt.h>
char *delete_uppercase_options(const char *input) {


  int tagc = stroptx(input, "", ",",STROPTX_ALLOW_MULTIPLE_SEP, NULL, NULL, NULL);


  if(tagc > 0) {


    char buf[strlen(input)+1];


    char *tags[tagc];


    int i;


    stroptx(input, "", ",",STROPTX_ALLOW_MULTIPLE_SEP, tags, NULL, buf);


    for (i = 0; i < tagc; i++)


      if (tags[i] && isupper(tags[i][0]))


        tags[i] = STROPTX_DELETED_TAG;


    return stropt2str(tags, NULL, ',', '=');


  } else


    return NULL;
}
int main(int argc, char *argv[]) {


  if (argc > 1) {


    char *result = delete_uppercase_options(argv[1]);


    printf("%s\n", result);


    free(result);


  }


  return 0;
}

AUTHOR

VirtualSquare. Project leader: Renzo Davoli.