{"id":17680675,"url":"https://github.com/elbywan/struct-mappings","last_synced_at":"2025-03-30T19:12:40.628Z","repository":{"id":152588077,"uuid":"222293908","full_name":"elbywan/struct-mappings","owner":"elbywan","description":"Generate Crystal classes mapping C structures.  🗺️","archived":false,"fork":false,"pushed_at":"2019-11-17T18:42:54.000Z","size":26,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-05T21:35:53.220Z","etag":null,"topics":["crystal","mappings","struct"],"latest_commit_sha":null,"homepage":"https://elbywan.github.io/struct-mappings/","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/elbywan.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":"2019-11-17T18:34:51.000Z","updated_at":"2019-11-17T21:58:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"a542f8c8-76be-4f22-91e4-d36ed1421001","html_url":"https://github.com/elbywan/struct-mappings","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fstruct-mappings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fstruct-mappings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fstruct-mappings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fstruct-mappings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elbywan","download_url":"https://codeload.github.com/elbywan/struct-mappings/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246365645,"owners_count":20765546,"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","mappings","struct"],"created_at":"2024-10-24T09:08:36.084Z","updated_at":"2025-03-30T19:12:40.583Z","avatar_url":"https://github.com/elbywan.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# struct-mappings\n\n#### Generate crystal classes mapping C structures.\n\n[![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://elbywan.github.io/struct-mappings/)\n[![GitHub release](https://img.shields.io/github/release/elbywan/struct-mappings.svg)](https://github.com/elbywan/struct-mappings/releases)\n[![Build Status](https://travis-ci.org/elbywan/struct-mappings.svg?branch=master)](https://travis-ci.org/elbywan/struct-mappings)\n\n## Purpose\n\n`struct-mappings` exposes useful macros that can be used to convert a [C struct](https://crystal-lang.org/reference/syntax_and_semantics/c_bindings/struct.html) into a Crystal class and vice versa.\n\nThe inner representation of the data is a [NamedTuple](https://crystal-lang.org/api/latest/NamedTuple.html) which is very convenient to use.\n\n## Utility\n\nConversion from \u0026 to a C structure could be useful in the following scenarios:\n\n- Persisting data that would get freed otherwise when calling an external library.\n- Avoiding calling `.value` on nested structure pointers.\n- C structs are arguably less convenient to use compared to named tuples.\n\n## Features\n\n- Supports nested structures.\n- Automatically allocates \u0026 dereference structure pointers.\n- C structures containing array pointers can be converted to an array wrapper class.\n- Conversion can be customized.\n\n## Installation\n\n1. Add the dependency to your `shard.yml`:\n\n   ```yaml\n   dependencies:\n     struct-mappings:\n       github: elbywan/struct-mappings\n   ```\n\n2. Run `shards install`\n\n## Usage\n\n#### Require\n\n```crystal\nrequire \"struct-mappings\"\n```\n\n#### Minimal use case\n\n```crystal\n# Include the Mappings module\ninclude Mappings\n\n# Define a dummy structure.\nlib C\n  struct Data\n    int: LibC::Int\n  end\nend\n\n# Map this structure to a crystal class.\nstruct_mapping Data, C::Data,\n  int : Int32\n\n# The class can be instantiated from a named tuple containing the fields…\ndata = Data.new({int: 10})\n# or directly from the C structure.\ndata_from_c = Data.new(\n  C::Data.new int: 10\n)\n# The two classes hold the same data.\npp data == data_from_c # =\u003e true\n# And it can be converted back using the `to_unsafe` method.\npp data.to_unsafe # =\u003e C::Data(@int=10)\n\n# For structures that represent arrays, it's also quite simple.\n\n# Define a dummy array.\nlib C\n  struct DataArray\n    data: Data*\n    size: LibC::Int\n  end\nend\n\n# Map the array to a crystal class.\n# Generates a `DataArray` class which is a wrapper around\n# an Array of `Data` classes, and mapping the `C::DataArray` struct.\nstruct_array_mapping DataArray, Data, C::DataArray\n\n# Can be instantiated from a crystal array…\narray_from_data = DataArray.new [\n  Data.new({int: 10}),\n  Data.new({int: 20}),\n]\npp array_from_data # =\u003e [{int: 10}, {int: 20}]\n\n# or a C structure representation.\narray_from_c = DataArray.new C::DataArray.new(\n  size: 2,\n  data: [\n    C::Data.new(int: 10),\n    C::Data.new(int: 20),\n  ].to_unsafe\n)\npp array_from_c # =\u003e [{int: 10}, {int: 20}]\n\n# The two classes hold the same data.\npp array_from_data == array_from_c # =\u003e true\n\n# And it can be converted back using the `to_unsafe` method.\npp array_from_data.to_unsafe # =\u003e C::DataArray(@data=Pointer(C::Data)@0x10e1cfda0, @size=2)\n```\n\n## Documentation\n\nThe exhaustive documentation is hosted [here](https://elbywan.github.io/struct-mappings).\n\n## Contributing\n\n1. Fork it (\u003chttps://github.com/your-github-user/struct-mappings/fork\u003e)\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- [elbywan](https://github.com/your-github-user) - creator and maintainer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felbywan%2Fstruct-mappings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felbywan%2Fstruct-mappings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felbywan%2Fstruct-mappings/lists"}