Clinical Quality Language STU3 Ballot (1.3)
This is the 2018 May Ballot Version of Clinical Quality Language STU 3
For a full list of available versions, see the Directory of published versions 
.
| Clinical Decision Support Work Group | Maturity Level: 4 | Ballot Status: STU 3 |
This page contains the Antlr 4.0 grammar for Clinical Quality Language.
grammar cql;
/*
* Clinical Quality Language Grammar Specification
* Version 1.3 - May 2018 STU3 Ballot
*/
import fhirpath;
/*
* Parser Rules
*/
library
:
libraryDefinition?
usingDefinition*
includeDefinition*
codesystemDefinition*
valuesetDefinition*
codeDefinition*
conceptDefinition*
parameterDefinition*
statement*
;
/*
* Definitions
*/
libraryDefinition
: 'library' identifier ('version' versionSpecifier)?
;
usingDefinition
: 'using' modelIdentifier ('version' versionSpecifier)?
;
includeDefinition
: 'include' identifier ('version' versionSpecifier)? ('called' localIdentifier)?
;
localIdentifier
: identifier
;
accessModifier
: 'public'
| 'private'
;
parameterDefinition
: accessModifier? 'parameter' identifier (typeSpecifier)? ('default' expression)?
;
codesystemDefinition
: accessModifier? 'codesystem' identifier ':' codesystemId ('version' versionSpecifier)?
;
valuesetDefinition
: accessModifier? 'valueset' identifier ':' valuesetId ('version' versionSpecifier)? codesystems?
;
codesystems
: 'codesystems' '{' codesystemIdentifier (',' codesystemIdentifier)* '}'
;
codesystemIdentifier
: (libraryIdentifier '.')? identifier
;
libraryIdentifier
: identifier
;
codeDefinition
: accessModifier? 'code' identifier ':' codeId 'from' codesystemIdentifier displayClause?
;
conceptDefinition
: accessModifier? 'concept' identifier ':' '{' codeIdentifier (',' codeIdentifier)* '}' displayClause?
;
codeIdentifier
: (libraryIdentifier '.')? identifier
;
codesystemId
: STRING
;
valuesetId
: STRING
;
versionSpecifier
: STRING
;
codeId
: STRING
;
/*
* Type Specifiers
*/
typeSpecifier
: namedTypeSpecifier
| listTypeSpecifier
| intervalTypeSpecifier
| tupleTypeSpecifier
| choiceTypeSpecifier
;
namedTypeSpecifier
: (qualifier '.')* identifier
;
modelIdentifier
: identifier
;
listTypeSpecifier
: 'List' '<' typeSpecifier '>'
;
intervalTypeSpecifier
: 'Interval' '<' typeSpecifier '>'
;
tupleTypeSpecifier
: 'Tuple' '{' tupleElementDefinition (',' tupleElementDefinition)* '}'
;
tupleElementDefinition
: identifier typeSpecifier
;
choiceTypeSpecifier
: 'Choice' '<' typeSpecifier (',' typeSpecifier)* '>'
;
/*
* Statements
*/
statement
: expressionDefinition
| contextDefinition
| functionDefinition
;
expressionDefinition
: 'define' accessModifier? identifier ':' expression
;
contextDefinition
: 'context' identifier
;
functionDefinition
: 'define' accessModifier? 'function' identifier '(' (operandDefinition (',' operandDefinition)*)? ')'
('returns' typeSpecifier)?
':' (functionBody | 'external')
;
operandDefinition
: identifier typeSpecifier
;
functionBody
: expression
;
/*
* Expressions
*/
querySource
: retrieve
| qualifiedIdentifier
| '(' expression ')'
;
aliasedQuerySource
: querySource alias
;
alias
: identifier
;
queryInclusionClause
: withClause
| withoutClause
;
withClause
: 'with' aliasedQuerySource 'such that' expression
;
withoutClause
: 'without' aliasedQuerySource 'such that' expression
;
retrieve
: '[' namedTypeSpecifier (':' (codePath 'in')? terminology)? ']'
;
codePath
: identifier
;
terminology
: qualifiedIdentifier
| expression
;
qualifier
: identifier
;
query
: sourceClause letClause? queryInclusionClause* whereClause? returnClause? sortClause?
;
sourceClause
: singleSourceClause
| multipleSourceClause
;
singleSourceClause
: aliasedQuerySource
;
multipleSourceClause
: 'from' aliasedQuerySource (',' aliasedQuerySource)*
;
letClause
: 'let' letClauseItem (',' letClauseItem)*
;
letClauseItem
: identifier ':' expression
;
whereClause
: 'where' expression
;
returnClause
: 'return' ('all' | 'distinct')? expression
;
sortClause
: 'sort' ( sortDirection | ('by' sortByItem (',' sortByItem)*) )
;
sortDirection
: 'asc' | 'ascending'
| 'desc' | 'descending'
;
sortByItem
: expressionTerm sortDirection?
;
qualifiedIdentifier
: (qualifier '.')* identifier
;
expression
: expressionTerm #termExpression
| retrieve #retrieveExpression
| query #queryExpression
| expression 'is' 'not'? ('null' | 'true' | 'false') #booleanExpression
| expression ('is' | 'as') typeSpecifier #typeExpression
| 'cast' expression 'as' typeSpecifier #castExpression
| 'not' expression #notExpression
| 'exists' expression #existenceExpression
| expression 'properly'? 'between' expressionTerm 'and' expressionTerm #betweenExpression
| ('duration' 'in')? pluralDateTimePrecision 'between' expressionTerm 'and' expressionTerm #durationBetweenExpression
| 'difference' 'in' pluralDateTimePrecision 'between' expressionTerm 'and' expressionTerm #differenceBetweenExpression
| expression ('<=' | '<' | '>' | '>=') expression #inequalityExpression
| expression intervalOperatorPhrase expression #timingExpression
| expression ('=' | '!=' | '~' | '!~') expression #equalityExpression
| expression ('in' | 'contains') dateTimePrecisionSpecifier? expression #membershipExpression
| expression 'and' expression #andExpression
| expression ('or' | 'xor') expression #orExpression
| expression 'implies' expression #impliesExpression
| expression ('|' | 'union' | 'intersect' | 'except') expression #inFixSetExpression
;
dateTimePrecision
: 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond'
;
dateTimeComponent
: dateTimePrecision
| 'date'
| 'time'
| 'timezone'
;
pluralDateTimePrecision
: 'years' | 'months' | 'weeks' | 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds'
;
expressionTerm
: term #termExpressionTerm
| expressionTerm '.' invocation #invocationExpressionTerm
| expressionTerm '[' expression ']' #indexedExpressionTerm
| 'convert' expression 'to' typeSpecifier #conversionExpressionTerm
| ('+' | '-') expressionTerm #polarityExpressionTerm
| ('start' | 'end') 'of' expressionTerm #timeBoundaryExpressionTerm
| dateTimeComponent 'from' expressionTerm #timeUnitExpressionTerm
| 'duration' 'in' pluralDateTimePrecision 'of' expressionTerm #durationExpressionTerm
| 'difference' 'in' pluralDateTimePrecision 'of' expressionTerm #differenceExpressionTerm
| 'width' 'of' expressionTerm #widthExpressionTerm
| 'successor' 'of' expressionTerm #successorExpressionTerm
| 'predecessor' 'of' expressionTerm #predecessorExpressionTerm
| 'singleton' 'from' expressionTerm #elementExtractorExpressionTerm
| 'point' 'from' expressionTerm #pointExtractorExpressionTerm
| ('minimum' | 'maximum') namedTypeSpecifier #typeExtentExpressionTerm
| expressionTerm '^' expressionTerm #powerExpressionTerm
| expressionTerm ('*' | '/' | 'div' | 'mod') expressionTerm #multiplicationExpressionTerm
| expressionTerm ('+' | '-' | '&') expressionTerm #additionExpressionTerm
| 'if' expression 'then' expression 'else' expression #ifThenElseExpressionTerm
| 'case' expression? caseExpressionItem+ 'else' expression 'end' #caseExpressionTerm
| ('distinct' | 'collapse' | 'flatten') expression #aggregateExpressionTerm
| 'expand' expression ('per' (dateTimePrecision | expression))? #expandExpressionTerm
;
caseExpressionItem
: 'when' expression 'then' expression
;
dateTimePrecisionSpecifier
: dateTimePrecision 'of'
;
relativeQualifier
: 'or before'
| 'or after'
;
offsetRelativeQualifier
: 'or more'
| 'or less'
;
exclusiveRelativeQualifier
: 'less than'
| 'more than'
;
quantityOffset
: (quantity offsetRelativeQualifier?)
| (exclusiveRelativeQualifier quantity)
;
temporalRelationship
: ('on or'? ('before' | 'after'))
| (('before' | 'after') 'or on'?)
;
intervalOperatorPhrase
: ('starts' | 'ends' | 'occurs')? 'same' dateTimePrecision? (relativeQualifier | 'as') ('start' | 'end')? #concurrentWithIntervalOperatorPhrase
| 'properly'? 'includes' dateTimePrecisionSpecifier? ('start' | 'end')? #includesIntervalOperatorPhrase
| ('starts' | 'ends' | 'occurs')? 'properly'? ('during' | 'included in') dateTimePrecisionSpecifier? #includedInIntervalOperatorPhrase
| ('starts' | 'ends' | 'occurs')? quantityOffset? temporalRelationship dateTimePrecisionSpecifier? ('start' | 'end')? #beforeOrAfterIntervalOperatorPhrase
| ('starts' | 'ends' | 'occurs')? 'properly'? 'within' quantity 'of' ('start' | 'end')? #withinIntervalOperatorPhrase
| 'meets' ('before' | 'after')? dateTimePrecisionSpecifier? #meetsIntervalOperatorPhrase
| 'overlaps' ('before' | 'after')? dateTimePrecisionSpecifier? #overlapsIntervalOperatorPhrase
| 'starts' dateTimePrecisionSpecifier? #startsIntervalOperatorPhrase
| 'ends' dateTimePrecisionSpecifier? #endsIntervalOperatorPhrase
;
term
: invocation #invocationTerm
| literal #literalTerm
| externalConstant #externalConstantTerm
| intervalSelector #intervalSelectorTerm
| tupleSelector #tupleSelectorTerm
| instanceSelector #instanceSelectorTerm
| listSelector #listSelectorTerm
| codeSelector #codeSelectorTerm
| conceptSelector #conceptSelectorTerm
| '(' expression ')' #parenthesizedTerm
;
ratio
: quantity ':' quantity
;
literal
: ('true' | 'false') #booleanLiteral
| 'null' #nullLiteral
| STRING #stringLiteral
| NUMBER #numberLiteral
| DATETIME #dateTimeLiteral
| TIME #timeLiteral
| quantity #quantityLiteral
| ratio #ratioLiteral
;
intervalSelector
: // TODO: Consider this as an alternative syntax for intervals... (would need to be moved up to expression to make it work)
//expression ( '..' | '*.' | '.*' | '**' ) expression;
'Interval' ('['|'(') expression ',' expression (']'|')')
;
tupleSelector
: 'Tuple'? '{' (':' | (tupleElementSelector (',' tupleElementSelector)*)) '}'
;
tupleElementSelector
: identifier ':' expression
;
instanceSelector
: namedTypeSpecifier '{' (':' | (instanceElementSelector (',' instanceElementSelector)*)) '}'
;
instanceElementSelector
: identifier ':' expression
;
listSelector
: ('List' ('<' typeSpecifier '>')?)? '{' (expression (',' expression)*)? '}'
;
displayClause
: 'display' STRING
;
codeSelector
: 'Code' STRING 'from' codesystemIdentifier displayClause?
;
conceptSelector
: 'Concept' '{' codeSelector (',' codeSelector)* '}' displayClause?
;
identifier
: IDENTIFIER
| QUOTEDIDENTIFIER
| 'all'
| 'Code'
| 'code'
| 'Concept'
| 'concept'
| 'contains'
| 'date'
| 'display'
| 'distinct'
| 'end'
// | 'exists' NOTE: This is excluded because including it causes a significant performance degradation in the ANTLR parser, still looking into a fix for this
| 'not'
| 'start'
| 'time'
| 'timezone'
| 'version'
| 'where'
;
NOTE: CQL extends from the FHIRPath grammar, and so uses the core production rules defined there. The FHIRPath grammar is included here for reference only, the FHIRPath grammar below is part of the FHIRPath specification. —-
grammar fhirpath;
// Grammar rules
//prog: line (line)*;
//line: ID ( '(' expr ')') ':' expr '\r'? '\n';
expression
: term #termExpression
| expression '.' invocation #invocationExpression
| expression '[' expression ']' #indexerExpression
| ('+' | '-') expression #polarityExpression
| expression ('*' | '/' | 'div' | 'mod') expression #multiplicativeExpression
| expression ('+' | '-' | '&') expression #additiveExpression
| expression ('is' | 'as') typeSpecifier #typeExpression
| expression '|' expression #unionExpression
| expression ('<=' | '<' | '>' | '>=') expression #inequalityExpression
| expression ('=' | '~' | '!=' | '!~') expression #equalityExpression
| expression ('in' | 'contains') expression #membershipExpression
| expression 'and' expression #andExpression
| expression ('or' | 'xor') expression #orExpression
| expression 'implies' expression #impliesExpression
//| (IDENTIFIER)? '=>' expression #lambdaExpression
;
term
: invocation #invocationTerm
| literal #literalTerm
| externalConstant #externalConstantTerm
| '(' expression ')' #parenthesizedTerm
;
literal
: '{' '}' #nullLiteral
| ('true' | 'false') #booleanLiteral
| STRING #stringLiteral
| NUMBER #numberLiteral
| DATETIME #dateTimeLiteral
| TIME #timeLiteral
| quantity #quantityLiteral
;
externalConstant
: '%' identifier
;
invocation // Terms that can be used after the function/member invocation '.'
: identifier #memberInvocation
| function #functionInvocation
| '$this' #thisInvocation
| '$index' #indexInvocation
| '$total' #totalInvocation
;
function
: identifier '(' paramList? ')'
;
paramList
: expression (',' expression)*
;
quantity
: NUMBER unit?
;
unit
: dateTimePrecision
| pluralDateTimePrecision
| STRING // UCUM syntax for units of measure
;
dateTimePrecision
: 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond'
;
pluralDateTimePrecision
: 'years' | 'months' | 'weeks' | 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds'
;
typeSpecifier
: qualifiedIdentifier
;
qualifiedIdentifier
: identifier ('.' identifier)*
;
identifier
: IDENTIFIER
| QUOTEDIDENTIFIER
| 'as'
| 'is'
;
/****************************************************************
Lexical rules
*****************************************************************/
// Not sure why, but with these as lexical rules, when the grammar is imported into CQL, they are not correctly recognized
// Moving the same rules into the literal production rule above corrects the issue
//EMPTY
// : '{' '}'
// ; // To create an empty array (and avoid a NULL literal)
//BOOL
// : 'true'
// | 'false'
// ;
DATETIME
: '@'
[0-9][0-9][0-9][0-9] // year
(
'-'[0-9][0-9] // month
(
'-'[0-9][0-9] // day
(
'T' TIMEFORMAT
)?
)?
)?
'Z'? // UTC specifier
;
TIME
: '@' 'T' TIMEFORMAT
;
fragment TIMEFORMAT
:
[0-9][0-9] (':'[0-9][0-9] (':'[0-9][0-9] ('.'[0-9]+)?)?)?
('Z' | ('+' | '-') [0-9][0-9]':'[0-9][0-9])? // timezone
;
IDENTIFIER
: ([A-Za-z] | '_')([A-Za-z0-9] | '_')* // Added _ to support CQL (FHIR could constrain it out)
;
QUOTEDIDENTIFIER
: '"' (ESC | .)*? '"'
;
STRING
: '\'' (ESC | .)*? '\''
;
// Also allows leading zeroes now (just like CQL and XSD)
NUMBER
: [0-9]+('.' [0-9]+)?
;
// Pipe whitespace to the HIDDEN channel to support retrieving source text through the parser.
WS
: [ \r\n\t]+ -> channel(HIDDEN)
;
COMMENT
: '/*' .*? '*/' -> channel(HIDDEN)
;
LINE_COMMENT
: '//' ~[\r\n]* -> channel(HIDDEN)
;
fragment ESC
: '\\' (["'\\/fnrt] | UNICODE) // allow \", \', \\, \/, \f, etc. and \uXXX
;
fragment UNICODE
: 'u' HEX HEX HEX HEX
;
fragment HEX
: [0-9a-fA-F]
;