JIRAI 🖤 🎀

A compiler for a markup language inspired by Jirai Kei. 🖤 🎀

ABOUT 📚

This repository contains the source code for a compiler for a Markdown-like language inspired by Jirai Kei. The compiler is a Rust crate written without any external dependencies and was made to be light and fast. The language itself was designed by me.

SPECIFICATION 🧮

List of block elements and inline elements

• Block elements:
  • Heading: A heading starts with the <3 symbol. The number of these symbols marks the heading's level. Example: <3<3 Heading 2
  • Paragraph: Paragraphs start with a piece of text that is not an inline element. Paragraphs end with a newline character.
  • Unordered List: An unordered list can only contain list items.
• Inline elements:
  • List item: List items start with the ~ symbol followed by a space. List items end with a newline character.
  • Link: A link is enclosed by brackets and reversed angle brackets. The link's information is inside three sections inside the brackets. Each section is delimited by square brackets. To mark the item as a link, the % operator is used to mark the item as a link. The first section is the link text. The second section is the alt text, and the third section is the URL of the link. Example: >(%[Click me!][Alt text here][https://example.com])<.
  • Code: Inline code is surrounded by angle brackets. Example:<inline code here>
  • Bold text: Bold text is surrounded by underscores. Example: _bold text here_
  • Image link: An image link is enclosed by brackets and reversed angle brackets. The image link's information is inside two sections inside the brackets. Each section is delimited by square brackets. To mark the item as an image link, the $ operator is used to mark the item as an image link. The first section is the alt text. The second section is the URL to the image. Example: >($[Alt text here][https://example.com])<.
  • Italic text: Italic text is surrounded by asterisks. Example: *italic text here*

Other rules

• File ending: Files containing Jirai markup have to end in the .jirai file extension.
• Comments: Comments have to start with the # operator and end with a newline character.
• Block elements can contain any number of inline elements.
• The following inline elements can contain other inline elements: list items, bold text, and italic text.

Extended Jirai

• The Extended Jirai format is a format that combines a section of data written in the Jirai Markup Language and a section of text written in Jirai. The document has to start and end with the (^-^) symbol and the data section has to be separated from the text section with the same symbol.

USAGE ⚒️

To add the Jirai crate to your Rust project and to compile text written in the Jirai format into HTML, add the following line to the dependencies section of your project's Cargo.toml:

jirai = { git = "https://git.alyxshang.boo/alyxshang/jirai", tag = "v.0.1.0" }

If you want to use the ejirai feature this crate offers, you would add the following line to the dependencies section of your project's Cargo.toml:

jirai = { git = "https://git.alyxshang.boo/alyxshang/jirai", tag = "v.0.1.0", features = ["ejirai"] }

You would use the Jirai crate in your code in a manner similar to the one outlined in the code samples below. These code samples assume that you have a file called sample.jirai in the same directory as your Cargo.toml.

# sample.jirai

<3 Heading 1
# This is a comment.
This is normal text with a very long sentence.
This is a sentence containing *italic* and _bold text_.
This is a link to an image >($[alt][https://alyxshang.boo])<.
This text contains some _bold text_.
This text contains some *italic text*.

<3<3 Heading 2

This paragraph contains some _nested *italic* text_.
And this is a >(%[link to my site][link to my site][https://alyxshang.boo])<.

~ This is item one of an unordered list.
~ This is item two of an unordered list.

use jirai::from_str;
use std::path::PathBuf;
use std::fs::read_to_string;

fn main(){
    let jirai_file_path: PathBuf = PathBuf::new();
    jirai_file_path.push(env!("CARGO_MANIFEST_DIR"));
    jirai_file_path.push(env!("sample.jirai"));
    let file_contents: String = read_to_string(
        &jirai_file_path.display().to_string()
    );
    let code: String = to_html(&file_contents)
        .expect("Could not compile Jirai code to HTML.");
    println!("{:?}", &code); // should output HTML code.
}

If you want to use Extended Jirai in your project, you would use the jirai crate in your code in the following manner. These code samples assume that you have a file called sample.ejirai in the same directory as your Cargo.toml.

(^-^)
# sample.ejirai
"layout" >~< "page"
"title" >~< "Page Title"
(^-^)
<3 Heading 1
# This is a comment.
This is normal text with a very long sentence.
This is a sentence containing *italic* and _bold text_.
This is a link to an image >($[alt][https://alyxshang.boo])<.
This text contains some _bold text_.
This text contains some *italic text*.

<3<3 Heading 2

This paragraph contains some _nested *italic* text_.
And this is a >(%[link to my site][link to my site][https://alyxshang.boo])<.

~ This is item one of an unordered list.
~ This is item two of an unordered list.
(^-^)

use serde::Deserialize;
use jirai::from_ejirai;
use std::path::PathBuf;
use jirai::ExtendedJirai;
use std::fs::read_to_string;

#[derive(Deserialize, Debug)]
pub struct PageData{
    pub title: String,
    pub layout: String
}

fn main(){
    let ejirai_file_path: PathBuf = PathBuf::new();
    ejirai_file_path.push(env!("CARGO_MANIFEST_DIR"));
    ejirai_file_path.push(env!("sample.ejirai"));
    let file_contents: String = read_to_string(
        &ejirai_file_path.display().to_string()
    );
    let deserialized: ExtendedJirai<PageData> = from_ejirai(&file_contents)
        .expect("Could not deserialize Extended Jirai code.");
    println!("{:?}", &deserialized.data); // should output "PageData"
    println!("{:?)", &deserialized.code); // should output HTML code
}

More information on the entities inside this crate can be obtained by reading the API documentation of this crate. The documentation can be read by cloning this repository and running the command cargo doc --open from the root of the repository.

CHANGELOG ✒️

Version 0.1.0

• Initial release.
• Initial upload to Forgejo.

Version 0.2.0

• Added support for ejirai.
• Added the ejirai feature.
• Added documentation for ejirai.

NOTE 📜

• Jirai 🖤 🎀 by Alyx Shang 🖤.
• Licensed under the FSL v1.