Design for #130: Fix the location object

["Larry Golding \(Comcast\)" <larrygolding@comcast.net>]

In Issue #130, “Fix the location object,” I described several logical and practical problems with the current design of the location object. Michael and I have known about these problems for a long time, but we’ve never come up with a good approach to addressing them. At the TC meeting on Wednesday, we’ll discuss the following proposal. In addition to the primary change (the fix to the location object), we opportunistically introduce certain other improvements.

 

Please read Issue #130 before you read this proposal. None of what’s below will make sense otherwise.

 

Michael: This proposal does not introduced the “logical location” encapsulation we discussed. It’s a completely separate issue, I haven’t studied it in the same detail I’ve studied the physical location issues, and I don’t want it to distract from the discussion of what is already a large change.

 

I enhanced the notation I used in my previous mail to better describe these changes. Here is the notation, with the new features marked with *NEW*:

 

• Object names are at the left margin (and bolded - *NEW*).
• Property names are indented under object names.
• If the property’s type of is the same as its name, we just show the property name, for example, location.
• If the property’s type is different from its name, we show it as propertyName:propertyType, for example, graphs:graph[] (the type of the graphs property is “array of graph”).
• + means a new object, or a new property on an existing object
• - means a property or object is removed.
• = means the property is unchanged, and is mentioned just for context. *NEW*
• ~ means the property was modified (renamed, or its type was changed) *NEW*

 

Here’s the proposal:

 

location

  -analysisTarget:physicalLocation         # This is the heart of the change: replace the physicalLocation-valued propertoes analysisTarget and

  -resultFile:physicalLocation             #  resultFile with a single physicalLocation property.

  +physicalLocation                        # The physicalLocation where the result was detected, equivalent to the removed resultFile property.

  +message                                 # With its new message property, a location object can do almost everything the annotatedCodeLocation object

                                           #  used to do, so most places that used to use annotatedCodeLocation can now use a vanilla location. That is,

                                           #  it's not only a more logically cohesive type, but as a result, it's more generally useful.

  =fullyQualifiedLogicalName

  =logicalLocationKey

 

result

  =locations:location[]

  +analysisTarget:fileLocation             # A single analysis target, at the "result" level, applying to all the location objects in the location array.

  ~relatedLocations:location[]             # Formerly an array of annotatedCodeLocation, but now that location has a message property, location suffices.

  =codeFlows:codeFlow[]

 

codeFlow

  =threadFlows:threadFlow[]                # This assumes we accept the change for #80, "Code flow enhancements."

 

threadFlow

  ~locations:codeFlowLocation[]            # Used to be annotatedCodeLocation[]. But many of the properties in aCL were *specific to* code flows, so

                                           #  we renamed the type.

 

physicalLocation

  fileLocation

  region

  +contextRegion:region                    # This addresses Jim's Issue #99.

 

region

  =startLine, ...                          # The existing region properties.

  +snippet:fileContent                     # region gains a snippet property, per #99

 

~codeFlowLocation                          # Approximately the same as the existing annotatedCodeLocation, but does *not* include a couple of

                                           #  properties that were used only on stack frames, not in code flows.

 

  -physicalLocation                        # Now that the location object no longer carries around the baggage of two logical-location-valued

  -fullyQualifiedLogcalName                #  properties, we can replace these four properties with a location (note that location now has a

  -logicalLocationKey                      #  message property!

  -message

  +location

 

  =step                                    # So a codeFlowLocation is a location plus a few code-flow-specific properties.

  =importance

  =nestingLevel                            # Assuming we approve #80

  =executionOrder                          # Assuming we approve #80

 

+stackFrameLocation                        # Similarly, instead of overloading annotatedCodeLocation with some code-flow-specific properties

  location                                 #  and some stack-frame-specific properties, we define a new type, which is a location plus just

  threadId                                 #  whatever a stack frame needs.

  module

 

Thanks for reading!

Larry