include_preprocessor/

lib.rs

//! # Include preprocessor
//!
//! Inlines UTF-8 encoded files into other UTF-8 encoded files using C-preprocessor style `#include`
//! directives.
//!
//! ## Basic Example
//!
//! Given file `hello.txt`:
//!
//! ```txt
//! Hello
//! #include "world.txt"
//! ```
//!
//! ...and file `world.txt` (in the same directory):
//!
//! ```txt
//! world!
//! ```
//!
//! ...then the following code:
//!
//! ```no_run
//! use std::path::Path;
//! use include_preprocessor::{preprocess, SearchPaths};
//!
//! let entry_point = Path::new("./hello.txt");
//! let search_paths = SearchPaths::new();
//! let output_sink = String::new();
//! let result = preprocess(&entry_point, search_paths, output_sink).unwrap();
//! ```
//!
//! ... will produce the following `result` string:
//!
//! ```txt
//! Hello
//! world!
//! ```
//!
//! ## The `#include` directive
//!
//! The `#include` directive must begin with the `#include` string. The `#include` directive takes a
//! single argument. This argument may either be:
//!
//! - A file path wrapped in double-quotes:
//!   ```txt
//!   #include "path/to/file"
//!   ```
//!
//! - A file path wrapped in angle brackets:
//!   ```txt
//!   #include <path/to/file>
//!   ```
//!
//! The `#include` directive must be on its own line, as demarcated by ASCII line-endings (either
//! newlines `\n` or carriage returns `\r`). The `#` must not be preceded by any other characters,
//! including whitespace. There must be at least one ASCII whitespace character between `#include`
//! and the file path. It may only be succeeded by whitespace. There must not be any line-endings
//! inside the file path.
//!
//! ```txt
//! // Invalid, other characters precede the directive
//! Hello #include "path/to/file"
//!
//! // Invalid, preceded by whitespace
//!  #include "path/to/file"
//!
//! // Invalid, other characters succeed the directive
//! #include "path/to/file" world!
//!
//! // Invalid, no whitespace between `include` and the file path
//! #include"path/to/file"
//!
//! // Invalid, a line-ending inside the file path
//! #include "path/to
//! /file"
//! ```
//!
//! ## File Resolution
//!
//! File resolution is configured by passing a [SearchPaths] instance as the second argument to
//! the [preprocess] function. A [SearchPaths] instance is constructed by adding "base paths" with
//! [SearchPaths::push_base_path] and/or "quoted paths" with [SearchPaths::push_quoted_path]:
//!
//! ```rust
//! use include_preprocessor::SearchPaths;
//!
//! let mut search_paths = SearchPaths::new();
//!
//! search_paths.push_base_path("/some/path");
//! search_paths.push_quoted_path("/some/other/path");
//! ```
//!
//! You may add any number of base paths and quote paths.
//!
//! An absolute path will always resolve to itself. For relative paths, resolution further depends
//! on whether the included path was wrapped in angle brackets (`<some/path>`) or in quotes
//! (`"some/path"`).
//!
//! For a relative path wrapped in angle brackets, resolution will attempt to join (see
//! [Path::join](std::path::Path::join)) the relative path with each of the "base paths" added to the
//! [SearchPaths] instance, in the order in which the base paths were added. The resolved path will
//! be the first such path that resolves to a file (see [Path::is_file](std::path::Path::is_file)).
//! If none of these paths produce a valid file path, then [preprocess] will return an error.
//!
//! For a relative path wrapped in quotes, resolution will go through the following steps (in
//! order):
//!
//! 1. It will attempt to join the relative path with the path of the parent directory of the
//!    including file.
//! 2. It will attempt to join the relative path with each of the "quoted paths" added to the
//!    [SearchPaths] instance, in the order in which they were added.
//! 3. It will attempt to join the relative path with each of the "base paths" added to the
//!    [SearchPaths] instance, in the order in which they were added.
//!
//! The resolved path will be the first such path that resolves to a file. If none of these paths
//! produce a valid file path, then [preprocess] will return an error.
//!
//! ## The `#pragma once` Directive
//!
//! This `#include` pre-processor also supports the "pragma once" directive, a non-standard, but
//! commonly supported directive in C/C++ preprocessors:
//!
//! ```txt
//! #pragma once
//! ```
//!
//! The `#pragma once` directive must be on its own line, as demarcated by ASCII line-endings
//! (either newlines `\n` or carriage returns `\r`). The `#` must not be preceded by any other
//! characters, including whitespace. There must be at least one ASCII whitespace character between
//! `#pragma` and `once`. It may only be succeeded by whitespace.
//!
//! If a `#pragma once` directive occurs anywhere in a file, then if that file is included into
//! the final output through `#include` directives, only the first time that any `#include`
//! directive resolves to this file will the file's contents be inlined; all subsequent `#include`
//! directives that resolve to the file will simply cause the `#include` directive's line to be
//! elided from the final output. To determine if two different `#include` directives resolve to the
//! same file, the pre-processor compares the "canonicalized" paths (see
//! [Path::canonicalize](std::path::Path::canonicalize)) after file resolution (see the
//! [File Resolution](crate#file-resolution) section above).
//!
//! For example, given the file `grandparent`:
//!
//! ```pseudocode
//! #pragma once
//!
//! struct MyStruct {
//!     a: u32
//! }
//! ```
//!
//! ...and the file `parent`:
//!
//! ```pseudocode
//! #include "grandparent"
//! ```
//!
//! ...and the file `child`:
//!
//! ```pseudocode
//! #include "grandparent"
//! #include "parent"
//! ```
//!
//! ...then include pre-processing will produce the following result:
//!
//! ```pseudocode
//!
//! struct MyStruct {
//!     a: u32
//! }
//! ```
//!
//! Most programming languages do not allow multiple struct definitions with the same name, so
//! without the `#pragma once` directive, the above example would probably have resulted in code
//! that fails to compile.
//!
//! ## The `include_str_ipp` Macro
//!
//! This crate has a companion crate called `include-preprocessor-macro` that defines the
//! `include_str_ipp` macro, which covers basic use-cases. It behaves similarly to the [include_str]
//! macro and will inline pre-processed file contents into your code as a `&'static str`. For
//! details on the macro's use, refer to the documentation of the `include-preprocessor-macro`
//! crate.
//!
//! ## Custom [OutputSink]
//!
//! The third argument to the [preprocess] function must implement the [OutputSink] trait. In the
//! basic example above, we use a [String] as the output-sink ([String] implements the [OutputSink]
//! trait), but you may also provide a custom output-sink. The output-sink will receive chunks of
//! text via [OutputSink::sink] and [OutputSink::sink_source_mapped]. Concatenating all chunk text
//! strings in the order in which they are received will produce the intended result string. Most
//! chunks will be delivered via [OutputSink::sink_source_mapped], which receives
//! [SourceMappedChunk]s, which in addition to the chunk text, also contain information about the
//! original text span that produced the chunk; this information may be useful for the construction
//! of a source-map. The pre-processor sometimes inserts blank lines for correctness; such lines
//! will not map to a source span and will instead be delivered via [OutputSink::sink].
//!
//! ## Source Tracking
//!
//! When using the [preprocess_with_source_tracker] function rather than the regular [preprocess]
//! function, the function takes an additional fourth argument that must implement the
//! [SourceTracker] trait. This source-tracker will be notified for each file that is included
//! through an `#include` directive via [SourceTracker::track] with the path of the file.
//!
//! This is intended to be used when building proc-macros. It can be used to make the Rust compiler
//! track files for changes that require recompilation when using Rust with incremental compilation.
//! For example, the `include-preprocessor-macro` crate defines the following [SourceTracker]:
//!
//! ```ignore
//! use proc_macro::tracked_path;
//!
//! struct ProcMacroPathTracker;
//!
//! impl SourceTracker for ProcMacroPathTracker {
//!     fn track(&mut self, path: &Path, _source: &str) {
//!         tracked_path::path(path.to_str().expect("cannot track non-unicode path"));
//!     }
//! }
//! ```

mod include_preprocessor;
mod line_parser;

pub use self::include_preprocessor::{
    Error, FileNotFoundError, OutputSink, ParseError, SearchPaths, SourceMappedChunk,
    SourceTracker, preprocess, preprocess_with_source_tracker,
};