Skip to content

Commit

Permalink
fix v5 options, add docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@amitguptagwl
amitguptagwl committed Mar 16, 2024
1 parent 391f24f commit 4c26aaa
Show file tree
Hide file tree
Showing 13 changed files with 525 additions and 263 deletions.
215 changes: 11 additions & 204 deletions docs/v5/1. Getting Started.md
View file
Original file line number Diff line number Diff line change
@@ -1,217 +1,24 @@


Example
Example with no configuration

```js
const options = {
preserveOrder: true,
removeNSPrefix: false, // remove NS from tag name or attribute name if true
stopNodes: [], //nested tags will not be parsed even for errors
htmlEntities: false,
tags:{
unpaired: [],
nameFor:{
cdata: false,
comment: false,
text: '#text'
},
separateTextProperty: false,
//"join" only if preserveOrder: true
valueParsers: ["trim","entities","join","boolean","number","currency","date"]
},
attributes: {
ignore: false,
booleanType:true,
entities: true,
//"groupBy": "att"
},
OutputBuilder: new JsObjOutputBuilder()
};
const parser = new XMLParser(options);
const XMLParser = require("fast-xml-parse/v5/XMLParser")
const parser = new XMLParser();
//read xmlData your own
let result = parser.parse(xmlData, true);
```

- You can build your own Output Builder. FXP provides 3 builders
- JsObjOutputBuilder
- JsArrBuilder
- JsMinArrBuilder
- You can control the sequence of value parsing for a tag or attribute
- You can pass a string or bytes array as input.
The default response of parse is built by `JsObjOutputBuilder`. FXP v5 comes with 2 more output builders. And you can set your custom output builder too to customize the output.

### Value Parser
You can change the sequence of value parsers or remove one or provide your own parser to control the parsing.

### Output builders
You can use provided output builds or your own output builder.

JsObjOutputBuilder
```js
{
"soap:Envelope": {
"@_xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/",
"soap:Body": {
"rpt:loadReportFileResponseElem": {
"@_xmlns:s": "http://bus.x.com/common/support/v1",
"@_xmlns:rpt": "http://bus.x.com/service/statement/v1",
"s:code": 0,
"s:responseTime": 2588,
"s:responseDbTime": 1893,
"s:requestId": "6b408fd09eb211e7a0807e34820340ec",
"s:route": "172.16.x.x:9192",
"rpt:result": {
"rpt:file": "<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">\n <soap:Body>\n <rpt:loadReportFileResponseElem\n xmlns:s=\"http://bus.x.com/common/support/v1\"\n xmlns:rpt=\"http://bus.x.com/service/statement/v1\">\n <s:code>0</s:code>\n <s:responseTime>2588</s:responseTime>\n <s:responseDbTime>1893</s:responseDbTime>\n <s:requestId>6b408fd09eb211e7a0807e34820340ec</s:requestId>\n <s:route>172.16.x.x:9192</s:route>\n <rpt:result>\n <rpt:file></rpt:file>\n </rpt:result>\n </rpt:loadReportFileResponseElem>\n </soap:Body>\n</soap:Envelope>"
}
}
}
}
}
```
const JsObjOutputBuilder = require("fast-xml-parse/v5/OutputBuilders/JsObjBuilder");

JsArrBuilder
```js
{
"tagname": "soap:Envelope",
"child": [
{
"tagname": "soap:Body",
"child": [
{
"tagname": "rpt:loadReportFileResponseElem",
"child": [
{
"tagname": "s:code",
"child": [
{
"#text": 0
}
]
},
{
"tagname": "s:responseTime",
"child": [
{
"#text": 2588
}
]
},
{
"tagname": "s:responseDbTime",
"child": [
{
"#text": 1893
}
]
},
{
"tagname": "s:requestId",
"child": [
{
"#text": "6b408fd09eb211e7a0807e34820340ec"
}
]
},
{
"tagname": "s:route",
"child": [
{
"#text": "172.16.x.x:9192"
}
]
},
{
"tagname": "rpt:result",
"child": [
{
"tagname": "rpt:file",
"child": [
{
"#text": "<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">\n <soap:Body>\n <rpt:loadReportFileResponseElem\n xmlns:s=\"http://bus.x.com/common/support/v1\"\n xmlns:rpt=\"http://bus.x.com/service/statement/v1\">\n <s:code>0</s:code>\n <s:responseTime>2588</s:responseTime>\n <s:responseDbTime>1893</s:responseDbTime>\n <s:requestId>6b408fd09eb211e7a0807e34820340ec</s:requestId>\n <s:route>172.16.x.x:9192</s:route>\n <rpt:result>\n <rpt:file></rpt:file>\n </rpt:result>\n </rpt:loadReportFileResponseElem>\n </soap:Body>\n</soap:Envelope>"
}
]
}
]
}
],
":@": {
"@_xmlns:s": "http://bus.x.com/common/support/v1",
"@_xmlns:rpt": "http://bus.x.com/service/statement/v1"
}
}
]
}
],
":@": {
"@_xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/"
}
}
const parser = new XMLParser({
OutputBuilder: new JsObjOutputBuilder()
});
//read xmlData your own
let result = parser.parse(xmlData, true);
```

JsMinArrBuilder
```js
{
"soap:Envelope": [
{
"soap:Body": [
{
"rpt:loadReportFileResponseElem": [
{
"s:code": [
{
"#text": 0
}
]
},
{
"s:responseTime": [
{
"#text": 2588
}
]
},
{
"s:responseDbTime": [
{
"#text": 1893
}
]
},
{
"s:requestId": [
{
"#text": "6b408fd09eb211e7a0807e34820340ec"
}
]
},
{
"s:route": [
{
"#text": "172.16.x.x:9192"
}
]
},
{
"rpt:result": [
{
"rpt:file": [
{
"#text": "<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">\n <soap:Body>\n <rpt:loadReportFileResponseElem\n xmlns:s=\"http://bus.x.com/common/support/v1\"\n xmlns:rpt=\"http://bus.x.com/service/statement/v1\">\n <s:code>0</s:code>\n <s:responseTime>2588</s:responseTime>\n <s:responseDbTime>1893</s:responseDbTime>\n <s:requestId>6b408fd09eb211e7a0807e34820340ec</s:requestId>\n <s:route>172.16.x.x:9192</s:route>\n <rpt:result>\n <rpt:file></rpt:file>\n </rpt:result>\n </rpt:loadReportFileResponseElem>\n </soap:Body>\n</soap:Envelope>"
}
]
}
]
}
],
":@": {
"@_xmlns:s": "http://bus.x.com/common/support/v1",
"@_xmlns:rpt": "http://bus.x.com/service/statement/v1"
}
}
]
}
],
":@": {
"@_xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/"
}
}
```

5 changes: 5 additions & 0 deletions docs/v5/2. Features.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Features
- **Output Builder**: Many projects want a different parsing result. Some wants to group the attributes, some wants to skip an attribute or tag, some wants index number with each property, and some wants to group some properties in array. So FXP v5 come up with 3 output builders. User can customize their behavior and use their own custom builder too.
- You can control the sequence of value parsing for a tag or attribute
- You can pass a string or bytes array as input.
- many to be listed
119 changes: 119 additions & 0 deletions docs/v5/3. Options.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
# Configuration

There are 2 set of configurations.
- Output Builder specific options
- Parser specific options

Eg.

### Parser configuration

```js
{
removeNSPrefix: false, // remove NS from tag name or attribute name if true
//ignoreRootElement : false,
stopNodes: [], //nested tags will not be parsed even for errors
// isArray: () => false, //User will set it
htmlEntities: false,
// skipEmptyListItem: false
tags:{
unpaired: [],
nameFor:{
cdata: false,
comment: false,
text: '#text'
},
separateTextProperty: false,
},
attributes:{
ignore: false,
booleanType: true,
entities: true,
},

// select: ["img[src]"],
// stop: ["anim", "[ads]"]
only: [], // rest tags will be skipped. It will result in flat array
hierarchy: false, //will be used when a particular tag is set to be parsed.
skip: [], // will be skipped from parse result. on('skip') will be triggered

select: [], // on('select', tag => tag ) will be called if match
stop: [], //given tagPath will not be parsed. innerXML will be set as string value
OutputBuilder: new JsArrBuilder(),
}
```

**Note**: There would be some properties which are yet to be supported but mentioned for future use.

### Output Builder specific options

```js
{
preserveOrder: false, // If set 'join' value parser will be used for tag values
nameFor:{
text: "#text",
comment: "",
cdata: "",
},
// onTagClose: () => {},
// onAttribute: () => {},
piTag: false,
declaration: false, //"?xml"
tags: {
valueParsers: [
// "trim",
// "boolean",
// "number",
// "currency",
// "date",
]
},
attributes:{
prefix: "@_",
suffix: "",
groupBy: "",

valueParsers: [
// "trim",
// "boolean",
// "number",
// "currency",
// "date",
]
}
}
```

By default `JsObjOutputBuilder` output builder is used with default options.


Example

```js
const XMLParser = require("fast-xml-parse/v5/XMLParser");
const JsObjOutputBuilder = require("fast-xml-parse/v5/OutputBuilders/JsObjBuilder");
const JsArrBuilder = require("fast-xml-parse/v5/OutputBuilders/JsArrBuilder");
const JsMinArrBuilder = require("fast-xml-parse/v5/OutputBuilders/JsMinArrBuilder");

const xmlData = fs.readFileSync("sample.xml").toString();

const outputBuilderOptions = {
onAttribute: (name, value, tagName) => {
console.log(name, value, tagName)
}
};

const parserOptions = {
attributes: {
ignore: false,
booleanType:true
},

OutputBuilder: new JsObjOutputBuilder(outputBuilderOptions)
};

const parser = new XMLParser(parserOptions);
let result = parser.parse(xmlData);

console.log(JSON.stringify(result,null,4));
```
Loading

0 comments on commit 4c26aaa

Please sign in to comment.