.\" Copyright (C) 2019 VirtualSquare. Project Leader: Renzo Davoli
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License,
.\" as published by the Free Software Foundation, either version 2
.\" of the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
.\" MA 02110-1301 USA.
.\"
.\" generated with Ronn-NG/v0.10.0
.\" http://github.com/apjanke/ronn-ng/tree/0.10.0-SNAPSHOT
.TH "STROPT" "3" "August 2020" "VirtualSquare"
.SH "NAME"
stropt, stroptx, stropt2buf, stropt2str \- Parse options from a string (it supports quotation, option arguments)
.SH "SYNOPSIS"
\fB#include <stropt\.h>\fR
.P
\fBint stropt(const char *\fR\fIinput\fR\fB, char **\fR\fItags\fR\fB, char **\fR\fIargs\fR\fB, char *\fR\fIbuf\fR\fB);\fR
.P
\fBint stroptx(const char *\fR\fIinput\fR\fB, char *\fR\fIfeatures\fR\fB, char *\fR\fIsep\fR\fB, int\fR \fIflags\fR\fB, char **\fR\fItags\fR\fB, char **\fR\fIargs\fR\fB, char *\fR\fIbuf\fR\fB);\fR
.P
\fBchar *stropt2buf(void *\fR\fIbuf\fR\fB, size_t\fR \fIsize\fR\fB, char **\fR\fItags\fR\fB, char **\fR\fIargs\fR\fB, char\fR \fIsep\fR\fB, char\fR \fIeq\fR\fB);\fR
.P
\fBchar *stropt2str(char **\fR\fItags\fR\fB, char **\fR\fIargs\fR\fB, char\fR \fIsep\fR\fB, char\fR \fIeq\fR\fB);\fR
.SH "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\. \fIuppercase,bold,underlined\fR )\. Options may have arguments (e\.g\. \fIro,noatime,uid=0,gid=0\fR )\. It is possible to protect symbols and spaces using quote, double quote and backslash (e\.g\. \fIvalues='1,2,3,4',equal==\fR )
.TP
\fBstropt\fR
This function parses a list of options from the string \fIinput\fR\. Options can be separated by commas, semicolons, tabs oe new lines\. Options may have arguments in the form \fIkeyword=value\fR\. \fIbuf\fR is a temporary buffer, it must have the same size of the \fIinput\fR string (including the NULL terminator)\. \fItags\fR and \fIargs\fR are the resulting arrays of options and arguments respectively\. Both \fItags\fR and \fIargs\fR have one NULL terminator element at the end\. When an option has not an argument the corresponding \fIargs\fR element is NULL\. For example if \fIinput\fR is "font=12,typeface=bodoni,italic", \fItags[0]\fR="font", \fItags[1]\fR="typeface", \fItags[2]\fR="italic", \fItags[4]\fR=NULL, \fIargs[0]\fR="12", \fIargs[1]\fR="bodoni", \fIargs[0]\fR=NULL, \fIargs[4]\fR=NULL\.
.IP
When \fBstropt\fR is called with \fItags\fR, \fIargs\fR, and \fIbuf\fR all NULL, it parses the input, counting the options\. The return value can be used to allocate suitable arrays for \fItags\fR and \fIargs\fR\.
.IP
It is possible to use the same variable as \fIinput\fR and \fIbuffer\fR\. In this case the original value of \fIinput\fR is overwritten\.
.TP
\fBstroptx\fR
This is a more configurable extension of \fBstropt\fR\. Arguments having the same names as in \fBstropt\fR have the same meaning as explained above\.
.IP
The string \fIfeatures\fR permits one to enable/disable some of the standard features\. Each feature corresponds to a mnemonic character, when the character is in the \fIfeatures\fR string the feature is enabled:
.IP
\fB'\fR: single quoting,
.IP
\fB"\fR: double quoting,
.IP
\fB\e\fR: character escape,
.IP
\fB\en\fR:input in several lines,
.IP
\fB=\fR: allow arguments,
.IP
\fB#\fR: support comments\.
.IP
If \fIfeatures\fR is NULL all the features are enabled, when \fIfeatures\fR is an empty string all features are disabled\.
.IP
All the characters included in \fIsep\fR are considered as option separators\. If \fIsep\fR is NULL, the default value is " \et;,"\.
.IP
The \fIflag\fR argument may include the bitwise OR of any of the following flag values:
.IP
\fBSTROPTX_KEEP_QUOTATION_MARKS_IN_TAGS\fR: preserve the quotation marks in tags,
.IP
\fBSTROPTX_KEEP_QUOTATION_MARKS_IN_ARGS\fR: preserve the quotation marks in args,
.IP
\fBSTROPTX_KEEP_QUOTATION_MARKS\fR: shortcut for \fBSTROPTX_KEEP_QUOTATION_MARKS_IN_TAGS | STROPTX_KEEP_QUOTATION_MARKS_IN_ARGS\fR
.IP
\fBSTROPTX_ALLOW_MULTIPLE_SEP\fR: 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\.
.IP
\fBSTROPTX_NEWLINE_TAGS\fR: when set each new line is encoded as a tag "\en"\.
.TP
\fBstropt2buf\fR
This function re\-encodes an array of options (and an array of arguments) in a string\. It is the inverse function of of \fBstropt\fR\. Given a buffer \fIbuf\fR of size \fIsize\fR, the array of options \fItags\fR with their corresponding values in the array \fIargs\fR is encoded using the separator character \fIsep\fR and the assignment character \fIeq\fR\.
.IP
Elements whose option tag (element of \fItags\fR) value is \fBSTROPTX_DELETED_TAG\fR are omitted in output\.
.TP
\fBstropt2str\fR
This is the sibling function of \fBstropt2buf\fR\. It uses dynamically allocated memory instead of a buffer provided by the caller\. The resulting string must be deallocated using free(3)\.
.SH "RETURN VALUE"
.IP "\(bu" 4
\fBstropt\fR and \fBstroptx\fR return the number of options + 1\.
.IP "\(bu" 4
\fBstropt2buf\fR and \fBstropt2str\fR return the resulting string\.
.IP "" 0
.SH "EXAMPLES"
The following function lists the option tags and arguments (without modyfying the input string)\.
.IP "" 4
.nf
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\en",tags[i], args[i]);
  }
}
.fi
.IP "" 0
.P
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)\.
.IP "" 4
.nf
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\en",tags[i], args[i]);
  }
}
.fi
.IP "" 0
.P
when options to parse have no arguments, args can be set to NULL\.
.IP "" 4
.nf
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 \en",tags[i]);
  }
}
.fi
.IP "" 0
.P
The following complete program parses and re\-encode a string of comma separated arguments deleting those which begin by an uppercase letter\.
.IP "" 4
.nf
#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\en", result);
    free(result);
  }
  return 0;
}
.fi
.IP "" 0
.SH "AUTHOR"
VirtualSquare\. Project leader: Renzo Davoli\.