Proposal: Support object favorites

[dustincoleman]

Object Favorites

Support user customization of variable presentation by allowing users to choose their "favorite" variables. Debug adapters can then return these variables as the top-most items in variables requests, as well as customize the displayed value of variables with "favorite" children.

VS Feature: https://devblogs.microsoft.com/visualstudio/pinnable-properties-debug-display-managed-objects-your-way/

interface Capabilities {
    // ...

    /** The debug adapter supports adding and removing favorites on variables. */
    supportsObjectFavorites?: boolean;
}

interface VariablePresentationHint {
  // ...

  /**
   * Set of attributes represented as an array of strings. Before introducing additional values, try to use the listed values.
   * Values: 
   * ...
   * 'canFavorite': Indicates the item can be added as a favorite of its parent type.
   * 'isFavorite': Indicates the item has been added as a favorite of its parent type.
   * 'hasFavorites': Indicates the item's current children contains at least one favorite item.
   * ...
   */
  attributes?: string[];

  // ...
}

/** 
 * Adds a variable to its parent variable's collection of favorites. 
 * Clients should only call this request if the capability 'supportsObjectFavorites' is true.
 */
interface AddFavoriteRequest extends Request {
    // command: 'addFavorite'
    arguments: AddFavoriteArguments;
}

/** Arguments for 'addFavorite' request */
interface AddFavoriteArguments{
  /**
   * The reference of the variable container for the variable to be added to its parent's favorites.
   */
  variablesReference: number;

  /**
   * The name of the variable in the container to be added to its parent's favorites.
   * Valid variables have a VariablePresentationHint attribute of 'canFavorite'.
   * Valid variables do not have a VariablePresentationHint attribute of 'isFavorite'.
   */
  name: string;
}

/** Response for 'addFavorite' request */
interface AddFavoriteResponse extends Response {
}

/** 
 * Removes a variable from its parent variable's collection of favorites. 
 * Clients should only call this request if the capability 'supportsObjectFavorites' is true.
 */
interface RemoveFavoriteRequest extends Request {
    // command: 'removeFavorite'
    arguments: RemoveFavoriteArguments;
}

/** Arguments for 'removeFavorite' request */
interface RemoveFavoriteArguments {
  /**
   * The reference of the variable container for the variable to be removed from its parent's favorites.
   */
  variablesReference: number;

  /**
   * The name of the variable in the container to be removed from its parent's favorites.
   * Valid variables have a VariablePresentationHint attribute of 'canFavorite'.
   * Valid variables have a VariablePresentationHint attribute of 'isFavorite'.
   */
  name: string;
}

/** Response for 'removeFavorite' request */
interface RemoveFavoriteResponse extends Response {
}

CC: @andrewcrawley, @weinand

[weinand]

@dustincoleman Thanks a lot for the new DAP feature proposal.

Here are some initial comments and questions:

• the feature makes sense, but from the overall reaction it has not sparked a lot of interest. That's the main reason why I'm so late in reviewing it..
• the name "Favorite" in the AddFavorite request is very broad. I suggest to make it more specific, e.g. AddFavoriteVariable.
• Since favorite variables rely on variablesReference they are only valid for a single debug session and cannot be used to persist them across sessions. Is this the intended behavior?

[dustincoleman]

Thank you for taking a look! It is up to the debug adapter to decide what is an appropriate way to persist variable favorite information (if at all). The client is just responsible to indicate which variable the user wanted to favorite. For example, in a typed language, a debug adapter can look at the type of the parent variable, and customize variables of that type. In an untyped language, maybe it would make sense to look at the variable name and scope. In either case it can persist this to a configuration file (ex: C# uses ~/.dotnet/visualizers/ObjectFavorites.json).