Am Sonntag, den 12.07.2020, 23:18 -0700 schrieb Flaming Hakama by
Elaine:
> > ---------- Forwarded message ----------
> > From: Urs Liska <[email protected]>
> > To: "[email protected]" <[email protected]>
> > 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
>
>
>
> HTH,
>
> Elaine Alt
> 415 . 341 .4954 "Confusion
> is highly underrated"
> [email protected]
> Producer ~ Composer ~ Instrumentalist ~ Educator
> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
> =-=-=-=-=-=-=-=-=-=-=-=-=-
