https://github.com/vrixyz/strinject

https://github.com/vrixyz/strinject

Last synced: 3 days ago
JSON representation

• Host: GitHub
• URL: https://github.com/vrixyz/strinject
• Owner: Vrixyz
• License: apache-2.0
• Created: 2024-11-20T09:03:20.000Z (2 months ago)
• Default Branch: main
• Last Pushed: 2024-12-16T09:31:45.000Z (about 1 month ago)
• Last Synced: 2025-01-16T08:34:49.298Z (10 days ago)
• Language: Rust
• Size: 53.7 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 3
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Text Inject

## Use case

When writing documentation, it's useful to reference and inline code snippets.

`strinject` helps you do that.

## Features

Replace text in a file, taking content from another file.

A simple API:

```rs

pub fn inject(source_text: &str) -> Result;

```

### Content Marker

Any occurrence of the tag ``

will load the file `tests/to_inject1.txt`, search for the text between `// DOCUSAURUS: ToInject1_1: start`

and the next `// DOCUSAURUS: ToInject1_1: stop`, and replace the tag with the text between those markers.

## Removes extraneous spaces

Useful code is sometimes indented, `strinject` removes out-of-context indentation.

## Download

Download external files pointed to by `path` with the feature `download`.

## Recommendations

We advise to setup your own diff tooling to verify no unintended modifications were introduced

after the injection took place.

See [parry.rs CI](https://github.com/dimforge/parry.rs/pull/3) for an example of such tool.

## Alternatives

- `rustdoc` checks the whole inlined code, and allows to hide specific lines

  - Good:

    - Easy to use

  - Bad:

    - Not ideal for code snippets which need a lot of setup boilerplate.

    - It is impractical to inline code with a more advanced setup.

    - Less customizable, `strinject` is context agnostic.

- using custom script with sed / awk / perl / whatever

  - Good:

    - it can work.

  - Bad:

    - cross-platform support is not ideal.

    - not trivial to write, and even worse to read.

- Tera/Askama/rinja/handlebars/

  - Good:

    - powerful

  - Bad:

    - A lot of features

    - difficult to know if it's possible to search specific data from somewhere else.

- manual copy pasting

  - Good:

    - Quick solution for simple cases

  - Bad:

    - error-prone

    - difficult to verify code correctness