{"id":15713671,"url":"https://github.com/lbarasti/dataclass","last_synced_at":"2025-05-08T20:37:18.891Z","repository":{"id":75375061,"uuid":"115942584","full_name":"lbarasti/dataclass","owner":"lbarasti","description":"Data class macro for the Crystal Language.","archived":false,"fork":false,"pushed_at":"2021-04-12T22:27:36.000Z","size":39,"stargazers_count":36,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-31T18:01:56.002Z","etag":null,"topics":["crystal-lang","dataclass","macros"],"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/lbarasti.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-01T19:39:17.000Z","updated_at":"2024-03-24T10:42:39.000Z","dependencies_parsed_at":"2023-06-06T08:00:15.526Z","dependency_job_id":null,"html_url":"https://github.com/lbarasti/dataclass","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbarasti%2Fdataclass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbarasti%2Fdataclass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbarasti%2Fdataclass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbarasti%2Fdataclass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lbarasti","download_url":"https://codeload.github.com/lbarasti/dataclass/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253146550,"owners_count":21861424,"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-lang","dataclass","macros"],"created_at":"2024-10-03T21:32:51.886Z","updated_at":"2025-05-08T20:37:18.838Z","avatar_url":"https://github.com/lbarasti.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GitHub release](https://img.shields.io/github/release/lbarasti/dataclass.svg)](https://github.com/lbarasti/dataclass/releases)\n![Build Status](https://github.com/lbarasti/dataclass/workflows/Crystal%20spec/badge.svg)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n# dataclass\n\nA [Crystal](http://crystal-lang.org/) macro to ease the definition of *data classes*, i.e. classes whose main purpose is to hold data.\n\nData class instances are immutable, and provide a natural implementation for the most common methods.\nThey also define some basic pattern matching functionality, to ease data extraction.\n\nFollow the links to read more about data classes in [Kotlin](https://kotlinlang.org/docs/reference/data-classes.html), [Scala](https://docs.scala-lang.org/tour/case-classes.html) and [Python](https://docs.python.org/3/library/dataclasses.html).\n\n## Installation\n\nAdd this to your application's `shard.yml`:\n\n```yaml\ndependencies:\n  dataclass:\n    github: lbarasti/dataclass\n```\n\n## Usage\n\n```crystal\nrequire \"dataclass\"\n```\n\nLet's define a class with read-only fields\n\n```crystal\ndataclass Person{name : String, age : Int = 18}\n```\n\nWe can now create instances and access fields\n\n```crystal\np = Person.new(\"Rick\", 28)\n\np.name # =\u003e \"Rick\"\np.age # =\u003e 28\n```\n\nThe equality operator is defined to perform structural comparison\n\n```crystal\nq = Person.new(\"Rick\", 28)\n\np == q # =\u003e true\n```\n\nThe `hash` method is defined accordingly. This guarantees predictable behaviour with Set and Hash.\n\n```crystal\n  visitors = Set(Person).new\n  visitors \u003c\u003c p\n  visitors \u003c\u003c q\n\n  visitors.size # =\u003e 1\n ```\n\n`to_s` is also defined to provide a human readable string representation for a data class instance\n\n```crystal\nputs p # prints \"Person(Rick, 28)\"\n```\n\nInstances of a data class are immutable. A `copy` method is provided to build new versions of a given object\n\n```crystal\np.copy(age: p.age + 1) # =\u003e Person(Rick, 29)\n```\n\n\n### Pattern-based parameter extraction\n\nData classes enable you to extract parameters using some sort of pattern matching. This is powered by a custom definition of the `[]=` operator on the data class itself.\n\nFor example, given the data classes\n\n```crystal\ndataclass Person{name : String, age : Int = 18}\ndataclass Address{line1 : String, postcode : String}\ndataclass Profile{person : Person, address : Address}\n```\n\nand a `Profile` instance `profile`\n\n```crystal\nprofile = Profile.new(Person.new(\"Alice\", 43), Address.new(\"10 Strand\", \"EC1\"))\n```\n\nthe following is supported\n\n```crystal\nage, postcode = nil, nil\nProfile[Person[_, age], Address[_, postcode]] = profile\n\nage == profile.person.age # =\u003e true\npostcode == profile.address.postcode # =\u003e true\n```\n\nNote that it is necessary for the variables used in the pattern matching to be initialized *before* they appear in the pattern.\n\nSkipping the initialization step will produce a compilation error as soon as you try to reuse such variables.\n\n\n### Destructuring assignment\n\nData classes support destructuring assignment. There is no magic involved here: data classes simply implement the indexing operator `#[](idx)`.\n\n```crystal\nperson, address = profile\n\nperson == profile.person # =\u003e true\naddress == profile.address # =\u003e true\n```\n\nThe inconvenience with this approach is that the type of both `person` and `address` at compile time is going to be `String | Int32`. This might make your code a bit uglier than it needs to be.\n\nTo circumvent this limitation, the `to_tuple` method is also provided. This assigns the right type to each extracted parameter even at compile-time\n\n```crystal\nprofile.to_tuple # =\u003e {Person(...), Address(...)}\n\nperson, address = profile.to_tuple\n\nperson == profile.person # =\u003e true\naddress == profile.address # =\u003e true\n```\n\nThe macro also defines a `to_named_tuple` method, which provides a natural transformation of your data class instance to `NamedTuple`\n\n```crystal\n  person.to_named_tuple # =\u003e {\"name\": \"Alice\", \"age\": 43}\n```\nMind that, by design, both `to_tuple` and `to_named_tuple` are not recursive - so they will not convert data class fields to tuples / named tuples respectively.\n\n### Support for inheritance\n\nThe `dataclass` macro supports inheritance, so the following code is valid\n\n```crystal\nclass Vehicle; end\ndataclass Car{passengers : Int16} \u003c Vehicle\n```\n\n### Support for type parameters\n\nThe `dataclass` macro supports type parameters, so the following code is valid\n\n```crystal\ndataclass Wrapper(T){value : T}\n```\n\n### Support for defining additional methods\n\nThe `dataclass` macro supports defining additional methods on your data class. If you pass the dataclass macro a code block, the body of the code block will be pasted into body of the expanded class definition.\n\n```crystal\ndataclass Person{name : String} do\n  def hello\n    \"Hello #{@name}\"\n  end\nend\n\nPerson.new(\"Matt\").hello  # =\u003e \"Hello Matt\"\n```\n\nThis also works in conjunction with inheritance.\n\n### Under the hood\n\nThe `dataclass` macro expands such that following definitions are equivalent.\n\n```crystal\ndataclass Person{name : String, age : Int = 18} \u003c OtherType do\n  def hello\n    \"Hello #{@name}\"\n  end\nend\n```\n\n```crystal\nclass Person \u003c OtherType\n  getter(name)\n  getter(age)\n\n  def initialize(@name : String, @age : Int = 18)\n  end\n\n  def hello\n    \"Hello #{@name}\"\n  end\n\n  def_equals_and_hash(@name, @age)\n\n  def copy(name = @name, age = @age) : Person\n    Person.new(name, age)\n  end\n\n  def [](idx)\n    [@name, @age][idx]\n  end\n\n  def to_tuple\n    {@name, @age}\n  end\n\n  def to_named_tuple\n    {name: @name, age: @age}\n  end\n\n  def to_s(io)\n    fields = [@name, @age]\n    io \u003c\u003c \"#{self.class}(#{fields.join(\", \")})\"\n  end\nend\n```\n\n### Known Limitations\n\n* dataclass definition must have *at least* one argument. This is by design. Use `class NoArgClass; end` instead.\n* trying to inherit from a data class will lead to a compilation error.\n```crystal\ndataclass A{id : String}\ndataclass B{id : String, extra : Int32} \u003c A # =\u003e won't compile\n```\nThis is by design. Try defining your data classes so that they [inherit from a common abstract class](https://stackoverflow.com/a/12706475) instead.\n\n## Development\n\nTo expand the macro\n\n```\ncrystal tool expand -c \u003cpath/to/file.cr\u003e:\u003cline\u003e:\u003ccol\u003e \u003cpath/to/file.cr\u003e\n```\n\n## Contributing\n\n1. Fork it ( https://github.com/lbarasti/dataclass/fork )\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'Add some feature')\n4. Push to the branch (git push origin my-new-feature)\n5. Create a new Pull Request\n\n## Contributors\n\n- [lbarasti](https://github.com/lbarasti) - creator, maintainer\n- [Matthew Berry](https://github.com/mattrberry) - contributor\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flbarasti%2Fdataclass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flbarasti%2Fdataclass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flbarasti%2Fdataclass/lists"}