rfc:simple-annotations

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Next revisionBoth sides next revision
rfc:simple-annotations [2016/05/13 10:52] – mindplayrfc:simple-annotations [2016/05/14 19:38] – mindplay
Line 1: Line 1:
 ====== PHP RFC: Simple Annotations ====== ====== PHP RFC: Simple Annotations ======
  
-  * Version: 0.1+  * Version: 0.3
   * Date: 2016-05-13   * Date: 2016-05-13
   * Author: Rasmus Schultz, rasmus@mindplay.dk   * Author: Rasmus Schultz, rasmus@mindplay.dk
Line 9: Line 9:
 ===== Introduction ===== ===== Introduction =====
  
-This RFC proposes the introduction of simple value annotations - arbitrary meta-data values applicable to classes and class members, obtainable via the reflection API.+This RFC proposes the introduction of simple value annotations - arbitrary values attached to classes and class members as meta-data, obtainable via reflection.
  
 As an alternative proposal to [[https://wiki.php.net/rfc/attributes|attributes]], this proposal aims to fully leverage existing language features, in order to provide more flexibility, lessen the learning curve, and expose meta-data in a manner that is more immediately useful, without having to build any run-time facilities. As an alternative proposal to [[https://wiki.php.net/rfc/attributes|attributes]], this proposal aims to fully leverage existing language features, in order to provide more flexibility, lessen the learning curve, and expose meta-data in a manner that is more immediately useful, without having to build any run-time facilities.
Line 17: Line 17:
 ===== Proposal ===== ===== Proposal =====
  
-The proposed syntax of a single annotation is extremely simple:+The proposed syntax of a single annotation is very simple:
  
 <code> <code>
Line 81: Line 81:
 Annotation expressions are not evaluated until reflection is invoked, and are evaluated only once and internally memoized upon the first call to ''getAnnotations()''. Annotation expressions are not evaluated until reflection is invoked, and are evaluated only once and internally memoized upon the first call to ''getAnnotations()''.
  
-==== Context Free ====+==== Annotations are Context-free ====
  
-Annotations are context-free - there is no access to variables in the parent class, file or global scope, no ''self'' or ''static'' or ''$this''.+By design, annotations expressions are evaluated individually in an empty scope - which means there is no access to variables in the parent class, file, local or global scope, e.g. no ''$this'', ''self'' or ''static''.
  
-This is by design - annotations work consistently regardless of which source element they are applied to, and may be evaluated without first creating an object instance.+Annotations work consistently regardless of which source element they are applied to, and may be evaluated without first creating an object instance.
  
-You can think of an annotation ''<< expression() >>'' as executing in an anonymous function scope, e.g.:+Annotations that do require context should explicitly ask for that context - for example, you could use an anonymous function, a ''callable'', or an anonymous class, to provide context via dependency injection.
  
-    function () { return expression(); }+==== Reflection API ====
  
-Annotations that do require context should explicitly ask for that context - for example, you could use an anonymous function to provide context via dependency injection.+The following classes will have an added ''getAnnotations()'' method: 
 + 
 + * ''ClassReflection'' 
 + * ''ReflectionFunctionAbstract'' (''ReflectionFunction'' and ''ReflectionMethod'') 
 + * ''ReflectionProperty'' 
 + * ''ReflectionParameter'' 
 + 
 +The ''getAnnotations()'' method has the following signature: 
 + 
 +    public function getAnnotations($filter = null) : array 
 + 
 +The optional ''$filter'' argument, if given, filters the returned list of annotations as follows: 
 + 
 + * If one of ''string'', ''int'', ''float'', ''bool'' are given, filters annotations using ''is_*()'' 
 + * If a fully-qualified class-name is given, filters annotations using ''instanceof'' 
 + 
 +If ''null'' is given (default) all annotations are returned. 
 + 
 +These methods do not take into account inheritance - annotations belong to the actual *declaration*, not to an abstract *member*, and as such, traversing parent classes, interfaces, etc. is up to the consumer.
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 125: Line 143:
 ===== Future Scope ===== ===== Future Scope =====
  
-TODO file-level annotations? others?+A future RFC might include certain system annotations containing directives for the language interpreter itself. This might include a memoization-annotation that instructs the interpreter to memoize a function result on first call, such as is [[https://docs.hhvm.com/hack/attributes/special|supported by Hack]].
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
rfc/simple-annotations.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools