On Mon, Jul 13, 2020 at 12:00 AM Urs Liska <li...@openlilylib.org> wrote:
> Am Sonntag, den 12.07.2020, 23:18 -0700 schrieb Flaming Hakama by Elaine:
>
>
> ---------- Forwarded message ----------
> From: Urs Liska <li...@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
> }
>
>
> 1. read the current values of all properties in the property set
> 2. look up a preset
> 3. if that has a parent, recursively go through the parents
> 4. override all properties defined in the (grand)parent preset, with
> the immediate preset last
> 5. 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
>
>
Yes, I did understand it to be more complex than my MWE.
But the two things I wanted to validate are that
* The preset is something you pass as part of a function invocation
\myFunction \with { preset = style-two }
* The preset resolves to a set of property/value pairs.
Yes, I can see that since the property set has defaults, using "default"
here would be inappropriate. Also, since they are only used in the context
of a call to \myFunction, they are not really acting like defaults.
I'm not sure how much this concept is tied to appearance, but a set of
styling properties is generally called a style sheet, like in CSS.
In fact, the "default"-like character of this is really more similar to
cascading style sheets.
So,
\definePropertySet my-function.appearance
#`((thickness ,number? 1)
(color ,color? ,red)
(label ,markup? "")
(extra-width ,number-pair? (0 . 0))
(Y-position ,integer? 0))
myFunction =
#(with-property-set define-music-function (mus)(ly:music?)
'(my-function appearance)
#{
\once \override NoteHead.color = #(property 'color)
#mus
#})
\defineStylesheet \with {
parent = default
color = #magenta
} my-function.appearance style-two
{
\myFunction \with {
stylesheet = style-two
} c'
}
If you wanted to reserve "stylesheet" for something more complete, another
other word in use for interchangeable style configurations is "theme"
\defineTheme \with {
parent = default
color = #magenta
} my-function.appearance style-two
{
\myFunction \with {
theme = style-two
} c'
}
HTH,
Elaine Alt
415 . 341 .4954 "*Confusion is
highly underrated*"
ela...@flaminghakama.com
Producer ~ Composer ~ Instrumentalist ~ Educator
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
