Skip to content

Commit f7d240d

Browse files
adia-devadia-dev
committed
update: 0.13.0
1 parent 9d8d7d9 commit f7d240d

File tree

2 files changed

+93
-116
lines changed

2 files changed

+93
-116
lines changed

‎LICENSE‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
MIT License
2+
3+
Copyright (c) 2024 @adia-dev
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.
22+

‎README.md‎

Lines changed: 71 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1,151 +1,106 @@
11
# Chroma
22

3-
Chroma is a Zig library that provides flexible and dynamic string formatting with ANSI color codes. It supports standard ANSI colors, ANSI 256 extended colors, and true color (24-bit) formats, allowing for colorful terminal output with ease.
3+
**Version:** 0.13.0
4+
**License:** MIT
5+
**Language:** [Zig](https://ziglang.org)
46

5-
# NOTE-test
7+
Chroma is a Zig library for advanced ANSI color and text styling in terminal output. It allows developers to dynamically format strings with embedded placeholders (e.g. `{red}`, `{bold}`, `{fg:255;100;0}` for true color) and converts them into ANSI escape sequences. This makes it easy to apply complex styles, switch between foreground/background colors, and reset formatting on the fly—all at compile time.
68

7-
> [!NOTE]
8-
> Chroma is currently in development and may not be fully functional. Please refer to the repository for the latest updates and information. It currently only support compile-time formatting. So make sure to use it in a compile-time context.
9+
## ✨ Features
910

10-
![Showcase example of the application on a terminal](./assets/chroma.png)
11+
- **Simple, Readable Syntax:**
12+
Use `{red}`, `{bold}`, or `{green,bgBlue}` inline within strings for clear and maintainable code.
1113

12-
## Table of Contents
14+
- **Comprehensive ANSI Codes:**
15+
Support for standard colors, background colors, bold, italic, underline, dim, and even less commonly supported effects like `blink` and `reverse`.
1316

14-
- [Introduction](#introduction)
15-
- [Installation](#installation)
16-
- [Usage](#usage)
17-
- [Features](#features)
18-
- [Dependencies](#dependencies)
19-
- [Configuration](#configuration)
20-
- [Documentation](#documentation)
21-
- [Examples](#examples)
22-
- [Troubleshooting](#troubleshooting)
23-
- [Contributors](#contributors)
24-
- [License](#license)
17+
- **Extended and True Color Support:**
18+
Take advantage of ANSI 256 extended color codes and true color (24-bit) formats using syntax like `{fg:120}`, `{bg:28}`, or `{fg:255;100;0}` for fine-grained color control.
2519

26-
## Introduction
20+
- **Compile-Time Safety:**
21+
Chroma verifies format strings at compile time, reducing runtime errors and ensuring your formatting instructions are valid.
2722

28-
This project aims to enhance terminal applications by enabling developers to use colors in their output more expressively and flexibly. With Chroma, you can easily format your strings with color by including color names or RGB values in curly braces within the text.
23+
- **Reset-Friendly:**
24+
Automatically appends `"\x1b[0m"` when necessary, ensuring that styles don’t “bleed” into subsequent output.
2925

30-
## Installation
26+
## 🚀 Getting Started
3127

32-
Chroma requires Zig version 0.12.0-dev.2701+d18f52197 or newer. You can include it in your Zig project by adding it as a package in your `build.zig` file:
28+
1. **Add Chroma to Your Zig Project:**
29+
Include Chroma as a dependency in your `build.zig` or your `build.zig.zon`. For example:
3330

34-
1. Fetch the project using `zig fetch` (recommended !)
31+
```zig
32+
const std = @import("std");
3533
36-
```bash
37-
zig fetch --save https://github.com/adia-dev/chroma-zig/archive/refs/tags/v0.1.0.tar.gz
38-
```
34+
pub fn build(b: *std.Build) void {
35+
const target = b.standardTargetOptions(.{});
36+
const optimize = b.standardOptimizeOption(.{});
3937
40-
Or manually paste this in your `build.zig.zon`
41-
42-
```zig
43-
.dependencies = .{
44-
// other deps...
45-
.chroma = .{
46-
.url = "https://github.com/adia-dev/chroma-zig/archive/refs/tags/v0.1.1.tar.gz",
47-
.hash = "<HASH_OF_THE_RELEASE>",
48-
},
49-
// ...
50-
},
51-
```
38+
const lib = b.addStaticLibrary(.{
39+
.name = "chroma",
40+
.root_source_file = .{ .src_path = .{ .owner = b, .sub_path = "src/lib.zig" } },
41+
.target = target,
42+
.optimize = optimize,
43+
});
5244
53-
Note that if you do not know the hash of the release, zig will spit it out as an error in the console.
45+
b.installArtifact(lib);
46+
}
47+
```
5448

55-
2. In your `build.zig`, add Chroma as a module:
49+
2. **Import and Use:**
50+
After building and installing, you can import `chroma` into your Zig code:
5651

57-
```zig
58-
// Add the chroma dep
59-
const chroma = b.dependency("chroma", .{});
60-
// Adding the module to the executable
61-
exe.root_module.addImport("chroma", chroma.module("chroma"));
62-
```
52+
```zig
53+
const std = @import("std");
54+
const chroma = @import("lib.zig");
6355
64-
3. Use `zig build` to compile your project.
65-
66-
## Usage
67-
68-
To use Chroma in your application, import the library and call the `format` function with your format string and arguments:
69-
70-
```zig
71-
const std = @import("std");
72-
const chroma = @import("lib.zig");
73-
74-
pub fn main() !void {
75-
const examples = [_]struct { fmt: []const u8, arg: ?[]const u8 }{
76-
// Basic color and style
77-
.{ .fmt = "{bold,red}Bold and Red{reset}", .arg = null },
78-
// Combining background and foreground with styles
79-
.{ .fmt = "{fg:cyan,bg:magenta}{underline}Cyan on Magenta underline{reset}", .arg = null },
80-
// Nested styles and colors
81-
.{ .fmt = "{green}Green {bold}and Bold{reset,blue,italic} to blue italic{reset}", .arg = null },
82-
// Extended ANSI color with arg example
83-
.{ .fmt = "{bg:120}Extended ANSI {s}{reset}", .arg = "Background" },
84-
// True color specification
85-
.{ .fmt = "{fg:255;100;0}True Color Orange Text{reset}", .arg = null },
86-
// Mixed color and style formats
87-
.{ .fmt = "{bg:28,italic}{fg:231}Mixed Background and Italic{reset}", .arg = null },
88-
// Unsupported/Invalid color code >= 256, Error thrown at compile time
89-
// .{ .fmt = "{fg:999}This should not crash{reset}", .arg = null },
90-
// Demonstrating blink, note: may not be supported in all terminals
91-
.{ .fmt = "{blink}Blinking Text (if supported){reset}", .arg = null },
92-
// Using dim and reverse video
93-
.{ .fmt = "{dim,reverse}Dim and Reversed{reset}", .arg = null },
94-
// Custom message with dynamic content
95-
.{ .fmt = "{blue,bg:magenta}User {bold}{s}{reset,0;255;0} logged in successfully.", .arg = "Charlie" },
96-
// Combining multiple styles and reset
97-
.{ .fmt = "{underline,cyan}Underlined Cyan{reset} then normal", .arg = null },
98-
// Multiple format specifiers for complex formatting
99-
.{ .fmt = "{fg:144,bg:52,bold,italic}Fancy {underline}Styling{reset}", .arg = null },
100-
// Jujutsu Kaisen !!
101-
.{ .fmt = "{bg:72,bold,italic}Jujutsu Kaisen !!{reset}", .arg = null },
102-
};
103-
104-
inline for (examples) |example| {
105-
if (example.arg) |arg| {
106-
std.debug.print(chroma.format(example.fmt) ++ "\n", .{arg});
107-
} else {
108-
std.debug.print(chroma.format(example.fmt) ++ "\n", .{});
109-
}
110-
}
111-
112-
std.debug.print(chroma.format("{blue}{underline}Eventually{reset}, the {red}formatting{reset} looks like {130;43;122}{s}!\n"), .{"this"});
113-
}
56+
pub fn main() !void {
57+
std.debug.print(chroma.format("{bold,red}Hello, Red World!{reset}\n"), .{});
58+
}
59+
```
11460

115-
```
61+
3. **Run and Test:**
62+
- Build your project with `zig build`.
63+
- Run your binary and see the styled output in your terminal!
64+
65+
## 🧪 Testing
11666

117-
## Features
67+
Chroma includes a suite of unit tests to ensure reliability:
11868

119-
- **Standard ANSI Colors**: Easily use standard ANSI colors in your strings.
120-
- **ANSI 256 Colors**: Utilize the extended set of 256 colors for more detailed color output.
121-
- **True Colors**: Use true color (24-bit) RGB values for precise color representation.
122-
- **Flexible Formatting**: Combine colors, reset styles, and include text dynamically within your format strings.
123-
- **Compile-Time Checks**: The format function is evaluated at compile-time, ensuring that your color format strings are valid.
69+
```bash
70+
zig build test
71+
```
12472

125-
## Dependencies
73+
If all tests pass, you’re good to go!
12674

127-
Chroma does not currently have any external dependencies beyond the Zig standard library.
75+
## 🔧 Configuration
12876

129-
## Configuration
77+
Chroma works out-of-the-box. For more complex scenarios (e.g., custom labels, multiple color formats), refer to `src/lib.zig` and `src/ansi.zig` for detailed code comments that explain available options and their intended usage.
13078

131-
No additional configuration is required to use Chroma in your Zig projects.
79+
## 📦 New in Version 0.13.0
13280

133-
## Documentation
81+
- **Updated Compatibility:** Now aligned with Zig `0.13.0`.
82+
- **Improved Parser Logic:** More robust handling of multiple formats within the same placeholder.
83+
- **Better Testing:** Additional tests ensure extended color and true color formats behave as expected.
84+
- **Performance Tweaks:** Minor compile-time optimizations for faster builds.
13485

135-
For detailed documentation on available colors and usage patterns, refer to the source files in the `src` directory. The main API is provided through `src/lib.zig`, with utility functions and ANSI color definitions located in `src/utils.zig` and `src/ansi.zig`, respectively.
86+
## 🤝 Contributing
13687

137-
## Examples
88+
Contributions are welcome! To get involved:
13889

139-
You can find an example of how to [use Chroma](https://github.com/adia-dev/use-chroma-zig) in this repository.
90+
1. **Fork & Clone:**
91+
Fork the repository and clone it locally.
14092

141-
## Troubleshooting
93+
2. **Branch & Develop:**
94+
Create a new branch and implement your changes or new features.
14295

143-
If you encounter any issues with compiling or using Chroma, ensure you are using a compatible Zig version. For further assistance, consult the Zig community resources or submit an issue on the Chroma GitHub repository.
96+
3. **Test & Document:**
97+
Run `zig build test` to ensure your changes haven’t broken anything. Update or add documentation as needed.
14498

145-
## Contributors
99+
4. **Pull Request:**
100+
Submit a Pull Request describing what you changed and why. We’ll review and merge it if everything looks good.
146101

147-
Contributions to Chroma are welcome! If you would like to contribute, please submit a pull request or issue on GitHub.
102+
## 📝 License
148103

149-
## License
104+
[MIT License](./LICENSE)
150105

151-
Chroma is open-source software licensed under the MIT license. For more details, see the LICENSE file in the repository.
106+
_Chroma aims to simplify ANSI coloring in Zig, making your command-line tools, logs, and output more expressive and visually appealing._

0 commit comments

Comments
 (0)