MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Sidecar.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "Request.hpp"
4
6
7/** @brief Path of the sidecar for @p header: Name.hpp becomes Name.describe.hpp beside it. */
8[[nodiscard]] std::filesystem::path sidecar_path(const std::filesystem::path& header);
9
10/** @brief sidecar_path() with another suffix, such as ".signatures.hpp": Name.hpp becomes Name.signatures.hpp. */
11[[nodiscard]] std::filesystem::path sidecar_path(const std::filesystem::path& header, std::string_view suffix);
12
13/** @brief The whole content of @p path, or nullopt when it cannot be read. */
14[[nodiscard]] std::optional<std::string> read_text(const std::filesystem::path& path);
15
16/** @brief Text of the sidecar for one header, with its records sorted by name. */
17[[nodiscard]] std::string render_sidecar(const HeaderRequests& requests);
18
19/** @brief Writes an empty sidecar when none exists, so the include never fails a first scan. */
20[[nodiscard]] bool ensure_stub(const std::filesystem::path& path, std::string& error);
21
22/** @brief Replaces @p path with @p content only when the content differs. */
23[[nodiscard]] bool write_if_changed(const std::filesystem::path& path, const std::string& content, std::string& error);
24
25/**
26 * @brief Inserts the sidecar include on the line after the last marker when the header has none.
27 *
28 * A header that already includes its sidecar anywhere is left untouched, so a
29 * misplaced include is reported by check_include and never moved.
30 *
31 * @param inserted Set to true when the header was edited.
32 * @return false with @p error set when the header cannot be read or written.
33 */
34[[nodiscard]] bool insert_include(const HeaderRequests& requests, bool& inserted, std::string& error);
35
36/**
37 * @brief Checks that the header includes its sidecar exactly once, after its last marker.
38 * @return A diagnostic, or nullopt when the placement is correct.
39 */
40[[nodiscard]] std::optional<std::string> check_include(const HeaderRequests& requests);
41
42/**
43 * @brief insert_include() for any marker, given the header, the line of its last marker and the sidecar suffix.
44 * @param last_marker The line after which the include may appear.
45 */
46[[nodiscard]] bool insert_include(const std::filesystem::path& header, unsigned last_marker,
47 std::string_view suffix, bool& inserted, std::string& error);
48
49/** @brief check_include() for any marker, given the header, the line of its last marker and the sidecar suffix. */
50[[nodiscard]] std::optional<std::string> check_include(
51 const std::filesystem::path& header, unsigned last_marker, std::string_view suffix);
52
53}
std::string render_sidecar(const HeaderRequests &requests)
Text of the sidecar for one header, with its records sorted by name.
Definition Sidecar.cpp:95
bool ensure_stub(const std::filesystem::path &path, std::string &error)
Writes an empty sidecar when none exists, so the include never fails a first scan.
Definition Sidecar.cpp:129
bool insert_include(const HeaderRequests &requests, bool &inserted, std::string &error)
Inserts the sidecar include on the line after the last marker when the header has none.
Definition Sidecar.cpp:41
std::optional< std::string > read_text(const std::filesystem::path &path)
The whole content of path, or nullopt when it cannot be read.
Definition Sidecar.cpp:30
std::filesystem::path sidecar_path(const std::filesystem::path &header)
Path of the sidecar for header: Name.hpp becomes Name.describe.hpp beside it.
Definition Sidecar.cpp:85
std::optional< std::string > check_include(const HeaderRequests &requests)
Checks that the header includes its sidecar exactly once, after its last marker.
Definition Sidecar.cpp:161
bool write_if_changed(const std::filesystem::path &path, const std::string &content, std::string &error)
Replaces path with content only when the content differs.
Definition Sidecar.cpp:137
Every record described by the MF_DESCRIBE markers of one header.
Definition Request.hpp:25