[squeak-dev] [Documentation] Pragma / Method Annotation / Method Property | SUMMARY

Hannes Hirzel hannes.hirzel at gmail.com
Tue Apr 27 17:44:43 UTC 2010


Dear all

I had a good learning experience yesterday in the discussion about pragmas.
I'll try to come up with a summary which hopefully will end in a
HelpSystem "book"
http://www.squeaksource.com/HelpSystem.html
I invite you to read through this and provide feedback and maybe updates.

The thread starts here:
http://lists.squeakfoundation.org/pipermail/squeak-dev/2010-April/149595.html

We are talking about the messages which appear between
   < >
at more than 800 places.

People call them
- Pragma
- or Method Annotation
- or Method Property

They can be seen as meta data, processing instructions, build information.
Special mechanisms make use of them.

It is a kind of second level within a method body.


Pragmas / Method Annotations / Method Properties
are used for
1) primitives
2) version information
3) preferences
4) and probably in the future for the menu definitions


--Hannes


APPENDIXES
1) The class comment of class 'Pragma'
2) An excerpt of the Pragma discussion thread



===========================================================================
1) Comment of the class 'Pragma'
===========================================================================

I represent an occurrence of a pragma in a compiled method.  A pragma
is a literal message pattern that occurs between angle brackets at the
start of a method after any temporaries.  A common example is the
primitive pragma:
	<primitive: 123 errorCode: 'errorCode'>
but one can add one's own and use them as metadata attached to a
method.  Because pragmas are messages one can browse senders and
implementors and perform them.  One can query a method for its pragmas
by sending it the pragmas message, which answers an Array of instances
of me, one for each pragma in the method.

I can provide information about the defining class, method, its
selector, as well as the information about the pragma keyword and its
arguments. See the two 'accessing' protocols for details.
'accessing-method' provides information about the method the pragma is
found in, while 'accessing-pragma' is about the pragma itself.

Instances are retrieved using one of the pragma search methods of the
'finding' protocol on the class side.

To browse all methods with pragmas in the system evaluate
	SystemNavigation default browseAllSelect: [:m| m pragmas notEmpty]
and to browse all nonprimitive methods with pragmas evaluate
	SystemNavigation default browseAllSelect: [:m| m primitive isZero
and: [m pragmas notEmpty]]




==========================================================================
2) Here is an excerpt of the first part of the thread, the second
parts deals with implementation questions of the menu system.
===========================================================================


Igor Stasenko
-------------------
Pragmas are not code, even in old and limited forms, they simply
contain a meta-information for compiler.

If pragmas were code, then you would expect them to look like code i.e.:
   <[  | x y |  x := 5. y:= 6. x+y ] >

I treat a pragma as a message, sent to the compiler or parser framework i.e.
whenever the compiler sees:

    < foo: a with: z bar: zork>

its can be simply interpreted as a message sent to compiler(or parser):
    pragmaConsumer foo: a with: z bar: zork

where pragmaConsumer is an object which can do anything it wants for
taking this information into account, when processing the method's
source code.





Andreas Raab
--------------------
"A pragma is something that gives the compiler information about the
code without being code itself". Here, I was referring to "<> syntax"
which used to be code, and now it no longer is. Calling it "pragma"
however is just completely and utterly wrong in whichever way you look
at it.


Terminology is important and the terminology we currently have is
*extremely* confusing. People refer to "pragmas" and whenever a third
party hears that they think "oh, compiler stuff, better stay away from
it" not realizing that that's not what these are. This is how this
discussion started after all.



Bert Freudenberg
-------------------------
I think that "method annotation" captures the meaning best of the
alternatives mentioned so far.


Igor Stasenko
--------------------
both terms
   pragma / method annotation
are fine


pragmas is a subset of 'additional
arbitrary method state', which having a formally
defined structure 'instance of Pragma class'.


Hannes Hirzel
--------------------
- Pragmas are used in connection with primitives
- they are used in connection with package versions.


Andreas Raab
--------------------
I still find "method property" to be the best name since it doesn't
presume whether the property has an impact on code or not. A primitive
can be a method property that represents code, a pragma can be a
property that represents a compiler instruction, an annotation can be
a property that is used for discovery.


Andreas Raab
--------------------
Method properties/Pragmas/Annotations are there for discovery by other
code. In case of menu definitions you are basically announcing "hey if
anyone cares, here's an action that you might want to place in a
menu".



More information about the Squeak-dev mailing list