{"id":22822703,"url":"https://github.com/smooks/smooks-csv-cartridge","last_synced_at":"2025-04-14T01:55:12.873Z","repository":{"id":37942413,"uuid":"247443127","full_name":"smooks/smooks-csv-cartridge","owner":"smooks","description":"Smooks CSV Cartridge","archived":false,"fork":false,"pushed_at":"2025-03-31T23:07:11.000Z","size":239,"stargazers_count":1,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-14T01:55:04.866Z","etag":null,"topics":["csv","csv-to-xml","smooks-cartridge"],"latest_commit_sha":null,"homepage":"https://www.smooks.org/documentation/#csv","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smooks.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-03-15T10:19:26.000Z","updated_at":"2025-02-02T15:01:31.000Z","dependencies_parsed_at":"2024-04-22T23:39:35.209Z","dependency_job_id":null,"html_url":"https://github.com/smooks/smooks-csv-cartridge","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smooks%2Fsmooks-csv-cartridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smooks%2Fsmooks-csv-cartridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smooks%2Fsmooks-csv-cartridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smooks%2Fsmooks-csv-cartridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smooks","download_url":"https://codeload.github.com/smooks/smooks-csv-cartridge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248809032,"owners_count":21164895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csv","csv-to-xml","smooks-cartridge"],"created_at":"2024-12-12T16:13:03.835Z","updated_at":"2025-04-14T01:55:12.842Z","avatar_url":"https://github.com/smooks.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Smooks CSV Cartridge\n\nimage:https://img.shields.io/maven-central/v/org.smooks.cartridges/smooks-csv-cartridge[Maven Central]\nimage:https://img.shields.io/nexus/s/org.smooks.cartridges/smooks-csv-cartridge?server=https%3A%2F%2Foss.sonatype.org[Sonatype Nexus (Snapshots)]\nimage:https://github.com/smooks/smooks-csv-cartridge/workflows/CI/badge.svg[Build Status]\nimage:https://img.shields.io/badge/group-user-red?logo=Gmail[email group,link=https://groups.google.com/g/smooks-user]\nimage:https://img.shields.io/badge/group-dev-red?logo=Gmail[email group,link=https://groups.google.com/g/smooks-dev]\nimage:https://img.shields.io/badge/chat-on%20gitter-46bc99.svg[Gitter chat,link=https://gitter.im/smooks/smooks]\n\n// tag::smooks-csv-cartridge[]\nThis example shows an XML resource configuration of a CSV reader:\n\n.smooks-config.xml\n[source,xml]\n----\n\u003c?xml version=\"1.0\"?\u003e\n\u003csmooks-resource-list xmlns=\"https://www.smooks.org/xsd/smooks-2.0.xsd\"\n                      xmlns:csv=\"https://www.smooks.org/xsd/smooks/csv-1.7.xsd\"\u003e\n\n    \u003c!--\n        Configure the CSV to parse the message into a stream of SAX events.\n    --\u003e\n    \u003ccsv:reader fields=\"firstname,lastname,gender,age,country\" separator=\"|\" quote=\"'\" skipLines=\"1\" /\u003e\n\n\u003c/smooks-resource-list\u003e\n----\n\nThe above configuration will generate an event stream of the form:\n\n[source,xml]\n----\n\u003ccsv-set\u003e\n    \u003ccsv-record\u003e\n        \u003cfirstname\u003eTom\u003c/firstname\u003e\n        \u003clastname\u003eFennelly\u003c/lastname\u003e\n        \u003cgender\u003eMale\u003c/gender\u003e\n        \u003cage\u003e21\u003c/age\u003e\n        \u003ccountry\u003eIreland\u003c/country\u003e\n    \u003c/csv-record\u003e\n    \u003ccsv-record\u003e\n        \u003cfirstname\u003eTom\u003c/firstname\u003e\n        \u003clastname\u003eFennelly\u003c/lastname\u003e\n        \u003cgender\u003eMale\u003c/gender\u003e\n        \u003cage\u003e21\u003c/age\u003e\n        \u003ccountry\u003eIreland\u003c/country\u003e\n    \u003c/csv-record\u003e\n\u003c/csv-set\u003e\n----\n\n== Defining fields\n\nFields can be defined in either of two ways:\n\n. On the `+fields+` attribute of the `+\u003ccsv:reader\u003e+` configuration (as shown above).\n. As the first record in the message after setting the `+fieldsInMessage+` attribute of the `+\u003ccsv:reader\u003e+` configuration to `+true+`.\n\nThe field names must follow the same naming rules like XML element names:\n\n* Names can contain letters, numbers, and other characters\n* Names cannot start with a number or punctuation character\n* Names cannot start with the letters xml (or XML, or Xml, etc...)\n* Names cannot contain spaces\n\nBy setting the `+rootElementName+` and `+recordElementName+` attributes you can modify the and element names. The same naming rules apply for these names.\n\n=== Multi-Record Field Definitions\n\nAll Flat File based reader configurations (including the CSV reader) support _Multi-Record Field Definitions_, which means that the reader can support CSV message streams containing varying (multiple different types) CSV record types.\n\nTake the following CSV message example:\n\n....\nbook,22 Britannia Road,Amanda Hodgkinson\nmagazine,Time,April,2011\nmagazine,Irish Garden,Jan,2011\nbook,The Finkler Question,Howard Jacobson\n....\n\nIn this stream, we have 2 record types of \"book\" and \"magazine\". We configure the CSV reader to process this stream as follows:\n\n.smooks-config.xml\n[source,xml]\n----\n\u003ccsv:reader fields=\"book[name,author] | magazine[*]\" rootElementName=\"sales\" indent=\"true\" /\u003e\n----\n\nThis reader configuration will generate the following output for the above sample message:\n\n[source,xml]\n----\n\u003csales\u003e\n    \u003cbook number=\"1\"\u003e\n        \u003cname\u003e22 Britannia Road\u003c/name\u003e\n        \u003cauthor\u003eAmanda Hodgkinson\u003c/author\u003e\n    \u003c/book\u003e\n    \u003cmagazine number=\"2\"\u003e\n        \u003cfield_0\u003eTime\u003c/field_0\u003e\n        \u003cfield_1\u003eApril\u003c/field_1\u003e\n        \u003cfield_2\u003e2011\u003c/field_2\u003e\n    \u003c/magazine\u003e\n    \u003cmagazine number=\"3\"\u003e\n        \u003cfield_0\u003eIrish Garden\u003c/field_0\u003e\n        \u003cfield_1\u003eJan\u003c/field_1\u003e\n        \u003cfield_2\u003e2011\u003c/field_2\u003e\n    \u003c/magazine\u003e\n    \u003cbook number=\"4\"\u003e\n        \u003cname\u003eThe Finkler Question\u003c/name\u003e\n        \u003cauthor\u003eHoward Jacobson\u003c/author\u003e\n    \u003c/book\u003e\n\u003c/sales\u003e\n----\n\nNote the syntax in the `+fields+` attribute. Each record definition is separated by the pipe character `+|+`. Each record definition is constructed as _record-name[field-name,field-name]_. _record-name_ is matched against the first field in the incoming message and so used to select the appropriate record definition to be used for outputting that record. Also note how you can use an astrix character ('*') when you don't want to name the record fields. In this case (as when extra/unexpected fields are present in a record), the reader will generate the output field elements using a generated element name e.g. \"field_0\", \"field_1\", etc... See the \"magazine\" record in the previous example.\n\nNOTE: Multi Record Field Definitions are not supported when the fields are defined in the message (`+fieldsInMessage=\"true\"+`).\n\n=== String Manipulation Functions\n\nLike the fixed-length cartridge, string manipulation functions can be defined per field. These functions are executed before that the data is converted into SAX events. The functions are defined after field name, separated with a question mark.\n\n.smooks-config.xml\n[source,xml]\n----\n\u003c?xml version=\"1.0\"?\u003e\n\u003csmooks-resource-list xmlns=\"https://www.smooks.org/xsd/smooks-2.0.xsd\"\n                      xmlns:csv=\"https://www.smooks.org/xsd/smooks/csv-1.7.xsd\"\u003e\n\n    \u003ccsv:reader fields=\"lastname?trim.capitalize,country?upper_case\" /\u003e\n\n\u003c/smooks-resource-list\u003e\n----\n\nTake a look at the fixed-length cartridge's https://github.com/smooks/smooks-fixed-length-cartridge/blob/master/README.adoc#string-manipulation-functions[string manipulation functions] to learn about the available functions and how the functions can be chained.\n\n=== Ignoring Fields\n\nOne or more fields of a CSV record can be ignored by specifying the `+$ignore$+` token in the fields configuration value. You can specify the number of fields to be ignored simply by following the $ignore$ token with a number e.g. `+$ignore$3+` to ignore the next 3 fields. `+$ignore$++` ignores all fields to the end of the CSV record.\n\n.smooks-config.xml\n[source,xml]\n----\n\u003c?xml version=\"1.0\"?\u003e\n\u003csmooks-resource-list xmlns=\"https://www.smooks.org/xsd/smooks-2.0.xsd\"\n                      xmlns:csv=\"https://www.smooks.org/xsd/smooks/csv-1.7.xsd\"\u003e\n\n    \u003ccsv:reader fields=\"firstname,$ignore$2,age,$ignore$+\" /\u003e\n\n\u003c/smooks-resource-list\u003e\n----\n\n=== Binding CSV Records to Java\n\nSmooks v1.2 added support for making the binding of CSV records to Java objects a very trivial task. You no longer need to use the Javabean Cartridge directly (i.e. Smooks main Java binding functionality).\n\nNOTE: This feature is not supported for Multi Record Field Definitions (see above), or when the fields are defined in the incoming message (`+fieldsInMessage=\"true\"+`).\n\nA Persons CSV record set such as:\n\n....\nTom,Fennelly,Male,4,Ireland\nMike,Fennelly,Male,2,Ireland\n....\n\nCan be bound to a Person of (no getters/setters):\n\n[source,java]\n----\npublic class Person {\n    private String firstname;\n    private String lastname;\n    private String country;\n    private Gender gender;\n    private int age;\n}\n\npublic enum Gender {\n    Male,\n    Female;\n}\n----\n\nUsing a config of the form:\n\n.smooks-config.xml\n[source,xml]\n----\n\u003c?xml version=\"1.0\"?\u003e\n\u003csmooks-resource-list xmlns=\"https://www.smooks.org/xsd/smooks-2.0.xsd\"\n                      xmlns:csv=\"https://www.smooks.org/xsd/smooks/csv-1.7.xsd\"\u003e\n\n    \u003ccsv:reader fields=\"firstname,lastname,gender,age,country\"\u003e\n        \u003c!-- Note how the field names match the property names on the Person class. --\u003e\n        \u003ccsv:listBinding beanId=\"people\" class=\"org.smooks.csv.Person\" /\u003e\n    \u003c/csv:reader\u003e\n\n\u003c/smooks-resource-list\u003e\n----\n\nTo execute this configuration:\n\n[source,java]\n----\nSmooks smooks = new Smooks(configStream);\nJavaSink sink = new JavaSink();\n\nsmooks.filterSource(new StreamSource(csvStream), sink);\n\nList\u003cPerson\u003e people = (List\u003cPerson\u003e) sink.getBean(\"people\");\n----\n\nSmooks also supports creation of Maps from the CSV record set:\n\n.smooks-config.xml\n[source,xml]\n----\n\u003c?xml version=\"1.0\"?\u003e\n\u003csmooks-resource-list xmlns=\"https://www.smooks.org/xsd/smooks-2.0.xsd\"\n                      xmlns:csv=\"https://www.smooks.org/xsd/smooks/csv-1.7.xsd\"\u003e\n\n    \u003ccsv:reader fields=\"firstname,lastname,gender,age,country\"\u003e\n        \u003ccsv:mapBinding beanId=\"people\" class=\"org.smooks.csv.Person\" keyField=\"firstname\" /\u003e\n    \u003c/csv:reader\u003e\n\n\u003c/smooks-resource-list\u003e\n----\n\nThe above configuration would produce a map of Person instances, keyed by the \"firstname\" value of each Person. It would be executed as follows:\n\n[source,java]\n----\nSmooks smooks = new Smooks(configStream);\nJavaSink sink = new JavaSink();\n\nsmooks.filterSource(new StreamSource(csvStream), sink);\n\nMap\u003cString, Person\u003e people = (Map\u003cString, Person\u003e) sink.getBean(\"people\");\n\nPerson tom = people.get(\"Tom\");\nPerson mike = people.get(\"Mike\");\n----\n\nlink:#virtual-object-models-maps--lists[Virtual Models] are also supported, so you can define the `+class+` attribute as a `+java.util.Map+` and have the CSV field values bound into Map instances, which are in turn added to a List or a Map.\n\n== Java API\n\nProgrammatically configuring the CSV Reader on a Smooks instance is trivial. A number of options are available.\n\n=== Configuring Directly on the Smooks Instance\n\nThe following code configures a Smooks instance with a `+CSVReader+` for reading a people record set (see above), binding the record set into a List of Person instances:\n\n[source,java]\n----\nSmooks smooks = new Smooks();\n\nsmooks.setReaderConfig(new CSVReaderConfigurator(\"firstname,lastname,gender,age,country\")\n      .setBinding(new CSVBinding(\"people\", Person.class, CSVBindingType.LIST)));\n\nJavaSink sink = new JavaSink();\nsmooks.filterSource(new ReaderSource(csvReader), sink);\n\nList\u003cPerson\u003e people = (List\u003cPerson\u003e) sink.getBean(\"people\");\n----\n\nOf course configuring the Java binding is totally optional. The Smooks instance could instead (or in conjunction with) be programmatically configured with other visitors for carrying out other forms of processing on the CSV record set.\n\n=== CSV List and Map Binders\n\nIf you're just interested in binding CSV records directly onto a `+List+` or `+Map+` of a Java type that reflects the data in your CSV records, then you can use the `+CSVListBinder+` or `+CSVMapBinder+` classes.\n\nCSVListBinder:\n\n[source,java]\n----\n// Note: The binder instance should be cached and reused...\nCSVListBinder binder = new CSVListBinder(\"firstname,lastname,gender,age,country\", Person.class);\n\nList\u003cPerson\u003e people = binder.bind(csvStream);\n----\n\nCSVMapBinder:\n\n[source,java]\n----\n// Note: The binder instance should be cached and reused...\nCSVMapBinder binder = new CSVMapBinder(\"firstname,lastname,gender,age,country\", Person.class, \"firstname\");\n\nMap\u003cString, Person\u003e people = binder.bind(csvStream);\n----\n\nIf you need more control over the binding process, revert back to the lower level APIs:\n\n* link:#configuring-directly-on-the-smooks-instance[Configuring Directly on the Smooks Instance]\n* link:#java-binding[Java Binding]\n\n== Maven Coordinates\n\n.pom.xml\n[source,xml]\n----\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.smooks.cartridges\u003c/groupId\u003e\n    \u003cartifactId\u003esmooks-csv-cartridge\u003c/artifactId\u003e\n    \u003cversion\u003e2.0.3\u003c/version\u003e\n\u003c/dependency\u003e\n----\n\n== XML Namespace\n....\nxmlns:csv=\"https://www.smooks.org/xsd/smooks/csv-1.7.xsd\"\n....\n// end::smooks-csv-cartridge[]\n\n== License\n\nSmooks CSV Cartridge is open source and licensed under the terms of the Apache License Version 2.0, or the GNU Lesser General Public License version 3.0 or later. You may use Smooks CSV Cartridge according to either of these licenses as is most appropriate for your project.\n\n`+SPDX-License-Identifier: Apache-2.0 OR LGPL-3.0-or-later+`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmooks%2Fsmooks-csv-cartridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmooks%2Fsmooks-csv-cartridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmooks%2Fsmooks-csv-cartridge/lists"}