{"id":23385548,"url":"https://github.com/souravgoswami/string_dot_gradient","last_synced_at":"2025-04-11T03:43:28.208Z","repository":{"id":59156630,"uuid":"327618056","full_name":"Souravgoswami/string_dot_gradient","owner":"Souravgoswami","description":"An itty-bitty extension that adds gradient method to String class that supports any hex colour, for Linux terminals only","archived":false,"fork":false,"pushed_at":"2021-06-25T15:20:09.000Z","size":2671,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-10T06:40:53.103Z","etag":null,"topics":["colour","gradient","itty-bitty-extension","linux-terminals","rubygem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/Souravgoswami.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-07T13:20:34.000Z","updated_at":"2021-06-25T15:20:12.000Z","dependencies_parsed_at":"2022-09-13T20:10:22.097Z","dependency_job_id":null,"html_url":"https://github.com/Souravgoswami/string_dot_gradient","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Souravgoswami%2Fstring_dot_gradient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Souravgoswami%2Fstring_dot_gradient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Souravgoswami%2Fstring_dot_gradient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Souravgoswami%2Fstring_dot_gradient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Souravgoswami","download_url":"https://codeload.github.com/Souravgoswami/string_dot_gradient/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248339289,"owners_count":21087213,"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":["colour","gradient","itty-bitty-extension","linux-terminals","rubygem"],"created_at":"2024-12-22T00:19:20.824Z","updated_at":"2025-04-11T03:43:28.181Z","avatar_url":"https://github.com/Souravgoswami.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StringDotGradient [![Gem Version](https://badge.fury.io/rb/string_dot_gradient.svg)](https://rubygems.org/gems/string_dot_gradient) ![Test](https://github.com/souravgoswami/string_dot_gradient/workflows/StringDotGradient/badge.svg)\n\nAn itty-bitty extension that adds gradient method to String class that supports any hex colour, for Linux terminals only:\n\n![Preview](https://github.com/Souravgoswami/string_dot_gradient/blob/master/images/preview.jpg)\n\n## Installation\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'string_dot_gradient'\n```\n\nAnd then execute:\n\n```\n$ bundle install\n```\n\nOr install it yourself as:\n\n```\n$ gem install string_dot_gradient\n```\n\n## Usage\n\n### With this gem installed, you can require 'string_dot_gradient' and run this on any string:\n\n```\nirb\nirb(main):001:0\u003e require 'string_dot_gradient'\n=\u003e true\n\nirb(main):002:0\u003e puts 'abcdefgh'.gradient('ff5', '55f')\nabcdefgh\n=\u003e nil\n\nirb(main):003:0\u003e puts 'abcdefgh'.gradient(0xffff55, 0x5555ff)\nabcdefgh\n=\u003e nil\n```\n\nThis actually generates ANSI sequences to create gradient colours:\n\n```\nirb(main):004:0\u003e 'abcdefgh'.gradient('ff5', '55f')\n=\u003e \"\\e[38;2;223;223;116ma\\e[38;2;191;191;148mb\\e[38;2;159;159;180mc\\e[38;2;127;127;212md\\e[38;2;95;95;244me\\e[38;2;63;63;255mf\\e[38;2;31;31;255mg\\e[38;2;0;0;255mh\\e[0m\"\n\nirb(main):005:0\u003e 'abcdefgh'.gradient(0xff5555, 0x5555ff)\n=\u003e \"\\e[38;2;223;223;116ma\\e[38;2;191;191;148mb\\e[38;2;159;159;180mc\\e[38;2;127;127;212md\\e[38;2;95;95;244me\\e[38;2;63;63;255mf\\e[38;2;31;31;255mg\\e[38;2;0;0;255mh\\e[0m\"\n```\n\n### You can also pass any arbitrary colours for multilined string, and get the colours rotate smoothly:\n\n```\nputs \"Hello 🐵\\nI am using string_dot_gradient!\\nLove this gem!\".gradient('f55', '55f', '3eb', 'f5f')\n```\n\n### Here's how the real method definition of gradient looks like:\n\n```\ndef gradient(*arg_colours,\n\texclude_spaces: true,\n\tbg: false,\n\tbold: false,\n\tblink: false,\n\tunderline: false,\n\tdouble_underline: false,\n\toverline: false,\n\titalic: false,\n\tstrikethrough: false\n\t)\n```\n\nDo note that the strikethrough, overline, double_underline may not work on every terminal.\nThe blink might not work on terminals that don't implement cursor blinking (integrated terminals in some IDE for example)\n\n### Colours\n\n##### The gradient can be any hex colour. Sample colours can be:\n\n1. #f55\n2. #ff5555\n3. f55\n4. ff5555\n5. 0xff5555\n\n##### Integer Colours:\nWhen an integer colour is passed, the conversion will be faster than a string parsing.\n\n+ For example: 0xffffff for white,\n+ 0x000000 or 0x0 for black, 0x00aa00 for deep green\n+ 0xff50a6 for pink, 0xff5555 for light red, etc.\n\nSimilarly you can use Integers directly (not recommended though):\n+ (255 * 256 * 256) + (255 * 256) + (255) =\u003e 0xffffff\n+ (0 * 256 * 256) + (0 * 256) + 0 =\u003e 0x0\n+ (255 * 256 * 256) + (85 * 256) + 85 =\u003e #ff5555\n+ (85 * 256 * 256) + (85 * 256) + 255 =\u003e #5555ff\n+ (255 * 256 * 256) + (170 * 256) + 0 =\u003e 0xffaa00\n+ (0 * 256 * 256) + (170 * 256) + 0 =\u003e 0x00aa00\n\n##### Bad Colours:\n+ Using any bad Integer can do the following:\n  + 0x00aa00aa00aa (any big Integer) will be aa00aa, clamping to last 6 hex digits.\n  + 0x0a0 (hex \u003c 6 digit) will be 0000a0, shifting the value to right.\n  + Negative Integer will cause unexpected output, but won't cause any major crash.\n+ Any bad String colour that's out of hex range, will raise ArgumentError.\n\n### From version 0.3.0, there's also a method called `String#multi_gradient()`\n\n```\n'Hello world this is multi_gradient()'.multi_gradient('3eb', '55f', 'f55', 'fa0')\n\"Hello world\\nthis is multi_gradient()\".multi_gradient('3eb', '55f', 'f55', 'fa0')\n\n# Or #\n'Hello world this is multi_gradient()'.multi_gradient(0x33eebb, 0x5555ff, 0xff5555, 0xffaa00)\n'Hello world\\nthis is multi_gradient()'.multi_gradient(0x33eebb, 0x5555ff, 0xff5555, 0xffaa00)\n```\n\nYou can pass N number of colours to multigradient, and prints that in one line.\nmulti_gradient() also accepts, bold, blink, underline, etc options that gradient() accepts.\n\nDo note that multiline colours will not get rotated like String#gradient(), but will be applied to each line instead.\n\n![Preview](https://github.com/Souravgoswami/string_dot_gradient/blob/master/images/multi_gradient.jpg)\n\n### Passing Blocks\nSometimes it can be time-consuming for a very big string. Also, this could consume a lot of memory.\nJust take a look at the return value of \"abcdefgh\" above, you know it has a lot of extra characters!\n\nTo prevent creating a new string, and yield whatever is getting processed, use a block.\n\nYou can use printf and whatnot in that block. For example:\n\n```\n$ irb\nirb(main):001:0\u003e require 'string_dot_gradient'\n=\u003e true\n\nirb(main):002:0\u003e \"Hello\\nWorld\".gradient(0xff5555, 0x5555ff) { |x| print x }\nHello\nWorld=\u003e nil\n\nirb(main):003:0\u003e \"Hello\\nWorld\".gradient('#f55', '#55f') { }\n=\u003e nil\n\n```\n\nAs you can see, it returns nil, but the value of the string is yielded to the block variable instead.\nThis makes it consume way lesser memory.\n\n### Animation\nYou can animate your text using blocks!\n\nHere's an example:\n\n![Preview](https://github.com/Souravgoswami/string_dot_gradient/blob/master/images/preview.gif)\n\nCode used:\n\n```\nrequire 'io/console'\nrequire 'string_dot_gradient'\n\nw = STDOUT.winsize[1] - 4\ni = -1\n\nstory = \u003c\u003c~'EOF'.gsub(?\\n, ?\\s)\n\tFour cows lived in a forest near a meadow. They were good friends and did\n\teverything together. They grazed together and stayed together, because of\n\twhich no tigers or lions were able to kill them for food. But one day, the friends\n\tfought and each cow went to graze in a different direction. A tiger and a lion saw\n\tthis and decided that it was the perfect opportunity to kill the cows. They hid in\n\tthe bushes and surprised the cows and killed them all, one by one.\nEOF\n\n# Adding new lines to the story based on the terminal size\nstory_with_newline = story.chars.each { |x|\n\ti += 1\n\n\t# Check if the w-th character exceeds the terminal size or not\n\t# If it exceeds the size, add a new line in the story\n\n\tif i \u003e w || i \u003e w - 6 \u0026\u0026 x == ?\\s.freeze\n\t\tx.rstrip!\n\t\tx \u003c\u003c ?\\n.freeze\n\t\ti = 0\n\tend\n}.join\n\nstory_with_newline.gradient('f55', '55f', '3eb', 'fa0', 'ff50a6', 'ff0') { |x|\n\tprint x\n\tsleep 0.01\n}\n\nputs\n```\n\n[ Story from: https://moralstories.top/read/the-cows-and-the-tiger ]\n\nYou can also use multi_gradient() and pass blocks, to yield the characters\nto the block instead.\n\n\n## Excluding Spaces and tabs\nA string can contain spaces or tabs, to exclude them, use the exclude_spaces optional.\nSet it to true or false. A truthy or falsey value will also work, but it's not recommended.\n\n+ if exclude_spaces is set to true, it will not waste colours on spaces and tabs\n+ if exclude_spaces is set to false, it will waste colours on spaces and tabs\n\n![Preview](https://github.com/Souravgoswami/string_dot_gradient/blob/master/images/exclude_spaces.jpg)\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies.\nYou can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/Souravgoswami/string_dot_gradient.\n\n## License\n\nThe gem is available as open-source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouravgoswami%2Fstring_dot_gradient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsouravgoswami%2Fstring_dot_gradient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsouravgoswami%2Fstring_dot_gradient/lists"}