> > > ---------- 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? 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' } HTH, Elaine Alt 415 . 341 .4954 "*Confusion is highly underrated*" ela...@flaminghakama.com Producer ~ Composer ~ Instrumentalist ~ Educator -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-