matrix-parser is a Node.js Middleware for parsing Matrix URIs
Install
npm install matrix-parser
Run Tests
traverse to the root directory 'matrix-parser' and:
npm installnpm test
API
var matrixParser = ;
The matrixParser
object exposes a single function - the Middleware to parse matrix-style URIs. When used, it creates the matrix Array inside the request object, which can be accessed like req.matrix
Options
You can pass an options
object when calling matrixParser (). The object currently supports the maxKeys
field, used to specify the maximum number of keys allowed per segment. Keys are added into the matrix object from left to right.
For example, using matrixParser ({ maxKeys: 2 })
and a URI http://example.com/home;k1=v2;k2=v2;k3=v3
will simply neglect all key-value pairs after k2.
NOTE: The middleware currently doesn't support Matrix URIs to be used in combination with query strings. You could use matrix parameters before the '?', followed by query parameters, but mixing is not currently supported.
Rules
Here are the rules matrix-parser follows to parse Matrix URIs. Check out this thread to understand in more detail.
1. The semicolon ';' is used to delimit key-value pairs (unlike the ampersand '&' in query strings)
eg- /index;a=b;c=d
2. '=' is used to delimit the keys and values
3. The string between / and the first ; is the segment name.
eg- /index;hello=world
here, segment = "index"
4. All keys are unique. For compatibility, the key's last declaration is used to assign its value
eg- /index;key1=value1;key2=v2;key1=helloworld
here, the value of key1 = 'helloworld' (NOT value1)
5. Comma ',' is used to assign multiple values to a key
eg- /index;list=1,2,3,4
here, list = [1,2,3,4] (array containing the comma-separated values)
6. Spaces are encoded as %20 instead of +
eg- /index;msg=hello%20world
7. If a key is not followed by the delimiter '=' and value, it is discarded
eg- /index;a=b;noValueKey;c=d
here, noValueKey will be discarded and will not be present in the matrix
8. If a key is followed by the delimiter '=' but not a value, its value is set to ''
eg- /index;key=;a=b
here, key = ''
9. If no segment name is given, it defaults to ''
eg- http://example.com/;key=value
here, segment = '' and key = 'value'
10. If the path name is empty, req.matrix defaults an array of single object with segment = '' and matrix = {}
eg- http://example.com/
here, req.matrix = [ {segment: "", matrix: {}} ]
Format
A typical Matrix URI looks like:
http://<DOMAIN>:<PORT>/<SEGMENT-0>;<KEY1>=<VALUE1>;<KEY2>=<VALUE2>/<SEGMENT-1>;<KEY1>=<VALUE1>
The constructed req.matrix looks like:
[
{
segment: <SEGMENT-0>,
matrix: {
<KEY1> : <VALUE1>,
<KEY2> : <VALUE2>
}
},
{
segment: <SEGMENT-1>,
matrix: {
<KEY2> : <VALUE2>
}
}
]
Examples
Express: Top-level generic
var app = matrixParser = ; app ;
NOTE: If you want to allow Matrix on a specific route (like '/index'), then you have to append '*' to it like
app;
Test:
curl 'http://localhost:8080/index;name=RAGHAV%20DUA;house=targarian/profile;age=20;email=duaraghav8%40gmail.com'
NOTICE THE %20 USED TO INDICATE SPACE INSTEAD OF +
Output Construct of req.matrix
:
segment: 'index' matrix: name: 'RAGHAV DUA' house: 'targarian' segment: 'profile' matrix: age: 20 email: 'duaraghav8@gmail.com'
Express: Route-specific
var app = matrixParser = ; var colorCodes = "white": "#FFFFFF" "black": "#000000"; var mpMiddleware = ; app ;
Test 1:
curl 'http://localhost:8080/index;color=white'
Output: Color code for white is #FFFFFF
Test 2:
curl 'http://localhost:8080/index;color=indigo'
Output: Color code for white is undefined
(because color code for indigo is not defined in colorCodes object in our script)
License
MIT