StructUtils.jl

Author quinnj
Popularity
9 Stars
Updated Last
4 Months Ago
Started In
February 2024

StructUtils

CI codecov deps version pkgeval

Installation

The package is registered in the General registry and so can be installed at the REPL with ] add StructUtils.

Documentation

The primary interface provided by StructUtils.jl is in the form of the exported @noarg, @defaults, and @tags macros, along with the unexported (to avoid clashing with the Base definition) of StructUtils.@kwdef. These macros can be used on struct definitions to provide a more ergonomic and flexible way to define structs with default values, keyword constructors, and more.

The @noarg macro can be used to define a "no argument" constructor, and must be used with mutable structs. This allows for programmatic construction and discovery of the supported behavior. Default values and field tags can also be defined in @noarg structs.

The @defaults macro can be used to define default values for fields in any kind of struct, and constructors will be defined that allow for the omission of fields with default values. Note that all fields with default values must be defined after any fields without default values.

The @tags macro can be used to define tags for fields in any kind of struct.

The @kwdef macro mirros the functionality of the Base defintion, while also allowing for the inclusion of field tags.

The other major interface StructUtils.jl provides is the StructUtils.make(T, source) function. It allows programmatic construction of a type T from a variety of source objects. For example, I could have a custom struct Foo and be able to construct an instance from an array of values, a dictionary, a database cursor, a JSON object, etc. This is done by allowing source objects to implement interfaces for how fields should be provided programmatically (the primary means being the StructUtils.applyeach function), while StructUtils.make uses the programmatic knowledge from the above-mentioned macros, along with potential field tags, to construct the object.

Additional documentation is forth-coming around how package developers can use the "under the hood" machinery of StructUtils.jl to provide a more flexible and ergonomic interface to their users, like custom serialization/deserialization, database interaction, etc.

Contributing and Questions

Contributions are very welcome, as are feature requests and suggestions. Please open an issue if you encounter any problems or would just like to ask a question.