View Source Builder
This is a feature that makes it possible to build numscripts dynamically within your application.
Usage
You just need to call Numscriptex.Builder.build/1
with the metadata necessary to build your numscript.
Metadata
Metadata is the sole argument you need to use the build/1
function, wich has the following fields:
Required fields:
- splits: a list of metadata needed to build numscripts (explained below)
Optional fields:
- percent_asset: monetary asset (BRL, USD, EUR, and etc.) to use when build numscripts using percentage values.
- remaining_to: where the rest of the money will go after the transaction is made
- Only needed if you want to designate a specific destination. The default is remaining kept wich makes the remainder go back to the source.
About the "list of metadata" mentioned on the split
field above:
Required fields:
- account: account whose the money will go to
- amount: amount of money transferred. Be aware that this field only accepts integer values, so if you want to send $5 your amount field value should be 500.
- type: the amount type, accepts two values:
- fixed: treats the
amount
field as a number - percent: treats the
amount
field as a percentage value
- fixed: treats the
Optional fields:
Also accepts aplits
and remaining_to
fields, and a asset
field:
- splits: in this case, this field is only neccessary if you want to build nested destinations, and therefore it is only valid if the
type
field value is:percent
- asset: also the monetary asset, but in this case is only needed on
:fixed
types
The remaining_to
field continues with the same behaviour as above.
Example
With the metadata type above in mind, let's build a simple numscript.
# metadata:
%{
splits: [
%{
type: :percent,
amount: 20,
account: "some:destination"
}
],
remaining_to: "another:destination",
percent_asset: "USD"
}
Wich will generate the following numscript:
send [USD *] (
source = @user
destination = {
20% to @some:destination
remaining to @another:destination
}
)
If the :remaining_to
field were not defined, the remaining would be kept:
send [USD *] (
source = @user
destination = {
20% to @some:destination
remaining kept
}
)
P.S.: The percent amount types will always be executed first, so we can assure that all of the percentages are based off of the initial value. This feature is still in development as we speak, but soon we will have more flexibility in those regards.
Examples
Example 1
Both fixed and percent types:
%{
splits: [
%{
type: :fixed,
amount: 500,
asset: "USD",
account: "some:destination:a"
},
%{
type: :percent,
amount: 20,
account: "some:destination:b"
}
],
remaining_to: "some:destination:c",
percent_asset: "USD"
}
Will generate:
send [USD *] (
source = @user
destination = {
20% to @some:destination:b
remaining kept
}
)
send [USD 500] (
source = @user
destination = @some:destination:a
)
Example 2
Nested percent-type, plus fixed
%{
splits: [
%{
type: :fixed,
amount: 1250,
asset: "USD",
account: "some:destination:a"
},
%{
type: :percent,
amount: 30,
remaining_to: "remaining:destination:b",
splits: [
%{
type: :percent,
amount: 40,
account: "some:destination:c"
},
%{
type: :percent,
amount: 20,
account: "some:destination:b"
}
]
}
],
remaining_to: "remaining:destination:a",
percent_asset: "USD"
}
Will generate:
send [USD *] (
source = @user
destination = {
30% to {
40% to @some:destination:c
20% to @some:destination:b
remaining to remaining:destination:b
}
remaining to remaining:destination:a
}
)
send [USD 1250] (
source = @user
destination = @some:destination:a
)
Note that the asset
field inside of nested destinations will be ignored, given that
they all go under the same send
scope.
Example 3
Nested percent-type, plus fixed, and with fixed-type within nests
%{
splits: [
%{
type: :fixed,
amount: 1050,
asset: "EUR",
account: "some:destination:a"
},
%{
type: :percent,
amount: 20,
account: "some:destination:b"
},
%{
type: :percent,
amount: 30,
remaining_to: "remaining:destination:b",
splits: [
%{
type: :fixed,
amount: 1250,
asset: "USD",
account: "some:destination:c"
},
%{
type: :percent,
amount: 15,
account: "some:destination:e"
},
%{
type: :percent,
amount: 20,
account: "some:destination:d"
},
%{
type: :percent,
amount: 50,
remaining_to: "remaining:destination:c",
splits: [
%{
type: :fixed,
amount: 500,
asset: "BRL",
account: "some:destination:b"
},
%{
type: :percent,
amount: 20,
account: "some:destination:a"
},
%{
type: :percent,
amount: 27,
account: "some:destination:a"
}
]
}
]
}
],
remaining_to: "remaining:destination:a",
percent_asset: "EUR"
}
Will generate:
send [EUR *] (
source = @user
destination = {
20% to @some:destination:b
30% to {
15% to @some:destination:e
20% to @some:destination:d
50% to {
20% to @some:destination:a
27% to @some:destination:a
remaining to @remaining:destination:c
}
remaining to @remaining:destination:b
}
remaining to @remaining:destination:a
}
)
send [USD 1250] (
source = @user
destination = @some:destination:c
)
send [BRL 500] (
source = @user
destination = @some:destination:b
)
send [EUR 1050] (
source = @user
destination = @some:destination:a
)
Note that the fixed
types in nested splits
(i.e. splits
fields inside of splits
fields) will be popped out and still
be built after the percent
types.