Component offers an API to parse and build a buffer of Comma Separated Values (CSV). The CSV snytax accepted by parse must adhere to IETF RFC 4180 while build produces one compliant to it.
API Index
API
Install
Test
License MIT
csv_field_append
csv_field_get
csv_field_get_unset_as_empty
# ##############################################################################
# #
# # Purpose
# # Build CSV by concatenating one or more fields to the tail
# # of an existing string or empty one. A comma will be added to an
# # existing string iff it's not already terminated by a comma. Field
# # values containing a double quote or comma are encapsulated in double
# # quotes to comply with spec.
# # In
# # $1 - A variable name whose value contains an existing string or
# # empty one.
# # $2-N - Zero, one, or more values passed by the caller to append
# # to the end of $1.
# # Out
# # $1 - This variable's value (call by reference) will be updated
# # to reflect the added CSV formatted fields.
# ##############################################################################
# ##############################################################################
# #
# # Purpose
# # Parse CSV and extract the values between each comma delimited field.
# # The extracted values are returned to the caller in separate variables.
# # In
# # $1 - A string conformant to CSV spec. An empty string is considered
# # conformant. Also, parser implements the imperfect everyday form
# # that's less strict then the specification For example: two commas
# # ",," without data preceeding or following them
# # are treated as three null fields.
# # $2 - A variable name to return the number of unset variable names
# # in the list of names that follows this parameter. A variable
# # is unset when there isn't a corresponding CSV field in the
# # supplied string. A corresponding CSV field must be terminated
# # by a deliminating comma. Except for the last field which
# # is terminated by an EOL.
# # $3-N - Zero, one, or more variable names passed by the caller that
# # receive the parsed values. To return the rest of the string,
# # that would be parsed to provide a value for the next requested
# # field, specify the variable csv_field_REMAINDER. Use bash
# # indirect expansion operator ${!csv_field_REMAINDER} to obtain
# # this variable's value that will be assigned the field's value.
# # This feature can be helpful to detect additional unexpected data.
# # Out
# # $2 - This return variable name is assigned the value of the number
# # of unset variables.
# # $3-N - The variable names defined by this list will be updated with
# # values extracted from the CSV string as long as this string isn't
# # exhausted. If a greater number of variables are specified than
# # can be satisfied, the remaining variables are not changed. This
# # behavior also applies to variable referenced by csv_field_REMAINDER.
# # Therefore, initialize this variable with some value, like a
# # zero length string so a nonempty remainder can be detected.
# # Ex: local ${csv_field_REMAINDER}=''
# # Return
# # 1 - Supplied CSV string fails to conform to CSV specification.
csv_field_get_unset_as_empty
# ##############################################################################
# #
# # Purpose
# # Performs same parse CSV and extract as csv_field_get, however, it places
# # an empty string value ('') in the passed variables when the CSV row
# # is truncated - leaving nothing to assign these variables. Remember, an
# # empty string assigned to a declared integer: "local -i variable" is
# # converted into "0".
# # In
# # $1 - A string conformant to CSV spec. An empty string is considered
# # conformant. Also, parser implements the imperfect everyday form
# # that's less strict then the specification For example: two commas
# # ",," without data preceeding or following them
# # are treated as three null fields.
# # $2-N - Zero, one, or more variable names passed by the caller that
# # receive the parsed values. To return the rest of the string,
# # that would be parsed to provide a value for the next requested
# # field, specify the variable csv_field_REMAINDER. Use bash
# # indirect expansion operator ${!csv_field_REMAINDER} to obtain
# # the field's value. his feature can be helpful to detect
# # additional unexpected data.
# # Out
# # $2-N - The variable names defined by this list will be updated with
# # values extracted from the CSV string. When a greater number
# # of variable names are specified than can be satisfied by the
# # CSV string, the remaining variables are are set to ''.
# # Return
# # 1 - Supplied CSV string fails to conform to CSV specification.
# ##############################################################################
Copy csv.source.sh into a directory then use the Bash source command to include this package in a Bash script before executing fuctions which rely on its API . Copying using:
git clone
to copy entire project contents including its git repository. Obtains current master which may include untested features. To synchronize the working directory to reflect the desired release, use git checkout tags/<tag_name>
.
wget https://github.com/whisperingchaos/csv.source.sh/tarball/master
creates a tarball that includes only the project files without the git repository. Obtains current master branch which may include untested features.
TODO
GNU Bash, version 4.3.48(1)-release
This component relies on nameref/name reference feature introduced in version 4.3.
After installing , change directory to csv.source.sh 's test
. Then run:
./config.sh
followed by
./csv_source_test.sh . It should complete successfully and not produce any messages.
host:~/Desktop/projects/csv.source.sh/test$ ./csv.source_test.sh
host:~/Desktop/projects/csv.source.sh/test$