{"id":17643470,"url":"https://github.com/sztheory/zaru_crystal","last_synced_at":"2025-05-07T00:26:41.554Z","repository":{"id":52824370,"uuid":"209103703","full_name":"szTheory/zaru_crystal","owner":"szTheory","description":"Crystal shard for filename sanitization","archived":false,"fork":false,"pushed_at":"2021-04-17T20:36:23.000Z","size":43,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-06T15:21:42.032Z","etag":null,"topics":["crystal","filename","sanitization","shard"],"latest_commit_sha":null,"homepage":"","language":"Crystal","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/szTheory.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","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":"2019-09-17T16:27:57.000Z","updated_at":"2024-05-04T00:39:53.000Z","dependencies_parsed_at":"2022-08-22T21:31:24.291Z","dependency_job_id":null,"html_url":"https://github.com/szTheory/zaru_crystal","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szTheory%2Fzaru_crystal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szTheory%2Fzaru_crystal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szTheory%2Fzaru_crystal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szTheory%2Fzaru_crystal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/szTheory","download_url":"https://codeload.github.com/szTheory/zaru_crystal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242868288,"owners_count":20198444,"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":["crystal","filename","sanitization","shard"],"created_at":"2024-10-23T09:04:54.065Z","updated_at":"2025-03-10T14:31:31.312Z","avatar_url":"https://github.com/szTheory.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"zaru_crystal\n====\n[![Build Status](https://travis-ci.org/szTheory/zaru_crystal.svg?branch=master)](https://travis-ci.org/szTheory/zaru_crystal) [![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://sztheory.github.io/zaru_crystal/) [![GitHub release](https://img.shields.io/github/release/szTheory/zaru_crystal.svg)](https://github.com/szTheory/zaru_crystal/releases) ![GitHub stars](https://img.shields.io/github/stars/szTheory/zaru_crystal?style=social)\n\nFilename sanitization for Crystal. This is useful when you generate filenames for downloads from user input. Port of the [Zaru gem for Ruby](https://github.com/madrobby/zaru). \n\n## Installation\n\n1. Add the dependency to your `shard.yml`:\n\n```yaml\n dependencies:\n   zaru_crystal:\n     github: szTheory/zaru_crystal\n```\n\n2. Run `shards install`\n\n## Usage\n\n```crystal\nrequire \"zaru_crystal\"\n```\n\n```crystal\nZaru.sanitize! \"  what\\ēver//wëird:user:înput:\"\n# =\u003e \"whatēverwëirduserînput\"\n```\n\nZaru takes a given filename (a string) and normalizes, filters and truncates it.\n\nIt removes the bad stuff but leaves unicode characters in place, so users can use whatever alphabets they want to. Zaru also doesn't remove whitespace– instead, any sequence of whitespace that is 1 or more characters in length is collapsed to a single space. Filenames are truncated so that they are at maximum 255 characters long.\n\nIf extra breathing room is required (for example to add your own filename extension later),\nyou can leave extra room with the `:padding` option:\n\n```crystal\nZaru.sanitize! \"A\"*400, padding: 100\n# resulting filename is 145 characters long\n```\n\nIf you need to customize the fallback filename you can add your own fallback\nwith the `:fallback` option:\n\n```crystal\nZaru.sanitize! \"\u003c\u003c\u003c\", fallback: \"no_file\"\n# resulting filename is \"no_file\"\n```\n\nBad things in filenames\n-----------------------\n\nWikipedia has a [good overview on filenames](http://en.wikipedia.org/wiki/Filename). Basically, on modern-ish operating systems, the following characters  are considered no-no (Zaru filters these):\n\n```\n/ \\ ? * : | \" \u003c \u003e\n```\n\nAdditionally the [ASCII control characters](http://en.wikipedia.org/wiki/ASCII#ASCII_control_characters) (hexadecimal `00` to `1f`) are filtered.\n\nAll [Unicode whitespace](http://en.wikipedia.org/wiki/Whitespace_character#Unicode) at the beginning and end of the potential filename is removed, and any Unicode whitespace within the filename is collapse to a single space character.\n\n[Certain filenames are reserved in Windows](http://msdn.microsoft.com/en-us/library/windows/desktop/aa365247%28v=vs.85%29.aspx) and are filtered.\n\n\n[Wait, what, Zaru?](http://en.wikipedia.org/wiki/Zaru)\n\n[zaru_crystal](https://github.com/szTheory/zaru_crystal) is licensed under the terms of the MIT license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsztheory%2Fzaru_crystal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsztheory%2Fzaru_crystal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsztheory%2Fzaru_crystal/lists"}