Am Sonntag, den 12.07.2020, 23:18 -0700 schrieb Flaming Hakama by Elaine: ---------- Forwarded message ---------- From: Urs Liska <lists@openlilylib.org> To: "lilypond-user@gnu.org" <lilypond-user@gnu.org> Date: Sun, 12 Jul 2020 15:38:03 +0200 Subject: Naming RFC: Properties, property sets, presets Hi all,
I'm writing some documentation for the new openLilyLib feature set of
properties, and I think this is the (last) moment to clarify some of
the naming.
I have implemented the concept of a set of properties, which is a place
to store typed variables. I'm pretty confident that the terms
"property" and "property set" are appropriate. To demonstrate:
\definePropertySet my-function.appearance
#`((thickness ,number? 1)
(color ,color? ,red)
(label ,markup? "")
(extra-width ,number-pair? (0 . 0))
(Y-position ,integer? 0))
This defines the set of properties applicable for my-function, along
with type predicates and default values.
Property values can (if necessary) be retrieved with
\getProperty my-function.appearance.label
and changed with
\setProperty my-function.appearance.color #green
\setProperty my-function.appearance.color "blue" % fails type check
The actual use of properties is from within functions:
myFunction =
#(with-property-set define-music-function (mus)(ly:music?)
'(my-function appearance)
#{
\once \override NoteHead.color = #(property 'color)
#mus
#})
Within a function created with the with-property-set macro a function
(property <key>) is available to produce the current value of the
property (which can be the currently set global value or a value passed
in the function
{
\myFunction c' % => (property 'color) => red
\setProperty my-function.appearance.color #blue
\myFunction c' % => (property 'color) => blue
\myFunction \with { color = #green } c' % => (property 'color) =>
#green
}
###
So far I'm pretty sure property and property set is the right naming.
However, there's one more step, and here I have been suggested to
reconsider the naming.
Properties can not only be changed globally or per instance but also
through something I so far call "presets". Alternative suggestions for
that concept were "contexts" or "environment", but I'm really not
convinced about them. So I'm looking for either common support for
either name or a better suggestion.
A "preset" is a subset of a property set with individual property
values. When invoking the function a preset can be requested while
properties not included in the preset are left unchanged. Presets can
inherit to create cascading structures.
\definePreset \with {
thickness = 3
Y-position = 2
} my-function.appearance default
\definePreset \with {
parent = default
color = #green
} my-function.appearance style-one
\definePreset \with {
parent = default
color = #magenta
} my-function.appearance style-two
Using it the properties included in the preset are used while others
keep the current global value. Additionally arbitrary properties can be
overridden locally:
{
\myFunction \with {
preset = style-two
label = "Foo"
thickness = 2 % properties from presets can be overridden too
} c'
}
###
So, to cut a long story short: What do you think this "is", i.e this
should be named: presets, contexts, environments, something else? If
you should think about styles, this has been discussed before, but a
property set isn't necessarily limited to matters of appearance, it
could configure arbitrary things, e.g. export target, lyrics language,
composition algorithm parameters, anything.
Actually I'd prefer one of two answers: A confirmation that I'm good to
go with "preset", or a better suggestion that is so striking that I can
immediately go with it.
Thanks
Urs
To be clear, to make sure I understand it correctly, when you are calling
\myFunction \with { preset = style-two } c'
that is a synonym for, assuming your original definition of style-two:
\myFunction \with { parent = default color = #magenta } c'
Is that correct?
Only partially. In fact what happens with
\myFunction \with { preset = style-two label = "Bar" Y-position = -1 }
(to provide additional local overrides)
\myFunction \with { thickness = 1 % provided by the property set color = #red % provided by the property set label = "" % provided by the property set extr-width = #'(0 . 0) % provided by the property set Y-position = 0 % provided by the property set thickness = 3 % overridden by "default" Y-position = 2 % overridden by "default" color = #magenta % overridden by "style-two" label = "Bar" % local override Y-position = -1 % local override }
- read the current values of all properties in the property set
- look up a preset
- if that has a parent, recursively go through the parents
- override all properties defined in the (grand)parent preset, with the immediate preset last
- override any local invocation properties
If so, to me, the elements of "preset" are in the vicinity of what I would call arguments, as they are values you supply to a function. But since these arguments are all properties, it's probably better to call them properties. Since they can be overridden, I'd think of them as property defaults.
I would find it clearer as
\defineDefaultProperties \with { parent = default color = #magenta
} my-function.appearance style-two
{ \myFunction \with { defaultProperties = style-two } c' }
If you wanted a more generic name, I would go with:
\defineArgumentDefaults \with { parent = default color = #magenta
} my-function.appearance style-two
{ \myFunction \with { argumentDefaults = style-two } c' }
This is intriguing, and I'll put it on the list of to-be-considered suggestions. But not "DefaultProperties" because that mixes badly with the property set level.
Best Urs
Producer ~ Composer ~ Instrumentalist ~ Educator
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|