<!---
The DSL this object parses is line-oriented in nature. Blank lines are
ignored, as are lines that (after having leading whitespace removed)
start with a hash sign (i.e. C-style single-line comments).

In December 2008 the parseReport() method was added and the parse()
method was deprecated.  This documentation is for parseReport(), and
understands a strict superset of the language parse() understood.
However, the parsed result (the in-memory data structure) has changed
in several important ways, so upgrading is NOT as simple as changing
your method calls.

Except for whitespace explicitly listed below (i.e. the newline and
space delimiters), all whitespace between tokens is semantically
meaningless, and is removed as part of parsing.

The BNF (or at least quasi-BNF) for the DSL is as follows. Literals are
enclosed in quotes.  UPPERCASED tokens are outside the DSL spec; their
semantics are implied by their names, but are only enforced by the
process using the DSL instance.

The 'query_string' entity is not actually handled by the parse
method directly, instead it's handled by the parseQuery method,
which is backed by the supplied querydsl's parse method.  In other
words, parse handles 'doc'-rooted instances of the language, while
parseQuery handles 'query_string'-rooted instances.  See the docs
for querydsl for specifics of the 'query_string' structure.  You
may, of course, specify any query DSL you want.

doc := line_list
line_list := line [ line_list ]
line := ( global | condition | aggregate ) "\n"
global_query := "+" query_string
condition := "?" condition_body
aggregate := "&" condition_body
condition_body := label_clause [ ">" value_clause ] ":" query_list  
label_clause := (QUOTE LABEL QUOTE | LABEL) 
value_clause := (QUOTE VALUE QUOTE | VALUE)
query_list := "*" | query_string

The semantics for the constructs are 100% up to the app that is using
the DSL.  The only place this "leaks" slightly is with the 'condition'
and 'aggregate' statements.  Both are identical, differing only in their
command character and the type their series is assigned.  The DSL
natively supports two statements here so if you need two types of
conditions, you can get it without having to rely on additional encoding
within the LABEL of the statement.  The name "aggregate" was chosen since
the representative example is for reporting: conditions are used to
break a dataset down into sections, and then aggregates are used to sum
them back up as needed.  This native differentiation allows you to
control the two types of conditions differently (for example, toggling
all aggregates on/off on a chart).

Of course, there is no requirement that you use aggregates, you may
synthesize this with encodings within the LABEL supplied to a condition.
You MUST do it that way if you require more than two differentiations
among the conditions.  And the names are completely arbitrary; I wanted
something more semantic than 'condition1' and 'condition2'.

Both LABELs and VALUEs may be optionally quoted.  The MUST be quoted if
they are empty or contain colons and/or right angle brackets (":" and/or
">").

Examples:
---------

I won't be discussing the query DSL portion of the examples, only the
report DSL portion.  I've aimed to make query strings that are obvious
in their nature.

The first example is for a simple report of hypothetical dining habits:

+ tag:dining -tag:home
? McDonalds : tag:mcdonalds
? Jack in the Box : tag:"jack in the box"
? Cheesecake Factory : tag:"cheesecake factory"
& Fast Food : tag:"fast food"
& Total : *

Assuming this is used to generate a chart, there would be five series
(one for each of rows 2-6).  The first three are "condition" series, and
the last two are "aggregate" series.  A distinction might be made by
rendering the former as columns and the latter as lines.

The first row provides global "stuff" for all the conditions and
and aggregates: it's contents could be prefixed to each individual row
without changing the semantics.  Using globals can significantly reduce
the size of your report spec, as well as make the intent of the report
far easier to deduce.

The second example is for tracking progress towards a goal of some sort:

? walk > 1 : tag:walking
? run > 2 : tag:running
? bike > 2 : tag:bicycling
? run/bike > 5 : tag:running tag:bicycling

This would be used assign a point value (the VALUE clause) to records
that match the given conditions.  If no VALUE clause is provided, the
LABEL clause will be used instead.

The next example is an example of a report that might be derived from
the data the above point assignment rules create:

+ points:>0
? Active : points:<=2
? Very Active : points:>=3
& Total : *

Note that the query DSL doesn't care about the ">", "<=", and ">="
strings within the queries.  Interpretation of those is up to the
application itself.

The VALUE clause may also be used in reports if you want to describe how
to deduce the series' value.  Assuming the goal above, without the final
line (the "run/bike" one), here's an example for reporting on average
distance:

+ points:>0
? Walking > avg(distance) : tag:walking
? Running > avg(distance) : tag:running
? Biking > avg(distance) : tag:bicycling

Note that like the operators in the previous example, the DSL doesn't
care about the string in the VALUE clause.  It's semantics are supplied
by the application (in this case the application will presumably average
the distance covered for activities matching each condition's query).
--->
<cfcomponent output="false">

	<cffunction name="init" access="public" output="false" returntype="reportdsl">
		<cfargument name="querydsl" type="any" required="true" />
		<cfset variables.my.querydsl = querydsl />
		<cfreturn this />
	</cffunction>
	
	
	<cffunction name="parse" deprecated="true" access="public" output="false" returntype="struct"
			hint="I parse a string in the DSL into a struct.  The DSL's definition can be found in a comment within the method.">
		<cfargument name="definition" type="string" required="true" />
		<cfargument name="parseQueries" type="boolean" default="true"
			hint="Whether to parse the query strings into an actual criterion instance (the raw query string is always included)." />
		<cfset var result = structNew() />
		<cfset var i = "" />
		<cfset var j = "" />
		<cfset var lines = listToArray(trim(definition), chr(10)) />
		<cfset var line = "" />
		<cfset var command = "" />
		<cfset var args = "" />
		<cfset var s = "" />
		<cfset var key = "" />
		<cftrace text="reportdsl.parse is deprecated and will be removed in a future release.  Use reportdsl.parseReport instead." />
		<cfloop from="1" to="#arrayLen(lines)#" index="i">
			<cfset line = trim(lines[i]) />
			<cfif len(line) GT 0>
				<cfset command = left(line, 1) />
				<cfset args = trim(removeChars(line, 1, 1)) />
				<cfswitch expression="#command#">
					<cfcase value="##">
						<!--- a comment - do nothing --->
					</cfcase>
					<cfcase value="+">
						<!--- create the raw query --->
						<cfif structKeyExists(result, "coreQuery")>
							<cfset result["coreQuery"] = listAppend(result["coreQuery"], args, " ") />
						<cfelse>
							<cfset result["coreQuery"] = args />
						</cfif>
						<!--- create the criterion --->
						<cfif parseQueries>
							<cfset result["coreCriterion"] = my.querydsl.parse(result["coreQuery"]) />
						</cfif>
					</cfcase>
					<cfcase value="?,&">
						<!--- set the key to populate --->
						<cfset key = iif(command EQ "?", de("conditions"), de("aggregates")) />
						<!--- process the args --->
						<cfset s = structNew() />
						<cfif listLen(args, ":") LT 2>
							<cfthrow type="MalformedDslDocument.InvalidCondition"
								message="Line #i# has an invalid condition (no criteria specified)." />
						</cfif>
						<cfset args = extractFirstToken(args, ">:") />
						<cfset s.value = args.token />
						<cfset s.query = trim(removeChars(args.remainder, 1, 1)) />
						<cfif s.query EQ "*">
							<cfset s.query = "" />
						</cfif>
						<cfif parseQueries>
							<cfset s.criterion = my.querydsl.parse(s.query) />
						</cfif>
						<cfif NOT structKeyExists(result, key)>
							<cfset result[key] = arrayNew(1) />
						</cfif>
						<cfset arrayAppend(result[key], s) />
					</cfcase>
					<cfdefaultcase>
						<cfthrow type="MalformedDslDocument.InvalidCommand"
							message="Line #i# has an invalid command specifier ('#command#')" />
					</cfdefaultcase>
				</cfswitch>
			</cfif>
		</cfloop>

		<cfreturn result />
	</cffunction>


	<cffunction name="parseReport" access="public" output="false" returntype="report"
			hint="I parse a string in the DSL into a report instance.  The DSL's definition can be found in a comment at the top of this component.">
		<cfargument name="definition" type="string" required="true" />
		<cfargument name="parseQueries" type="boolean" default="true"
			hint="Whether to parse the query strings into an actual criterion instance (the raw query string is always available)." />
		<cfset var lines = listToArray(trim(definition), chr(10)) />
		<cfset var i = "" />
		<cfset var s = "" />
		<cfset var globalQuery = "" />
		<cfset var series = [] />
		<cfset var args = "" />
		<cfset var temp = "" />
		<!--- gotta get all the globals first --->
		<cfloop from="1" to="#arrayLen(lines)#" index="i">
			<cfset lines[i] = trim(lines[i]) />
			<cfif len(lines[i]) GT 0 AND left(lines[i], 1) EQ "+">
				<!--- it's a global --->
				<cfset globalQuery = listAppend(globalQuery, trim(removeChars(lines[i], 1, 1)), " ") />
			</cfif>
		</cfloop>
		<cfloop from="1" to="#arrayLen(lines)#" index="i">
			<cfif len(lines[i]) GT 0>
				<cfset args = trim(removeChars(lines[i], 1, 1)) />
				<cfswitch expression="#left(lines[i], 1)#">
					<cfcase value="?,&">
						<cfset s = {
							type = iif(left(lines[i], 1) EQ "?", de("condition"), de("aggregate"))
						} />
						<cfif listLen(args, ":") LT 2>
							<cfthrow type="MalformedDslDocument.InvalidCondition"
								message="Line #i# has an invalid condition (no criteria specified)." />
						</cfif>
						<!--- get the label (possibly quoted) --->
						<cfset temp = extractFirstToken(args, ">:") />
						<cfset s.label = temp.token />
						<cfset args = trim(temp.remainder) />
						<!--- strip the value, if present --->
						<cfif left(args, 1) EQ ">">
							<cfset temp = extractFirstToken(trim(removeChars(args, 1, 1)), ":") />
							<cfset s.value = temp.token />
							<cfset args = trim(temp.remainder) />
						</cfif>
						<!--- redo the query check in case the colon found above was part of a quoted label --->
						<cfif len(args) EQ 0 OR left(args, 1) NEQ ":">
							<cfthrow type="MalformedDslDocument.InvalidCondition"
								message="Line #i# has an invalid condition (no criteria specified)." />
						</cfif>
						<cfset s.query = trim(removeChars(args, 1, 1)) />
						<!--- process the query --->
						<cfif s.query EQ "*">
							<cfset s.query = globalQuery />
						<cfelseif len(globalQuery) GT 0>
							<cfset s.query = listAppend("(" & globalQuery & ")", s.query, " ") />
						</cfif>
						<!--- parse the query if needed --->
						<cfif parseQueries>
							<cfset s.criterion = parseQuery(s.query) />
						</cfif>
						<cfset arrayAppend(series, s) />
					</cfcase>
					<cfcase value="##,+">
						<!--- whatever.  we don't care anymore --->
					</cfcase>
					<cfdefaultcase>
						<cfthrow type="MalformedDslDocument.InvalidCommand"
							message="Line #i# has an invalid command specifier ('#left(lines[i], 1)#')" />
					</cfdefaultcase>
				</cfswitch>
			</cfif>
		</cfloop>
		<cfreturn createObject("component", "report").init(series, globalQuery) />
	</cffunction>


	<cffunction name="parseQuery" access="public" output="false" returntype="criterion">
		<cfargument name="queryString" type="string" required="true" />
		<cfreturn my.querydsl.parse(queryString) />
	</cffunction>
	

	<cffunction name="parsePredicateMap" access="public" output="false" returntype="struct">
		<cfargument name="queryString" type="string" required="true" />
		<cfreturn my.querydsl.parsePredicateMap(queryString) />
	</cffunction>
	
	
	<cffunction name="flatten" deprecated="true" access="public" output="false" returntype="struct"
		hint="I take a struct returned from parse() and push the core criterion down into each condition and aggregate, returning a flattened (coreless) struct">
		<cfargument name="def" type="struct" required="true" />
		<cfset var i = "" />
		<cftrace text="reportdsl.flatten is deprecated and will be removed in a future release.  Use reportdsl.parseReport instead of reportdsl.parse to eliminate the need for flatten." />
		<cfif NOT structKeyExists(def, "coreCriterion")>
			<cfreturn def />
		</cfif>
		<cfif structKeyExists(def, "conditions")>
			<cfloop from="1" to="#arrayLen(def.conditions)#" index="i">
				<cfset def.conditions[i].query = listAppend(def.coreQuery, def.conditions[i].query, " ") />
				<cfset def.conditions[i].criterion = andTogether(def.coreCriterion, def.conditions[i].criterion) />
			</cfloop>
		</cfif>
		<cfif structKeyExists(def, "aggregates")>
			<cfloop from="1" to="#arrayLen(def.aggregates)#" index="i">
				<cfset def.aggregates[i].query = listAppend(def.coreQuery, def.aggregates[i].query, " ") />
				<cfset def.aggregates[i].criterion = andTogether(def.coreCriterion, def.aggregates[i].criterion) />
			</cfloop>
		</cfif>
		<cfset structDelete(def, "coreCriterion") />
		<cfset structDelete(def, "coreQuery") />
		<cfreturn def />
	</cffunction>
	
	
	<cffunction name="extractFirstToken" access="private" output="false" returntype="struct">
		<cfargument name="args" type="string" required="true" />
		<cfargument name="terminators" type="string" required="true" />
		<cfset var result = {} />
		<cfset var char = "" />
		<cfif left(args, 1) EQ """" OR left(args, 1) EQ "'">
			<cfset char = find(left(args, 1), args, 2) />
			<cfset result.token = trim(mid(args, 2, char - 2)) />
			<cfset char = findOneOf(terminators, args, char) />
		<cfelse>
			<cfset char = findOneOf(terminators, args) />
			<cfset result.token = trim(left(args, char - 1)) />
		</cfif>
		<cfset result.remainder = trim(removeChars(args, 1, char - 1)) />
		<cfreturn result />
	</cffunction>


	<cffunction name="andTogether" access="private" output="false" returntype="criterion">
		<cfargument name="left" type="criterion" required="true" />
		<cfargument name="right" type="criterion" required="true" />
		<!--- take care of some simple cases --->
		<cfif isInstanceOf(left, "truecriterion")>
			<cfreturn right />
		<cfelseif isInstanceOf(right, "truecriterion")>
			<cfreturn left />
		<cfelseif isInstanceOf(left, "falsecriterion")>
			<cfreturn left />
		<cfelseif isInstanceOf(right, "falsecriterion")>
			<cfreturn right />
		</cfif>
		<cfreturn createObject("component", "andcriterion").init(left, right) />
	</cffunction>
	
	
	<cffunction name="sortConditionsByValue" deprecated="true" access="public" output="false" returntype="struct"
			hint="I sort the 'conditions' array of a parse result">
		<cfargument name="def" type="struct" required="true" />
		<cfargument name="sortType" type="string" default="numeric"
			hint="The sort type to use.  Must be a valid argument to the listSort built-in function" />
		<cfargument name="sortDirection" type="string" default="desc"
			hint="The direction of the sort" />
		<cfargument name="sortAggregates" type="boolean" default="false"
			hint="If set true, the aggregates will be sorted instead of the conditions." />
		<cfset var key = "conditions" />
		<cfset var i = "" />
		<cfset var subkey = "" />
		<!--- hashmap to allow case-sensitivity to work --->
		<cfset var sorter = createObject("java", "java.util.HashMap").init() />
		<cftrace text="reportdsl.sortConditionsByValue is deprecated and will be removed in a future release.  Use report.sortSeriesByValue (and reportdsl.parseReport) instead." />
		<cfif sortAggregates>
			<cfset key = "aggregates" />
		</cfif>
		<cfif NOT structKeyExists(def, key) OR arrayLen(def[key]) EQ 0>
			<cfreturn />
		</cfif>
		<cfloop from="1" to="#arrayLen(def[key])#" index="i">
			<cfif NOT structKeyExists(sorter, def[key][i].value)>
				<cfset sorter[def[key][i].value] = [def[key][i]] />
			<cfelse>
				<cfset arrayAppend(sorter[def[key][i].value], def[key][i]) />
			</cfif>
		</cfloop>
		<cfset def[key] = [] />
		<cfloop list="#listSort(structKeyList(sorter), sortType, sortDirection)#" index="subkey">
			<cfloop from="1" to="#arrayLen(sorter[subkey])#" index="i">
				<cfset arrayAppend(def[key], sorter[subkey][i]) />
			</cfloop>
		</cfloop>
		<cfreturn def />
	</cffunction>
	
<cfoutput></cfoutput>
</cfcomponent>