{"id":13714205,"url":"https://github.com/go-compression/raisin","last_synced_at":"2025-05-07T01:32:41.787Z","repository":{"id":57538932,"uuid":"277634345","full_name":"go-compression/raisin","owner":"go-compression","description":"A simple lightweight set of implementations and bindings for compression algorithms written in Go.","archived":false,"fork":false,"pushed_at":"2021-05-20T22:58:29.000Z","size":4747,"stargazers_count":20,"open_issues_count":3,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-03T23:29:53.541Z","etag":null,"topics":["algorithms","command-line","command-line-tool","compression","compression-algorithms","decompression","go","hacktoberfest","huffman","information-theory","lzss"],"latest_commit_sha":null,"homepage":"https://go-compression.github.io/raisin/","language":"Go","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/go-compression.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-06T19:47:09.000Z","updated_at":"2023-09-29T03:59:51.000Z","dependencies_parsed_at":"2022-09-26T17:51:33.624Z","dependency_job_id":null,"html_url":"https://github.com/go-compression/raisin","commit_stats":null,"previous_names":["mrfleap/custom-compression"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-compression%2Fraisin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-compression%2Fraisin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-compression%2Fraisin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-compression%2Fraisin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/go-compression","download_url":"https://codeload.github.com/go-compression/raisin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224551174,"owners_count":17330090,"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":["algorithms","command-line","command-line-tool","compression","compression-algorithms","decompression","go","hacktoberfest","huffman","information-theory","lzss"],"created_at":"2024-08-02T23:01:54.786Z","updated_at":"2024-11-14T01:30:46.962Z","avatar_url":"https://github.com/go-compression.png","language":"Go","readme":"# Raisin\n\n[![Build Status](https://travis-ci.com/go-compression/raisin.svg?branch=master)](https://travis-ci.com/go-compression/raisin) [![Go Report Card](https://goreportcard.com/badge/github.com/go-compression/raisin)](https://goreportcard.com/report/github.com/go-compression/raisin) [![Coverage Status](https://coveralls.io/repos/github/go-compression/raisin/badge.svg?branch=master)](https://coveralls.io/github/go-compression/raisin?branch=master) [![Documentation](https://godoc.org/github.com/yangwenmai/how-to-add-badge-in-github-readme?status.svg)](http://godoc.org/github.com/go-compression/raisin)\n\n[View benchmarks for latest deployment](https://go-compression.github.io/raisin/)\n\nA simple lightweight set of implementations and bindings for compression algorithms written in Go.\n\nThis project contains the source code for a summer mentorship about learning how to implement and create different compression algorithms. This includes common algorithms such as huffman, lempel-ziv, and arithmetic along with bindings for builtin Go compression algorithms.\n\n## Usage from the CLI\n\nTo start using this package from the command line, install it with `go get` and `go install`\n\n```console\n$ go get -u github.com/go-compression/raisin\n$ go install github.com/go-compression/raisin/cmd/...\n```\n\nOnce done, you should be able to start using it\n\n```console\n$ echo \"Hello world!\" \u003e test.txt\n$ raisin test.txt\nCompressing...\nOriginal bytes: 13\nCompressed bytes: 14\nCompression ratio: 107.69%\n$ cat test.txt.rsn\n\u0014�ӷ     �?��KD+\n               �\n$ rm test.txt\n$ raisin -decompress test.txt.rsn\nDecompressing...\n$ cat test.txt\nHello world!\n```\n\nThe possible commands include:\n\n- `-compress` - Compress a given file and output the compressed contents to a file with \".rsn\" at the end\n- `-decompress` - Decompress a given file and output the decompressed contents to a file without \".rsn\" at the end\n- `-benchmark` - Benchmark a given file and measure the compression ratio, outputs a .rsn and a .decompressed file\n\nThe most important flag is the `-algorithm` flag which allows you to specify which algorithm to use during compression, decompression, or benchmarking. By default for `compress` and `decompress` this is `lzss,arithmetic`. The possible algorithms include:\n\n- lzss\n- dmc\n- huffman\n- mcc\n- arithmetic\n- flate\n- gzip\n- lzw\n- zlib\n\nHere's an example of usage:\n\n```console\n$ raisin -algorithm=arithmetic test.txt\n```\n\nYou can also combine algorithms together in \"layers\", this will essentially compress the file with the first algorithm, then the second, etc. This stacking of algorithms is what powers virtually all modern compression, gzip and zip is powered by the FLATE algorithm which is essentially lempel-ziv (similar to lzss) and huffman coding stacked on toip of each other.\n\n```console\n$ raisin -algorithm=lzss,huffman test.txt\nCompressing...\nCompression ratio: 307.69%\n$ raisin -decompress -algorithm=lzss,huffman test.txt.rsn\nDecompressing...\n```\n\nOn top of this, you can easily compress or decompress multiple files by chaining them together with commas.\n\n```console\n$ raisin test1.txt,test2.txt\nCompressing...\nCompression ratio: 68.53%\n$ ls\ntest1.txt  test1.txt.rsn  test2.txt  test2.txt.rsn\n```\n\nWhen using `compress` and `decompress` a few more options become available to make it easy to use from the command line:\n\n- `delete` - Delete original file after compression/decompressed (defaults to true for decompression)\n- `out` - File name to be outputted (defaults to original file + .rsn for compression and file - .rsn for decompression, only available with a single file being compressed/decompressed)\n- `outext` - File extension to be outputted when compressing multiple files (unavailable with a single file being compressed/decompressed)\n\nLet's take at the usage of `delete`, keep in mind that `delete` is on by default for `decompress`ing.\n\n```console\n$ echo \"Hello world!\" \u003e test.txt\n$ raisin -delete test.txt\nCompressing...\nCompression ratio: 107.69%\n$ ls\ntest.txt.rsn\n$ raisin -decompress -delete test.txt.rsn\nDecompressing...\n$ ls\ntest.txt\n$ raisin -delete=false test.txt\nCompressing...\nCompression ratio: 107.69%\n$ ls\ntest.txt  test.txt.rsn\n```\n\nThe `out` command simply lets you change what file is outputted when compressing a single file:\n\n```console\n$ echo \"Hello world!\" \u003e test.txt\n$ raisin -out=compressed.txt test.txt\nCompressing...\nCompression ratio: 107.69%\n$ ls\ntest.txt  compressed.txt\n$ raisin -decompress -out=decompressed.txt compressed.txt\nDecompressing...\n$ ls\ntest.txt  decompressed.txt\n```\n\n`outext` is similar to `out` but exists for when we compress/decompress multiple files. If `outext` is provided, it will be used as the **out**put **ext**ension for the files. Note that the default for compression for outext is `.rsn` and for decompression it's an empty string (`outext=`) which tells the program to remove the last extension.\n\n```console\n$ ls\ntest1.txt  test2.txt  test3.txt\n$ raisin -delete -outext=.testing test1.txt,test2.txt,test3.txt\nCompressing...\nCompression ratio: 107.69%\n$ ls\ntest1.txt.testing  test2.txt.testing  test3.txt.testing\n$ raisin -decompress -outext=.decompressed test1.txt.testing,test2.txt.testing,test3.txt.testing\nDecompressing...\n$ ls\ntest1.txt  test2.txt  test3.txt\n```\n\n## Benchmarking\n\nYou can use the `benchmark` command to generate benchmarked results for a set of algorithms, layers, and files. This is helpful for generating results in a table, [website](https://go-compression.github.io/raisin/), or in bindings for other languages such as python (see the `ai` folder).\n\nUsage is relatively similar to the `compress` and `decompress` commands.\n\n```console\n$ echo \"Hello world!\" \u003e test.txt\n$ echo \"abcabcabcabcabcabcabcabc\" \u003e test2.txt\n$ raisin -benchmark -algorithm=lzss,huffman,arithmetic,gzip,[lzss,arithmetic] test.txt,test2.txt\n┌─────────────────┬────────────┬───────────────────┬────────────────┬─────────────────────┬──────────┐\n│ ENGINE          │ TIME TAKEN │ COMPRESSION RATIO │ ACTUAL ENTROPY │ THEORETICAL ENTROPY │ LOSSLESS │\n├─────────────────┼────────────┼───────────────────┼────────────────┼─────────────────────┼──────────┤\n│ lzss            │ 350µs      │ 100.00%           │ 2.20           │ 2.20                │ true     │\n│ arithmetic      │ 50µs       │ 107.69%           │ 2.12           │ 2.20                │ true     │\n│ lzss,arithmetic │ 210µs      │ 107.69%           │ 2.12           │ 2.20                │ true     │\n│ gzip            │ 280µs      │ 284.62%           │ 1.14           │ 2.20                │ true     │\n│ huffman         │ 190µs      │ 307.69%           │ 1.08           │ 2.20                │ true     │\n├─────────────────┼────────────┼───────────────────┼────────────────┼─────────────────────┼──────────┤\n│ File            │ test.txt   │ Size              │ 13 B           │                     │          │\n└─────────────────┴────────────┴───────────────────┴────────────────┴─────────────────────┴──────────┘\n┌─────────────────┬────────────┬───────────────────┬────────────────┬─────────────────────┬──────────┐\n│ ENGINE          │ TIME TAKEN │ COMPRESSION RATIO │ ACTUAL ENTROPY │ THEORETICAL ENTROPY │ LOSSLESS │\n├─────────────────┼────────────┼───────────────────┼────────────────┼─────────────────────┼──────────┤\n│ lzss,arithmetic │ 160µs      │ 84.00%            │ 1.25           │ 1.22                │ true     │\n│ lzss            │ 310µs      │ 84.00%            │ 1.25           │ 1.22                │ true     │\n│ arithmetic      │ 160µs      │ 84.00%            │ 1.25           │ 1.22                │ true     │\n│ huffman         │ 170µs      │ 92.00%            │ 1.24           │ 1.22                │ true     │\n│ gzip            │ 430µs      │ 120.00%           │ 1.17           │ 1.22                │ true     │\n├─────────────────┼────────────┼───────────────────┼────────────────┼─────────────────────┼──────────┤\n│ File            │ test2.txt  │ Size              │ 25 B           │                     │          │\n└─────────────────┴────────────┴───────────────────┴────────────────┴─────────────────────┴──────────┘\n```\n\nA larger example, taken from the `.travis.yml` file to generate the [benchmark page](https://go-compression.github.io/raisin/). Notice the `-generate` flag, this tells it to generate an html file and output it as `index.html`, which is then used and uploaded to the [GitHub Pages branch](https://github.com/go-compression/raisin/tree/gh-pages). Keep in mind the program expects a template file to be at `templates/benchmark.html` relative to your working directory. The command is as follows:\n\n```console\n$ raisin -benchmark -generate -algorithm=lzss,dmc,huffman,flate,gzip,lzw,zlib,arithmetic,[lzss,huffman],[lzss,arithmetic],[arithmetic,huffman] alice29.txt,asyoulik.txt,cp.html,fields.c,grammar.lsp,kennedy.xls,lcet10.txt,plrabn12.txt,ptt5,sum,xargs.1\n```\n\nShout-out to [jedib0t](https://github.com/jedib0t) for his wonderful [go-pretty module](https://github.com/jedib0t/go-pretty) for generating these tables and the HTML tables used in the GitHub Pages site.\n\n## Building\n\nTo build the binary from source, simply `go get` the package:\n\n```console\n$ go get -u github.com/go-compression/raisin\n```\n\nInstall the dependencies:\n\n```console\n$ go get\n```\n\nAnd build:\n\n```console\n$ go build\n```\n\n## Usage as a module\n\nTo use this package as a module, simply import the engine package and use the io.Reader and io.Writer interfaces.\n\n```go\nimport (\n\t\"fmt\"\n\t\"github.com/go-compression/raisin/engine\"\n)\n\nfunc main() {\n\ttext := []byte(\"Hello world!\")\n\n\tfile := engine.CompressedFile{}\n\tfile.CompressionEngine = \"arithmetic\"\n\tfile.Write(text)\n\tfmt.Println(\"Compressed:\", string(file.Compressed))\n}\n```\n\n## Documentation\n\nDocumentation is available at [godoc](https://godoc.org/github.com/go-compression/raisin), please note that most of the code is currently undocumented as it is still a work in progress.\n","funding_links":[],"categories":["Repositories"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-compression%2Fraisin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgo-compression%2Fraisin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-compression%2Fraisin/lists"}