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 -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-