eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Annotation':

Home

Documentation
www.exept.de
Everywhere
for:
 [back]

Class: Annotation

Inheritance:

   Object
   |
   +--Annotation
      |
      +--Annotation::JavaScriptSelector
      |
      +--Annotation::NameSpace
      |
      +--Annotation::Resource
      |
      +--Annotation::Unknown
      |
      +--HTTPSimpleJSONRestService::RestCallAnnotation
Package:
stx:libbasic
Category:
Kernel-Extensions
Version:
rev: 1.39 date: 2024/02/13 19:57:04
user: cg
file: Annotation.st directory: libbasic
module: stx stc-classLibrary: libbasic

Description:


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 before or after any temporaries.  

A common example is the primitive pragma:
    <primitive: 123 errorCode: 'errorCode'>
but you can add your 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
        SystemBrowser default browseAllSelect: [:m| m pragmas notEmpty] 
    or: 
        Smalltalk browseAllSelect: [:m| m pragmas notEmpty]

(in Squeak/Pharo): to browse all nonprimitive methods with pragmas evaluate
    SystemBrowser default browseAllSelect: [:m| m primitive isZero and: [m pragmas notEmpty]]

knownPragmas
    context flagging:
        <context: #return>
            tells the compiler that this context will be returned through
            via 'thisContext sender ... sender return' from a lower context.
            The compiler's will create a returnable context
            (i.e. prevent context optimizations/eliminations)

    exception handling:    
        <exception: #handle> 
            marks contexts as exception handlers.

        <exception: #unwind>
            marks contexts which contain unwind actions

        <exception: #raise>
            marks contexts which raise an exception

    misc:        
        <resource: #skipInDebuggersWalkBack>
            will not be shown in the debugger

        <resource: #style (...)>
            affected by style sheet

        <resource: #obsolete>
            marks obsolete methods

        <modifier: #super> 
            must be called if redefined i.e. redefiners MUST do a super-send

        <inspector2Tab>     
        <postLoad>
        <swizzle: selector>

        <category: '...'>
            GNU-smalltalk's way of defining method categories


copyright
COPYRIGHT (c) 2010 by Jan Vrany, SWING Research Group. CTU in Prague
             All Rights Reserved

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the 'Software'), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

Class protocol:

finding
o  allInMethod: aMethod
VisualWorks compatibility.
Answer a collection of all pragmas found in the given method

o  allNamed: aSymbol
Answer a collection of all pragmas found in all methods of all classes whose keyword is aSymbol.

Usage example(s): 

     Annotation allNamed:'worldMenu'

o  allNamed: aSymbol from: aSubClass to: aSuperClass
Answer a collection of all pragmas found in methods of all classes
between aSubClass and aSuperClass (inclusive) whose keyword is aSymbol.

o  allNamed: aSymbol from: aSubClass to: aSuperClass sortedByArgument: anInteger
Answer a collection of all pragmas found in methods of all classes between aSubClass and aSuperClass (inclusive) whose keyword is aSymbol, sorted according to argument anInteger.

o  allNamed: aSymbol from: aSubClass to: aSuperClass sortedUsing: aSortBlock
Answer a collection of all pragmas found in methods of all classes between aSubClass and aSuperClass (inclusive) whose keyword is aSymbol, sorted according to aSortBlock.

o  allNamed: aSymbol in: aClass
Answer a collection of all pragmas found in methods of aClass whose keyword is aSymbol.

o  allNamed: aSymbol in: aClass sortedByArgument: anInteger
Answer a collection of all pragmas found in methods of aClass whose keyword is aSymbol, sorted according to argument anInteger.

o  allNamed: aSymbol in: aClass sortedUsing: aSortBlock
Answer a collection of all pragmas found in methods of aClass whose keyword is aSymbol, sorted according to aSortBlock.

initialization
o  initialize
Invoked at system start or when the class is dynamically loaded.

instance creation
o  Rest: args
( an extension from the stx:goodies/webServer package )
Used by HTTPRestService to define service call entry methods.
Should never appear in source code!

o  javaScript: aSymbolOrString
Used to define the javascript replacement selector (function name)

o  nameSpace: aString

o  namespace: aString

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  resource: type
resource method - returns menu, spec or image,
or accesses/uses the viewStyle

o  resource: type values: value
resource method - returns menu, spec or image,
or accesses/uses the viewStyle

instance creation - basic
o  for: aMethod selector: aSelector arguments: anArray
Q: is this obsolete?

o  key: key arguments: arguments
cg: do not react on all those methods inherited from Object (such as inline:)

o  keyword: aSymbol arguments: anArray
Modified (format): / 29-08-2018 / 10:32:31 / Claus Gittinger

o  method: method key: key arguments: arguments
cg: do not react on all those methods inherited from Object (such as inline:)

private
o  withPragmasIn: aClass do: aBlock

Instance protocol:

accessing
o  arguments

o  first

o  key

accessing-method
o  method
Answer the compiled-method containing the pragma.

o  methodClass
Answer the class of the method containing the pragma.

o  methodSelector
Answer the selector of the method containing the pragma.
Added to not confuse this with the selector (i.e. key) of the pragma's message pattern.

o  selector
Answer the selector of the method containing the pragma.
Do not confuse this with the selector (i.e. key) of the pragma's message pattern.
(use methodSelector, to make this clear)

accessing-pragma
o  argumentAt: anInteger
Answer one of the arguments of the pragma.

o  argumentAt: anInteger ifAbsent: exceptionValue
Answer one of the arguments of the pragma or exceptionValue's value if not present.

o  argumentCount
Answer the number of arguments in the pragma.

o  message
Answer the message of the receiving pragma.

o  numArgs
marked as obsolete by Stefan Vogel at 9-Feb-2024

** This is an obsolete interface - do not use it (it may vanish in future versions) **

comparing
o  analogousCodeTo: anObject

compatibility - squeak
o  keyword

initialization
o  key: keyArg

o  key: keyArg arguments: argumentsArg

o  setArguments: anArray

o  setKeyword: aSymbol

o  setMethod: aCompiledMethod

** This method must be redefined in concrete classes (subclassResponsibility) **

printing & storing
o  printOn: aStream
append a printed representation of the receiver to the argument, aStream

o  storeOn: aStream
superclass Annotation says that I am responsible to implement this method

processing
o  annotatesClass: aClass
Nothing to do

o  annotatesMethod: aMethod
Nothing to do

o  installedInMethod: aMethod
called right after being added to a method's annotations.
Can be redefined in concrete annotation classes to do something with the
method or class

o  sendTo: anObject
Send the pragma keyword together with its arguments to anObject and answer the result.

o  withArgumentsDo: aBlock
Pass the arguments of the receiving pragma into aBlock and answer the result.

queries
o  refersToLiteral: anObject
return true if the receiver or recursively any array element in the
receiver refers to aLiteral (i.e. a deep search)

o  refersToLiteralMatching: aMatchString

testing
o  hasLiteral: aLiteral

o  hasLiteralSuchThat: aBlock
Answer true if litBlock returns true for any literal in the receiver, even if embedded in further array structure.
This method is only intended for private use by CompiledMethod hasLiteralSuchThat:

o  isJavaScriptSelector
true if this is a (wellknown) javascript selector annotation

o  isResource
true if this is a (wellknown) resource annotation

o  isUnknown
true if this is a (non-wellknown) other annotation

Private classes:

    JavaScriptSelector
    NameSpace
    Resource
    Unknown

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 04:44:16 GMT