Drop `assert()´ check in subpath parsing

[CGirls] / request.h

diff --git a/request.h b/request.h
index 2ab70e0a01e87ae681a74ac6850dc0df34bb5c01..7e95fbead4dca132f69c9dd634030313805d59e7 100644 (file)
--- a/request.h
+++ b/request.h
@@ -1,90 +1,229 @@
 // SPDX-FileCopyrightText: 2025 Lady <https://www.ladys.computer/about/#lady>
 // SPDX-License-Identifier: GPL-2.0-only
 
 // SPDX-FileCopyrightText: 2025 Lady <https://www.ladys.computer/about/#lady>
 // SPDX-License-Identifier: GPL-2.0-only
 

+/**
+ ** This file defines types, constants, and function signatures
+ ** necessary for dealing with the ⹐semantics⹑ of C·Girls requests.
+ ** (Implementations of these functions are provided in `request.c´.)
+ **/
+

 #ifndef CGIRLS_REQUEST_H
 #define CGIRLS_REQUEST_H
 
 #ifndef CGIRLS_REQUEST_H
 #define CGIRLS_REQUEST_H
 

-enum cgirls_mediatype : unsigned char {
-       // Unspecified media type
-       cgirls_mediatype_any = 0x00,
-       // Text media types
-       cgirls_mediatype_txt = 0x10,
-       cgirls_mediatype_htm = 0x11,
-       // X·M·L media types
-       cgirls_mediatype_xml = 0x20,
-       cgirls_mediatype_rdf = 0x21,
+/**
+ ** § Types
+ **////////////////////////////////////////////////////////////////////
+/**
+ ** ❦ `enum ⸤cgirls_mtype⸥´
+ **
+ ** The `⸤cgirls_mtype⸥´ enumeration is used to indicate recognized
+ ** mediatype extensions.
+ **/
+enum cgirls_mtype : unsigned char {
+/**
+ ** The value `⟨cgirls_mtype_any⟩´ indicates no mediatype preference.
+ **/
+       cgirls_mtype_any = 0,
+
+/**
+ ** The value `⟨cgirls_mtype_txt⟩´ indicates a preference for
+ ** `text/plain´ content.
+ **/
+       cgirls_mtype_txt = 1,
+
+/**
+ ** The value `⟨cgirls_mtype_htm⟩´ indicates a preference for
+ ** `text/html´ content.
+ **/
+       cgirls_mtype_htm = 2,
+
+/**
+ ** The value `⟨cgirls_mtype_xml⟩´ indicates a preference for
+ ** `application/xml´ content, ideally with an `<?xml-stylesheet?>´
+ ** processing instruction.
+ **/
+       cgirls_mtype_xml = 3,
+
+/**
+ ** The value `⟨cgirls_mtype_rdf⟩´ indicates a preference for
+ ** `application/rdf+xml´ content.
+ **/
+       cgirls_mtype_rdf = 4,
+

 };
 };

-typedef enum cgirls_mediatype cgirls_mediatype;
+typedef enum cgirls_mtype cgirls_mtype;

 
 

+/**
+ ** ❦ `enum ⸤cgirls_vb⸥´
+ **
+ ** The `⸤cgirls_vb⸥´ enumeration is used to indicate recognized verbs
+ ** for requests.
+ **/

 enum cgirls_vb : unsigned char {
 enum cgirls_vb : unsigned char {

-       // Actions in general
-       cgirls_vb_index = 0x00,
-       // Actions on projects
-       cgirls_vb_branches = 0x10,
-       cgirls_vb_tags = 0x11,
-       // Actions on single objects
-       cgirls_vb_show = 0x20,
-       cgirls_vb_raw = 0x21,
-       cgirls_vb_blame = 0x22,
-       // Actions on ranges of objects
-       cgirls_vb_log = 0x30,
-       cgirls_vb_shortlog = 0x31,
-       cgirls_vb_atom = 0x32,
-       cgirls_vb_patch = 0x33,
-       // Unknown verb
-       cgirls_vb_unknown = 0xFF,
+
+/**
+ ** The value `⟨cgirls_vb_unknown⟩´ indicates an unknown or unspecified
+ ** verb.
+ **/
+       cgirls_vb_unknown = 0,
+
+/**
+ ** The value `⟨cgirls_vb_index⟩´ indicates a request for an index of
+ ** projects.
+ **/
+       cgirls_vb_index = 1,
+
+/**
+ ** The value `⟨cgirls_vb_branches⟩´ indicates a request for an index
+ ** of branches in a given project. The value `⟨cgirls_vb_tags⟩´
+ ** indicates a request for an index of tags.
+ **/
+       // cgirls_vb_branches = ??,
+       // cgirls_vb_tags = ??,
+
+/**
+ ** The value `⟨cgirls_vb_show⟩´ indicates a request for an object in a
+ ** human‐readable manner. The value `⟨cgirls_vb_raw⟩´ indicates a
+ ** request for the raw contents of an object. The value
+ ** `⟨cgirls_vb_blame⟩´ indicates a request for a blame of a commit.
+ **/
+       cgirls_vb_show = 2,
+       // cgirls_vb_raw = ??,
+       // cgirls_vb_blame = ??,
+
+/**
+ ** The value `⟨cgirls_vb_index⟩´ indicates a request for a diff
+ ** between two commits.
+ **/
+       // cgirls_vb_diff = ??,
+
+/**
+ ** The values `⟨cgirls_vb_log⟩´, `⟨cgirls_vb_shortlog⟩´,
+ ** `⟨cgirls_vb_atom⟩´, and `⟨cgirls_vb_patch⟩´ indicate requests for
+ ** logs of a number of commits in various formats.
+ **/
+       // cgirls_vb_log = ??,
+       // cgirls_vb_shortlog = ??,
+       // cgirls_vb_atom = ??,
+       // cgirls_vb_patch = ??,
+
+/**
+ ** Note that the numbering for verbs does not follow their order in
+ ** the above list, but rather is fixed to when they were first
+ ** supported. New verbs may be added in the future.
+ **
+ ** Verbs can be categorized into a few distinct classes :—
+ **
+ ** • Verbs which do not require a project :— `⟨cgirls_vb_index⟩´.
+ **
+ ** • Verbs which require a project, but not a revspec :—
+ ** `⟨cgirls_vb_branches⟩´, `⟨cgirls_vb_tags⟩´.
+ **
+ ** • Verbs which request information about a single object :—
+ ** `⟨cgirls_vb_show⟩´, `⟨cgirls_vb_raw⟩´, `⟨cgirls_vb_blame⟩´.
+ **
+ ** • Verbs which compare two commits :— `⟨cgirls_vb_diff⟩´.
+ **
+ ** • Verbs which produce information about an open‐ended number of
+ ** commits :— `⟨cgirls_vb_log⟩´, `⟨cgirls_vb_shortlog⟩´,
+ ** `⟨cgirls_vb_atom⟩´, `⟨cgirls_vb_patch⟩´.
+ **/

 };
 typedef enum cgirls_vb cgirls_vb;
 
 };
 typedef enum cgirls_vb cgirls_vb;
 

+/**
+ ** ❦ `struct ⸤cgirls_req_status⸥´
+ **
+ ** The struct `⸤cgirls_req_status⸥´ wraps a status code and message
+ ** for a response.
+ **
+ ** The `⟨.message⟩´ is only significant if `⟨.code⟩´ is not `200´.
+ **/

 typedef struct cgirls_req_status cgirls_req_status;
 struct cgirls_req_status {
 typedef struct cgirls_req_status cgirls_req_status;
 struct cgirls_req_status {

-       unsigned short cgirls_code;
-       char* cgirls_message; // if `cgirls_code´ is not ok
+       unsigned short code;
+       char* message; // if `code´ is not ok

 };
 
 };
 

+/**
+ ** ❦ `struct ⸤cgirls_req⸥´
+ **
+ ** The struct `⸤cgirls_req⸥´ represents a request.
+ **
+ ** Requests must have a verb, may specify a mediatype extension, and
+ ** might also reference a project, revspec, and subpath. The value of
+ ** `⟨.subpath⟩´, if not `⟨nullptr⟩´, must be a `⟨nullptr⟩´‐terminated
+ ** array of strings.
+ **
+ ** All requests have a status, which is used to express request
+ ** validity. If `⟨.status⟩⟨.code⟩´ is not `200´, the request is
+ ** invalid and a response with the associated code and message is
+ ** recommended.
+ **/

 typedef struct cgirls_req cgirls_req;
 struct cgirls_req {
 typedef struct cgirls_req cgirls_req;
 struct cgirls_req {

-       cgirls_vb cgirls_action;
-       cgirls_mediatype cgirls_type;
-       char* cgirls_project;
-       char* cgirls_id;
-       char** cgirls_subpath;
-       char* cgirls_baseid;
-       cgirls_req_status cgirls_status;
+       cgirls_vb verb;
+       cgirls_mtype mtype;
+       char* project;
+       char* id_THIS_WILL_CHANGE;
+       char** subpath;
+       char* baseid_THIS_WILL_CHANGE;
+       cgirls_req_status status;

 };
 
 };
 

-/*
-Frees up any dynamically‐allocated memory which was allocated by
-`cgirls_path2req´.
-*/
-void cgirls_freereq (cgirls_req req);
-
-/*
-Converts the provided “path info” string into a `cgirls_req´ struct
-and returns the result.
-
-This struct contains dynamically‐allocated strings which must be freed
-by calling `cgirls_freereq´.
-
-Maximally, a “path info” string has the following form :—
-
-       {project}/{action}/{baseid}..{id}/{subpath}
-
-—: (where subpath can contain additional slashes, and action may
-optionally include one of a small number of supported extensions).
-`baseid´ is optional; if omitted, the dots preceding `id´ are also
-dropped. For all other components, all preceding components must be
-provided if a given component is provided.
-*/
-cgirls_req cgirls_path2req(char const*const pathinfo);
+/**
+ ** § Functions
+ **////////////////////////////////////////////////////////////////////
+/**
+ ** ❦ `⸤cgirls_req⸥ ⟨cgirls_path·to·req⟩(⸤char const*const⸥)´
+ **
+ ** The `⟨cgirls_path·to·req⟩´ function takes a path string (such as
+ ** one provided by the C·G·I `⟨PATH_INFO⟩´ environment variable) and
+ ** returns a `⸤cgirls_req⸥´ which represents its semantics.
+ **
+ ** This resulting struct contains a lot of dynamically‐allocated data,
+ ** so it ☞︎must☜︎ be freed with `⟨cgirls_req·free⟩´ after use.
+ **
+ ** Maximally, the path string is processed according to the following
+ ** form :—
+ **
+ ** |`{project}/{action}/{revspec}/{subpath}´
+ **
+ ** —: (where `{subpath}´ can contain additional slashes, and
+ ** `{action}´ consists of a verb and optionally a supported mediatype
+ ** extension). Not all components necessarily need to be specified,
+ ** and not all possible values are valid or meaningful.
+ **
+ ** In case of an error, `⟨.status⟩⟨.code⟩´ on the returned
+ ** `⸤cgirls_req⸥´ will be some·thing other than `200´.
+ **/
+cgirls_req cgirls_path·to·req(char const*const);

 
 

-/*
-Returns the canonical “path info” string which represents the provided
-`cgirls_req´.
+/**
+ ** ❦ `⸤void⸥ ⟨cgirls_req·free⟩(⸤cgirls_req⸥)´
+ **
+ ** The `⟨cgirls_req·free⟩´ function frees up any dynamically‐allocated
+ ** memory in the provided `⸤cgirls_req⸥´, assuming that it was created
+ ** with `⟨cgirls_path·to·req⟩´ or similar.
+ **/
+void cgirls_req·free(cgirls_req);

 
 

-Note that if `cgirls_req.cgirls_project´ is the null pointer, the
-canonical “path info” string is always the empty string.
-*/
-char* cgirls_req2path(cgirls_req);
+/**
+ ** ❦ `⸤char*⸥ ⟨cgirls_req·to·path⟩(⸤cgirls_req⸥)´
+ **
+ ** The `⟨cgirls_req·to·path⟩´ function does the reverse of
+ ** `⟨cgirls_path·to·req⟩´: It takes in a `⸤cgirls_req⸥´ struct and
+ ** returns the canonical path string which represents it.
+ **
+ ** All possible `⸤cgirls_req⸥´s have a canonical string
+ ** representation; `⟨cgirls_req·to·path⟩´ will only return `⟨nullptr⟩´
+ ** if it fails to allocate memory while constructing the resulting
+ ** string. Return values are dynamically allocated and must be
+ ** manually freed with `⟨free⟩´.
+ **
+ ** It is worth noting that, if the `⟨.project⟩´ is the null pointer,
+ ** the canonical path string will always be the empty string.
+ **/
+char* cgirls_req·to·path(cgirls_req);

 
 #endif /* CGIRLS_REQUEST_H */
 
 #endif /* CGIRLS_REQUEST_H */