# CQL Developer documentation

Formerly: AQL

## Abbreviations inventory (TODO add plz!)

These need some documentation in the code, and maybe some of them could be renamed. Let's start by figuring out what the letters stand for, and what they mean.

- `GTerm` (now named `Carrier`): should this be called `ETerm` for entity term?
> yes, ETerm is better. ETerms are the carrier for the initial algebra of an instance; they are just terms. I made a separate type so this could be changed. For example aql-java just uses natural numbers as the carrier.
- `TTerm` (now named `TalgGen`): type term?
> yes. TTerms are the generating labelled nulls for the type algebra of the associated instance.
- `nf`: normal form
- `dp`: decision procedure?
- `w`:

More obvious ones:
- tys: typeside(s) (is this also used for 'types'?)
- sym: type side function/constant symbol
- var: variable
- fk: foreign key
- en: entity
- ens: entities
- att: attribute
- gen: generator
- sk : skolem term / labelled null / (like a generator for a type rather than entity)
- col: collage
- sch: schema
- ins: instance

## Codebase

General code standards: https://hackmd.io/U8vrBv94TqK413F0GIEAfg

## Secret ingedients
- `maybe`, `fromMaybe`, `either`, etc in favour of pattern matching, which is quite low-level and can't be generified
- `Map.mapWithKey`
- `fmap`, `<$>`
- `Set.map`
- `Map.fromSet`
- `member`
- applicatives, eg `add <$> Just 42 <*> Nothing`
- `pure` instead of `return`; induces weaker `Applicative` constraint
- `pure`, `mzero` could be used
- `Left` and `Right` instead of`pure` and `Left`; while keeping it generic is a worthy goal, `pure` and `Left` as a combo aren't so great; as long as we're using one specialised constructors, we might as well be explicit in the other.

Ryan comments:
> Left should probably be replaced with a monadic/applicative/whatever 'throwError' in 95% of the code

# Caution

If we could get rid of some of these things in the codebase, that'd be nice; worth a bit of investigation:
- avoid `fromJust`; at least mitigate by perhaps doing it properly using `Maybe`, and deferring the `fromJust` to the call site.
-- Almost all of the uses of `fromJust` are places where Map lookups are guaranteed not to fail.
- `absurd`
-- I use these to do typesafe conversion of terms, see below
- `undefined`
-- Some of the `undefined` are places where code still needs to be written, but in a few places it is used deliberately, such as creating instances without theorem provers. In such places it's safely used as a null value.

## Questions

- what are the `upXxx` funs for?

Ryan says:
> Terms are parameterized by the type of symbols they carry. For example, `Term Void Void Void en fk Void gen Void` is the type of terms on the entity side in the presentation of an instance, making explicit the fact that e.g., variables can't be present. But sometimes we want to convert the term; for example, add it to a list of `Term var ty sym en fk att gen sk`. Then we use one of the `upXxx` functions to do the conversion, by eliminating the `Void` types with `absurd`.

- performance of bound `foo = toList ...` followed by operation on `foo` vs. inline version (TODO: find example)

Ryan says:
> there are a lot of places that look like `toMap (list map) fromMap`, because I'm not that familiar with the Map interface. Ditto for sets. These can be replaced.

# Haskell, GHC and tooling things that may prove useful

- warn about redundant type constraints with [--Wredundant-constraints](--Wredundant-constraints )
- infer type constraints with [PartialTypeSignatures](https://ghc.haskell.org/trac/ghc/wiki/PartialTypeSignatures#extra-constraints-wildcard)
- make hlint force newline after `do` with github.com/lspitzner/brittany
- use [hindent](https://github.com/commercialhaskell/hindent) to help with formatting and alignment
- we use `-Werror` to make any warning into a compiler error, so we can ensure our code is syntactically correct
- we use `-Weverything` to enable all the possible compiler warnings and then we disable only the undesired ones using the `-Wno-` options. FOr example we use `-Wno-unused-type-patters` to avoid warning on unused function arguments and `-Wno-name-shadowing` to allow variable name shadowing

# Feature support

source: [Options.hs](https://github.com/statebox/cql/blob/1609241a2c188319241d9b5ea7fe51441edb41c4/src/Language/Options.hs)

- [ ] generate SQL
- [ ] pivot

# TODO

- [ ] Erik to look at https://github.com/statebox/aql/issues/54#issuecomment-430962183
- [ ] Erik to look at `pivot` feature in Java AQL:
- https://github.com/CategoricalData/fql/blob/master/src/main/java/catdata/aql/AqlPivot.java
- https://github.com/CategoricalData/fql/commit/efaea9217ea4ef40f0d6e82d41eb14c250b47b5e
- https://github.com/CategoricalData/fql/commit/a58d1cd13b59b422f37d69a20b91657b961eb891