hot-line/src/models/app-constants.lisp

(defpackage #:app-constants
  (:use #:cl)
  (:export #:+false+
	   #:+true+

	   ;; OTHER-ITEMS LIST SIZES
	   #:+default-other-items-size+
	   #:+single-other-items-size+
	   #:+small-other-items-size+
	   #:+large-other-items-size+
	   #:+extra-large-other-items-size+
	   
	   ;; PAGINATION SIZES
	   #:+default-page-size+
	   #:+extra-small-page-size+
	   #:+small-page-size+
	   #:+single-page-size+
	   #:+extra-large-page-size+
	   #:+large-page-size+

	   ;; DIRECTORIES
	   #:+media-directory+
	   #:+uploads-directory+

	   ;; GENERAL/GENERIC MESSAGES
	   #:+generic-fail+
	   #:+generic-success+
	   #:+nil-or-empty-string-used+
	   #:+undetermined-file-type+
	   
	   ;; SESSION MANAGEMENT
	   #:+incorrect-login-details+
	   #:+user-not-found+

	   ;; STORAGE SECTION
	   #:+storage-directory-not-found+
	   #:+storage-directory-deleted+
	   #:+storage-file-already-exists+
	   #:+storage-file-deleted+
	   #:+storage-file-not-found+
	   #:+storage-file-successful-upload+
	   #:+storage-file-successfully-updated+

	   ;; USER MANAGEMENT
	   #:+username-already-taken+
	   #:+new-user-added+
	   #:+user-deleted+
	   #:+user-not-authorised+
	   #:+user-role-updated+
	   #:+display-name-updated+
	   #:+password-updated+
	   #:+old-password-incorrect+))
(in-package #:app-constants)

#| Switched to `DEFINE-CONSTANT' from `DEFCONSTANT'.
================================================================================
Because this website uses Steel Bank Common Lisp (SBCL), I need to go through a
cycle of confirming changes to the constant values even though they have not
changed. This behaviour is explained in the SBCL Manual 2.1.3 2021-03 (Section
2.3.4 Defining Constants, page 5 (printed) page 13 (PDF)). The key part of the
section is,

'ANSI says that doing `DEFCONSTANT' of the same symbol more than once is
undefined unless the new value is eql to the old value.'

http://www.sbcl.org/manual/#Defining-Constants (this URL should provide the
latest information of the subject).

A workaround, provided by the SBCL Manual is to use the `DEFINE-CONSTANT' macro
instead of `DEFCONST'. By doing this, I can use Quickload to reload the code
(after a big change for example) and not have to repeat the cycle of 'updating'
the constants when they have not changed.
|#

(defmacro define-constant (name value &optional doc)
  `(defconstant ,name (if (boundp ',name) (symbol-value ',name) ,value)
     ,@(when doc (list doc))))

#| SQLite does not have Boolean value types.
================================================================================
At the time of writing (February 2022), the website uses SQLite as its
database. So, I have made these constants to reduce hard-coded `1'
and/or `0' values when `TRUE' and `NIL'/`FALSE' values are want is
meant (in the code-base).
|#

(define-constant +false+ 0
  "An integer representing 'false' (for SQLite mostly).")

(define-constant +true+ 1
  "An integer representing 'true' (for SQLite mostly.")

;; These refer to the size of the 'Other X' lists displayed in the
;; 'Other X' sections of the content.html templates. Examples of the
;; 'Other' lists are 'Other Software Projects' and 'Other Artworks'.
(define-constant +default-other-items-size+ 10
  "The default number of items to show in the 'other X' section of
  content.html templates.")

(define-constant +single-other-items-size+ 1
  "Display a single item in the 'other X' section of content.html
  templates -- use for testing.")

(define-constant +small-other-items-size+ 5
  "The number of items to show in the 'other X' section of
  content.html templates.")

(define-constant +large-other-items-size+ 20
  "The number of items to show in the 'other X' section of
  content.html templates.")

(define-constant +extra-large-other-items-size+ 30
  "The number of items to show in the 'other X' section of
  content.html templates.")

;; The pagination code has a default value of 200 built-in. That is
;; why the amounts seems odd.
(define-constant +default-page-size+ 100
  "The default value for the amount of items to display on a paginated
  page.")

(define-constant +single-page-size+ 1
  "Display only one item per paginated page -- use for testing.")

(define-constant +extra-small-page-size+ 25
  "The value for a smaller than default amount of items on a paginated
  page.")

(define-constant +small-page-size+ 50
  "The value for a smaller than default amount of items on a paginated
  page.")

(define-constant +large-page-size+ 150
  "The value for a larger than default amount of items on a paginated
  page.")

(define-constant +extra-large-page-size+ 250
  "The value for a larger than default amount of items on a paginated
  page.")

#| Alert Messages (add '| safe' to djula filter in HTML templates)
================================================================================
How the alerts are normally rendered in the HTML templates:

{% if alert %}{{alert | safe}}{% endif %}

The constants below are to be used with the `:ALERT' values when rendering an
HTML template as part of a 'defroute' in 'web.lisp'. The reason for these
string values being stored here instead of in-lining them when the :alert is
formatted is two-fold:

1. These messages can be multiple lines long which can make the code the
defroute a little messy.
2. Reduce repetitive code. The amount of repetitive code is not that high. But,
this will help.

The '| safe' filter (djula) is needed because the HTML tags are removed without
it.  Refer to the djula manual for more information:

https://mmontone.github.io/djula/djula/Filters.html#format
|#

(define-constant +generic-success+
  "<p class=\"ui-message-success\">Task completed. Great success!</p>"
  "Alert message. Intended as a basic or placeholder message.")

(define-constant +media-directory+ "media"
  "The /media directory holds the user's generic file uploads.")

(define-constant +uploads-directory+ "uploads"
  "The directory which holds the user's uploaded .csv and .tsv files.")

(define-constant +generic-fail+
  "<p class=\"ui-message-error\">Task failed.</p>"
  "Alert message. Intended as a basic or placeholder message.")

(define-constant +nil-or-empty-string-used+
  "<p class=\"ui-message-error\">An 'empty-string' was provided by the user (most likely), or the
website's code came across a 'nil' value instead of a string.</p>"
  "Alert message. Intended as an error message for all user-input sections.")

(define-constant +undetermined-file-type+
  "<p class=\"ui-message-error\">Cannot determine if file is a .csv or .tsv file.</p>"
  "Alert message. Intended as an error message for all user-input sections.")

(define-constant +incorrect-login-details+
  "<p class=\"ui-message-error\">Name and password do not match.</p>"
  "Use as an alert message, intented for the login routes.")

(define-constant +user-not-found+
  "<p class=\"ui-message-error\">No account found with those details.</p>"
  "Use as an alert message, intented for the loging routes.")

(define-constant +storage-directory-deleted+
  "<p class=\"ui-message-success\">Directory deleted from /storage.</p>"
  "Use as an alert message, intented for the /storage routes.
This is used for relaying a directory within the /storage directory is
deleted. It does not mean the /storage directory is deleted.")

(define-constant +storage-directory-not-found+
  "<p class=\"ui-message-error\">Directory not found in /storage.</p>"
  "Use as an alert message, intented for the /storage routes.
Used to indicated a directory within /storage is not found and not the
/storage directory itself.")

(define-constant +storage-file-already-exists+
  "<p class=\"ui-message-error\">A file with that name already exists.</p>"
  "Use as an alert message, intended for the /storage routes.")

(define-constant +storage-file-deleted+
  "<p class=\"ui-message-success\">File deleted.</p>"
  "User as an alert message. Intended for the /storage routes.")

(define-constant +storage-file-not-found+
  "<p class=\"ui-message-error\">File(s) could not be found.</p>"
  "Use as an alert message. Intended for the /storage routes.")

(define-constant +storage-file-successful-upload+
  "<p class=\"ui-message-success\">File uploaded. Great success!</p>"
  "Use as an alert message. Intended for the /storage routes.")

(define-constant +storage-file-successfully-updated+
  "<p class=\"ui-message-success\">File updated!</p>"
  "Use as an alert message. Intended for the /storage routes.")

(define-constant +username-already-taken+
  "<p class=\"ui-message-error\">Username already taken.</p>"
  "Use as an alert message, intented for the /user routes.")

(define-constant +new-user-added+
  "<p class=\"ui-message-success\">New user added.</p>"
  "Use as an alert message, intented for the /user routes.")

(define-constant +user-deleted+
  "<p class=\"ui-message-success\">User deleted.</p>"
  "Use as an alert message, intented for the /user routes.")

(define-constant +user-not-authorised+
  "<p class=\"ui-message-error\">User is not authorised to make this change.</p>"
  "Use as an alert message, intented for the /user routes.")

(define-constant +user-role-updated+
  "<p class=\"ui-message-success\">Role updated.</p>"
  "Use as an alert message, intented for the /user routes.")

(define-constant +display-name-updated+
  "<p class=\"ui-message-success\">Display name changed.</p>"
  "Use as an alert message, intented for the /user routes.")

(define-constant +password-updated+
  "<p class=\"ui-message-success\">Password updated.</p>"
  "Use as an alert message, intented for the /user routes.")

(define-constant +old-password-incorrect+
  "<p class=\"ui-message-error\">Old password is incorrect.</p>"
  "Use as an alert message, intented for the /user routes.")