Difference between revisions of "LavishScript:Object Queries"

From Lavish Software Wiki
Jump to: navigation, search
 
Line 1: Line 1:
 
== Description ==
 
== Description ==
An object query is a math formula where all variables are relative to a specific object, and results in a boolean value -- the query is either true, or it is false.
+
An object query is a math formula where all variables are relative to a specific object, and results in a boolean value -- the query is either true, or it is false. That is to say, it efficiently determines whether one object meets various conditions.
  
 
:Query math can compare and manipulate text, decimals, or integers (note that bool counts as an integer for this purpose) with standard math operators. Text comparisons are not case sensitive.
 
:Query math can compare and manipulate text, decimals, or integers (note that bool counts as an integer for this purpose) with standard math operators. Text comparisons are not case sensitive.
 
:One intended use for object queries is a uniform search mechanism, to find an object or set of objects from a larger set of objects (compare to a SQL SELECT statement, where a LavishScript object query is the WHERE clause).
 
:One intended use for object queries is a uniform search mechanism, to find an object or set of objects from a larger set of objects (compare to a SQL SELECT statement, where a LavishScript object query is the WHERE clause).
 +
 +
== Queries and IDs ==
 +
Queries are internally compiled and retained in order to improve re-use performance. Compiled queries are referenced by an ID, which is returned by CreateQuery. Each query can then be used any number of times to determine whether one or more objects match the specified conditions.
 +
 +
When a query will no longer be used, it should be desroyed via FreeQuery to reduce memory usage. If the same query ''will'' be used again, it is more efficient to keep the query ID than to Free it and/or re-Create it again.
  
 
== Members ==
 
== Members ==

Latest revision as of 06:54, 11 August 2012

Description

An object query is a math formula where all variables are relative to a specific object, and results in a boolean value -- the query is either true, or it is false. That is to say, it efficiently determines whether one object meets various conditions.

Query math can compare and manipulate text, decimals, or integers (note that bool counts as an integer for this purpose) with standard math operators. Text comparisons are not case sensitive.
One intended use for object queries is a uniform search mechanism, to find an object or set of objects from a larger set of objects (compare to a SQL SELECT statement, where a LavishScript object query is the WHERE clause).

Queries and IDs

Queries are internally compiled and retained in order to improve re-use performance. Compiled queries are referenced by an ID, which is returned by CreateQuery. Each query can then be used any number of times to determine whether one or more objects match the specified conditions.

When a query will no longer be used, it should be desroyed via FreeQuery to reduce memory usage. If the same query will be used again, it is more efficient to keep the query ID than to Free it and/or re-Create it again.

Members

  • uint LavishScript.CreateQuery[expression]: Creates a query with the given expression -- e.g. ${LavishScript.CreateQuery[Name=="Bonkers"]}
  • string LavishScript.RetrieveQueryExpression[#]: Retrieves the query expression for a previously created query, by ID
  • bool LavishScript.QueryEvaluate[#, object]: Determines if the given object matches the given query

Methods

  • LavishScript:FreeQuery[#]: Frees a previously created query, by ID

Expression/Operator Notes

  • Math operators identical to LS
  • &&, ||, and () are supported
  • Special keyword NULL replicates "(exists)" typecast behavior
a !~ NULL is true if ${a(exists)}
a =~ NULL is true if !${a(exists)}
  • Special Operators:
  • =- Case Insensitive Substring Search
Name =- "Boobies" is true if Name.Find[Boobies]
  • = Weak compare, value only
  • == Strong compare, value + type
  • =~ Strong compare, value + type (same as ==)
  •  !~ Strong compare, NOT value or type

Example 1

function main()
{
	variable int ID
	variable int ID1
   
	; Example: Compare System.OS
	ID:Set[${LavishScript.CreateQuery[OS = "Windows 7 Ultimate"]}]
	ID1:Set[${LavishScript.CreateQuery[OS = "Windows 7 Ultimate && MemFree < 500 && MemTotal > 1000"]}]
  
	echo ID ${ID}
	echo LavishScript.RetrieveQueryExpression[${ID}] "${LavishScript.RetrieveQueryExpression[${ID}]}"
	echo LavishScript.RetrieveQueryExpression[${ID1}] "${LavishScript.RetrieveQueryExpression[${ID1}]}"
    
	echo System.OS ${System.OS}
	echo LavishScript.QueryEvaluate[${ID}, System] ${LavishScript.QueryEvaluate[${ID}, System]}
	echo LavishScript.QueryEvaluate[${ID1}, System] ${LavishScript.QueryEvaluate[${ID}, System]}
   
       LavishScript.FreeQuery[${ID}]
       LavishScript.FreeQuery[${ID1}]
}
ID 7
LavishScript.RetrieveQueryExpression[7] "OS = "Windows 7 Ultimate""
LavishScript.RetrieveQueryExpression[8] "OS = "Windows 7 Ultimate && MemFree < 500 && MemTotal > 1000""
System.OS Windows 7 Ultimate
LavishScript.QueryEvaluate[7, System] TRUE
LavishScript.QueryEvaluate[8, System] FALSE

Example 2 (Using container/index methods)

  • Original Code:
 variable index:item anItemIndex
 variable iterator   anIterator

 MyShip:GetCargo[anItemIndex]
 anItemIndex:GetIterator[anIterator]

 if ${anIterator:First(exists)}
 do
 {
     if ${anIterator.Value.GroupID} == GROUPID_SECURE_CONTAINER
     {
         return TRUE
     }
 }
 while ${anIterator:Next(exists)}
  • Converted To Query System:
 variable index:item Items
 variable iterator   ItemIterator

 MyShip:GetCargo[Items]
 Items:GetIterator[ItemIterator]

 variable string Query = "GroupID != GROUPID_SECURE_CONTAINER"
 Items:RemoveByQuery[${LSQueryCache[${Query}]}]
 
 if ${ItemIterator:First(exists)}
 {
     return TRUE
 }