From 5358770b25bd118a96109d593e49a3451e58311d Mon Sep 17 00:00:00 2001 From: Simon Brooke Date: Sun, 25 May 2025 13:16:21 +0100 Subject: [PATCH] Fixed most linting issues in to_selmer_templates; commented out unfinished code in to_swagger --- docs/adl.main.html | 16 +- docs/adl.to-cache.html | 10 +- docs/adl.to-hugsql-queries.html | 32 +- docs/adl.to-json-routes.html | 21 +- docs/adl.to-psql.html | 54 ++- docs/adl.to-reframe.html | 10 +- docs/adl.to-selmer-routes.html | 47 +-- docs/adl.to-selmer-templates.html | 96 ++--- docs/adl.to-swagger.html | 6 +- docs/adl.validator.html | 379 ++++++++---------- docs/index.html | 16 +- project.clj | 6 +- resources/schemas/adl-1.4.7.dtd | 628 ++++++++++++++++++++++++++++++ resources/schemas/adl-1.4.7.xsd | 559 ++++++++++++++++++++++++++ src/adl/to_selmer_templates.clj | 55 +-- src/adl/to_swagger.clj | 153 ++++---- 16 files changed, 1600 insertions(+), 488 deletions(-) create mode 100644 resources/schemas/adl-1.4.7.dtd create mode 100644 resources/schemas/adl-1.4.7.xsd diff --git a/docs/adl.main.html b/docs/adl.main.html index 6989ec2..7c8aea4 100644 --- a/docs/adl.main.html +++ b/docs/adl.main.html @@ -1,10 +1,10 @@ -adl.main documentation

Project

Namespaces

Public Vars

adl.main

Application Description Language - command line invocation.
-

-main

(-main & args)
Parses options and arguments. Expects as args the path-name of one or
-more ADL files.

adl->canonical

A function which takes ADL text as its single argument and returns
-canonicalised ADL text as its result.

canonicalise

(canonicalise filepath)
Canonicalise the ADL document indicated by this `filepath` (if it is not
-already canonical) and return a path to the canonical version.

cli-options

Command-line interface options
-

process

(process options)
Process these parsed `options`.
-

usage

(usage parsed-options)
Show a usage message. `parsed-options` should be options as
-parsed by [clojure.tools.cli](https://github.com/clojure/tools.cli)
\ No newline at end of file +adl.main documentation

Project

Namespaces

Public Vars

adl.main

Application Description Language - command line invocation.

+

-main

(-main & args)

Parses options and arguments. Expects as args the path-name of one or more ADL files.

+

adl->canonical

A function which takes ADL text as its single argument and returns canonicalised ADL text as its result.

+

canonicalise

(canonicalise filepath)

Canonicalise the ADL document indicated by this filepath (if it is not already canonical) and return a path to the canonical version.

+

cli-options

Command-line interface options

+

process

(process options)

Process these parsed options.

+

usage

(usage parsed-options)

Show a usage message. parsed-options should be options as parsed by clojure.tools.cli

+
\ No newline at end of file diff --git a/docs/adl.to-cache.html b/docs/adl.to-cache.html index 4d7617a..a6437ab 100644 --- a/docs/adl.to-cache.html +++ b/docs/adl.to-cache.html @@ -1,7 +1,7 @@ -adl.to-cache documentation

Project

Namespaces

Public Vars

adl.to-cache

Application Description Language: generate caching layer for database requests.
-

file-header

(file-header application)
Generate an appropriate file header for JSON routes for this `application`.
-

handler

(handler query)
Generate declarations for handlers for this `query`. Cache handlers are needed only for select queries.
-

to-cache

(to-cache application)
Generate a `/cache.clj` file for this `application`.
-
\ No newline at end of file +adl.to-cache documentation

Project

Namespaces

Public Vars

adl.to-cache

Application Description Language: generate caching layer for database requests.

+

file-header

(file-header application)

Generate an appropriate file header for JSON routes for this application.

+

handler

(handler query)

Generate declarations for handlers for this query. Cache handlers are needed only for select queries.

+

to-cache

(to-cache application)

Generate a /cache.clj file for this application.

+
\ No newline at end of file diff --git a/docs/adl.to-hugsql-queries.html b/docs/adl.to-hugsql-queries.html index 71d000a..f6a7565 100644 --- a/docs/adl.to-hugsql-queries.html +++ b/docs/adl.to-hugsql-queries.html @@ -1,18 +1,18 @@ -adl.to-hugsql-queries documentation

Project

Namespaces

Public Vars

adl.to-hugsql-queries

Application Description Language - generate HUGSQL queries file.
-

delete-query

(delete-query entity)
Generate an appropriate `delete` query for this `entity`
-

expanded-token

FIXME: write docs

foreign-queries

(foreign-queries entity application)
Generate any foreign entity queries for this `entity` of this `application`.
-

generate-documentation

(generate-documentation query)
Generate, as a string, appropriate documentation for a function wrapping this `query` map.
-

insert-query

(insert-query entity)
Generate an appropriate `insert` query for this `entity`.
-TODO: this depends on the idea that system-unique properties
-are not insertable, which is... dodgy.

list-query

(list-query entity)
Generate a query to list records in the table represented by this `entity`.
-Parameters `:limit` and `:offset` may be supplied. If not present limit defaults
-to 100 and offset to 0.

order-by-clause

(order-by-clause entity)(order-by-clause entity prefix)(order-by-clause entity prefix expanded?)
Generate an appropriate `order by` clause for queries on this `entity`
-

queries

(queries application entity)(queries application)
Generate all standard queries for this `entity` in this `application`; if
-no entity is specified, generate all queries for the application.

search-query

(search-query entity application)
FIXME: write docs

select-query

(select-query entity properties)(select-query entity)
Generate an appropriate `select` query for this `entity`
-

to-hugsql-queries

(to-hugsql-queries application)
Generate all [HugSQL](https://www.hugsql.org/) queries implied by this ADL `application` spec.
-

update-query

(update-query entity)
Generate an appropriate `update` query for this `entity`
-

where-clause

(where-clause entity)(where-clause entity properties)
Generate an appropriate `where` clause for queries on this `entity`;
-if `properties` are passed, filter on those properties, otherwise the key
-properties.
\ No newline at end of file +adl.to-hugsql-queries documentation

Project

Namespaces

Public Vars

adl.to-hugsql-queries

Application Description Language - generate HUGSQL queries file.

+

delete-query

(delete-query entity)

Generate an appropriate delete query for this entity

+

expanded-token

*TODO: write docs

+

foreign-queries

(foreign-queries entity application)

Generate any foreign entity queries for this entity of this application.

+

generate-documentation

(generate-documentation query)

Generate, as a string, appropriate documentation for a function wrapping this query map.

+

insert-query

(insert-query entity)

Generate an appropriate insert query for this entity. TODO: this depends on the idea that system-unique properties are not insertable, which is… dodgy.

+

list-query

(list-query entity)

Generate a query to list records in the table represented by this entity. Parameters :limit and :offset may be supplied. If not present limit defaults to 100 and offset to 0.

+

order-by-clause

(order-by-clause entity)(order-by-clause entity prefix)(order-by-clause entity prefix expanded?)

Generate an appropriate order by clause for queries on this entity

+

queries

(queries application entity)(queries application)

Generate all standard queries for this entity in this application; if no entity is specified, generate all queries for the application.

+

search-query

(search-query entity _)(search-query entity)

Generate an appropriate search query for string fields of this entity.

+

Unused second argument was application, and is retained for backward compatibility.

+

select-query

(select-query entity properties)(select-query entity)

Generate an appropriate select query for this entity

+

to-hugsql-queries

(to-hugsql-queries application)

Generate all HugSQL queries implied by this ADL application spec.

+

update-query

(update-query entity)

Generate an appropriate update query for this entity

+

where-clause

(where-clause entity)(where-clause entity properties)

Generate an appropriate where clause for queries on this entity; if properties are passed, filter on those properties, otherwise the key properties.

+
\ No newline at end of file diff --git a/docs/adl.to-json-routes.html b/docs/adl.to-json-routes.html index 8783709..916a080 100644 --- a/docs/adl.to-json-routes.html +++ b/docs/adl.to-json-routes.html @@ -1,13 +1,12 @@ -adl.to-json-routes documentation

Project

Namespaces

Public Vars

adl.to-json-routes

Application Description Language: generate RING routes for REST requests.
-

declarations

(declarations handlers-map)
Generate a forward declaration of all JSON route handlers we're going to
-generate for this `application`.

defroutes

(defroutes handlers-map)
Generate JSON routes for all queries implied by this ADL `application` spec.
-

file-header

(file-header application)
Generate an appropriate file header for JSON routes for this `application`.
-

generate-handler-body

(generate-handler-body query)
Generate and return the function body for the handler for this `query`.
-

generate-handler-src

(generate-handler-src handler-name query-map method)
Generate and return the handler for this `query`.
-

handler

(handler query-key queries-map application)
Generate declarations for handlers from query with this `query-key` in this `queries-map`
-taken from within this `application`. This method must follow the structure of
-`to-hugsql-queries/queries` quite closely, because we must generate the same names.

make-handlers-map

(make-handlers-map application)
Analyse this `application` and generate from it a map of the handlers to be output.
-

to-json-routes

(to-json-routes application)
Generate a `/routes/auto-json.clj` file for this `application`.
-
\ No newline at end of file +adl.to-json-routes documentation

Project

Namespaces

Public Vars

adl.to-json-routes

Application Description Language: generate RING routes for REST requests.

+

declarations

(declarations handlers-map)

Generate a forward declaration of all JSON route handlers we’re going to generate for this application.

+

defroutes

(defroutes handlers-map)

Generate JSON routes for all queries implied by this ADL application spec.

+

file-header

(file-header application)

Generate an appropriate file header for JSON routes for this application.

+

generate-handler-body

(generate-handler-body query)

Generate and return the function body for the handler for this query.

+

generate-handler-src

(generate-handler-src handler-name query-map method)

Generate and return the handler for this query.

+

handler

(handler query-key queries-map application)

Generate declarations for handlers from query with this query-key in this queries-map taken from within this application. This method must follow the structure of to-hugsql-queries/queries quite closely, because we must generate the same names.

+

make-handlers-map

(make-handlers-map application)

Analyse this application and generate from it a map of the handlers to be output.

+

to-json-routes

(to-json-routes application)

Generate a /routes/auto-json.clj file for this application.

+
\ No newline at end of file diff --git a/docs/adl.to-psql.html b/docs/adl.to-psql.html index 1b81eac..34be32e 100644 --- a/docs/adl.to-psql.html +++ b/docs/adl.to-psql.html @@ -1,32 +1,26 @@ -adl.to-psql documentation

Project

Namespaces

Public Vars

adl.to-psql

Application Description Language: generate Postgres database definition.
-

compose-convenience-entity-field

(compose-convenience-entity-field field entity application)
FIXME: write docs

compose-convenience-view-select-list

(compose-convenience-view-select-list entity application top-level?)
Compose the body of an SQL `SELECT` statement for a convenience view of this
-`entity` within this `application`, recursively. `top-level?` should be set
-only on first invocation.

compose-convenience-where-clause

(compose-convenience-where-clause entity application top-level?)
Compose an SQL `WHERE` clause for a convenience view of this
-`entity` within this `application`.
-TODO: does not correctly compose links at one stage down the tree.
-See `lv_electors`, `lv_followuprequests` for examples of the problem.

emit-application

(emit-application application)
Emit all SQL declarations required to initialise a Postgres database for
-this `application`.

emit-convenience-entity-field

(emit-convenience-entity-field field entity application)
FIXME: write docs

emit-convenience-view

(emit-convenience-view entity application)
Emit a convenience view of this `entity` of this `application` for use in generating lists,
-menus, et cetera.

emit-defined-field-type

(emit-defined-field-type property application)
Generate appropriate field type and constraints for this `property`
-given this `typedef`.

emit-entity-field-type

(emit-entity-field-type property application)
Emit an appropriate field type for this `property`, expected to reference an entity, in this `application`.
-

emit-field-type

(emit-field-type property entity application key?)
Emit an appropriate field type for this `property`, expected to belong to
-this `entity` within this `application`.

emit-file-header

(emit-file-header application)
Generate an appropriate file header for the Postgres initialisation script
-for this `application`.

emit-group-declaration

(emit-group-declaration group application)
Emit a declaration for this authorisation `group` within this `application`.
-

emit-permissions-grant

(emit-permissions-grant table-name privilege permissions)
Emit an appropriate grant of permissions on this `table-name` at this
-`privilege` level given these `permissions`. `privilege` is expected
-to be one of #{:SELECT :INSERT :UPDATE :DELETE}.
-TODO: more thought needed here.

emit-property

(emit-property property entity application)(emit-property property entity application key?)
Emit a field declaration representing this `property` of this `entity` within this `application`.
-

emit-table

(emit-table entity application doc-comment)(emit-table entity application)
Emit a table declaration for this `entity` of this `application`,
-documented with this `doc-comment` if specified.

field-name

(field-name property)
Return the appropriate field name for this `property`.
-TODO: really belongs in `adl-support.utils`.

to-psql

(to-psql application)
Generate a complete Postgres database initialisation script for this `application`.
-
\ No newline at end of file +adl.to-psql documentation

Project

Namespaces

Public Vars

adl.to-psql

Application Description Language: generate Postgres database definition.

+

compose-convenience-entity-field

(compose-convenience-entity-field field entity application)(compose-convenience-entity-field field entity application table-alias)

*TODO: write docs

+

compose-convenience-view-from-list

(compose-convenience-view-from-list entity application top-level?)

Compose the FROM list of an SQL SELECT statement for a convenience view of this entity within this application, recursively. top-level? should be set only on first invocation.

+

compose-convenience-where-clause

(compose-convenience-where-clause entity application top-level?)

Compose an SQL WHERE clause for a convenience view of this entity within this application. TODO: does not correctly compose links at one stage down the tree. See lv_electors, lv_followuprequests for examples of the problem.

+

emit-application

(emit-application application)

Emit all SQL declarations required to initialise a Postgres database for this application.

+

emit-convenience-entity-field

(emit-convenience-entity-field property entity application)(emit-convenience-entity-field property entity application table-alias)

*TODO: write docs

+

emit-convenience-view

(emit-convenience-view entity application)

Emit a convenience view of this entity of this application for use in generating lists, menus, et cetera.

+

emit-defined-field-type

(emit-defined-field-type property application)

Generate appropriate field type and constraints for this property given this typedef.

+

emit-entity-field-type

(emit-entity-field-type property application)

Emit an appropriate field type for this property, expected to reference an entity, in this application.

+

emit-field-type

(emit-field-type property entity application key?)

Emit an appropriate field type for this property, expected to belong to this entity within this application.

+

emit-file-header

(emit-file-header application)

Generate an appropriate file header for the Postgres initialisation script for this application.

+

emit-group-declaration

(emit-group-declaration group)

Emit a declaration for this authorisation group.

+

emit-permissions-grant

(emit-permissions-grant table-name privilege permissions)

Emit an appropriate grant of permissions on this table-name at this privilege level given these permissions. privilege is expected to be one of #{:SELECT :INSERT :UPDATE :DELETE}. TODO: more thought needed here.

+

emit-property

(emit-property property entity application)(emit-property property entity application key?)

Emit a field declaration representing this property of this entity within this application.

+

emit-table

(emit-table entity application doc-comment)(emit-table entity application)

Emit a table declaration for this entity of this application, documented with this doc-comment if specified.

+

field-name

(field-name property)

Return the appropriate field name for this property. TODO: really belongs in adl-support.utils.

+

to-psql

(to-psql application)

Generate a complete Postgres database initialisation script for this application.

+
\ No newline at end of file diff --git a/docs/adl.to-reframe.html b/docs/adl.to-reframe.html index c479abd..be3171e 100644 --- a/docs/adl.to-reframe.html +++ b/docs/adl.to-reframe.html @@ -1,7 +1,7 @@ -adl.to-reframe documentation

Project

Namespaces

Public Vars

adl.to-reframe

Application Description Language: generate re-frame UI. TODO: doesn't even nearly work yet.
-

file-header

(file-header parent-name this-name extra-requires)(file-header parent-name this-name)
Generate an appropriate file header for a re-frame view.
-

generate-form

(generate-form form entity application)
Generate as re-frame this `form` taken from this `entity` of this `application`.
-
-TODO: write it!
\ No newline at end of file +adl.to-reframe documentation

Project

Namespaces

Public Vars

adl.to-reframe

Application Description Language: generate re-frame UI. TODO: doesn’t even nearly work yet.

+

file-header

(file-header parent-name this-name extra-requires)(file-header parent-name this-name)

Generate an appropriate file header for a re-frame view.

+

generate-form

(generate-form form entity application)

Generate as re-frame this form taken from this entity of this application.

+

TODO: write it!

+
\ No newline at end of file diff --git a/docs/adl.to-selmer-routes.html b/docs/adl.to-selmer-routes.html index 3a6e1b5..50dcd41 100644 --- a/docs/adl.to-selmer-routes.html +++ b/docs/adl.to-selmer-routes.html @@ -1,30 +1,21 @@ -adl.to-selmer-routes documentation

Project

Namespaces

Public Vars

adl.to-selmer-routes

Application Description Language: generate routes for user interface requests.
-

compose-fetch-auxlist-data

(compose-fetch-auxlist-data auxlist entity application)
Compose Clojure code to fetch data to populate this `auxlist` of a form
-editing a record of this `entity` within this `application`.

compose-fetch-record

(compose-fetch-record e a)
Compose Clojure code to retrieve a single record of entity `e` in application `a`; in addition
-to the fields of the record in the database, the record should also contain the values of
-the `link` and `list` properties of the entity, retrieved from their tables.
-TODO: what about `entity` properties?.

compose-get-menu-options

(compose-get-menu-options property nearside application)
Compose Clojure code to fetch from the database menu options for this
-`property` within this `application`.

file-header

(file-header application)
FIXME: write docs

generate-handler-resolver

(generate-handler-resolver application)
Dodgy, dodgy, dodgy. Generate code which will look up functions in the
-manual and in this namespace. I'm sure someone who really knew what they
-were doing could write this more elegantly.

handler-name

(handler-name f e a m)
Generate the name of the appropriate handler function for form `f` of
-entity `e` of application `a` for method `m`, where `f`, `e`, and `a`
-are expected to be elements and `m` is expected to be one of the keywords
-`:put` `:get`.

make-defroutes

(make-defroutes application)
Generate a `defroutes` declaration for all routes of all forms, pages and
-lists within this `application`.

make-form-get-handler-content

(make-form-get-handler-content f e a n)
Compose Clojure code to form body of an HTTP `GET` handler for the form
-`f` of the entity `e` within application `a`. The argument `n`
-is not used.

make-form-post-handler-content

(make-form-post-handler-content f e a n)
Generate the body of the post handler for the form `f` of
-entity `e` in application `a`. The argument `n` is bound to the name
-of the function, but is not currently used.
-
-Literally the only thing the post handler has to do is to
-execute the database store operation. Then it can hand off
-to the get handler.

make-get-handler

(make-get-handler f e a)
Generate a Clojure function to handle HTTP `GET` requests for form, list or
-page `f` of entity `e` within application `a`.

make-handlers

(make-handlers e application)
Generate all the Selmer route handlers for all the forms, lists and pages
-of the entity `e` within this `application`.

make-list-get-handler-content

(make-list-get-handler-content f e a n)
Compose Clojure code to form body of an HTTP `GET` handler for the list
-`f` of the entity `e` within application `a`. The argument `n` is ignored.

make-page-get-handler-content

(make-page-get-handler-content f e a n)
Compose Clojure code to form body of an HTTP `GET` handler for the page
-`f` of the entity `e` within application `a`. The argument `n` is ignored.

make-post-handler

(make-post-handler f e a)
Generate an HTTP `POST` handler for the page, form or list `f` of the
-entity `e` of application `a`.

make-route

(make-route m n)
Make a route for method `m` to request the resource with name `n`.
-

to-selmer-routes

(to-selmer-routes application)
Generate a `/routes/auto.clj` file for this `application`.
-
\ No newline at end of file +adl.to-selmer-routes documentation

Project

Namespaces

Public Vars

adl.to-selmer-routes

Application Description Language: generate routes for user interface requests.

+

compose-fetch-auxlist-data

(compose-fetch-auxlist-data auxlist entity application)

Compose Clojure code to fetch data to populate this auxlist of a form editing a record of this entity within this application.

+

compose-fetch-record

(compose-fetch-record e a)

Compose Clojure code to retrieve a single record of entity e in application a; in addition to the fields of the record in the database, the record should also contain the values of the link and list properties of the entity, retrieved from their tables. TODO: what about entity properties?.

+

compose-get-menu-options

(compose-get-menu-options property nearside application)

Compose Clojure code to fetch from the database menu options for this property within this application.

+

file-header

(file-header application)

*TODO: write docs

+

generate-handler-resolver

(generate-handler-resolver application)

Dodgy, dodgy, dodgy. Generate code which will look up functions in the manual and in this namespace. I’m sure someone who really knew what they were doing could write this more elegantly.

+

handler-name

(handler-name f e a m)

Generate the name of the appropriate handler function for form f of entity e of application a for method m, where f, e, and a are expected to be elements and m is expected to be one of the keywords :put :get.

+

make-defroutes

(make-defroutes application)

Generate a defroutes declaration for all routes of all forms, pages and lists within this application.

+

make-form-get-handler-content

(make-form-get-handler-content f e a n)

Compose Clojure code to form body of an HTTP GET handler for the form f of the entity e within application a. The argument n is not used.

+

make-form-post-handler-content

(make-form-post-handler-content f e a n)

Generate the body of the post handler for the form f of entity e in application a. The argument n is bound to the name of the function, but is not currently used.

+

Literally the only thing the post handler has to do is to execute the database store operation. Then it can hand off to the get handler.

+

make-get-handler

(make-get-handler f e a)

Generate a Clojure function to handle HTTP GET requests for form, list or page f of entity e within application a.

+

make-handlers

(make-handlers e application)

Generate all the Selmer route handlers for all the forms, lists and pages of the entity e within this application.

+

make-list-get-handler-content

(make-list-get-handler-content f e a n)

Compose Clojure code to form body of an HTTP GET handler for the list f of the entity e within application a. The argument n is ignored.

+

make-page-get-handler-content

(make-page-get-handler-content f e a n)

Compose Clojure code to form body of an HTTP GET handler for the page f of the entity e within application a. The argument n is ignored.

+

make-post-handler

(make-post-handler f e a)

Generate an HTTP POST handler for the page, form or list f of the entity e of application a.

+

make-route

(make-route m n)

Make a route for method m to request the resource with name n.

+

to-selmer-routes

(to-selmer-routes application)

Generate a /routes/auto.clj file for this application.

+
\ No newline at end of file diff --git a/docs/adl.to-selmer-templates.html b/docs/adl.to-selmer-templates.html index 0772454..9067370 100644 --- a/docs/adl.to-selmer-templates.html +++ b/docs/adl.to-selmer-templates.html @@ -1,57 +1,43 @@ -adl.to-selmer-templates documentation

Project

Namespaces

Public Vars

adl.to-selmer-templates

Application Description Language - generate Selmer templates for
-the HTML pages implied by an ADL file.

application-to-template

(application-to-template application)
FIXME: write docs

compose-form-auxlist

(compose-form-auxlist auxlist form entity application)
Compose an auxiliary list from this `auxlist` specification of dependent
-records (i.e. the far side of a
-one-to-many link) of the record of this `entity` within this `application`
-being edited in this `form`

compose-form-auxlists

(compose-form-auxlists form entity application)
Generate all auxiliary lists required for this `form` of this `entity`
-within this `application`.

compose-form-content

(compose-form-content form entity application)
Compose the content for this `form` of this `entity` within this `application`.
-

compose-form-extra-head

(compose-form-extra-head form entity application)
Compose any extra-head declarations (i.e. special Javascript tags) required
-for this `form` of this `entity` within this `application`.

compose-form-extra-tail

(compose-form-extra-tail form entity application)
Compose any extra-tail declarations (i.e. special Javascript tags) required
-for this `form` of this `entity` within this `application`.

compose-if-member-of-tag

(compose-if-member-of-tag privilege & elts)
Generate an appropriate `ifmemberof` tag (see `adl-support.tags`) given this
-`privilege` for the  ADL elements listed in `elts`, which may be fields,
-properties, list, forms, pages or entities.

compose-input-widget-para

(compose-input-widget-para property form entity application widget-name)
Generate an input widget for this `field-or-property` of this `form` for
-this `entity` taken from within this `application`, in context of a para
-also containing its label.

compose-list-search-widget

(compose-list-search-widget field entity)
Compose a list search widget for this `field` referencing a property within
-this `entity`.

compose-readable-or-not-authorised

(compose-readable-or-not-authorised p f e a w)
Compose content to emit if the user is not authorised to write, or
-not authorised to read, property `p` in form, list or page `f` of
-entity `e` within application `a`, while generating a widget with id
-`w`.

compose-widget-para

(compose-widget-para p f e a w content)
Compose a widget paragraph for property `p` in form, list or page `f` of
-entity `e` within application `a`, with id `w` and this `content`.

csrf-widget

(csrf-widget)
For the present, just return the standard cross site scripting protection
-field statement

delete-widget

(delete-widget form entity application)
Return an appropriate 'save' widget for this `form` operating on this
-`entity` taken from this `application`.

embed-script-fragment

(embed-script-fragment resource-path substitutions)(embed-script-fragment resource-path)
Return the content of the file at `resource-path`, with these
-`substitutions` made into it in order. Substitutions should be pairs
-[`pattern` `value`], where `pattern` is a string, a char, or a regular
-expression.

emit-content

(emit-content content)(emit-content filename application k)(emit-content filename spec entity application k)
FIXME: write docs

emit-entity-dd

(emit-entity-dd entity application)
FIXME: write docs

emit-entity-dt

(emit-entity-dt entity application)
FIXME: write docs

entity-to-templates

(entity-to-templates entity application)
Generate one or more templates for editing instances of this
-`entity` in this `application`

file-header

(file-header filename application)(file-header filename spec entity application)
Generate a header for a template file with this `filename` for this `spec`
-of this `entity` within this `application`.

form-to-template

(form-to-template form entity application)
Generate a template as specified by this `form` element for this `entity`,
-taken from this `application`. If `form` is nill, generate a default form
-template for the entity.

get-options

(get-options property form entity application)
Produce template code to get options for this `property` of this `entity`
-taken from this `application`.

get-size-for-widget

(get-size-for-widget property)
Return, as an integer, the fieldwidth for the input widget for this
-`property`.

list-tbody

(list-tbody source list-spec entity application)
Return a table body element for the list view for this `list-spec` of
-this `entity` within this `application`, using data from this `source`.

list-to-template

(list-to-template list-spec entity application)
Generate a template as specified by this `list` element for this `entity`,
-taken from this `application`. If `list` is nill, generate a default list
-template for the entity.

page-to-template

(page-to-template page entity application)
Generate a template as specified by this `page` element for this `entity`,
-taken from this `application`. If `page` is nil, generate a default page
-template for the entity.
-
-TODO: not yet written.

save-widget

(save-widget form entity application)
Return an appropriate 'save' widget for this `form` operating on this
-`entity` taken from this `application`.
-TODO: should be suppressed unless a member of a group which can insert
-or edit.

select-field-name

(select-field-name entity)
FIXME: write docs

select-property

(select-property entity)
Return the property on which we will by default do a user search on this
-`entity`.

select-widget

(select-widget property form entity application)
Generate an HTML `SELECT` widget for this `property` of this `entity` within
-this `application`, to be used in this `form`. TODO: Many selectable things
-are potentially too numerous to be simply represented in a simple static
-SELECT, it needs some asynchronous fetching. See
-[issue 47](https://github.com/simon-brooke/youyesyet/issues/47).

to-selmer-templates

(to-selmer-templates application)
Generate all [Selmer](https://github.com/yogthos/Selmer) templates implied
-by this ADL `application` spec.

widget

(widget field-or-property form entity application)
Generate a widget for this `field-or-property` of this `form` for this
-`entity` taken from within this `application`, in context of a para also
-containing its label.

widget-type

(widget-type property application)(widget-type property application typedef)
Return an appropriate HTML5 input type for this property.
-

wrap-in-if-member-of

(wrap-in-if-member-of content privilege & context)
Wrap this `content` in an if-member-of tag; if `writeable?` is true,
-allow those groups by whom it is writeable, else those by whom it is
-readable. `context` should be a sequence of adl elements from which
-permissions may be obtained.

write-template-file

(write-template-file filename template application)
Write a template file with this `filename` from this `template` in the
-context of this `application`.
\ No newline at end of file +adl.to-selmer-templates documentation

Project

Namespaces

Public Vars

adl.to-selmer-templates

Application Description Language - generate Selmer templates for the HTML pages implied by an ADL file.

+

application-to-template

(application-to-template application)

*TODO: write docs

+

compose-form-auxlist

(compose-form-auxlist auxlist form entity application)

Compose an auxiliary list from this auxlist specification of dependent records (i.e. the far side of a one-to-many link) of the record of this entity within this application being edited in this form

+

compose-form-auxlists

(compose-form-auxlists form entity application)

Generate all auxiliary lists required for this form of this entity within this application.

+

compose-form-content

(compose-form-content form entity application)

Compose the content for this form of this entity within this application.

+

compose-form-extra-head

(compose-form-extra-head form entity application)

Compose any extra-head declarations (i.e. special Javascript tags) required for this form of this entity within this application.

+

compose-form-extra-tail

(compose-form-extra-tail form entity application)

Compose any extra-tail declarations (i.e. special Javascript tags) required for this form of this entity within this application.

+

compose-if-member-of-tag

(compose-if-member-of-tag privilege & elts)

Generate an appropriate ifmemberof tag (see adl-support.tags) given this privilege for the ADL elements listed in elts, which may be fields, properties, list, forms, pages or entities.

+

compose-input-widget-para

(compose-input-widget-para property form entity application widget-name)

Generate an input widget for this field-or-property of this form for this entity taken from within this application, in context of a para also containing its label.

+

compose-list-search-widget

(compose-list-search-widget field entity)

Compose a list search widget for this field referencing a property within this entity.

+

compose-readable-or-not-authorised

(compose-readable-or-not-authorised p f e a w)

Compose content to emit if the user is not authorised to write, or not authorised to read, property p in form, list or page f of entity e within application a, while generating a widget with id w.

+

compose-widget-para

(compose-widget-para p f e a w content)

Compose a widget paragraph for property p in form, list or page f of entity e within application a, with id w and this content.

+

csrf-widget

(csrf-widget)

For the present, just return the standard cross site scripting protection field statement

+

delete-widget

(delete-widget form entity application)

Return an appropriate ‘save’ widget for this form operating on this entity taken from this application.

+

embed-script-fragment

(embed-script-fragment resource-path substitutions)(embed-script-fragment resource-path)

Return the content of the file at resource-path, with these substitutions made into it in order. Substitutions should be pairs pattern value, where pattern is a string, a char, or a regular expression.

+

emit-content

(emit-content content)(emit-content filename application k)(emit-content filename spec entity application k)

*TODO: write docs

+

emit-entity-dd

(emit-entity-dd entity application)

*TODO: write docs

+

emit-entity-dt

(emit-entity-dt entity application)

*TODO: write docs

+

entity-to-templates

(entity-to-templates entity application)

Generate one or more templates for editing instances of this entity in this application

+

file-header

(file-header filename application)(file-header filename spec entity application)

Generate a header for a template file with this filename for this spec of this entity within this application.

+

form-to-template

(form-to-template form entity application)

Generate a template as specified by this form element for this entity, taken from this application. If form is nill, generate a default form template for the entity.

+

get-options

(get-options property form entity application)

Produce template code to get options for this property of this entity taken from this application.

+

get-size-for-widget

(get-size-for-widget property)

Return, as an integer, the fieldwidth for the input widget for this property.

+

list-tbody

(list-tbody source list-spec entity application)

Return a table body element for the list view for this list-spec of this entity within this application, using data from this source.

+

list-to-template

(list-to-template list-spec entity application)

Generate a template as specified by this list element for this entity, taken from this application. If list is nill, generate a default list template for the entity.

+

page-to-template

(page-to-template page entity application)

Generate a template as specified by this page element for this entity, taken from this application. If page is nil, generate a default page template for the entity.

+

TODO: not yet written.

+

save-widget

(save-widget form entity application)

Return an appropriate ‘save’ widget for this form operating on this entity taken from this application. TODO: should be suppressed unless a member of a group which can insert or edit.

+

select-field-name

(select-field-name entity)

*TODO: write docs

+

select-property

(select-property entity)

Return the property on which we will by default do a user search on this entity.

+

select-widget

(select-widget property form entity application)

Generate an HTML SELECT widget for this property of this entity within this application, to be used in this form. TODO: Many selectable things are potentially too numerous to be simply represented in a simple static SELECT, it needs some asynchronous fetching. See issue 47.

+

to-selmer-templates

(to-selmer-templates application)

Generate all Selmer templates implied by this ADL application spec.

+

widget

(widget field-or-property form entity application)

Generate a widget for this field-or-property of this form for this entity taken from within this application, in context of a para also containing its label.

+

widget-type

(widget-type property application)(widget-type property application typedef)

Return an appropriate HTML5 input type for this property.

+

wrap-in-if-member-of

(wrap-in-if-member-of content privilege & context)

Wrap this content in an if-member-of tag; if writeable? is true, allow those groups by whom it is writeable, else those by whom it is readable. context should be a sequence of adl elements from which permissions may be obtained.

+

write-template-file

(write-template-file filename template application)

Write a template file with this filename from this template in the context of this application.

+
\ No newline at end of file diff --git a/docs/adl.to-swagger.html b/docs/adl.to-swagger.html index 56c56e1..9df3d9b 100644 --- a/docs/adl.to-swagger.html +++ b/docs/adl.to-swagger.html @@ -1,5 +1,5 @@ -adl.to-swagger documentation

Project

Namespaces

Public Vars

adl.to-swagger

Application Description Language: generate swagger routes.
-

file-header

(file-header application)
TODO: Nothing here works yet.
-
\ No newline at end of file +adl.to-swagger documentation

Project

Namespaces

Public Vars

adl.to-swagger

Application Description Language: generate swagger routes.

+

file-header

(file-header application)

TODO: Nothing here works yet.

+
\ No newline at end of file diff --git a/docs/adl.validator.html b/docs/adl.validator.html index ff05cf9..e75000f 100644 --- a/docs/adl.validator.html +++ b/docs/adl.validator.html @@ -1,221 +1,162 @@ -adl.validator documentation

Project

Namespaces

Public Vars

adl.validator

Application Description Language: validator for ADL structure.
-TODO: this is at present largely a failed experiment.

all-data-types

FIXME: write docs

application-validations

FIXME: write docs

auxlist-validations

a subsidiary list, on which entities related to primary
-entities in the enclosing page or list are listed
-
-* `property`:   the property of the enclosing entity that this
-            list displays (obviously, must be of type='list')
-* `onselect`:   the form or page of the listed entity to call
-            when an item from the list is selected
-* `canadd`:     true if the user should be able to add records
-            to this list

cascade-actions

actions which should be cascaded to dependent objects. All these values except
-'manual' are taken from Hibernate and should be passed through the adl2hibernate
-mapping transparently. Relevent only for properties with type='entity', type='link'
-and type='list'
-
-* `all`:       cascade delete, save and update
-* `all-delete-orphan`: see hibernate documentation; relates to transient objects only
-* `delete`:    cascade delete actions, but not save and update
-* `manual`:    cascading will be handled in manually managed code, code to
-            handle cascading should not be generated
-* `save-update`: cascade save and update actions, but not delete.

complex-data-types

data types which are more complex than SimpleDataTypes...
-* `entity` : 		a foreign key link to another entity (i.e. the 'many' end of a
-				    one-to-many link);
-* `list` :			a list of some other entity that links to me (i.e. the 'one' end of
-				    a one-to-many link);
-* `link` : 			a many to many link (via a link table);
-* `defined` : 	a type defined by a typedef.

content

content, for things like pages (i.e. forms, lists, pages)
-

content-validations

FIXME: write docs

defineable-data-types

data types which can be used in a typedef to provide validation -
-e.g. a string can be used with a regexp or a scalar can be used with
-min and max values
-* `string`: 		varchar		java.sql.Types.VARCHAR
-* `integer`:		int			java.sql.Types.INTEGER
-* `real`:			double		java.sql.Types.DOUBLE
-* `money`:			money		java.sql.Types.INTEGER
-* `date`:			date		java.sql.Types.DATE
-* `time`:			time		java.sql.Types.TIME
-* `timestamp`:		timestamp	java.sql.Types.TIMESTAMP
-* `uploadable`:		varchar		java.sql.Types.VARCHAR
-* `image`:			varchar		java.sql.Types.VARCHAR
-
-uploadable is as string but points to an uploaded file; image is as
-uploadable but points to an uploadable graphical image file.

disjunct-valid?

macro

(disjunct-valid? o & validations)
Yes, this is a horrible hack. I should be returning the error structure
-not printing it. But I can't see how to make that work with `bouncer`.
-OK, so: most of the validators will (usually) fail, and that's OK. How
-do we identify the one which ought not to have failed?

documentation-validations

contains documentation on the element which immediately contains it. TODO:
-should HTML markup within a documentation element be allowed? If so, are
-there restrictions?

entity-validations

an entity which has properties and relationships; maps onto a database
-table or a Java serialisable class - or, of course, various other things
-
- * `name`:         obviously, the name of this entity
- * `natural-key`:  if present, the name of a property of this entity which forms
-               a natural primary key [NOTE: Only partly implemented. NOTE: much of
-               the present implementation assumes all primary keys will be
-               integers. This needs to be fixed!] DEPRECATED: remove; replace with the
-               'key' element, below.
- * `table`:        the name of the table in which this entity is stored. Defaults to same
-               as name of entity. Strongly recommend this is not used unless it needs
-               to be different from the name of the entity
- * `foreign`:      this entity is part of some other system; no code will be generated
-               for it, although code which links to it will be generated

field-stuff

FIXME: write docs

field-validations

a field in a form or page
-
-* `property`:   the property which this field displays/edits.

fieldgroup-validations

a group of fields and other controls within a form or list, which the
-renderer might render as a single pane in a tabbed display, for example.

foot-validations

content to place in the bottom of the body of the generated document;
-this is any HTML block or inline level element.

form-validations

a form through which an entity may be added or edited
-

generator-actions

FIXME: write docs

generator-validations

marks a property which is auto-generated by some part of the system.
-This is based on the Hibernate construct, except that the Hibernate
-implementation folds both its internal generators and custom generators
-onto the same attribute. This separates them onto two attributes so we
-can police values for Hibernate's 'builtin' generators.
-
-* `action`:       one of the supported Hibernate builtin generators, or
-              'manual'. 'native' is strongly recommended in most instances
-* `class`:        if action is 'manual', the name of a manually maintained
-              class conforming to the Hibernate IdentifierGenerator
-              interface, or its equivalent in other languages.

group-validations

a group of people with similar permissions to one another
-
-* `name`: the name of this group
-* `parent`: the name of a group of which this group is subset

head-validations

content to place in the head of the generated document; normally HTML.
-

help-validations

helptext about a property of an entity, or a field of a page, form or
-list, or a typedef. Typically there will be only one of these per property
- per locale; if there are more than one all those matching the locale may
- be concatenated, or just one may be used.
-
-* `locale`:			the locale in which to prefer this prompt

ifmissing-validations

helpful text to be shown if a property value is missing, typically when
- a form is submitted. Typically there will be only one of these per property
- per locale; if there are more than one all those matching the locale may
- be concatenated, or just one may be used. Later there may be more sophisticated
- behaviour here.
-
-* `locale`:			the locale in which to prefer this prompt

in-implementation-validations

information about how to translate a type into types known to different target
-languages. TODO: Once again I'm not wholly comfortable with the name; I'm not
-really comfortable that this belongs in ADL at all.
-
-* `target`:     the target language
-* `value`:      the type to use in that target language
-* `kind`:       OK, I confess I don't understand this, but Andrew needs it...

key-validations

FIXME: write docs

list-validations

a list on which entities of a given type are listed
-
-* `onselect`:		name of form/page/list to go to when
-				    a selection is made from the list

option-validations

one of an explicit list of optional values a property may have
-NOTE: whether options get encoded at application layer or at database layer
-is UNDEFINED; either behaviour is correct. If at database layer it's also
-UNDEFINED whether they're encoded as a single reference data table or as
-separate reference data tables for each property.
-
-* `value`:	the value of this option.

order-validations

an ordering or records in a list
-* `property`:	the property on which to order
-* `sequence`:	the sequence in which to order

page-content

FIXME: write docs

page-stuff

FIXME: write docs

page-validations

a page on which an entity may be displayed
-

param-validations

A parameter passed to the generator. Again, based on the Hibernate
-implementation.
-
-* `name`:   the name of this parameter.

permission-validations

permissions policy on an entity, a page, form, list or field
-
-* `group`: 			the group to which permission is granted
-* `permission`:		the permission which is granted to that group

permissions

permissions a group may have on an entity, list, page, form or field
-permissions are deemed to increase as you go right. A group cannot
-have greater permission on a field than on the form it is in, or
-greater permission on form than the entity it belongs to
-
-* `none`:			none
-* `read`:			select
-* `insert`:			insert
-* `noedit`:			select, insert
-* `edit`:			select, insert, update
-* `all`:			select, insert, update, delete

pragma-validations

pragmatic advice to generators of lists and forms, in the form of
-name/value pairs which may contain anything. Over time some pragmas
-will become 'well known', but the whole point of having a pragma
-architecture is that it is extensible.

prompt-validations

a prompt for a property or field; used as the prompt text for a widget
-which edits it. Typically there will be only one of these per property
- per locale; if there are more than one all those matching the locale may
- be concatenated, or just one may be used.
-
-* `prompt`:			the prompt to use
-* `locale`:			the locale in which to prefer this prompt.

property-validations

a property (field) of an entity (table)
-
-* `name`:			  the name of this property.
-* `type`:			  the type of this property.
-* `default`:		the default value of this property. There will probably be
-				    magic values of this!
-* `typedef`:	  name of the typedef to use, it type = 'defined'.
-* `distinct`:		distinct='system' required that every value in the system
-				    will be distinct (i.e. natural primary key);
-				    distinct='user' implies that the value may be used by users
-				    in distinguishing entities even if values are not formally
-				    unique;
-				    distinct='all' implies that the values are formally unique
-				    /and/ are user friendly (NOTE: not implemented).
-* `entity`:	if type='entity', the name of the entity this property is
-				    a foreign key link to.
-             if type='list', the name of the entity that has a foreign
-             key link to this entity
-* `farkey`:   if type='list', the name of farside key in the listed
-             entity; if type='entity' and the farside field to join to
-             is not the farside primary key, then the name of that
-             farside field
-* `required`:		whether this propery is required (i.e. 'not null').
-* `immutable`:		if true, once a value has been set it cannot be changed.
-* `size`: 			fieldwidth of the property if specified.
-* `concrete`: if set to 'false', this property is not stored in the
-             database but must be computed (manually written code must
-             be provided to support this)
-* `cascade`:  what action(s) on the parent entity should be cascaded to
-             entitie(s) linked on this property. Valid only if type='entity',
-             type='link' or type='list'.
-* `column`:   name of the column in a SQL database table in which this property
-             is stored. TODO: Think about this.
-* `unsaved-value`:
-             of a property whose persistent value is set on first being
-             committed to persistent store, the value which it holds before
-             it has been committed

reference-validations

The 'specification' and 'reference' elements are for documentation only,
-and do not contribute to the engineering of the application described.
-
-A reference element is a reference to a specifying document.
-
-* `abbr`:		The abbreviated name of the specification to which this
-			reference refers
-* `section`:	The 'anchor part' (part following a hash character) which,
-			when appended to the URL, will locate the exact section
-			referenced.
-* `entity`:		A reference to another entity within this ADL document
-* `property`:	A reference to another property within this ADL document;
-			if entity is also specified then of that entity, else of
-			the ancestor entity if any

sequences

FIXME: write docs

simple-data-types

data types which are fairly straightforward translations of JDBC data types
-* `boolean`:		boolean 	java.sql.Types.BIT or char(1)		  java.sql.Types.CHAR
-* `text`:			  text or		  java.sql.Types.LONGVARCHAR
-memo		    java.sql.Types.CLOB

special-data-types

data types which require special handling - which don't simply map onto
-common SQL data types
-* `geopos` :    a latitude/longitude pair (experimental and not yet implemented)
-* `image` :     a raster image file, in jpeg, gif, or png format (experimental, not yet implemented)
-* `message` :   an internationalised message, having different translations for different locales

specification-validations

The 'specification' and 'reference' elements are for documentation only,
-and do not contribute to the engineering of the application described.
-
-A specification element is intended chiefly to declare the reference
-documents which may be used in documentation elements later in the
-document.
-
-* `url`:		The URL from which the document referenced can be retrieved
-* `name`:		The full name (title) given to this document
-* `abbr`:		A convenient abbreviated name.

top-validations

content to place in the top of the body of the generated document;
-this is any HTML block or inline level element.

try-validate

(try-validate o validation)
Pass this `validation` and the object `o` to bouncer
-

typedef-validations

the definition of a defined type. At this stage a defined type is either
-* a string		in which case it must have size and pattern, or
-* a scalar		in which case it must have minimum and/or maximum
-pattern must be a regular expression as interpreted by org.apache.regexp.RE
-minimum and maximum must be of appropriate format for the datatype specified.
-Validation may be done client-side and/or server-side at application layer
-and/or server side at database layer.
-
- * `name`:     the name of this typedef
- * `type`:     the simple type on which this defined type is based; must be
-           present unless in-implementation children are supplied
- * `size`:     the data size of this defined type
- * `pattern`:  a regular expression which values for this type must match
- * `minimum`:  the minimum value for this type (if base type is scalar)
- * `maximum`:  the maximum value for this type (if base type is scalar)

valid-adl?

(valid-adl? src)
Return `true` if `src` is syntactically valid ADL.
-

validate-adl

(validate-adl src)
FIXME: write docs

validate-adl-file

(validate-adl-file filepath)
FIXME: write docs

verb-validations

a verb is something that may be done through a form. Probably the verbs 'store'
-and 'delete' are implied, but maybe they need to be explicitly declared. The 'verb'
-attribute of the verb is what gets returned to the controller
-
-* `verb`  what gets returned to the controller when this verb is selected
-* `dangerous`  true if this verb causes a destructive change.
\ No newline at end of file +adl.validator documentation

Project

Namespaces

Public Vars

adl.validator

Application Description Language: validator for ADL structure. TODO: this is at present largely a failed experiment.

+

all-data-types

*TODO: write docs

+

application-validations

*TODO: write docs

+

auxlist-validations

a subsidiary list, on which entities related to primary entities in the enclosing page or list are listed

+
    +
  • property: the property of the enclosing entity that this list displays (obviously, must be of type=‘list’)
    • +
  • onselect: the form or page of the listed entity to call when an item from the list is selected
    • +
  • canadd: true if the user should be able to add records to this list
    • +
+

cascade-actions

actions which should be cascaded to dependent objects. All these values except ‘manual’ are taken from Hibernate and should be passed through the adl2hibernate mapping transparently. Relevent only for properties with type=‘entity’, type=‘link’ and type=‘list’

+
    +
  • all: cascade delete, save and update
    • +
  • all-delete-orphan: see hibernate documentation; relates to transient objects only
    • +
  • delete: cascade delete actions, but not save and update
    • +
  • manual: cascading will be handled in manually managed code, code to handle cascading should not be generated
    • +
  • save-update: cascade save and update actions, but not delete.
    • +
+

complex-data-types

data types which are more complex than SimpleDataTypes… * entity : a foreign key link to another entity (i.e. the ‘many’ end of a one-to-many link); * list : a list of some other entity that links to me (i.e. the ‘one’ end of a one-to-many link); * link : a many to many link (via a link table); * defined : a type defined by a typedef.

+

content

content, for things like pages (i.e. forms, lists, pages)

+

content-validations

*TODO: write docs

+

defineable-data-types

data types which can be used in a typedef to provide validation - e.g. a string can be used with a regexp or a scalar can be used with min and max values * string: varchar java.sql.Types.VARCHAR * integer: int java.sql.Types.INTEGER * real: double java.sql.Types.DOUBLE * money: money java.sql.Types.INTEGER * date: date java.sql.Types.DATE * time: time java.sql.Types.TIME * timestamp: timestamp java.sql.Types.TIMESTAMP * uploadable: varchar java.sql.Types.VARCHAR * image: varchar java.sql.Types.VARCHAR

+

uploadable is as string but points to an uploaded file; image is as uploadable but points to an uploadable graphical image file.

+

disjunct-valid?

(disjunct-valid? o & validations)

Yes, this is a horrible hack. I should be returning the error structure not printing it. But I can’t see how to make that work with bouncer. OK, so: most of the validators will (usually) fail, and that’s OK. How do we identify the one which ought not to have failed?

+

documentation-validations

contains documentation on the element which immediately contains it. For the time being, HTML markup is not permitted within documentation, but Markdown (which may include a string representation of HTML markup) should be.

+

entity-validations

an entity which has properties and relationships; maps onto a database table or a Java serialisable class - or, of course, various other things

+ +

field-stuff

*TODO: write docs

+

field-validations

a field in a form or page

+
    +
  • property: the property which this field displays/edits.
    • +
+

fieldgroup-validations

a group of fields and other controls within a form or list, which the renderer might render as a single pane in a tabbed display, for example.

+

foot-validations

content to place in the bottom of the body of the generated document; this is any HTML block or inline level element.

+

form-validations

a form through which an entity may be added or edited

+

generator-actions

*TODO: write docs

+

generator-validations

marks a property which is auto-generated by some part of the system. This is based on the Hibernate construct, except that the Hibernate implementation folds both its internal generators and custom generators onto the same attribute. This separates them onto two attributes so we can police values for Hibernate’s ‘builtin’ generators.

+
    +
  • action: one of the supported Hibernate builtin generators, or ‘manual’. ‘native’ is strongly recommended in most instances
    • +
  • class: if action is ‘manual’, the name of a manually maintained class conforming to the Hibernate IdentifierGenerator interface, or its equivalent in other languages.
    • +
+

group-validations

a group of people with similar permissions to one another

+
    +
  • name: the name of this group
    • +
  • parent: the name of a group of which this group is subset
    • +
+

head-validations

content to place in the head of the generated document; normally HTML.

+

help-validations

helptext about a property of an entity, or a field of a page, form or list, or a typedef. Typically there will be only one of these per property per locale; if there are more than one all those matching the locale may be concatenated, or just one may be used.

+
    +
  • locale: the locale in which to prefer this prompt
    • +
+

ifmissing-validations

helpful text to be shown if a property value is missing, typically when a form is submitted. Typically there will be only one of these per property per locale; if there are more than one all those matching the locale may be concatenated, or just one may be used. Later there may be more sophisticated behaviour here.

+
    +
  • locale: the locale in which to prefer this prompt
    • +
+

in-implementation-validations

information about how to translate a type into types known to different target languages. TODO: Once again I’m not wholly comfortable with the name; I’m not really comfortable that this belongs in ADL at all.

+
    +
  • target: the target language
    • +
  • value: the type to use in that target language
    • +
  • kind: OK, I confess I don’t understand this, but Andrew needs it…
    • +
+

key-validations

*TODO: write docs

+

list-validations

a list on which entities of a given type are listed

+
    +
  • onselect: name of form/page/list to go to when a selection is made from the list
    • +
+

option-validations

one of an explicit list of optional values a property may have NOTE: whether options get encoded at application layer or at database layer is UNDEFINED; either behaviour is correct. If at database layer it’s also UNDEFINED whether they’re encoded as a single reference data table or as separate reference data tables for each property.

+
    +
  • value: the value of this option.
    • +
+

order-validations

an ordering or records in a list * property: the property on which to order * sequence: the sequence in which to order

+

page-content

*TODO: write docs

+

page-stuff

*TODO: write docs

+

page-validations

a page on which an entity may be displayed

+

param-validations

A parameter passed to the generator. Again, based on the Hibernate implementation.

+
    +
  • name: the name of this parameter.
    • +
+

permission-validations

permissions policy on an entity, a page, form, list or field

+
    +
  • group: the group to which permission is granted
    • +
  • permission: the permission which is granted to that group
    • +
+

permissions

permissions a group may have on an entity, list, page, form or field permissions are deemed to increase as you go right. A group cannot have greater permission on a field than on the form it is in, or greater permission on form than the entity it belongs to

+
    +
  • none: none
    • +
  • read: select
    • +
  • insert: insert
    • +
  • noedit: select, insert
    • +
  • edit: select, insert, update
    • +
  • all: select, insert, update, delete
    • +
+

pragma-validations

pragmatic advice to generators of lists and forms, in the form of name/value pairs which may contain anything. Over time some pragmas will become ‘well known’, but the whole point of having a pragma architecture is that it is extensible.

+

prompt-validations

a prompt for a property or field; used as the prompt text for a widget which edits it. Typically there will be only one of these per property per locale; if there are more than one all those matching the locale may be concatenated, or just one may be used.

+
    +
  • prompt: the prompt to use
    • +
  • locale: the locale in which to prefer this prompt.
    • +
+

property-validations

a property (field) of an entity (table)

+
    +
  • name: the name of this property.
    • +
  • type: the type of this property.
    • +
  • default: the default value of this property. There will probably be magic values of this!
    • +
  • typedef: name of the typedef to use, it type = ‘defined’.
    • +
  • distinct: distinct=‘system’ required that every value in the system will be distinct (i.e. natural primary key); distinct=‘user’ implies that the value may be used by users in distinguishing entities even if values are not formally unique; distinct=‘all’ implies that the values are formally unique /and/ are user friendly (NOTE: not implemented).
    • +
  • entity: if type=‘entity’, the name of the entity this property is a foreign key link to. if type=‘list’, the name of the entity that has a foreign key link to this entity
    • +
  • farkey: if type=‘list’, the name of farside key in the listed entity; if type=‘entity’ and the farside field to join to is not the farside primary key, then the name of that farside field
    • +
  • required: whether this propery is required (i.e. ‘not null’).
    • +
  • immutable: if true, once a value has been set it cannot be changed.
    • +
  • size: fieldwidth of the property if specified.
    • +
  • concrete: if set to ‘false’, this property is not stored in the database but must be computed (manually written code must be provided to support this)
    • +
  • cascade: what action(s) on the parent entity should be cascaded to entitie(s) linked on this property. Valid only if type=‘entity’, type=‘link’ or type=‘list’.
    • +
  • column: name of the column in a SQL database table in which this property is stored. TODO: Think about this.
    • +
  • unsaved-value: of a property whose persistent value is set on first being committed to persistent store, the value which it holds before it has been committed
    • +
+

reference-validations

The ‘specification’ and ‘reference’ elements are for documentation only, and do not contribute to the engineering of the application described.

+

A reference element is a reference to a specifying document.

+
    +
  • abbr: The abbreviated name of the specification to which this reference refers
    • +
  • section: The ‘anchor part’ (part following a hash character) which, when appended to the URL, will locate the exact section referenced.
    • +
  • entity: A reference to another entity within this ADL document
    • +
  • property: A reference to another property within this ADL document; if entity is also specified then of that entity, else of the ancestor entity if any
    • +
+

sample-option

*TODO: write docs

+

sequences

*TODO: write docs

+

simple-data-types

data types which are fairly straightforward translations of JDBC data types * boolean: boolean java.sql.Types.BIT or char(1) java.sql.Types.CHAR * text: text or java.sql.Types.LONGVARCHAR memo java.sql.Types.CLOB

+

special-data-types

data types which require special handling - which don’t simply map onto common SQL data types * geopos : a latitude/longitude pair (experimental and not yet implemented) * image : a raster image file, in jpeg, gif, or png format (experimental, not yet implemented) * message : an internationalised message, having different translations for different locales

+

specification-validations

The ‘specification’ and ‘reference’ elements are for documentation only, and do not contribute to the engineering of the application described.

+

A specification element is intended chiefly to declare the reference documents which may be used in documentation elements later in the document.

+
    +
  • url: The URL from which the document referenced can be retrieved
    • +
  • name: The full name (title) given to this document
    • +
  • abbr: A convenient abbreviated name.
    • +
+

top-validations

content to place in the top of the body of the generated document; this is any HTML block or inline level element.

+

try-validate

(try-validate o validation)

Pass this validation and the object o to bouncer

+

typedef-validations

the definition of a defined type. At this stage a defined type is either * a string in which case it must have size and pattern, or * a scalar in which case it must have minimum and/or maximum pattern must be a regular expression as interpreted by org.apache.regexp.RE minimum and maximum must be of appropriate format for the datatype specified. Validation may be done client-side and/or server-side at application layer and/or server side at database layer.

+
    +
  • name: the name of this typedef
    • +
  • type: the simple type on which this defined type is based; must be present unless in-implementation children are supplied
    • +
  • size: the data size of this defined type
    • +
  • pattern: a regular expression which values for this type must match
    • +
  • minimum: the minimum value for this type (if base type is scalar)
    • +
  • maximum: the maximum value for this type (if base type is scalar)
    • +
+

valid-adl?

(valid-adl? src)

Return true if src is syntactically valid ADL.

+

validate-adl

(validate-adl src)

*TODO: write docs

+

validate-adl-file

(validate-adl-file filepath)

*TODO: write docs

+

verb-validations

a verb is something that may be done through a form. Probably the verbs ‘store’ and ‘delete’ are implied, but maybe they need to be explicitly declared. The ‘verb’ attribute of the verb is what gets returned to the controller

+
    +
  • verb what gets returned to the controller when this verb is selected
    • +
  • dangerous true if this verb causes a destructive change.
    • +
+
\ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 000ecec..276f9eb 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,6 +1,14 @@ -Adl 1.4.6

Project

Namespaces

Adl 1.4.6

Released under the GNU Lesser General Public License, version 3.0 or (at your option) any later version

An application to transform an ADL application specification - document into skeleton code for a Clojure web-app.

Installation

To install, add the following dependency to your project or build file:

[adl "1.4.6"]

Namespaces

adl.main

Application Description Language - command line invocation.

Public variables and functions:

adl.to-cache

Application Description Language: generate caching layer for database requests.

Public variables and functions:

adl.to-hugsql-queries

Application Description Language - generate HUGSQL queries file.

Public variables and functions:

adl.to-json-routes

Application Description Language: generate RING routes for REST requests.

Public variables and functions:

adl.to-psql

Application Description Language: generate Postgres database definition.

Public variables and functions:

adl.to-reframe

Application Description Language: generate re-frame UI. TODO: doesn't even nearly work yet.

Public variables and functions:

adl.to-selmer-routes

Application Description Language: generate routes for user interface requests.

Public variables and functions:

adl.to-selmer-templates

Application Description Language - generate Selmer templates for
-the HTML pages implied by an ADL file.

Public variables and functions:

adl.to-swagger

Application Description Language: generate swagger routes.

Public variables and functions:

adl.validator

Application Description Language: validator for ADL structure.
-TODO: this is at present largely a failed experiment.

Public variables and functions:

\ No newline at end of file +Adl 1.4.7-SNAPSHOT

Project

Namespaces

Adl 1.4.7-SNAPSHOT

Released under the GNU Lesser General Public License, version 3.0 or (at your option) any later version

An application to transform an ADL application specification + document into skeleton code for a Clojure web-app.

Installation

To install, add the following dependency to your project or build file:

[adl "1.4.7-SNAPSHOT"]

Namespaces

adl.main

Application Description Language - command line invocation.

+

Public variables and functions:

adl.to-cache

Application Description Language: generate caching layer for database requests.

+

Public variables and functions:

adl.to-hugsql-queries

Application Description Language - generate HUGSQL queries file.

+

Public variables and functions:

adl.to-json-routes

Application Description Language: generate RING routes for REST requests.

+

Public variables and functions:

adl.to-psql

Application Description Language: generate Postgres database definition.

+

Public variables and functions:

adl.to-reframe

Application Description Language: generate re-frame UI. TODO: doesn’t even nearly work yet.

+

Public variables and functions:

adl.to-selmer-routes

Application Description Language: generate routes for user interface requests.

+

Public variables and functions:

adl.to-selmer-templates

Application Description Language - generate Selmer templates for the HTML pages implied by an ADL file.

+

Public variables and functions:

adl.to-swagger

Application Description Language: generate swagger routes.

+

Public variables and functions:

adl.validator

Application Description Language: validator for ADL structure. TODO: this is at present largely a failed experiment.

+

Public variables and functions:

\ No newline at end of file diff --git a/project.clj b/project.clj index f07537d..63bc4fa 100644 --- a/project.clj +++ b/project.clj @@ -18,9 +18,9 @@ :main adl.main - :plugins [[lein-codox "0.10.3"] - [lein-kibit "0.1.6"] - [lein-release "1.0.5"]] + :plugins [[lein-codox "0.10.8"] + [lein-kibit "0.1.11"] + [lein-release "1.1.3"]] :codox {:metadata {:doc "**TODO*: write docs" :doc/format :markdown} diff --git a/resources/schemas/adl-1.4.7.dtd b/resources/schemas/adl-1.4.7.dtd new file mode 100644 index 0000000..9ec3fa9 --- /dev/null +++ b/resources/schemas/adl-1.4.7.dtd @@ -0,0 +1,628 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/resources/schemas/adl-1.4.7.xsd b/resources/schemas/adl-1.4.7.xsd new file mode 100644 index 0000000..225477a --- /dev/null +++ b/resources/schemas/adl-1.4.7.xsd @@ -0,0 +1,559 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/adl/to_selmer_templates.clj b/src/adl/to_selmer_templates.clj index e4ceb04..f33cac2 100644 --- a/src/adl/to_selmer_templates.clj +++ b/src/adl/to_selmer_templates.clj @@ -2,17 +2,21 @@ the HTML pages implied by an ADL file." :author "Simon Brooke"} adl.to-selmer-templates - (:require [adl-support.core :refer :all] - [adl-support.forms-support :refer :all] - [adl.to-hugsql-queries :refer [expanded-token]] - [adl-support.utils :refer :all] - [clojure.java.io :refer [file make-parents resource]] - [clojure.pprint :as p] - [clojure.string :as s] - [clojure.xml :as x] - [clj-time.core :as t] - [clj-time.format :as f] - [hiccup.core :as h])) + (:require + [adl-support.core :refer [*warn* do-or-warn]] + [adl-support.forms-support :refer [auxlist-data-name]] + [adl-support.utils :refer [*output-path* *verbosity* all-properties + child-with-tag children children-with-tag + descendant-with-tag descendants-with-tag + editor-name entity-for-property find-permissions + key-names link-table? path-part pretty-name + prompt property-for-field safe-name typedef + user-distinct-properties visible-to writeable-by]] + [adl.to-hugsql-queries :refer [expanded-token]] + [clj-time.core :as t] + [clojure.java.io :refer [make-parents resource]] + [clojure.string :as s] + [clojure.xml :as x])) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;;; @@ -93,7 +97,7 @@ (children-with-tag (child-with-tag application :content) k))))] - (if + (when content (flatten (list @@ -200,7 +204,7 @@ :name "save-button" :class "action-safe" :type "submit" - :value (str "Save!")}}]} + :value "Save!"}}]} :editable entity application)) @@ -231,7 +235,7 @@ :name "delete-button" :class "action-dangerous" :type "submit" - :value (str "Delete!")}}]} + :value "Delete!"}}]} :editable entity application) @@ -327,8 +331,7 @@ SELECT, it needs some asynchronous fetching. See [issue 47](https://github.com/simon-brooke/youyesyet/issues/47)." [property form entity application] - (let [farname (:entity (:attrs property)) - farside (entity-for-property property application) + (let [farside (entity-for-property property application) magnitude (try (read-string (:magnitude (:attrs farside))) (catch Exception _ 7)) @@ -338,7 +341,7 @@ :attrs (merge {:id widget-name :name widget-name} - (if + (when (= (:type (:attrs property)) "link") {:multiple "multiple"})) :content (apply @@ -439,10 +442,10 @@ {:step 1} nil) ;; TODO: should match pattern from typedef - (if + (when (:minimum (:attrs typedef)) {:min (:minimum (:attrs typedef))}) - (if + (when (:maximum (:attrs typedef)) {:max (:maximum (:attrs typedef))}))}))) @@ -465,7 +468,7 @@ nil) typedef (typedef property application) w-type (widget-type property application typedef)] - (if + (when property (case w-type "hidden" @@ -601,7 +604,7 @@ (-> % :attrs :name) (-> auxlist :attrs :property))) farside (entity-for-property property application)] - (if + (when (and property farside) {:tag :div :attrs {:class "auxlist"} @@ -790,7 +793,7 @@ #(= "select" (widget-type (property-for-field % entity) application)))) - (if + (when (child-with-tag form :field #(= @@ -983,7 +986,7 @@ [forms (children-with-tag entity :form) pages (children-with-tag entity :page) lists (children-with-tag entity :list)] - (if + (when (and (= (:tag entity) :entity) ;; it seems to be an ADL entity (not (link-table? entity))) @@ -1092,7 +1095,7 @@ *output-path* "resources/templates/auto/" filename)] - (if + (when template (do-or-warn (do @@ -1113,9 +1116,9 @@ "{% endblock %}")) (keys template))) (file-footer filename application))))) - (if + (when (pos? *verbosity*) - (*warn* "\tGenerated " filepath)) + (*warn* (str "\tGenerated " filepath))) (str filepath)) (str "While generating " filepath))))) diff --git a/src/adl/to_swagger.clj b/src/adl/to_swagger.clj index 521b385..ec57613 100644 --- a/src/adl/to_swagger.clj +++ b/src/adl/to_swagger.clj @@ -61,80 +61,83 @@ '[ring.util.http-response :refer :all] '[clojure.java.io :as io]))) +;; TODO: This isn't working, it's breaking stuff, and I can't even remember +;; why I wanted it. + +;; (declare def-routes) + +;; (defn def-routes +;; "Generate Swagger routes for all queries implied by this ADL `application` spec." +;; ;; THIS ISN'T NEARLY FINISHED! +;; ([application] +;; (list 'defn 'auto-api-routes [] +;; ["/api" +;; {:coercion spec-coercion/coercion +;; :muuntaja formats/instance +;; :swagger {:id ::api} +;; :middleware [;; query-params & form-params +;; parameters/parameters-middleware +;; ;; content-negotiation +;; muuntaja/format-negotiate-middleware +;; ;; encoding response body +;; muuntaja/format-response-middleware +;; ;; exception handling +;; exception/exception-middleware +;; ;; decoding request body +;; muuntaja/format-request-middleware +;; ;; coercing response bodys +;; coercion/coerce-response-middleware +;; ;; coercing request parameters +;; coercion/coerce-request-middleware +;; ;; multipart +;; multipart/multipart-middleware]}] +;; (map #(def-routes application %) +;; (children-with-tag application :entity))) +;; ([application entity] +;; [(str "/" (safe-name entity)) +;; {:get (make-get-route entity) +;; (cons +;; 'defroutes +;; (cons +;; 'auto-rest-routes +;; (map +;; #(let [handler (handlers-map %)] +;; (list +;; (symbol (s/upper-case (name (:method handler)))) +;; (str "/json/auto/" (safe-name (:name handler))) +;; 'request +;; (list +;; 'route/restricted +;; (list (:name handler) 'request)))) +;; (sort +;; (keys handlers-map)))))}]))) -(defn def-routes - "Generate Swagger routes for all queries implied by this ADL `application` spec." - ;; THIS ISN'T NEARLY FINISHED! - ([application] - (list 'defn 'auto-api-routes [] - ["/api" - {:coercion spec-coercion/coercion - :muuntaja formats/instance - :swagger {:id ::api} - :middleware [;; query-params & form-params - parameters/parameters-middleware - ;; content-negotiation - muuntaja/format-negotiate-middleware - ;; encoding response body - muuntaja/format-response-middleware - ;; exception handling - exception/exception-middleware - ;; decoding request body - muuntaja/format-request-middleware - ;; coercing response bodys - coercion/coerce-response-middleware - ;; coercing request parameters - coercion/coerce-request-middleware - ;; multipart - multipart/multipart-middleware]}] - (map #(def-routes application %) - (children-with-tag application :entity))) - ([application entity] - [(str "/" (safe-name entity)) - {:get (make-get-route entity) - (cons - 'defroutes - (cons - 'auto-rest-routes - (map - #(let [handler (handlers-map %)] - (list - (symbol (s/upper-case (name (:method handler)))) - (str "/json/auto/" (safe-name (:name handler))) - 'request - (list - 'route/restricted - (list (:name handler) 'request)))) - (sort - (keys handlers-map)))))}]))) - - -(defn to-swagger - "Generate a Swagger API for all queries implied by this ADL `application` spec." - [application] - (let [filepath (str - *output-path* - "src/" - (safe-name (:name (:attrs application))) - "/routes/auto_api.clj")] - (make-parents filepath) - (do-or-warn - (do - (spit - filepath - (s/join - "\n\n" - (cons - (file-header application) - (map - (fn [q] - (str - ;; THIS ISN'T NEARLY FINISHED! - )) - (sort - #(compare (:name %1) (:name %2)) - (vals - (queries application))))))) - (if (pos? *verbosity*) - (*warn* (str "\tGenerated " filepath))))))) +;; (defn to-swagger +;; "Generate a Swagger API for all queries implied by this ADL `application` spec." +;; [application] +;; (let [filepath (str +;; *output-path* +;; "src/" +;; (safe-name (:name (:attrs application))) +;; "/routes/auto_api.clj")] +;; (make-parents filepath) +;; (do-or-warn +;; (do +;; (spit +;; filepath +;; (s/join +;; "\n\n" +;; (cons +;; (file-header application) +;; (map +;; (fn [q] +;; (str +;; ;; THIS ISN'T NEARLY FINISHED! +;; )) +;; (sort +;; #(compare (:name %1) (:name %2)) +;; (vals +;; (queries application))))))) +;; (if (pos? *verbosity*) +;; (*warn* (str "\tGenerated " filepath)))))))