{"id":13687306,"url":"https://github.com/serokell/haskell-with-utf8","last_synced_at":"2025-04-15T04:15:17.256Z","repository":{"id":54437503,"uuid":"240806300","full_name":"serokell/haskell-with-utf8","owner":"serokell","description":"Get your IO right on the first try","archived":false,"fork":false,"pushed_at":"2025-04-14T02:01:14.000Z","size":163,"stargazers_count":54,"open_issues_count":4,"forks_count":3,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-14T03:19:34.676Z","etag":null,"topics":["files","haskell","input-output","unicode","utf8"],"latest_commit_sha":null,"homepage":"https://serokell.io/blog/haskell-with-utf8","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/serokell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSES/MPL-2.0.txt","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}},"created_at":"2020-02-16T00:09:21.000Z","updated_at":"2025-03-31T14:29:31.000Z","dependencies_parsed_at":"2023-12-12T16:51:27.011Z","dependency_job_id":"ba1e0423-d70e-4d9d-9a48-23d00da81f31","html_url":"https://github.com/serokell/haskell-with-utf8","commit_stats":{"total_commits":65,"total_committers":3,"mean_commits":"21.666666666666668","dds":0.03076923076923077,"last_synced_commit":"d1dc7d55b11438487c018b5ef0d3815767add6d9"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serokell%2Fhaskell-with-utf8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serokell%2Fhaskell-with-utf8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serokell%2Fhaskell-with-utf8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serokell%2Fhaskell-with-utf8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serokell","download_url":"https://codeload.github.com/serokell/haskell-with-utf8/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248813909,"owners_count":21165647,"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":["files","haskell","input-output","unicode","utf8"],"created_at":"2024-08-02T15:00:52.104Z","updated_at":"2025-04-15T04:15:17.223Z","avatar_url":"https://github.com/serokell.png","language":"Haskell","funding_links":[],"categories":["Haskell"],"sub_categories":[],"readme":"# `with-utf8`\n\nGet your IO right on the first try.\n\nReading files in Haskell is trickier than it could be due to the non-obvious\ninteractions between file encodings and system locale. This library is meant\nto make it easy once and for all by providing “defaults” that make more sense\nin the modern world.\n\nSee [this blog post][blog:post] for more details on why this library needs to\nexists and an explanation of some of the opinionated decisions it is based on.\n\n[blog:post]: https://serokell.io/blog/haskell-with-utf8\n\n\n## Use\n\nSee the documentation on Hackage for details, this is a quick summary.\n\n### Step 1: Get it\n\nThe [library is on Hackage][hackage:with-utf8],\ngo ahead and add it to the dependencies of your project.\n\n[hackage:with-utf8]: https://hackage.haskell.org/package/with-utf8\n\n### Step 2: Wrap your `main`\n\nImport `withUtf8` from `Main.Utf8` and wrap it around your `main`:\n\n```haskell\nimport Main.Utf8 (withUtf8)\n\nmain :: IO ()\nmain = withUtf8 $\n  {- ... your main function ... -}\n```\n\nThis will make sure that if your program reads something from `stdin` or\noutputs something to `stdout`/`stderr`, it will not fail with a runtime\nerror due to encoding issues.\n\n### Step 3: Read files using UTF-8\n\nIf you are going to read a text file (to be precise, if you are going to open\na file in text mode), you’ll probably use `withFile`, `openFile`, or `readFile`.\nGrab the first two from `System.IO.Utf8` or the latter from `Data.Text.IO.Utf8`.\nStarting from `text-2.1`, `Data.Text.IO.Utf8` is available in the `text` package\nitself, hence this module in `with-utf8` is now deprecated.\n\n_Note: it is best to import these modules qualified._\n\n_Note: there is no `System.IO.Utf8.readFile` because it’s 2024 and\nyou should not read `String`s from files._\n\nAll these functions will make sure that the content will be treated as if it\nwas encoded in UTF-8.\n\nIf, for some reason, you really need to use `withFile`/`openFile` from `base`,\nor you got your file handle from somewhere else, wrap the code that works\nwith it in a call to `withHandle` from `System.IO.Utf8`:\n\n```haskell\nimport qualified System.IO as IO\nimport qualified System.IO.Utf8 as Utf8\n\ndoSomethingWithAFile :: IO.Handle -\u003e IO ()\ndoSomethingWithAFile h = Utf8.withhandle h $ do\n    {- ... work with the file ... -}\n```\n\n### Step 4: Write files using UTF-8\n\nWhen writing a file either open it using `withFile`/`openFile` from\n`System.IO.Utf8` or write to it directly with `writeFile` from\n`Data.Text.IO.Utf8`.\nStarting from `text-2.1`, `Data.Text.IO.Utf8` is available in the `text` package\nitself, hence this module in `with-utf8` is now deprecated.\n\n_Note: it is best to import these modules qualified._\n\n_Note: there is no `System.IO.Utf8.writeFile`._\n\nIf, for some reason, you really need to use `withFile`/`openFile` from `base`,\ndo the same as in the previous step.\n\n## Troubleshooting\n\nLocales are pretty straightforward, but some people might have their terminals\nmisconfigured for various reasons. To help troubleshoot any potential issues,\nthis package comes with a tool called `utf8-troubleshoot`.\n\nThis tool outputs some basic information about locale settings in the OS and\nwhat they end up being mapped to in Haskell. If you are looking for help,\nplease, provide the output of this tool, or if you are helping someone,\nask them to run this tool and provide the output.\n\n## Contributing\n\nIf you encounter any issues when using this library or have improvement ideas,\nplease open report in issue on GitHub. You are also very welcome to submit\npull request, if you feel like doing so.\n\n\n## License\n\n[MPL-2.0] © [Serokell]\n\n[MPL-2.0]: https://spdx.org/licenses/MPL-2.0.html\n[Serokell]: https://serokell.io/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserokell%2Fhaskell-with-utf8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserokell%2Fhaskell-with-utf8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserokell%2Fhaskell-with-utf8/lists"}