zngur-prelude

zngur-prelude is a CLI program, as well as a static collection of files which can be used to improve developer experience when using Zngur. This framework for Rust and C++ interop allows specifying the language boundary, but standard library types must be specified manually, so this tool generates the most commonly used standard container types with common types as the parameter, and you may copy the prelude directory, or use the tool to generate your own prelude.

This project was created as part of research into Zngur, to broaden knowledge about Rust / C++ interop. KDAB also maintains a larger scale Rust interop project, CXX-Qt, with video tutorials, and a comprehensive book.

Please visit https://www.kdab.com to meet the people who write code like this.

Read the blog about Zngur on KDAB Blogs.

How To Use

There are 2 main ways this project may be used. First, you may want to generate your own prelude for your project. The project is not yet on https://www.crates.io but may be at some point, so you might be able to cargo install zngur-prelude in the future. After cloning the project, the tool can be used with a simple cargo run in the root directory, and then command line arguments can be specified as follows:

• First choose a subcommand, which is the container type to generate, from the supported containers
  • option
  • result (Currently just always uses String as the error type)
  • vec
  • vec-vec (2D vector, e.g. Vec<Vec<T>>)
  • hash-map (Uses types differently, explained below)
• Then choose the types you want to specialize this type for, specifying one after another separated by spaces
  • Integers like u8 or i8
  • String is called string
  • References to these primitives, by prepending "ref_", like ref_u8 -> &u8
  • Vectors of these primitives by prepending "vec_" like vec_u8 -> Vec<u8>
  • References to vectors of these primitives by prepending "ref_vec_" like ref_vec_i16 -> &Vec<i16>
• There are also presets / shorthands available
  • ints -> all integer primitives
  • int_refs -> references to all integer primitives
  • ints_all -> combines the above two presets
  • vec_ints -> vectors of all integer primitives
  • vec_int_refs -> references to vectors of all integer primitives
  • vec_all -> combines the above two presets

HashMaps are generated slightly differently than the other containers, in the way that types specified are used. Since there are 2 type parameters in HashMaps, the types generated will be a Cartesian product of the input set: hash-map t1 t2 t3 -> HashMap<t1, t2>, HashMap<t1, t3>, HashMap<t2, t1>, HashMap<t2, t3>, HashMap<t3, t2>, HashMap<t3, t1>

The next way you may want to use the project is to simply clone the prelude folder, and place it inside your project, as this will generate all the types you might want, and increase the size of the generated code, but not using a type you have declared has no other adverse effects. In order to use the generated code, you will need a main zng file, for example prelude.zng or main.zng, and in this, you will need String declared, and imports for the other prelude files that have been generated. You can then use all of these types by importing them as if they were all inside that main file.

Possible Improvements

In the future, it would be ideal to support arbitrary nesting of types, e.g. vec vec vec u8 would generate a 3D vector, which is currently not possible, but this would require rewriting aspects of the parsing and generation, so is currently left out.

Adding a flag for trait methods would also be a nice feature to have, e.g. specifying that you want to generate the methods associated with Deref<target=[T]> when generating these types. This would open up more useful std methods, such as iteration, and shared borrowing (as a slice), as well as allowing things like Eq and Default.

Combining types in one command would also be nice, such as vec option u8 yielding Vec<u8>, Option<u8>, Vec<Option<u8>> and Option<Vec<u8> would make this tool much more flexible, and allow generating many more type definitions.