{"id":13438644,"url":"https://github.com/ogham/rust-ansi-term","last_synced_at":"2025-05-14T18:04:34.315Z","repository":{"id":18239374,"uuid":"21386406","full_name":"ogham/rust-ansi-term","owner":"ogham","description":"Rust library for ANSI terminal colours and styles (bold, underline)","archived":false,"fork":false,"pushed_at":"2024-08-01T16:26:07.000Z","size":207,"stargazers_count":466,"open_issues_count":27,"forks_count":79,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-08T00:08:54.554Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://crates.io/crates/ansi_term","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ogham.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-07-01T12:13:31.000Z","updated_at":"2025-05-02T00:29:56.000Z","dependencies_parsed_at":"2024-10-19T07:49:49.058Z","dependency_job_id":null,"html_url":"https://github.com/ogham/rust-ansi-term","commit_stats":{"total_commits":145,"total_committers":22,"mean_commits":6.590909090909091,"dds":"0.32413793103448274","last_synced_commit":"ff7eba98d55ad609c7fcc8c7bb0859b37c7545cc"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogham%2Frust-ansi-term","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogham%2Frust-ansi-term/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogham%2Frust-ansi-term/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogham%2Frust-ansi-term/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ogham","download_url":"https://codeload.github.com/ogham/rust-ansi-term/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253342299,"owners_count":21893558,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T03:01:07.174Z","updated_at":"2025-05-14T18:04:34.271Z","avatar_url":"https://github.com/ogham.png","language":"Rust","funding_links":[],"categories":["Libraries","Rust","库 Libraries","库"],"sub_categories":["Command-line","命令行 Command-line","命令行"],"readme":"# rust-ansi-term [![ansi-term on crates.io](http://meritbadge.herokuapp.com/ansi-term)](https://crates.io/crates/ansi_term) [![Build status](https://img.shields.io/travis/ogham/rust-ansi-term/master.svg?style=flat)](https://travis-ci.org/ogham/rust-ansi-term) [![Build status](https://img.shields.io/appveyor/ci/ogham/rust-ansi-term/master.svg?style=flat\u0026logo=AppVeyor\u0026logoColor=silver)](https://ci.appveyor.com/project/ogham/rust-ansi-term) [![Coverage status](https://coveralls.io/repos/ogham/rust-ansi-term/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/ogham/rust-ansi-term?branch=master)\n\nThis is a library for controlling colours and formatting, such as red bold text or blue underlined text, on ANSI terminals.\n\n### [View the Rustdoc](https://docs.rs/ansi_term/)\n\n\n# Installation\n\nThis crate works with [Cargo](http://crates.io). Add the following to your `Cargo.toml` dependencies section:\n\n```toml\n[dependencies]\nansi_term = \"0.12\"\n```\n\n\n## Basic usage\n\nThere are three main types in this crate that you need to be concerned with: `ANSIString`, `Style`, and `Colour`.\n\nA `Style` holds stylistic information: foreground and background colours, whether the text should be bold, or blinking, or other properties.\nThe `Colour` enum represents the available colours.\nAnd an `ANSIString` is a string paired with a `Style`.\n\n`Color` is also available as an alias to `Colour`.\n\nTo format a string, call the `paint` method on a `Style` or a `Colour`, passing in the string you want to format as the argument.\nFor example, here’s how to get some red text:\n\n```rust\nuse ansi_term::Colour::Red;\n\nprintln!(\"This is in red: {}\", Red.paint(\"a red string\"));\n```\n\nIt’s important to note that the `paint` method does *not* actually return a string with the ANSI control characters surrounding it.\nInstead, it returns an `ANSIString` value that has a `Display` implementation that, when formatted, returns the characters.\nThis allows strings to be printed with a minimum of `String` allocations being performed behind the scenes.\n\nIf you *do* want to get at the escape codes, then you can convert the `ANSIString` to a string as you would any other `Display` value:\n\n```rust\nuse ansi_term::Colour::Red;\n\nlet red_string = Red.paint(\"a red string\").to_string();\n```\n\n**Note for Windows 10 users:** On Windows 10, the application must enable ANSI support first:\n\n```rust,ignore\nlet enabled = ansi_term::enable_ansi_support();\n```\n\n## Bold, underline, background, and other styles\n\nFor anything more complex than plain foreground colour changes, you need to construct `Style` values themselves, rather than beginning with a `Colour`.\nYou can do this by chaining methods based on a new `Style`, created with `Style::new()`.\nEach method creates a new style that has that specific property set.\nFor example:\n\n```rust\nuse ansi_term::Style;\n\nprintln!(\"How about some {} and {}?\",\n         Style::new().bold().paint(\"bold\"),\n         Style::new().underline().paint(\"underline\"));\n```\n\nFor brevity, these methods have also been implemented for `Colour` values, so you can give your styles a foreground colour without having to begin with an empty `Style` value:\n\n```rust\nuse ansi_term::Colour::{Blue, Yellow};\n\nprintln!(\"Demonstrating {} and {}!\",\n         Blue.bold().paint(\"blue bold\"),\n         Yellow.underline().paint(\"yellow underline\"));\n\nprintln!(\"Yellow on blue: {}\", Yellow.on(Blue).paint(\"wow!\"));\n```\n\nThe complete list of styles you can use are:\n`bold`, `dimmed`, `italic`, `underline`, `blink`, `reverse`, `hidden`, and `on` for background colours.\n\nIn some cases, you may find it easier to change the foreground on an existing `Style` rather than starting from the appropriate `Colour`.\nYou can do this using the `fg` method:\n\n```rust\nuse ansi_term::Style;\nuse ansi_term::Colour::{Blue, Cyan, Yellow};\n\nprintln!(\"Yellow on blue: {}\", Style::new().on(Blue).fg(Yellow).paint(\"yow!\"));\nprintln!(\"Also yellow on blue: {}\", Cyan.on(Blue).fg(Yellow).paint(\"zow!\"));\n```\n\nYou can turn a `Colour` into a `Style` with the `normal` method.\nThis will produce the exact same `ANSIString` as if you just used the `paint` method on the `Colour` directly, but it’s useful in certain cases: for example, you may have a method that returns `Styles`, and need to represent both the “red bold” and “red, but not bold” styles with values of the same type. The `Style` struct also has a `Default` implementation if you want to have a style with *nothing* set.\n\n```rust\nuse ansi_term::Style;\nuse ansi_term::Colour::Red;\n\nRed.normal().paint(\"yet another red string\");\nStyle::default().paint(\"a completely regular string\");\n```\n\n\n## Extended colours\n\nYou can access the extended range of 256 colours by using the `Colour::Fixed` variant, which takes an argument of the colour number to use.\nThis can be included wherever you would use a `Colour`:\n\n```rust\nuse ansi_term::Colour::Fixed;\n\nFixed(134).paint(\"A sort of light purple\");\nFixed(221).on(Fixed(124)).paint(\"Mustard in the ketchup\");\n```\n\nThe first sixteen of these values are the same as the normal and bold standard colour variants.\nThere’s nothing stopping you from using these as `Fixed` colours instead, but there’s nothing to be gained by doing so either.\n\nYou can also access full 24-bit colour by using the `Colour::RGB` variant, which takes separate `u8` arguments for red, green, and blue:\n\n```rust\nuse ansi_term::Colour::RGB;\n\nRGB(70, 130, 180).paint(\"Steel blue\");\n```\n\n## Combining successive coloured strings\n\nThe benefit of writing ANSI escape codes to the terminal is that they *stack*: you do not need to end every coloured string with a reset code if the text that follows it is of a similar style.\nFor example, if you want to have some blue text followed by some blue bold text, it’s possible to send the ANSI code for blue, followed by the ANSI code for bold, and finishing with a reset code without having to have an extra one between the two strings.\n\nThis crate can optimise the ANSI codes that get printed in situations like this, making life easier for your terminal renderer.\nThe `ANSIStrings` struct takes a slice of several `ANSIString` values, and will iterate over each of them, printing only the codes for the styles that need to be updated as part of its formatting routine.\n\nThe following code snippet uses this to enclose a binary number displayed in red bold text inside some red, but not bold, brackets:\n\n```rust\nuse ansi_term::Colour::Red;\nuse ansi_term::{ANSIString, ANSIStrings};\n\nlet some_value = format!(\"{:b}\", 42);\nlet strings: \u0026[ANSIString\u003c'static\u003e] = \u0026[\n    Red.paint(\"[\"),\n    Red.bold().paint(some_value),\n    Red.paint(\"]\"),\n];\n\nprintln!(\"Value: {}\", ANSIStrings(strings));\n```\n\nThere are several things to note here.\nFirstly, the `paint` method can take *either* an owned `String` or a borrowed `\u0026str`.\nInternally, an `ANSIString` holds a copy-on-write (`Cow`) string value to deal with both owned and borrowed strings at the same time.\nThis is used here to display a `String`, the result of the `format!` call, using the same mechanism as some statically-available `\u0026str` slices.\nSecondly, that the `ANSIStrings` value works in the same way as its singular counterpart, with a `Display` implementation that only performs the formatting when required.\n\n## Byte strings\n\nThis library also supports formatting `[u8]` byte strings; this supports applications working with text in an unknown encoding.\n`Style` and `Colour` support painting `[u8]` values, resulting in an `ANSIByteString`.\nThis type does not implement `Display`, as it may not contain UTF-8, but it does provide a method `write_to` to write the result to any value that implements `Write`:\n\n```rust\nuse ansi_term::Colour::Green;\n\nGreen.paint(\"user data\".as_bytes()).write_to(\u0026mut std::io::stdout()).unwrap();\n```\n\nSimilarly, the type `ANSIByteStrings` supports writing a list of `ANSIByteString` values with minimal escape sequences:\n\n```rust\nuse ansi_term::Colour::Green;\nuse ansi_term::ANSIByteStrings;\n\nANSIByteStrings(\u0026[\n    Green.paint(\"user data 1\\n\".as_bytes()),\n    Green.bold().paint(\"user data 2\\n\".as_bytes()),\n]).write_to(\u0026mut std::io::stdout()).unwrap();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogham%2Frust-ansi-term","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fogham%2Frust-ansi-term","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogham%2Frust-ansi-term/lists"}