[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Naming RFC: Properties, property sets, presets

From: Urs Liska
Subject: Re: Naming RFC: Properties, property sets, presets
Date: Mon, 13 Jul 2020 09:00:54 +0200
User-agent: Evolution 3.36.3-1

Am Sonntag, den 12.07.2020, 23:18 -0700 schrieb Flaming Hakama by Elaine:

---------- Forwarded message ----------
From: Urs Liska <>
To: "" <>
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)

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


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.


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.



Elaine Alt
415 . 341 .4954                                           "Confusion is highly underrated"
Producer ~ Composer ~ Instrumentalist ~ Educator

reply via email to

[Prev in Thread] Current Thread [Next in Thread]