Crate ogc_cql2

Expand description

OGC CQL2 parser and runtime interpreter…

§Third-party crates

This project relies on few 3^rd party crates to satisfy the requirements of the CQL2 standard. These are…

Geometry
- geos: Rust bindings for GEOS C API for handling geometries.
JSON Deserialization:
- serde: for the basic capabilities.
- serde_json: for the JSON format bindings.
- serde_with: for custom helpers.
Date + Time:
- jiff: for time-zone-aware date and timestamp handling.
Case + Accent Insensitive Strings:
- unicase: for comparing strings when case is not important.
- unicode-normalization: for un-accenting strings w/ Unicode decomposition.
CRS Transformation:
- proj: for coordinate transformation via bindings to the PROJ API.

§Functions

The CQL2 Standard makes provisions for externally defined Functions in addition to few specific ones defined in the specs.

This project implements all the required standard functions. It also offers:

Support for few ones called builtins that can be used in Filter Expressions.
A mechanism for externally defined functions, implemented as Rust Closures, that can be registered in a Context which is then passed to an Evaluator implementation (such as EvaluatorImpl) for processing an Expression against one or more Resource.

Examples of both types, and the plumbing to wire them, abound in the tests folder. Here is a working simple example:

use ogc_cql2::prelude::*;

// define a function that adds 2 numbers together...
let sum = |x: f64, y: f64| x + y;

// create a Context and register that function and its metadata...
let mut ctx = Context::new();
ctx.register(
    "sum",
    vec![ExtDataType::Num, ExtDataType::Num],
    ExtDataType::Num,
    move |args| {
        let a1 = args.first()?.downcast_ref::<f64>()?;
        let a2 = args.get(1)?.downcast_ref::<f64>()?;
        Some(Box::new(sum(*a1, *a2)))
    },
 );

// freeze the Context (make it read-only) so we can share it safely... 
let shared_ctx = ctx.freeze();

// parse an Expression from a text string...
let expression = Expression::try_from_text("3 = sum(1, 2)")?;

// instantiate an Evaluator instance and feed it the Context...
let mut evaluator = EvaluatorImpl::new(shared_ctx);

// now set up that Evaluator for evaluating Resources...
evaluator.setup(expression)?;

// since our Expression does not need any queryable Resource property,
// use an empty one...
let feature = Resource::new();

// evaluate the Expression...
let res = evaluator.evaluate(&feature)?;

// assert the outcome is TRUE...
assert!(matches!(res, Outcome::T));

// tear down the Evaluator...
evaluator.teardown()?;

§Data types

This library supports a subset of data types available in a Rust environment for use with function arguments and results. The ExtDataType variants embody those types. Each variant maps to a specific yet opaque (for now) Rust type…

`ExtDataType` variant	Symbol	inner type
`Num`	`N`	f64
`Str`	`S`	QString (only the plain variant)
`Bool`	`B`	bool
`Timestamp`	`Z`	jiff::Zoned
`Date`	`Z`	jiff::Zoned
`Geom`	`G`	geos::Geom

§Numeric (`Num`) builtins

Name	Argument(s)	Result	Description	See
`abs`	x: `N`	`N`	Compute absolute value of `x`.	See
`acos`	x: `N`	`N`	Compute arccosine of `x`. Result is in radians.	See
`asin`	x: `N`	`N`	Compute arcsine of `x`. Result is in radians.	See
`atan`	x: `N`	`N`	Compute arctangent of `x`. Result is in radians.	See
`cbrt`	x: `N`	`N`	Compute cube root of `x`.	See
`ceil`	x: `N`	`N`	Compute smallest integer greater than or equal to `x`.	See
`cos`	x: `N`	`N`	Compute cosine of `x` (in radians).	See
`floor`	x: `N`	`N`	Compute largest integer less than or equal to `x`.	See
`ln`	x: `N`	`N`	Compute natural logarithm of `x`.	See
`sin`	x: `N`	`N`	Compute sine of `x` (in radians).	See
`sqrt`	x: `N`	`N`	Compute square root of `x`.	See
`tan`	x: `N`	`N`	Compute tangent of `x` (in radians).	See
`max`	x: `N`, y: `N`	`N`	Compute maximum of `x` and `y`.	See
`avg`	x: `N`, y: `N`	`N`	Compute midpoint (average) between `x` and `y`.	See
`min`	x: `N`, y: `N`	`N`	Compute minimum of `x` and `y`.	See

§String (`Str`) builtins

Name	Argument(s)	Result	Description	See
`trim`	x: `S`	`S`	Remove leading and trailing whitespaces from `x`.	See
`len`	x: `S`	`N`	Compute length of `x` in bytes.	See
`concat`	x: `S`, y: `S`	`S`	Append `y` to the end of `x`.	See
`starts_with`	x: `S`, y: `S`	`B`	Return TRUE if `y` is a prefix of `x`. FALSE otherwise.	See
`ends_with`	x: `S`, y: `S`	`B`	Return TRUE if `y` is a suffix of `x`. FALSE otherwise.	See

§Temporal builtins

Name	Argument(s)	Result	Description
`now`		`Z`	Return the current timestamp in UTC time-zone.
`today`		`Z`	Return today’s date in UTC time-zone.

§Geometry (`Geom`) builtins

Name	Argument(s)	Result	Description
`boundary`	x: `G`	`G`	Return the closure of combinatorial boundary of `x`.
`buffer`	x: `G`, y: `N`	`G`	Return a geometry representing all points whose distance from `x` is less than or equal to `y`.
`envelope`	x: `G`	`G`	Return the minimum bouding box of `x`.
`centroid`	x: `G`	`G`	Return the geometric centre of `x`.
`convex_hull`	x: `G`	`G`	Return minimum convex geometry that encloses all geometries within `x`.
`get_x`	x: `G`	`N`	Return the X coordinate of `x` if it’s a Point.
`get_y`	x: `G`	`N`	Return the Y coordinate of `x` if it’s a Point.
`get_z`	x: `G`	`N`	Return the Z coordinate of `x` if it’s a Point and is 3D.
`wkt`	x: `G`	`S`	Return a WKT representation of `x`.

§Configuring this library

This library, so far, relies on 3 environment variables DEFAULT_CRS, DEFAULT_PRECISION, and RUST_LOG.

The file .env.template contains those variables w/ their defaults. To adapt it to your environment make a copy, rename it .env and change the values as required.

§`DEFAULT_CRS`

This environment variable defines the implicit Coordinate Reference System (CRS) code to use when checking if coordinates fall w/in a geometry’s CRS validity extent (a.k.a Area Of Use). It defaults to EPSG:4326 if undefined.

The standard mentions this in…

Since WKT and GeoJSON do not provide a capability to specify the CRS of a geometry literal, the server has to determine the CRS of the geometry literals in a filter expression through another mechanism.

This value is fed to a Context when created using the new() constructor and will trickle down and be used when parsing Expressions containing geometry queryables and literals. For example…

    let shared_ctx = Context::new().freeze();

Because the Conformance Tests expect EPSG:4326 to be indeed the implicit CRS when using included (in the standard) test data, this library allows overriding the global implicit CRS when constructing a Context before freezing and handing it over to Evaluators. Here’s an example when used in most of the Conformance Tests…

    let shared_ctx = Context::try_with_crs("EPSG:4326")?.freeze();

§`DEFAULT_PRECISION`

By Precision I mean the number of digits after the decimal point.

This environment variable controls 2 things: (a) the precision to keep when ingesting geometry coordinates, and (b) the precision to use when rendering geometry WKT output using the to_wkt() generic method.

The default value of 6 ensures that coordinates in WGS 84 (which is the default implicit CRS) are compared w/ an accuracy of 11.1 cm.

For now only integers greater than or equal to 0 and less than 8 are allowed.

The GTrait made public since vesion 0.2.0 and implemented for all geometry variants allows for fine-tuning the WKT output by offering the following method…

    fn to_wkt_fmt(&self, precision: usize) -> String;

§`RUST_LOG`

See https://docs.rs/env_logger/latest/env_logger/#enabling-logging for details.

Modules§

prelude: Group imports of many common traits and types by adding a glob import for use by clients of this library.

Structs§

BBox: 2D or 3D bounding box.
CRS: Representation of a Coordinate Reference System
Context: A Context object we will be handing to evaluators so they are aware of external registered Functions.
EvaluatorImpl: An example of a concrete evaluator.
FnInfo: A struct that holds metadata about a Function.
Geometries: Collection of mixed geometries.
JsonEncoded: JSON-encoded CQL2 Expression.
Line: 2D or 3D line-string geometry.
Lines: Collection of line-string geometries.
Point: 2D or 3D point geometry.
Points: Collection of point geometries.
Polygon: 2D or 3D polygon geometry.
Polygons: Collection of polygon geometries.
QString: String based type used by Queryables to represent a plain string, and a set of flags to indicate how to use it in case and/or accent insensitive contexts.
TextEncoded: Text-encoded CQL2 Expression.

Enums§

Bound: Possible variants of a CQL2 Instant and Interval limit.
Expression: An instance of an OGC CQL2 filter.
ExtDataType: Externally visible data type variants for arguments and result types used and referenced by user-defined and registered functions invoked in filter expressions.
G: Geometry type variants handled by this library.
MyError: Variants of error raised from this library.
Outcome: Possible outcome values when evaluating an Expression against an individual Resource from a collection.
Q: A Resource queryable property possible concrete value variants.

Traits§

Evaluator: Trait to be implmented by concrete evaluators of OGC CQL2 expressions both text- and json-encoded.
GTrait: Geometry Trait implemented by all geometry types in this library.

Type Aliases§

Resource: A dictionary of queryable property names (strings) to Q values. Queryables have same lifetime as their parent.
SharedContext: What we share between Evaluators.

Crate ogc_cql2

Crate ogc_cql2 Copy item path

§Third-party crates

§Functions

§Data types

§Numeric (Num) builtins

§String (Str) builtins

§Temporal builtins

§Geometry (Geom) builtins

§Configuring this library

§DEFAULT_CRS

§DEFAULT_PRECISION

§RUST_LOG

Modules§

Structs§

Enums§

Traits§

Type Aliases§

Crate ogc_cql2

§Numeric (`Num`) builtins

§String (`Str`) builtins

§Geometry (`Geom`) builtins

§`DEFAULT_CRS`

§`DEFAULT_PRECISION`

§`RUST_LOG`