// 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
-/*
-The following constant expressions provide recognized media type
-extensions.
-*/
-constexpr char* cgirls_mtype_any = nullptr;
-constexpr char cgirls_mtype_txt[] = ".txt";
-constexpr char cgirls_mtype_htm[] = ".htm";
-constexpr char cgirls_mtype_xml[] = ".xml";
-constexpr char cgirls_mtype_rdf[] = ".rdf";
-typedef char const* cgirls_mtype;
-constexpr size_t cgirls_n·mtypes = 4;
-static cgirls_mtype const cgirls_mtypes[cgirls_n·mtypes] = {
- cgirls_mtype_txt,
- cgirls_mtype_htm,
- cgirls_mtype_xml,
- cgirls_mtype_rdf,
-};
+/**
+ ** § 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,
-/*
-The following constant expressions provide recognized action verbs.
-*/
-// Actions in general:
-constexpr char cgirls_vb_index[] = "index";
-constexpr char cgirls_vb_unknown[] = "unknown";
-// Actions on projects:
-// constexpr char cgirls_vb_branches[] = "branches";
-// constexpr char cgirls_vb_tags[] = "tags";
-// Actions on single objects:
-constexpr char cgirls_vb_show[] = "show";
-// constexpr char cgirls_vb_raw[] = "raw";
-// constexpr char cgirls_vb_blame[] = "blame";
-// Actions on ranges of commits:
-// constexpr char cgirls_vb_diff[] = "diff";
-// Actions on lists of commits:
-// constexpr char cgirls_vb_log[] = "log";
-// constexpr char cgirls_vb_shortlog[] = "shortlog";
-// constexpr char cgirls_vb_atom[] = "atom";
-// constexpr char cgirls_vb_patch[] = "patch";
-typedef char const* cgirls_vb;
-constexpr size_t cgirls_n·vbs = 3;
-static cgirls_vb const cgirls_vbs[cgirls_n·vbs] = {
- cgirls_vb_index,
- cgirls_vb_unknown,
- cgirls_vb_show,
};
-constexpr size_t cgirls_n·parsable·vbs = 2;
-static cgirls_vb const cgirls_parsable·vbs[cgirls_n·parsable·vbs] = {
- cgirls_vb_index,
- cgirls_vb_show,
+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 {
+
+/**
+ ** 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;
+/**
+ ** ❦ `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 {
- 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.
+ **
+ ** 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 {
- cgirls_vb cgirls_action;
- cgirls_mtype 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´ structure 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
+ **
+ ** 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 */
Lady’s Gitweb / CGirls / blobdiff