{"id":13801621,"url":"https://github.com/scodec/scodec","last_synced_at":"2025-05-13T19:16:20.984Z","repository":{"id":537902,"uuid":"9599709","full_name":"scodec/scodec","owner":"scodec","description":"Scala combinator library for working with binary data","archived":false,"fork":false,"pushed_at":"2025-05-06T13:53:25.000Z","size":7705,"stargazers_count":813,"open_issues_count":6,"forks_count":106,"subscribers_count":29,"default_branch":"main","last_synced_at":"2025-05-06T15:03:00.559Z","etag":null,"topics":["binary","decoding","encoding","scala","scodec","typelevel"],"latest_commit_sha":null,"homepage":"http://scodec.org","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scodec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2013-04-22T13:36:08.000Z","updated_at":"2025-05-06T13:53:31.000Z","dependencies_parsed_at":"2023-07-06T07:28:20.823Z","dependency_job_id":"15f48a28-5ac0-4c09-a1ac-956a93436252","html_url":"https://github.com/scodec/scodec","commit_stats":{"total_commits":1083,"total_committers":62,"mean_commits":"17.467741935483872","dds":0.3628808864265928,"last_synced_commit":"a528a47993a4610912fef946a2f346d0cd0bb992"},"previous_names":["mpilquist/scodec"],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scodec%2Fscodec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scodec%2Fscodec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scodec%2Fscodec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scodec%2Fscodec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scodec","download_url":"https://codeload.github.com/scodec/scodec/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010823,"owners_count":21999003,"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":["binary","decoding","encoding","scala","scodec","typelevel"],"created_at":"2024-08-04T00:01:25.070Z","updated_at":"2025-05-13T19:16:20.918Z","avatar_url":"https://github.com/scodec.png","language":"Scala","readme":"scodec\n======\n\n[![Discord](https://img.shields.io/discord/632277896739946517.svg?label=\u0026logo=discord\u0026logoColor=ffffff\u0026color=404244\u0026labelColor=6A7EC2)](https://discord.gg/wKn3cpfRVz)\n[![Maven Central](https://img.shields.io/maven-central/v/org.scodec/scodec-core_3)](https://maven-badges.herokuapp.com/maven-central/org.scodec/scodec-core_3)\n[![javadoc](https://javadoc.io/badge2/org.scodec/scodec-core_3/javadoc.svg)](https://javadoc.io/doc/org.scodec/scodec-core_3)\n\nScala combinator library for working with binary data.\n\nDesign Constraints\n------------------\n\nThis library focuses on contract-first and pure functional encoding and decoding of binary data.\nThe following design constraints are considered:\n - Binary structure should mirror protocol definitions and be self-evident under casual reading\n - Mapping binary structures to types should be statically verified\n - Encoding and decoding should be purely functional\n - Failures in encoding and decoding should provide descriptive errors\n - Compiler plugin should not be used\n\nAs a result, the library is implemented as a combinator based DSL.\nPerformance is considered but yields to the above design constraints.\n\nAcknowledgements\n----------------\nScodec 1.x used [Shapeless](https://github.com/milessabin/shapeless)\nand is heavily influenced by scala.util.parsing.combinator. As of Scodec 2.x, the library only\ndepends on the standard library.\n\nAdministrative\n--------------\n\nThis project is licensed under a [3-clause BSD license](LICENSE).\n\nThe [scodec channel on Typelevel Discord](https://discord.gg/wKn3cpfRVz) is a good place to go for help.\n\nIntroduction\n------------\n\nThe primary abstraction is a [`Codec[A]`](shared/src/main/scala/scodec/Codec.scala), which supports encoding a value of type `A` to a\n`BitVector` and decoding a `BitVector` to a value of type `A`.\n\nThe [`codecs`](shared/src/main/scala/scodec/codecs.scala) objects provides a number of predefined codecs and combinators.\n\n```scala\n    import scodec.*\n    import scodec.bits.*\n    import scodec.codecs.*\n\n    // Create a codec for an 8-bit unsigned int followed by an 8-bit unsigned int followed by a 16-bit unsigned int\n    val firstCodec = uint8 :: uint8 :: uint16\n\n    // Decode a bit vector using that codec\n    val result: Attempt[DecodeResult[(Int, Int, Int)]] = firstCodec.decode(hex\"102a03ff\".bits)\n    // Successful(DecodeResult(((16, 42), 1023), BitVector(empty)))\n\n    // Sum the result\n    val add3 = (_: Int) + (_: Int) + (_: Int)\n    val sum: Attempt[DecodeResult[Int]] = result.map(_.map(add3))\n    // Successful(DecodeResult(1081, BitVector(empty)))\n```\n\nAutomatic case class binding is supported via tuples:\n\n```scala\n    case class Point(x: Int, y: Int, z: Int)\n\n    val pointCodec: Codec[Point] = (int8 :: int8 :: int8).as[Point]\n\n    val encoded: Attempt[BitVector] = pointCodec.encode(Point(-5, 10, 1))\n    // Successful(BitVector(24 bits, 0xfb0a01))\n\n    val decoded: Attempt[DecodeResult[Point]] = pointCodec.decode(0xfb0a01)\n    // Successful(DecodeResult(Point(-5, 10, 1), BitVector(empty)))\n```\n\nCodecs can also be derived, resulting in usage like:\n\n```scala\n    case class Point(x: Int, y: Int, z: Int) derives Codec\n\n    val encoded: Attempt[BitVector] = Codec.encode(Point(-5, 10, 1))\n    // Successful(BitVector(96 bits, 0x000000fb0000000a00000001))\n\n    val decoded: Attempt[DecodeResult[Point]] = Codec.decode[Point](0x000000fb0000000a00000001)\n    // Successful(DecodeResult(Point(-5, 10, 1), BitVector(empty)))\n```\n\nNew codecs can be created by either implementing the `Codec` trait though typically new codecs are created by applying one or more combinators to existing codecs.\n\nSee [the guide](http://scodec.org/guide/) for detailed documentation. Also, see [ScalaDoc](https://javadoc.io/doc/org.scodec/scodec-core_3). Especially:\n - [`Codec`](https://javadoc.io/doc/org.scodec/scodec-core_3/latest/scodec/Codec.html)\n - [`codecs` package](https://javadoc.io/doc/org.scodec/scodec-core_3/latest/scodec/codecs.html)\n\nEcosystem\n---------\n\nMany libraries have support for scodec:\n  - [FS2](https://github.com/typelevel/fs2)\n  - [Circe](https://github.com/circe/circe)\n  - [Refined](https://github.com/fthomas/refined)\n\nExamples\n--------\n\nThere are various examples in the test directory, including codecs for:\n\n - [UDP Datagrams](unitTests/shared/src/test/scala/scodec/examples/UdpDatagramExample.scala)\n - [MPEG Packets](unitTests/shared/src/test/scala/scodec/examples/MpegPacketExample.scala)\n - [libpcap Files](unitTests/jvm/src/test/scala/scodec/examples/PcapExample.scala)\n\nThe [protocols](https://github.com/typelevel/fs2/tree/main/protocols) module of fs2 has production\nquality codecs for the above examples.\n\nThe [skunk](https://github.com/tpolecat/skunk) database library uses scodec to communicate with Postgres.\n\nThe [hippo](https://github.com/indoorvivants/hippo) project uses scodec to parse .hprof files.\n\nThe [bitcoin-scodec](https://github.com/yzernik/bitcoin-scodec) library has a codec for the Bitcoin network protocol.\n\nThe [scodec-msgpack](https://github.com/pocketberserker/scodec-msgpack) library provides\ncodecs for [MessagePack](http://msgpack.org/).\n\nThe [fs2-http](https://github.com/Spinoco/fs2-http) project uses FS2, scodec, and shapeless to implement a minimal HTTP client and server.\n\nThe [scodec-bson](https://gitlab.com/lJoublanc/scodec-bson) library implements [BSON](http://bsonspec.org) codecs and combinators.\n\nTesting Your Own Codecs\n-----------------------\n\nIf you're creating your own `Codec` instances scodec publishes some of its own test tooling in the `scodec-testkit` module.\n\nGetting Binaries\n----------------\n\n```scala\nlibraryDependencies += \"org.scodec\" %%% \"scodec-core\" % \n  (if (scalaVersion.value.startsWith(\"2.\")) \"1.11.9\" else \"2.1.0\")\n```\n\nBuilding\n--------\n\nThis project uses sbt and requires node.js to be installed in order to run Scala.js tests. To build, run `sbt publishLocal`.\n\nCode of Conduct\n---------------\n\nSee the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n","funding_links":[],"categories":["Serialization","Table of Contents","Scala"],"sub_categories":["Serialization"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscodec%2Fscodec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscodec%2Fscodec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscodec%2Fscodec/lists"}