603 lines
19 KiB
HTML
603 lines
19 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="sidebar-visible no-js light">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Mercator Parser</title>
|
|
|
|
<meta name="robots" content="noindex" />
|
|
|
|
|
|
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
|
<meta name="description" content="">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff" />
|
|
|
|
<link rel="shortcut icon" href="favicon.png">
|
|
<link rel="stylesheet" href="css/variables.css">
|
|
<link rel="stylesheet" href="css/general.css">
|
|
<link rel="stylesheet" href="css/chrome.css">
|
|
<link rel="stylesheet" href="css/print.css" media="print">
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
|
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
|
|
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" href="highlight.css">
|
|
<link rel="stylesheet" href="tomorrow-night.css">
|
|
<link rel="stylesheet" href="ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
|
|
|
|
|
|
</head>
|
|
<body>
|
|
<!-- Provide site root to javascript -->
|
|
<script type="text/javascript">
|
|
var path_to_root = "";
|
|
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "light" : "light";
|
|
</script>
|
|
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script type="text/javascript">
|
|
try {
|
|
var theme = localStorage.getItem('mdbook-theme');
|
|
var sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script type="text/javascript">
|
|
var theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
var html = document.querySelector('html');
|
|
html.classList.remove('no-js')
|
|
html.classList.remove('light')
|
|
html.classList.add(theme);
|
|
html.classList.add('js');
|
|
</script>
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script type="text/javascript">
|
|
var html = document.querySelector('html');
|
|
var sidebar = 'hidden';
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
}
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<div id="sidebar-scrollbox" class="sidebar-scrollbox">
|
|
<ol class="chapter"><li class="expanded affix "><a href="introduction.html">Introduction</a></li><li class="expanded "><a href="filters.html"><strong aria-hidden="true">1.</strong> Filter Grammar</a></li><li class="expanded "><a href="queries.html"><strong aria-hidden="true">2.</strong> Query Grammar</a></li></ol>
|
|
</div>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky bordered">
|
|
<div class="left-buttons">
|
|
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</button>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
|
|
</div>
|
|
|
|
<h1 class="menu-title">Mercator Parser</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script type="text/javascript">
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1><a class="header" href="#introduction" id="introduction">Introduction</a></h1>
|
|
<p>To support volumetric queries for Mercator, a new domain-specific language (DSL) was created.</p>
|
|
<p>ANTLR was used to write and test the SDL, to check it stays simple
|
|
to parse and and fast to execute. The actual <a href="https://epfl-dias.github.io/mercator_parser/">parser</a> and interpreter is
|
|
defined in rust, using <a href="https://docs.rs/lalrpop/0.18.1/lalrpop/">LALRPOP</a>.</p>
|
|
<h1><a class="header" href="#filter-grammar" id="filter-grammar">Filter Grammar</a></h1>
|
|
<p>You will find below the definition of this SDL, for filtering data
|
|
from the index.</p>
|
|
<h2><a class="header" href="#filtersg4" id="filtersg4">filters.g4</a></h2>
|
|
<pre><code class="language-antlr">grammar filters;
|
|
|
|
/**********************************************************************/
|
|
/* SELECTING / FILTERING DATA */
|
|
/**********************************************************************/
|
|
filters
|
|
: bag_expression
|
|
;
|
|
|
|
/* All these expressions generate bags. */
|
|
bag_expression
|
|
// Bag Operators
|
|
: distinct
|
|
| filter
|
|
| complement
|
|
| intersection
|
|
| union
|
|
| bag
|
|
// Spatial Operators
|
|
| inside
|
|
| outside
|
|
//| shape
|
|
;
|
|
|
|
/**********************************************************************/
|
|
/* BAG OPERATORS */
|
|
/**********************************************************************/
|
|
distinct
|
|
: 'distinct' '(' bag_expression ')'
|
|
;
|
|
|
|
/* Returns all the points which are NOT part of the bag. */
|
|
complement
|
|
: 'complement' '(' bag_expression ')'
|
|
;
|
|
|
|
/* Returns points which are part of both left and right sets. */
|
|
intersection
|
|
: 'intersection' '(' bag_expression ',' bag_expression ')'
|
|
;
|
|
|
|
/* Returns points which are either part of left or right sets
|
|
* (or both). */
|
|
union
|
|
: 'union' '(' bag_expression ',' bag_expression ')'
|
|
;
|
|
|
|
/* Filters point so that points part of the resulting bag respect
|
|
* the predicate. */
|
|
filter
|
|
: 'filter' '(' ( bag_expression | predicate ( ',' bag_expression )? ) ')'
|
|
;
|
|
|
|
predicate
|
|
: less
|
|
| greater
|
|
| equal
|
|
| str_cmp
|
|
| not
|
|
| and
|
|
| or
|
|
;
|
|
|
|
less
|
|
: '<' '(' position_expr ',' position ')'
|
|
;
|
|
|
|
greater
|
|
: '>' '(' position_expr ',' position ')'
|
|
;
|
|
|
|
equal
|
|
: '=' '(' position_expr ',' position ')'
|
|
;
|
|
|
|
not
|
|
: '!' '(' predicate ')'
|
|
;
|
|
|
|
and
|
|
: '&' '(' predicate ',' predicate ')'
|
|
;
|
|
|
|
or
|
|
: '|' '(' predicate ',' predicate ')'
|
|
;
|
|
|
|
/* Arbitrary bag of positions. */
|
|
bag
|
|
: 'bag' '{' bag_expression (',' bag_expression )* '}'
|
|
;
|
|
|
|
/**********************************************************************/
|
|
/* SPATIAL OPERATORS */
|
|
/**********************************************************************/
|
|
|
|
/* Faces | vertices are included to allow selection on a pure plane or
|
|
* boundary.
|
|
*
|
|
* For example:
|
|
* intersection(outside(hyperrectangle{[0,0], [1,1]},
|
|
* inside(hyperrectangle{[0,0], [1,1]})
|
|
* will be true for any point lying EXACTLY on a face, corner or edge
|
|
* of the cube [0,0], [1,1].
|
|
*/
|
|
|
|
/* Returns the set of points outside the shape, (face included) */
|
|
outside
|
|
: 'outside' '(' shapes ')'
|
|
;
|
|
|
|
/* Returns the set of points inside the shape, (face included) */
|
|
inside
|
|
: 'inside' '(' shapes ')'
|
|
;
|
|
|
|
/* Returns the set of positions inside the shape, (face included) */
|
|
shape
|
|
: 'shape' '(' shapes ')'
|
|
;
|
|
|
|
/**********************************************************************/
|
|
/* SHAPES */
|
|
/**********************************************************************/
|
|
shapes
|
|
: point
|
|
| hyperrectangle
|
|
| hypersphere
|
|
| nifti
|
|
;
|
|
|
|
/* If the hyperrectangle is aligned with the axes, then two points are
|
|
* enough, if not we need all the points to be specified.
|
|
*/
|
|
hyperrectangle
|
|
: 'hyperrectangle' '{'
|
|
position ',' position
|
|
( ',' position ',' position )*
|
|
( ',' STRING )?
|
|
'}'
|
|
;
|
|
|
|
/* A hypersphere is defined by its center and a radius, independantly
|
|
* of the number of dimensions of the space. */
|
|
hypersphere
|
|
: 'hypersphere' '{'
|
|
position
|
|
',' positive_number
|
|
( ',' STRING )?
|
|
'}'
|
|
;
|
|
|
|
point
|
|
: 'point' '{' position ( ',' STRING )? '}'
|
|
;
|
|
|
|
/* Define a shape as the non-zero values in a NIfTI object, defined by
|
|
* nifti{
|
|
* lower_corner: position, // Optional, default to the origin
|
|
* rotation: [ position+ ], // Optional, no rotation by default
|
|
* bytes: uri(STRING), // uri to the NIfTI object
|
|
* spaceId: string
|
|
* }
|
|
*/
|
|
nifti
|
|
: 'nifti' '{'
|
|
(position ',' )?
|
|
( '[' position ( ',' position )* ']' ',' )?
|
|
byte_provider ','
|
|
STRING
|
|
'}'
|
|
;
|
|
|
|
/* TODO: STRING is assumed to be a well-formed URI, fully specify here?
|
|
*
|
|
* TODO: Add a provider for in-line raw-byte stream.
|
|
*/
|
|
byte_provider
|
|
: 'uri' '(' STRING ')'
|
|
;
|
|
|
|
/**********************************************************************/
|
|
/* POSITIONS */
|
|
/**********************************************************************/
|
|
|
|
/* Always returns a vector of numbers, a.k.a a position (a scalar will
|
|
* be represented as a vector of one element) */
|
|
position_expr
|
|
: str_cmp_icase
|
|
| str_cmp
|
|
| selector
|
|
| position
|
|
;
|
|
|
|
/* Compare lexicographically two strings, and returns a `position`:
|
|
* [-1] : String is lexicographically before,
|
|
* [ 0] : is equal,
|
|
* [ 1] : is after.
|
|
*/
|
|
str_cmp
|
|
: 'str_cmp' '(' selector ',' STRING ')'
|
|
;
|
|
|
|
/* Same, but case insensitive. */
|
|
str_cmp_icase
|
|
: 'str_cmp_ignore_case' '(' selector ',' STRING ')'
|
|
;
|
|
|
|
/* TODO: FIELDS are expected to be exisiting in the data model. Root Object is assumed to be the type of the ressource on which the POST call was done.
|
|
*/
|
|
selector
|
|
: ( FIELD )+
|
|
;
|
|
|
|
position
|
|
: '[' number ( ',' number )* ']'
|
|
;
|
|
|
|
/**********************************************************************/
|
|
/* TOKENS - STRINGS */
|
|
/**********************************************************************/
|
|
|
|
/* Accept field descriptor which
|
|
* 1. start with a dot ('.')
|
|
* 2. optionnally followed by a field name consisting of a letter or
|
|
* underscore, followed by letters, numbers or underscore,
|
|
* 3. optionnally followed by brakets enclosing an natural number
|
|
* denoting an offset in a list or array. */
|
|
FIELD
|
|
: '.' ( [a-zA-Z_] [a-zA-Z0-9_]* )? ('[' INTEGER ']')?
|
|
;
|
|
|
|
STRING
|
|
: '"' (ESC | SAFECODEPOINT)* '"'
|
|
;
|
|
|
|
fragment ESC
|
|
: '\\' (["\\/bfnrt] | UNICODE)
|
|
;
|
|
|
|
fragment UNICODE
|
|
: 'u' HEX HEX HEX HEX
|
|
;
|
|
|
|
fragment HEX
|
|
: [0-9a-fA-F]
|
|
;
|
|
|
|
fragment SAFECODEPOINT
|
|
: ~ ["\\\u0000-\u001F]
|
|
;
|
|
|
|
/**********************************************************************/
|
|
/* TOKENS - NUMBERS */
|
|
/**********************************************************************/
|
|
/* We define 3 kinds of number, to avoid ambiguities in the rules. */
|
|
|
|
/* No optional leading '+' */
|
|
json_number
|
|
: '-'? NUM
|
|
;
|
|
|
|
positive_number
|
|
: '+'? NUM
|
|
;
|
|
|
|
number
|
|
: ( '+' | '-' )? NUM
|
|
;
|
|
|
|
NUM
|
|
: INTEGER ('.' [0-9]+ )? EXP?
|
|
;
|
|
|
|
fragment EXP
|
|
: [Ee] [+\-]? INTEGER
|
|
;
|
|
|
|
|
|
/* No leading zeros */
|
|
fragment INTEGER
|
|
: '0' | [1-9] [0-9]*
|
|
;
|
|
|
|
/**********************************************************************/
|
|
/* WHITESPACES & COMMENTS */
|
|
/**********************************************************************/
|
|
COMMENTS
|
|
: ( '//' ~[\r\n]* | '/*' .*? '*/' ) -> skip
|
|
;
|
|
|
|
WS
|
|
: [ \t\r\n]+ -> skip
|
|
; // skip spaces, tabs, newlines
|
|
</code></pre>
|
|
<h1><a class="header" href="#query-grammar" id="query-grammar">Query Grammar</a></h1>
|
|
<p>You will find below the definition of this SDL, for queries. This builds on top of the <a href="filters.html">filters</a> grammar. </p>
|
|
<h2><a class="header" href="#queriesg4" id="queriesg4">queries.g4</a></h2>
|
|
<pre><code class="language-antlr">grammar queries;
|
|
import filters;
|
|
|
|
/**********************************************************************/
|
|
/* FORMATTING DATA */
|
|
/**********************************************************************/
|
|
queries
|
|
: projection_operators?
|
|
;
|
|
|
|
projection_operators
|
|
: nifti_operator
|
|
| json_operator
|
|
;
|
|
|
|
/* If selector is not provided, one (1) will be used as the values for
|
|
* each position where there is a point in bag_expression.
|
|
*
|
|
* If it is provided, it MUST resolve to a NUMBER. */
|
|
nifti_operator
|
|
: 'nifti' '(' ( selector ',' )? bag_expression ( ',' STRING )? ')'
|
|
;
|
|
|
|
json_operator
|
|
: 'json' '(' jslt ',' bag_expression ( ',' STRING )? ')'
|
|
;
|
|
|
|
jslt
|
|
: json
|
|
;
|
|
|
|
/**********************************************************************/
|
|
/* JSON */
|
|
/**********************************************************************/
|
|
|
|
/**
|
|
* Taken and adapted from:
|
|
* https://github.com/antlr/grammars-v4/blob/master/json/JSON.g4
|
|
*
|
|
* Some of the parser / lexer rules are in the imported grammar as well.
|
|
*/
|
|
json
|
|
: json_value
|
|
;
|
|
|
|
json_obj
|
|
: '{' json_pair (',' json_pair)* '}'
|
|
| '{' '}'
|
|
;
|
|
|
|
json_pair
|
|
: STRING ':' json_value
|
|
;
|
|
|
|
json_array
|
|
: '[' json_value (',' json_value)* ']'
|
|
| '[' ']'
|
|
;
|
|
|
|
json_value
|
|
: STRING
|
|
| json_number
|
|
| json_obj
|
|
| json_array
|
|
| 'true'
|
|
| 'false'
|
|
| 'null'
|
|
/* Add support to reference values from the selected bag. */
|
|
| selector
|
|
| aggregation_expr
|
|
;
|
|
|
|
/* The bag expression is implicit here, as this is te
|
|
* second argument to the json operator */
|
|
aggregation_expr
|
|
: 'count' '(' 'distinct'? selector ')'
|
|
| 'sum' '(' selector ')'
|
|
| 'min' '(' selector ')'
|
|
| 'max' '(' selector ')'
|
|
| 'nifti' '(' selector ')'
|
|
| 'mbb' '(' ')'
|
|
;
|
|
</code></pre>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
|
|
|
|
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
|
|
|
|
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
window.playpen_copyable = true;
|
|
</script>
|
|
|
|
|
|
|
|
|
|
|
|
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
|
|
|
|
|
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
window.addEventListener('load', function() {
|
|
window.setTimeout(window.print, 100);
|
|
});
|
|
</script>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|