Represents a single NoTeX project: its location and metadata. More...

#include <notex/manager.hpp>

Public Member Functions
	Manager (std::filesystem::path start_dir=std::filesystem::current_path())
	Locates and loads the project that contains `start_dir`.
const std::filesystem::path &	root_dir () const noexcept
const ProjectConfig &	config () const noexcept
ProjectConfig &	config () noexcept
void	save () const
	Persists the current metadata back to .notex/notex.json.
void	set_theme (std::string_view theme)
	Switches the project's theme.
void	add_section (std::string_view title)
	Adds a new section titled `title`.
bool	remove_section (int number)
	Removes the section numbered `number`.
void	add_bibliography ()
	Adds a bibliography.
void	remove_bibliography ()
	Removes the bibliography commands added by add_bibliography() from the main file.
std::vector< std::filesystem::path >	project_files () const
std::vector< std::string >	orphan_sections () const
bool	reset (bool force=false)
	Regenerates the main file from the template, after backing up the previous one to <main_file>.bak.
bool	delete_scaffolding (bool remove_all=false, bool force=false)
	Removes NoTeX's own scaffolding from the project.
void	set_config_value (std::string_view key, std::string_view value)
	Sets a single whitelisted metadata key directly.

Static Public Member Functions
static std::optional< std::filesystem::path >	find_project_root (const std::filesystem::path &start_dir)
	Searches upward from `start_dir` for a .notex/ directory, without requiring one to exist.
static Manager	init (const std::filesystem::path &target_dir, templates::ProjectType project_type=templates::ProjectType::MULTI, bool force=false)
	Creates a new NoTeX project inside `target_dir`.
static void	write_config (const std::filesystem::path &root_dir, const ProjectConfig &config)
	Writes `config` as <root_dir>/.notex/notex.json, creating <root_dir>/.notex/ first if it does not already exist.
static CleanReport	clean (const std::filesystem::path &start_dir, bool dry_run=false)
	Recursively removes known LaTeX build artefacts from `start_dir`.
static std::vector< std::string >	available_themes ()

Detailed Description

Represents a single NoTeX project: its location and metadata.

A Manager locates its project the way git locates a repository: it starts from a given directory and walks upward until it finds the hidden .notex/ directory that marks the project root, then loads the project's metadata from .notex/notex.json.

Definition at line 74 of file manager.hpp.

Constructor & Destructor Documentation

◆ Manager()

notex::Manager::Manager ( std::filesystem::path start_dir = std::filesystem::current_path() )

explicit

Locates and loads the project that contains start_dir.

Parameters

start_dir Directory to start the upward search from; defaults to the current working directory.

Exceptions

ProjectNotFoundError	if no .notex/ directory is found between `start_dir` and the filesystem root.
ConfigError	if .notex/notex.json exists but cannot be parsed.

Definition at line 337 of file manager.cpp.

References find_project_root().

Referenced by init().

Member Function Documentation

◆ add_bibliography()

void notex::Manager::add_bibliography ( )

Adds a bibliography.

Creates bibliography_file (defaulting to "bibliography.bib") from templates::bibliography_starter() if it does not already exist, then inserts the bibliography commands appropriate to the document: \addbibresource/\printbibliography if a biblatex \usepackage line is detected in the main file, or the classic \bibliographystyle/\bibliography pair otherwise. Idempotent: a command already present is left untouched.

Exceptions

DocumentError if the main file has no unique \documentclass or \end{document} line to anchor the insertion on.

Definition at line 571 of file manager.cpp.

References notex::templates::bibliography_starter(), notex::Document::find_all(), notex::Document::load(), notex::Document::save(), and save().

◆ add_section()

void notex::Manager::add_section ( std::string_view title )

Adds a new section titled title.

In a single-file project, inserts a \section{} heading before the unique \end{document}. In a multi-file project, determines the next section number by scanning sections/ (never tracked in the metadata, so sections added or removed by hand are always respected), writes a new numbered subfile from templates::section(), and inserts the corresponding \subfile line after the last one already in the main file.

Parameters

title Section title.

Exceptions

DocumentError if the expected anchor (\end{document} for a single-file project, the last \subfile{sections/...} line for a multi-file one) is missing or ambiguous.

Definition at line 488 of file manager.cpp.

References notex::Document::find_last(), notex::Document::find_unique(), notex::Document::insert_line(), notex::Document::insert_lines(), notex::Document::load(), notex::Document::save(), notex::templates::section(), and notex::templates::section_stem().

◆ available_themes()

std::vector< std::string > notex::Manager::available_themes ( )

static

Returns: The theme names available, derived from the embedded notex-theme-*.tex files (e.g. "bw", "dark", "light", "tokyo").

Definition at line 451 of file manager.cpp.

References notex::assets::latex_files().

Referenced by set_theme().

◆ clean()

CleanReport notex::Manager::clean	(	const std::filesystem::path &	start_dir,
		bool	dry_run = false )

static

Recursively removes known LaTeX build artefacts from start_dir.

Operates on an arbitrary path and needs no project, which is why this is a static operation rather than an instance method. Files are matched by filename suffix rather than by std::filesystem::path::extension(), because several artefacts, such as .synctex.gz and -blx.bib, are not true extensions; directories generated by the minted package are matched by the _minted- prefix that package always uses, regardless of the project's file names. A start_dir that does not exist, or is not a directory, yields an empty report rather than an error, so that the command works the same way whether or not it happens to be run inside a project.

Parameters

start_dir	Directory to clean, recursively.
dry_run	When true, nothing is deleted; the report describes what would have been removed.

Returns: A report of every file and directory removed (or that would have been, under a dry run).

Definition at line 410 of file manager.cpp.

References notex::CleanReport::total_removed().

Referenced by delete_scaffolding().

◆ config() [1/2]

const ProjectConfig & notex::Manager::config ( ) const

inlinenoexcept

Returns: The project's current metadata.

Definition at line 105 of file manager.hpp.

Referenced by init(), notex::Installer::install_local(), notex::Installer::uninstall_local(), and write_config().

◆ config() [2/2]

ProjectConfig & notex::Manager::config ( )

inlinenoexcept

Returns: The project's current metadata, mutable so that later phases can update it before calling save().

Definition at line 109 of file manager.hpp.

◆ delete_scaffolding()

bool notex::Manager::delete_scaffolding	(	bool	remove_all = false,
		bool	force = false )

Removes NoTeX's own scaffolding from the project.

Removes .notex/, settings/, fonts/, and any build artefacts (via clean()), but preserves every user-authored file — the main file, sections, the bibliography, and anything else — unless remove_all is set, in which case the entire project directory is removed. Asks for confirmation first.

Parameters

remove_all	Also remove every user-authored file (the whole project directory), not just NoTeX's own.
force	Skip the confirmation prompt.

Returns: True if the deletion was performed; false if the user declined the confirmation prompt.

Definition at line 707 of file manager.cpp.

References clean(), notex::ui::confirm(), and notex::ui::warning().

◆ find_project_root()

std::optional< std::filesystem::path > notex::Manager::find_project_root ( const std::filesystem::path & start_dir )

static

Searches upward from start_dir for a .notex/ directory, without requiring one to exist.

Parameters

start_dir Directory to start the search from.

Returns: The project root directory, or std::nullopt if none is found before reaching the filesystem root.

Definition at line 279 of file manager.cpp.

Referenced by Manager().

◆ init()

Manager notex::Manager::init	(	const std::filesystem::path &	target_dir,
		templates::ProjectType	project_type = templates::ProjectType::MULTI,
		bool	force = false )

static

Creates a new NoTeX project inside target_dir.

Writes a fresh main.tex — a single file for templates::ProjectType::MONO, or a main.tex plus a sections/ directory holding one introductory section for templates::ProjectType::MULTI — and records the project's metadata in a newly created .notex/notex.json. The generated main.tex refers to \documentclass{settings/notex} when target_dir already holds a local installation, and to plain notex otherwise, warning when no installation at all can be found.

Parameters

target_dir	Directory to create the project in; created if it does not already exist.
project_type	Whether to scaffold a single-file or a multi-file project.
force	Overwrite an existing main.tex or .notex/ directory instead of refusing to.

Exceptions

FilesystemError if target_dir already looks like a project and force is not set, or if a file cannot be written.

Returns: A Manager for the newly created project.

Definition at line 374 of file manager.cpp.

References config(), Manager(), notex::templates::MONO, notex::templates::mono_main(), notex::templates::multi_main(), notex::templates::section(), notex::templates::section_stem(), notex::templates::to_string(), and write_config().

◆ orphan_sections()

std::vector< std::string > notex::Manager::orphan_sections ( ) const

Returns: The filename stems (see templates::section_stem()) of every section file present under sections/ that is not referenced by any \subfile line in the main file. Always empty for a single-file project, or if the main file does not exist. Used by checkhealth.

Definition at line 649 of file manager.cpp.

References notex::Document::lines(), and notex::Document::load().

◆ project_files()

std::vector< std::filesystem::path > notex::Manager::project_files ( ) const

Returns: Every file this project is considered to genuinely own: the main file, every file under sections/ (for a multi-file project), and the bibliography file — each only if it actually exists on disk. Used by ls.

Definition at line 623 of file manager.cpp.

◆ remove_bibliography()

void notex::Manager::remove_bibliography ( )

Removes the bibliography commands added by add_bibliography() from the main file.

Always strips the commands themselves, which is non-destructive to any content; separately asks for confirmation before deleting the .bib file itself, since that step is not reversible.

Definition at line 602 of file manager.cpp.

References notex::ui::confirm(), notex::Document::load(), notex::Document::save(), and save().

◆ remove_section()

bool notex::Manager::remove_section ( int number )

Removes the section numbered number.

Only supported in a multi-file project, since a single-file project has no single section body that could be removed unambiguously. Asks for confirmation before deleting anything.

Parameters

number Section number, as scanned from sections/.

Exceptions

UsageError	if this is a single-file project, or if no section numbered `number` exists.
DocumentError	if more than one \subfile line references the section being removed.

Returns: True if the section was removed; false if the user declined the confirmation prompt.

Definition at line 519 of file manager.cpp.

References notex::ui::confirm(), notex::Document::find_all(), notex::Document::load(), notex::Document::remove_line(), notex::Document::save(), and notex::ui::warning().

◆ reset()

bool notex::Manager::reset ( bool force = false )

Regenerates the main file from the template, after backing up the previous one to <main_file>.bak.

A multi-file project's regenerated main file references every section currently present under sections/, in number order, not just the first — sections and the bibliography file themselves are left untouched. Asks for confirmation first.

Parameters

force Skip the confirmation prompt.

Returns: True if the reset was performed; false if the user declined the confirmation prompt.

Definition at line 674 of file manager.cpp.

References notex::ui::confirm(), notex::templates::mono_main(), notex::templates::multi_main(), and notex::ui::warning().

◆ root_dir()

const std::filesystem::path & notex::Manager::root_dir ( ) const

inlinenoexcept

Returns: The project's root directory (the one containing .notex/).

Definition at line 100 of file manager.hpp.

Referenced by write_config().

◆ save()

void notex::Manager::save ( ) const

Persists the current metadata back to .notex/notex.json.

Exceptions

ConfigError if the file cannot be written.

Definition at line 350 of file manager.cpp.

References write_config().

Referenced by add_bibliography(), remove_bibliography(), set_config_value(), set_theme(), and notex::Installer::uninstall_local().

◆ set_config_value()

void notex::Manager::set_config_value	(	std::string_view	key,
		std::string_view	value )

Sets a single whitelisted metadata key directly.

A low-level escape hatch for the fields the higher-level commands (theme, add/remove section/bib) don't cover the raw editing of; unlike set_theme(), this does not touch the main file's content at all, only the recorded metadata.

Parameters

key	One of "main_file", "theme", "bibliography_file".
value	New value for `key`.

Exceptions

UsageError if key is not one of the whitelisted keys.

Definition at line 737 of file manager.cpp.

References save().

◆ set_theme()

void notex::Manager::set_theme ( std::string_view theme )

Switches the project's theme.

Rewrites the \documentclass options of the project's main file to select theme instead of whichever other theme was there, and records it in the project's metadata.

Parameters

theme Theme name; must be one of available_themes().

Exceptions

UsageError	if `theme` is not a known theme.
DocumentError	if the main file's \documentclass line is missing, ambiguous, or malformed.

Definition at line 466 of file manager.cpp.

References available_themes(), notex::Document::load(), notex::Document::save(), save(), and notex::Document::set_documentclass_option().

◆ write_config()

void notex::Manager::write_config	(	const std::filesystem::path &	root_dir,
		const ProjectConfig &	config )

static

Writes config as <root_dir>/.notex/notex.json, creating <root_dir>/.notex/ first if it does not already exist.

Unlike the constructor, this does not require root_dir to already be a NoTeX project: it is the mechanical write operation that both save() and a fresh install use, the latter to bootstrap .notex/ for a directory that is not a project yet.

Parameters

root_dir	Directory whose .notex/ should hold the config.
config	Metadata to write.

Exceptions

ConfigError if the file cannot be written.

Definition at line 352 of file manager.cpp.

References config(), and root_dir().

Referenced by init(), notex::Installer::install_local(), and save().

The documentation for this class was generated from the following files:

notex/include/notex/manager.hpp
notex/src/notex/manager.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Manager()

Member Function Documentation

◆ add_bibliography()

◆ add_section()

◆ available_themes()

◆ clean()

◆ config() [1/2]

◆ config() [2/2]

◆ delete_scaffolding()

◆ find_project_root()

◆ init()

◆ orphan_sections()

◆ project_files()

◆ remove_bibliography()

◆ remove_section()

◆ reset()

◆ root_dir()

◆ save()

◆ set_config_value()

◆ set_theme()

◆ write_config()