[[Property:title|What makes a Certified Attachment Pattern]]
[[Property:weight|8]]
[[Property:uuid|1a20197d-5a88-59c3-9a04-512399125661]]
{{underconstruction}}



==A little background on CAPs==

Certified Attachment Patterns (CAPs) were described in the section on [[Void-safety: Background, definition, and tools#Certified attachment patterns (CAPs)|void-safety tools]]. To review, a CAP is a code pattern for a certain expression, say <code>exp</code> of a detachable type that ensures that <code>exp</code> will never have a void run-time value within the covered scope. 

A simple example is the familiar test for void reference:
<code>
            if l_x /= Void then
                l_x.do_something
            end
</code>
We know that after the explicit check to make sure <code>l_x</code> is not <code>Void</code>, that the feature application <code>l_x.do_something</code> is void-safe.
Of course, you should remember from previous discussions that <code>l_x</code> must be a local variable, a formal argument, or a  [[Void-safety: Background, definition, and tools#Stable attributes|stable attribute]].

When void-safety was first envisioned for Eiffel, it was intended that individual CAPs would be proven or certified and documented. This would produce a "catalog" of CAPs. 

What happened instead is that the members of the Eiffel standards committee have been able to produce and publish as part of the [http://www.ecma-international.org/publications/standards/Ecma-367.htm standard] a definition of the nature of a CAP from which a determination can be made as to whether a particular code pattern is or is not a CAP. 

The definition in the standard document is not easily readable by most developers. So, in this documentation, you will see various examples of CAPs and the rationale behind them.


==The standard CAP definition==

The Eiffel standard (2nd edition, June 2006) defines a CAP as follows:
----
'''''A Certified Attachment Pattern (or CAP) for an expression <code>exp</code> whose type is detachable is an occurrence of <code>exp</code> in one of the following contexts: '''''


'''''1. <code>exp</code> is an Object-Test Local and the occurrence is in its scope. '''''

'''''2. <code>exp</code> is a read-only entity and the occurrence is in the scope of a void test involving <code>exp</code>.'''''
----

The terminology used in the definition is precise. For example, terms like "read-only entity" and "scope of a void test" have specific meanings that are supported by their own definitions in the standard. 

Still, the standard does contain informative text that gives us a guideline that a CAP is a scheme to ensure that a particular expression of a detachable type will never have void run-time value in the scope covered by the CAP.

The discussion here will follow that guideline, and, as such, will be less formal (and consequently less precise) than that in the standard, and is intended to be a practical guide. Of course, the [http://www.ecma-international.org/publications/standards/Ecma-367.htm standard document] is available for download if you wish to investigate the specifics.


==CAP-able expressions==

In the first context in the definition above, the expression <code>exp</code> can be an '''Object-Test Local'''. An Object-Test Local is the identifier specified for a fresh local entity in an '''object test'''. Remember, object tests are coded using the [[Void-safety: Background, definition, and tools#The attached syntax (object test)|attached syntax]]. 
<code>
            attached x as l_x 
</code>
In the object test expression above, the identifier '''<code>l_x</code>''' is an Object-Test Local.

In the second context, the expression can be a '''read-only entity'''. Read-only entities are:
# Constant attributes
# Formal arguments
# Object-Test Locals
# <code>Current</code>

Additionally, the Eiffel Software compiler allows for [[Void-safety: Background, definition, and tools#Stable attributes|stable attributes]] and local variables to be protected by a CAP. 

Stable attributes are the only class attributes which are CAP-able. This is because stable attributes, once attached at run-time, can never have a void value again. 

Local variables can be used in a CAP as long as they are not the target of an assignment whose source is <code>Void</code> or some expression which could possibly be void.

So, for a local variable <code>l_string</code>, the following is valid:
<code>
        local
            l_string: detachable STRING
        do
            if l_string /= Void then
                l_string.append ("xyz")        -- Valid
                    ...
</code>
But, if <code>l_string</code> had been a target of an assignment in which the source could possibly have been void, then it could no longer be guaranteed that <code>l_string</code> is non-void. So, assuming that <code>my_detachable_string</code> is an attribute declared as type <code>detachable STRING</code>, the code in this example would be invalid:
<code>
        local
            l_string: detachable STRING
        do
            if l_string /= Void then
                l_string := my_detachable_string
                l_string.append ("xyz")        -- Invalid: my_detachable_string could be void
                    ...
</code>