spex-parser 0.1.4 → 0.6.1

package/tests/props/flask_todo_web.spex

@@ -0,0 +1,111 @@
+-- The Flask realization of the Todo Web app.
+--
+-- Imports the shared TodoWeb representation, the todo operations, and the
+-- Flask environment. SQLite storage, the route handlers, and the main
+-- exponential are defined as separate objects, and the concept is realized
+-- as a product of them in the realize statement. Flask handlers receive a
+-- request and return a response.
+
+import TodoWeb from "todo.spex";
+import Todo from "todo.spex";
+import TodoId from "todo.spex";
+import TodoTitle from "todo.spex";
+import AddTodo from "todo.spex";
+import ListTodos from "todo.spex";
+import CompleteTodo from "todo.spex";
+import HttpRequest from "todo.spex";
+import HttpResponse from "todo.spex";
+import FlaskWebEnv from "flask_web_env.spex";
+
+-- TODO: realize the shared HttpRequest and HttpResponse objects using the
+-- types provided by the flask dependency in FlaskWebEnv.
+
+/* SQLite storage. */
+create SqliteConnection as (
+  path: string
+);
+
+create OpenSqlite as
+from (path: string) -> SqliteConnection
+select {
+  1. open the SQLite database at @path
+  2. create the todos table if it does not exist
+};
+
+create SelectTodos as
+from (connection: SqliteConnection) -> Todo[]
+select {
+  1. select the id, title, and completed columns from the todos table
+  2. map each row to a @Todo
+};
+
+create InsertTodo as
+from (connection: SqliteConnection, todo: Todo) -> unit
+select {
+  1. insert the id, title, and completed values of @todo into the todos table
+  2. commit the transaction
+};
+
+create UpdateTodo as
+from (connection: SqliteConnection, todo: Todo) -> unit
+select {
+  1. update the completed value of the row matching the id of @todo
+  2. commit the transaction
+};
+
+/* Route handlers. */
+create ListTodosHandler as
+from (request: HttpRequest) -> HttpResponse
+select {
+  1. open the database with @OpenSqlite
+  2. load the todos with @SelectTodos
+  3. return a 200 response with the todos serialized as JSON
+};
+
+create AddTodoHandler as
+from (request: HttpRequest) -> HttpResponse
+select {
+  1. parse the JSON body of @request into a @TodoTitle
+  2. create the todo with @AddTodo
+  3. open the database with @OpenSqlite
+  4. persist the todo with @InsertTodo
+  5. return a 201 response with the created todo serialized as JSON
+};
+
+create CompleteTodoHandler as
+from (request: HttpRequest) -> HttpResponse
+select {
+  1. extract the todo id from the path of @request
+  2. open the database with @OpenSqlite
+  3. load the todos with @SelectTodos
+  4. find the matching @Todo and complete it with @CompleteTodo
+  5. persist it with @UpdateTodo
+  6. return a 200 response with the updated todo serialized as JSON
+};
+
+/* The main entry exponential. */
+create FlaskTodoWeb as
+from unit -> unit
+select {
+  1. create the Flask application object
+  2. register @ListTodosHandler on the GET /todos route
+  3. register @AddTodoHandler on the POST /todos route
+  4. register @CompleteTodoHandler on the PATCH /todos/:id route
+  5. run the application
+};
+
+realize TodoWeb as (
+  list: ListTodosHandler,
+  add: AddTodoHandler,
+  complete: CompleteTodoHandler,
+  storage: (
+    open: OpenSqlite,
+    query: SelectTodos,
+    insert: InsertTodo,
+    update: UpdateTodo
+  ),
+  main: FlaskTodoWeb
+) in FlaskWebEnv;
+
+generate FlaskTodoWeb;
+package executable flasktodo as FlaskTodoWeb;

package/tests/props/flask_web_env.spex

@@ -0,0 +1,16 @@
+-- The Flask web environment.
+--
+-- A subobject of the shared Web environment intersected with the shared
+-- Python environment.
+
+import Web from "todo.spex";
+import Python from "todo.spex";
+
+create FlaskWebEnv as
+from Web intersect Python
+select {
+  dependencies: flask,
+  database: SQLite
+};
+
+export FlaskWebEnv;

package/tests/props/python_cli_env.spex

@@ -0,0 +1,16 @@
+-- The Python CLI environment.
+--
+-- A subobject of the shared Cli environment intersected with the shared
+-- Python environment.
+
+import Cli from "todo.spex";
+import Python from "todo.spex";
+
+create PythonCliEnv as
+from Cli intersect Python
+select {
+  dependencies: standard library,
+  storage: JSON file
+};
+
+export PythonCliEnv;

package/tests/props/python_todo_cli.spex

@@ -0,0 +1,70 @@
+-- The Python realization of the Todo CLI.
+--
+-- Imports the shared TodoCli representation, the todo operations, and the
+-- Python CLI environment. The argument parsing and JSON file storage are
+-- defined as separate objects, and the concept is realized as a product of
+-- them in the realize statement.
+
+import TodoCli from "todo.spex";
+import Todo from "todo.spex";
+import TodoId from "todo.spex";
+import TodoTitle from "todo.spex";
+import AddTodo from "todo.spex";
+import ListTodos from "todo.spex";
+import CompleteTodo from "todo.spex";
+import PythonCliEnv from "python_cli_env.spex";
+
+/* Argument parsing. */
+create CliCommand as (
+  command: string,
+  arguments: string[]
+);
+
+create ParseArgs as
+from (args: string[]) -> CliCommand
+select {
+  1. create an argparse parser with the add, list, and complete subcommands
+  2. parse @args into a command and its arguments
+  3. return the parsed command
+};
+
+/* JSON file storage. */
+create LoadTodosFile as
+from (path: string) -> Todo[]
+select {
+  1. check whether the file at @path exists
+  2. read the file at @path
+  3. parse the JSON content into todos
+  4. return an empty list if the file does not exist
+  5. throw an exception if the JSON is invalid
+};
+
+create SaveTodosFile as
+from (path: string, todos: Todo[]) -> unit
+select {
+  1. serialize @todos as formatted JSON
+  2. write the JSON to @path
+};
+
+/* The main entry exponential. */
+create PythonTodoCli as
+from (args: string[]) -> unit
+select {
+  1. parse the command with @ParseArgs
+  2. load the todos from the JSON file with @LoadTodosFile
+  3. dispatch the command:
+     - add: call @AddTodo with the given @TodoTitle, then persist with @SaveTodosFile
+     - list: call @ListTodos and print the result to stdout
+     - complete: call @CompleteTodo with the given @TodoId, then persist with @SaveTodosFile
+  4. print user-friendly error messages for exceptions
+};
+
+realize TodoCli as (
+  parse: ParseArgs,
+  load: LoadTodosFile,
+  save: SaveTodosFile,
+  main: PythonTodoCli
+) in PythonCliEnv;
+
+generate PythonTodoCli;
+package executable mytodocli as PythonTodoCli;

package/tests/props/todo.spex

@@ -1,85 +1,125 @@
-create Todo as (
-  id: string,
-  title: string,
-  description: string,
-  completed: bool,
-  createdAt: string
-);
-
-create TodoTitle as from string select {
-  are not empty and are shorter than 120 characters
-};
+-- The shared abstract model of a Todo application written in Spex.
+--
+-- This file defines the domain model, the todo operations, the application
+-- concept, its CLI and Web representations, and the base environments that
+-- are shared between multiple realizations. Concrete environments and
+-- realizations live in separate files and import what they need from here.
 
-create TodoFilePath as from string select {
-  represent a valid path to a JSON file storing todos
+/* The domain model. */
+create TodoId as
+from string
+select {
+  are valid UUIDs
 };
 
-create TodoId as from string select {
-  are valid UUIDs
+create TodoTitle as
+from string
+select {
+  are not empty and are shorter than 120 characters
 };
 
-create CliArgs as (
-  command: string,
-  arguments: string[]
+create Todo as (
+  id: TodoId,
+  title: TodoTitle,
+  completed: bool
 );
 
-create LoadTodos as from (path: TodoFilePath) -> Todo[] select {
-  1. read the JSON file at @path
-  2. return an empty list if the file does not exist
-  3. parse the JSON content into todos
-  4. throw an exception if the JSON is invalid
-};
+create HttpRequest as (
+  method: string,
+  path: string,
+  body: string
+);
 
-create SaveTodos as from (path: TodoFilePath, todos: Todo[]) -> unit select {
-  1. serialize @todos as formatted JSON
-  2. write the JSON to @path
-};
+create HttpResponse as (
+  status: number,
+  body: string
+);
 
-create CreateTodo as from (title: TodoTitle) -> Todo select {
+/* The todo operations, defined once and reused by every realization. */
+create AddTodo as
+from (title: TodoTitle) -> Todo
+select {
   1. generate a UUID for the todo id
   2. create a todo with completed set to false
   3. return the created todo
 };
 
-create AddTodo as from (path: TodoFilePath, title: TodoTitle) -> Todo select {
-  1. call @LoadTodos using @path
-  2. call @CreateTodo using @title
-  3. append the new todo to the loaded todos
-  4. call @SaveTodos to persist the updated todos
-  5. return the created todo
+create ListTodos as
+from unit -> Todo[]
+select {
+  return all the todos
+};
+
+create CompleteTodo as
+from (id: TodoId) -> Todo
+select {
+  1. mark the todo with the given id as completed
+  2. return the updated todo
+};
+
+/* The application, specified as an abstract concept. */
+create TodoApp as
+from concept
+select {
+  provide adding, listing, and completing todos by composing @AddTodo, @ListTodos, and @CompleteTodo
 };
 
-create ListTodos as from (path: TodoFilePath) -> string select {
-  1. load todos using @LoadTodos
-  2. return a formatted string representation of all todos
-  3. show completed todos with a checkmark
-  4. show incomplete todos with an empty checkbox
+/* The concept realized into a CLI and a Web representation. */
+create TodoCli as
+from TodoApp
+select {
+  expose the todo operations through a command-line interface
 };
 
-create CompleteTodo as from (path: TodoFilePath, id: TodoId) -> Todo select {
-  1. load todos using @LoadTodos
-  2. search for the todo matching @id
-  3. throw an exception if the todo does not exist
-  4. set the todo completed status to true
-  5. persist the updated todo list using @SaveTodos
-  6. return the updated todo
+create TodoWeb as
+from TodoApp
+select {
+  expose the todo operations through HTTP endpoints
 };
 
-create ParseCliArgs as from string[] -> CliArgs select {
-  1. parse the command line arguments
-  2. extract the command name
-  3. extract the command arguments
+realize TodoApp as TodoCli in Cli;
+realize TodoApp as TodoWeb in Web;
+
+/* The base environments shared between realizations. */
+create Cli as
+from environment
+select {
+  interact with the user through a terminal
 };
 
-create Main as from string[] -> unit select {
-  1. parse process arguments using @ParseCliArgs
-  2. if the command is "add": call @AddTodo
-  3. if the command is "list": call @ListTodos and print the result to stdout
-  4. if the command is "complete": call @CompleteTodo
-  5. print a help message if the command is invalid
-  6. print user-friendly error messages for exceptions
+create Web as
+from environment
+select {
+  serve HTTP requests and produce HTTP responses
 };
 
-generate TodoTitle;
+create Python as
+from environment
+select {
+  language: Python,
+  runtime: CPython 3.12
+};
+
+create TypeScript as
+from environment
+select {
+  language: TypeScript,
+  runtime: Node.js 20
+};
 
-package executable MyTodo as Main;
+/* Exports for the concrete realizations. */
+export TodoId;
+export TodoTitle;
+export Todo;
+export HttpRequest;
+export HttpResponse;
+export AddTodo;
+export ListTodos;
+export CompleteTodo;
+export TodoApp;
+export TodoCli;
+export TodoWeb;
+export Cli;
+export Web;
+export Python;
+export TypeScript;

package/tests/props/typescript_cli_env.spex

@@ -0,0 +1,16 @@
+-- The TypeScript CLI environment.
+--
+-- A subobject of the shared Cli environment intersected with the shared
+-- TypeScript environment.
+
+import Cli from "todo.spex";
+import TypeScript from "todo.spex";
+
+create TypeScriptCliEnv as
+from Cli intersect TypeScript
+select {
+  dependencies: Node.js standard library,
+  storage: JSON file
+};
+
+export TypeScriptCliEnv;

package/tests/props/typescript_todo_cli.spex

@@ -0,0 +1,70 @@
+-- The TypeScript realization of the Todo CLI.
+--
+-- Imports the shared TodoCli representation, the todo operations, and the
+-- TypeScript CLI environment. The argument parsing and JSON file storage
+-- are defined as separate objects, and the concept is realized as a product
+-- of them in the realize statement.
+
+import TodoCli from "todo.spex";
+import Todo from "todo.spex";
+import TodoId from "todo.spex";
+import TodoTitle from "todo.spex";
+import AddTodo from "todo.spex";
+import ListTodos from "todo.spex";
+import CompleteTodo from "todo.spex";
+import TypeScriptCliEnv from "typescript_cli_env.spex";
+
+/* Argument parsing. */
+create CliCommand as (
+  command: string,
+  arguments: string[]
+);
+
+create ParseArgs as
+from (args: string[]) -> CliCommand
+select {
+  1. read the command and its arguments from @args
+  2. map the command to the add, list, or complete command
+  3. return the parsed command
+};
+
+/* JSON file storage. */
+create LoadTodosFile as
+from (path: string) -> Todo[]
+select {
+  1. check whether the file at @path exists with the filesystem module
+  2. read the file at @path
+  3. parse the JSON content into todos
+  4. return an empty list if the file does not exist
+  5. throw an exception if the JSON is invalid
+};
+
+create SaveTodosFile as
+from (path: string, todos: Todo[]) -> unit
+select {
+  1. serialize @todos as formatted JSON
+  2. write the JSON to @path
+};
+
+/* The main entry exponential. */
+create TypeScriptTodoCli as
+from (args: string[]) -> unit
+select {
+  1. parse the command with @ParseArgs
+  2. load the todos from the JSON file with @LoadTodosFile
+  3. dispatch the command:
+     - add: call @AddTodo with the given @TodoTitle, then persist with @SaveTodosFile
+     - list: call @ListTodos and print the result to stdout
+     - complete: call @CompleteTodo with the given @TodoId, then persist with @SaveTodosFile
+  4. print user-friendly error messages for exceptions
+};
+
+realize TodoCli as (
+  parse: ParseArgs,
+  load: LoadTodosFile,
+  save: SaveTodosFile,
+  main: TypeScriptTodoCli
+) in TypeScriptCliEnv;
+
+generate TypeScriptTodoCli;
+package executable mytotscli as TypeScriptTodoCli;