tia; trait, impl accessors | automatic
This is a syntax sugar proc-macro crate for trait
, impl
accessors patterns. tia
generate to an accessor impl
s of an indivisual trait
s for any struct
|enun
|union
s.
Features
tia
can be generate aimpl
codes automatically.- Target types:
struct
|enum
|union
. - Setting levels: {for all fields} | {per field}.
trait
supporting: Can be generate with multipletrait
s. (See also the Example-3 in below.)- Generative accessors: Getter-like {move,
Copy
,&
,&mut
}, Setter-like { move,Copy
,Clone
,Into
}. (See also the Example-1,2 and Reference/tia directive section.) - Useful +features: {
print
,file-pretty
,include
,disable
}. (See also the Reference/features section.) - Naming patters: { prefix, suffix, fullname }. (See also the Reference/tia directive section.)
Example
Example-1; The introduction of tia
It is minimal, very simple version. Without trait
s complex.
use Tia; // 1. use
// 2. derive
// 3. tia directives
cargo run
, then you will get the output:
foo=123 bar=Hello
- (1,2) are preparing.
- (3) is tia directive for the struct-level.
- (4,5) are an automatic generated accessors by
tia
.
The automatic generated code is:
It could be output to src/.tia/MyStruct
if use file-pretty
features in Cargo.toml
:
[]
={ ="*", =["file-pretty"] }
Example-2; A little complex/practical usage
use Tia; // use
// derive
// <-- tia directives, for all fields
cargo run
:
&foo = 42
&mys = MyStruct
a: mys.bar = Hello,
b: mys.bar = tia.
c: mys.bar = tia.
x = 0
&mys = MyStruct
y =
Example-3; trait
usage
use Tia;
//include!(".tia/MyStruct.rs");
// derive
Then cargo run
:
The generated code with print
, file
or file-pretty
features:
Reference
Usage
- Preparing, add
tia="*"
in[dependencies]
section of the projectCargo.toml
file. ( Or I likecargo add tia
via cargo-edit )- FYI: The
file-pretty
features is good tool for your debugging. Read the bottom section "features" if you want.
- FYI: The
- Use:
- Write
#[derive(Tia)]
proc-macro on head of your struct|enum|union. - Write
#[tia(...)]
proc-macro below the#[derive(Tia)]
(for struct|enum|union-level settings) or top of the specific fields....
is explanate in the next section "tia directives".
- Write
tia directives
tia
's proc-macro can parse the pattern:
#[tia( $tia_directive_0, $tia_directive_1,$tia_directive_2, ... )]
And the $tia_directive
pattern:
- Accessor directive
- Accessors:
- Getter accessor like:
gm
=> ([g]et [m]ove
) ⚠ Move ⚠ pattern, it is NOT use for casually; likefn (self) -> i32 { self.value }
g
=> ([g]et
) ForCopy
-able values, for use a primitive types such asu8
,f32
or aimpl Copy
-ed types; likereturn &self.value
.rg
=> ([r]eference [g]et
) Return a reference&
pattern. It can be use in casually for most situations.rmg
=> ([r]eference [m]ut [g]et
) Return a reference mutable&mut
. Sometimes useful, and sometimes so complex and difficult.
- Setter accelike:
s
=> ([s]et
) Raw value move pattern.rs
=> ([r]eference [s]et
) Reference&
pattern, forCopy
-able types.rsc
=> ([r]eference [s]et [c]lone
)Clone
pattern, forClone
-able types such asString
. This pattern require the same type for the input.rsi
=> ([r]eference [s]et [i]nto
)Into
pattern, forInto
-able types such asString
. This pattern could be type conversions. For eg,&str
|String
|&String
and more types are input toString
with this pattern.
- Getter accessor like:
- Naming policy
- Default ( eg.
g
,rg
rgi
) => Getters are same as the Prefix with "get", Setters are same as the Prefix with "set". g="my_awesome_prefix"
=> Prefix with specialized prefix-part string pattern. It will be generatefn my_awesome_prefix_xxxx
forxxxx
field symbol.g+="my_awesome_suffix"
=> Suffix with specialized suffix-part string pattern. It will be generatefn xxxx_my_awesome_suffix
forxxxx
field symbol.g*="my_awesome_fullname"
=> Fullname pattern. It will be generatefn my_awesome_fullname
for a field.
- Default ( eg.
- Accessors:
- Trait directive
- Default ( no trait directives ) => It will be generate
impl for MyStruct
codes for a fields. "TraitSymbol"
=> It will be generateimpl TraitSymbol for MyStruct
codes for a fields that appear in the after of this directive.""
=> It will be generateimpl for MyStruct
codes for a fields that appear in the after of this directive.
- Default ( no trait directives ) => It will be generate
features
disable
Usage example:
[]
={ ="*", =["disable"] }
tia
will be output nothing.- But
tia
is not removed, thus it allow the#[derive(Tia)]
and#[tia(...)]
proc-macros with no effects.
print
Usage example:
[]
={ ="*", =["print"] }
tia
will be output the generated code to STDERR.- But it is difficully to human eyes, thus
file-pretty
is better for human eyes.
- But it is difficully to human eyes, thus
file
|file-pretty
Usage example:
[]
={ ="*", =["file-pretty"] }
tia
will be output/update the generated code to the file such assrc/.tia/MyStruct.rs
.- This file is not for use in build, but if you want check the generated code with your eyes then it helpful.
What's the difference of file
and file-pretty
:
file
will be output the raw generated code. It is very compressed.file-pretty
will be output the raw generated code, and then applyrustfmt
automatically.- note: this feature reqwire the
rustfmt
command in your development environment. (It is not a lib crate dependency.)
- note: this feature reqwire the
include
|include-pretty
|include-force
Usage example:
[]
={ ="*", =["include-pretty"] }
tia
will be:
- Generate codes if not exists.
- Generate
include!(...)
macro such asinclude!("src/.tia/MyStruct")
instead.
What's the difference of include
, include-pretty
and include-force
:
include
will be generate (=file
) code if the generated code is not found.include-pretty
will be generate and prettify (=file-pretty
) if the generated code is not found.include-force
will not be generate if the generated code is not found, maybe build will stop with an error(s).
Note
tia
provide a useful syntax sugar, it will helpful if you should impl many interface-like specifications. For eg, something designed for object-oriented paradigm mainly languages such as C#, Java, C++, or complex data definition based by UML such as XMLSchema. But, it is just a syntax sugar. Please do not overdose tia
unnecessarily.
LICENSE
Contributor
Thank you!😍
Author
- USAGI.NETWORK / Usagi Ito https://github.com/usagi/