diff --git a/README.md b/README.md index 5f614d81..a7f0b274 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,5 @@ # xmpp.js -[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier) -[![build status](https://img.shields.io/travis/xmppjs/xmpp.js/master.svg?maxAge=2592000&style=flat-square)](https://travis-ci.org/xmppjs/xmpp.js/branches) -[![license](https://img.shields.io/github/license/xmppjs/xmpp.js.svg?maxAge=2592000&style=flat-square)](https://raw.githubusercontent.com/xmppjs/xmpp.js/master/LICENSE) - > XMPP is an open technology for real-time communication, which powers a wide range of applications including instant messaging, presence, multi-party chat, voice and video calls, collaboration, lightweight middleware, content syndication, and generalized routing of XML data. > [xmpp.org/about-xmpp/technology-overview/](https://xmpp.org/about/technology-overview.html) diff --git a/packages/xml/README.md b/packages/xml/README.md index 49a76450..e1f45f1e 100644 --- a/packages/xml/README.md +++ b/packages/xml/README.md @@ -2,7 +2,7 @@ ## Install -Note, if you're using `@xmpp/client` or `@xmpp/component`, you don't need to install `@xmpp/xml` yourself. +Note, if you're using `@xmpp/client` or `@xmpp/component`, you don't need to install `@xmpp/xml`. `npm install @xmpp/xml` or `yarn add @xmpp/xml` @@ -64,7 +64,7 @@ const message = ( ); ``` -Requires a [preprocessor](https://www.npmjs.com/package/babel-plugin-transform-react-jsx) such as [Babel](http://babeljs.io/) with [@babel/plugin-transform-react-jsx](https://babeljs.io/docs/en/next/babel-plugin-transform-react-jsx.html). +Requires a preprocessor such as [TypeScript](https://www.typescriptlang.org/) or [Babel](http://babeljs.io/) with [@babel/plugin-transform-react-jsx](https://babeljs.io/docs/en/next/babel-plugin-transform-react-jsx.html). ## Reading @@ -201,19 +201,9 @@ const body = message.getChild("body"); message.remove(body); ``` -## Parsing XML string - -To parse a string into an XML Element, there's a helper script included in the module. - -```js -const parse = require('@xmpp/xml/lib/parse'); -const ctx = parse('hello world'); -ctx.getChildText("body"); // hello world -``` - ## JSON -You can embed JSON anywhere but it is recommended to use an appropriate semantic. +You can embed JSON anywhere but it is recommended to use appropriate semantic. ```js /** @jsx xml */ @@ -234,3 +224,30 @@ JSON.parse( ``` See [JSON Containers](https://xmpp.org/extensions/xep-0335.html) + +## Parsing XML strings + +`@xmpp/xml` include a function to parse XML strings. + +⚠ Use with care. Untrusted input or substitutions can result in invalid XML and side effects. + +```js +const { escapeXML, escapeXMLText }; +const parse = require("@xmpp/xml/lib/parse"); + +const ctx = parse("hello world"); +ctx.getChildText("body"); // hello world +``` + +If you must use with untrusted input, escape it with `escapeXML` and `escapeXMLText`. + +```js +const { escapeXML, escapeXMLText } = require("@xmpp/xml"); +const parse = require("@xmpp/xml/lib/parse"); + +const message = parse(` + + ${escapeXMLText(body)} + , +`); +```