> For the complete documentation index, see [llms.txt](https://ampersandtarski.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ampersandtarski.gitbook.io/documentation/the-language-ampersand/services/crud.md). # CRUD CRUD annotations are used in services to constrain the functionality of fields and boxes in an `INTERFACE`-statement. This allows you to minimize the functionality for your users, to design for easy learning. Each CRUD annotation comes right after a [term](/documentation/the-language-ampersand/terms.md), so we can always refer to "the term" to which a CRUD annotation belongs. A CRUD annotation constrains the things your user can do with the target atoms and the pairs of its term. The CRUD-annotation specifies Create, Read, Update, and Delete rights for the term it follows. Capital = allowed, Non-capital = not allowed. CRUD is the default, so if you specify nothing, everything is allowed. The following service definition illustrates this. ``` INTERFACE Overview : "_SESSION" cRud BOX [ Students : V[SESSION*Student] cRuD BOX [ "Student" : I[Student] cRud , "Enrolled for" : isEnrolledFor cRUD , "Course" : takes CRUD ] , Course : V[SESSION*Course] cRuD -- used for a box BOX
[ "Course" : I cRud -- used for a field , "Modules" : isPartOf~ -- CRUD is default ] , Modules : V[SESSION*Module] cRud BOX
[ "Modules" : I cRuD , "Course" : isPartOf cRUd , "Students" : isEnrolledFor~ CRUD ] ] ``` The user interface defined by this service is shown as a screenshot below. Notice that the lowercase r in the annotation of the Students box prevents showing the underlying box. The full CRUD functionality in Course yields 'create' functionality (the green plus-button), 'remove pair' functionality (red minus button), and 'delete atom' functionality (the red trash can button). The lowercase c, u, and d in the Modules box prevents displaying that functionality in the user interface. ![Column-oriented layout of a user interface with columns in each row](https://3502282321-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9s__kkYiQvvyW5CKOk%2F-LKg2Ld-ppc_kxXCDZ7J%2F-LKg5cmNAo5GWNz8zkd_%2FCOLS%20layout%20example.png?alt=media\&token=eaa22cc7-3df4-47ea-8632-adcc83127afb) The next sections give some more detailed information on the run time semantics for CRUD annotations as implemented in Ampersand. ## Create | CRUD | for a box | for a field. | | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | C | ![Creating atoms is done by pressing the + button](https://3502282321-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9s__kkYiQvvyW5CKOk%2F-LKl6NawzUcAyJHrZW6m%2F-LKl156H6WxMPzh48OAz%2Fbox-crud-create.png?generation=1535201091249718\&alt=media) A + (plus) button is displayed that lets you create a new atom, but only if the box-expression is editable. | ![Creating atoms is done by pressing the + button](https://3502282321-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9s__kkYiQvvyW5CKOk%2F-LKonnDv1hTFg_RR-RIG%2F-LKgDG2qrt6CPhW3-w_S%2FCreate%20Field.png?generation=1535263067225594\&alt=media) Enter a new atom and a `+` button appears. Click the + to add that atom to the listed set of atoms. If you enter an atom that exists (Peter), you can select it. | | c | Atoms cannot be created | Atoms cannot be created | ## Read | Read | CRUD for boxes | | CRUD for fields | | ---- | ------------------- | - | ------------------- | | R | Read is allowed | | Read is allowed | | r | Read is not allowed | | Read is not allowed | ## Update | Update | CRUD for boxes | CRUD for fields | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | U | ![Deleting a pair is done with the - button](https://3502282321-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9s__kkYiQvvyW5CKOk%2F-LKl7IbbULvbpbnjjrpk%2F-LKl7Jv2YtqFKUNZjvOl%2Fbox-crud-update.png?generation=1535201337102404\&alt=media) Removing and/or adding a pair (src,tgt) is allowed if expr is editable and the atom exists. Deleting a pair is done with the - button; the atom will NOT be deleted. | ![Deleting a pair is done with the - button](https://3502282321-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9s__kkYiQvvyW5CKOk%2F-LKqdySsXyfFBeDXU201%2F-LKl8B6USa3NsWS_lZHm%2Ffield-crud-update.png?generation=1535294044929649\&alt=media) Removing and/or adding a pair (src,tgt) is allowed if expr is editable and the atom exists. Deleting a pair is done with the - button; the atom will NOT be deleted. | | u | Update is not allowed | Update is not allowed | ## Delete | Delete | CRUD for boxes | CRUD for fields | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | D | ![Deleting a pair is done with the - button](https://3502282321-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9s__kkYiQvvyW5CKOk%2F-LKozZba6wBwkkjByPC1%2F-LKoyprb4soklzv0Ik93%2Fbox-crud-delete.png?generation=1535266151062546\&alt=media) Deleting a pair is done with the - (minus) button. Deleting an atom is done with the trash bin. | ![Deleting a pair is done with the - button](https://3502282321-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9s__kkYiQvvyW5CKOk%2F-LKqdySsXyfFBeDXU201%2F-LKqdze8PQ6Xp3rSGSIl%2Ffield-crud-delete.png?generation=1535294048790123\&alt=media) Delete atom (tgt) and all pairs in which it is used. | | d | delete not allowed | delete not allowed | A top-level Update or Create are common in my own scripts, e.g. to create an overview of People and be able to create a new Person: `INTERFACE "People" : V[SESSION*Person] CRud COLS []`. And update is also possible. ## Things to remember 1. The red minus is enabled by `U`. It unlinks an atom (by deleting a pair from a relation) and leaves the atom alone. 2. The red trash bin is enabled by `D`. It removes an atom and all pairs in which that atom is used. ## Background Motivations for CRUD-functionality are found in the [GitHub discussions on CRUD](https://github.com/AmpersandTarski/Ampersand/issues?utf8=✓\&q=is%3Aissue+label%3Acrud+) functionality.