| blob | 9bade56965939549c59ae4efa3f476b34b84a3a0 |
1 ;;; semantic/scope.el --- Analyzer Scope Calculations
3 ;; Copyright (C) 2007-2017 Free Software Foundation, Inc.
5 ;; Author: Eric M. Ludlam <eric@siege-engine.com>
7 ;; This file is part of GNU Emacs.
9 ;; GNU Emacs is free software: you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation, either version 3 of the License, or
12 ;; (at your option) any later version.
14 ;; GNU Emacs is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
22 ;;; Commentary:
23 ;;
24 ;; Calculate information about the current scope.
25 ;;
26 ;; Manages the current scope as a structure that can be cached on a
27 ;; per-file basis and recycled between different occurrences of
28 ;; analysis on different parts of a file.
29 ;;
30 ;; Pattern for Scope Calculation
31 ;;
32 ;; Step 1: Calculate DataTypes in Scope:
33 ;;
34 ;; a) What is in scope via using statements or local namespaces
35 ;; b) Lineage of current context. Some names drawn from step 1.
36 ;;
37 ;; Step 2: Convert type names into lists of concrete tags
38 ;;
39 ;; a) Convert each datatype into the real datatype tag
40 ;; b) Convert namespaces into the list of contents of the namespace.
41 ;; c) Merge all existing scopes together into one search list.
42 ;;
43 ;; Step 3: Local variables
44 ;;
45 ;; a) Local variables are in the master search list.
46 ;;
61 ;;; Code:
65 :documentation
68 :documentation
69 "The list of types currently in scope.
70 For C++, this would contain anonymous namespaces known, and
73 :documentation
74 "List of parents in scope w/in the body of this function.
75 Presumably, the members of these parent classes are available for access
79 Each entry is ( PARENT . PROTECTION ), where PARENT is a type, and
82 :documentation
85 :documentation
88 :documentation
91 :documentation
94 :documentation
96 )
97 "Cache used for storage of the current scope by the Semantic Analyzer.
100 ;;; METHODS
101 ;;
102 ;; Methods for basic management of the structure in semanticdb.
103 ;;
105 "Reset OBJ back to it's empty settings."
115 )
118 new-tags)
119 "Synchronize a CACHE with some NEW-TAGS."
124 new-tags)
125 "Synchronize a CACHE with some changed NEW-TAGS."
126 ;; If there are any includes or datatypes changed, then clear.
131 )
134 "Get the current cached scope, and reset it."
141 types-in-scope)
142 "Set the :typescope property on CACHE to some types.
143 TYPES-IN-SCOPE is a list of type tags whos members are
144 currently in scope. For each type in TYPES-IN-SCOPE,
145 add those members to the types list.
146 If nil, then the typescope is reset."
150 newts))
151 )
154 ;;; TAG SCOPES
155 ;;
156 ;; These fcns should be used by search routines that return a single
157 ;; tag which, in turn, may have come from a deep scope. The scope
158 ;; will be attached to the tag. Thus, in future scope based calls, a
159 ;; tag can be passed in and a scope derived from it.
162 "Clone TAG, and return it. Add SCOPETAGS as a tag-local scope.
163 Stores the SCOPETAGS as a set of tag properties on the cloned tag."
165 )
167 ))
170 "Get from TAG the list of tags comprising the scope from TAG."
173 ;;; SCOPE UTILITIES
174 ;;
175 ;; Functions that do the main scope calculations
179 "Return a list of types currently in scope at POSITION.
180 This is based on what tags exist at POSITION, and any associated
184 "Return a list of types currently in scope at POSITION.
185 Use `semantic-ctxt-scoped-types' to find types."
190 ;; Let's ask if any types are currently scoped. Scoped
191 ;; classes and types provide their public methods and types
192 ;; in source code, but are unrelated hierarchically.
195 ;; Get this thing as a tag
199 ;; If we did not find it in the typecache,
200 ;; look in the tags we found so far
203 code-scoped-types))))
209 code-scoped-types)))
221 )))
223 ;;------------------------------------------------------------
225 "Return a list of types in order of nesting for the context of POSITION.
226 If POSITION is in a method with a named parent, find that parent, and
227 identify it's scope via overlay instead.
228 Optional SCOPETYPES are additional scoped entities in which our parent might
232 "Return a list of types in order of nesting for the context of POSITION.
233 If POSITION is in a method with a named parent, find that parent, and
234 identify it's scope via overlay instead.
235 Optional SCOPETYPES are additional scoped entities in which our parent might
236 be found.
237 This only finds ONE immediate parent by name. All other parents returned
238 are from nesting data types."
246 )
247 ;; In case of arg lists or some-such, throw out non-types.
251 ;; Remove duplicates
255 ;; Step 1:
256 ;; Analyze the stack of tags we are nested in as parents.
257 ;;
259 ;; If we have a pparent tag, let's go there
260 ;; an analyze that stack of tags.
264 ;; Step one, find the merged version of stack in the typecache.
267 )
268 ;; @todo - can we use the typecache ability to
269 ;; put a scope into a tag to do this?
276 ;; When there was nothing from the typecache, then just
277 ;; use what's right here.
279 ;; Add things to STACK until we cease finding tags of class type.
281 ;; Otherwise, just add this to the returnlist, but make
282 ;; sure we didn't already have that tag in scopetypes
288 ))
289 )
291 ;; Only do this level of analysis for functions.
293 ;; Step 2:
294 ;; If the function tag itself has a "parent" by name, then that
295 ;; parent will exist in the scope we just calculated, so look it
296 ;; up now.
297 ;;
300 ;; We have a parent, search for it.
308 searchname
313 ptag)
315 ;; Find the next entry in the referenced type for
316 ;; our function, and append to return list till our
317 ;; returnlist is empty.
331 )))
332 )
338 'type
339 miniscope
340 ))
341 ))
348 )
352 )))
353 )
354 returnlist
355 )))
358 "Return the full lineage of tags from PARENTS.
359 The return list is of the form ( TAG . PROTECTION ), where TAG is a tag,
360 and PROTECTION is the level of protection offered by the relationship.
361 Optional SCOPETYPES are additional scoped entities in which our parent might
365 "Return the full lineage of tags from PARENTS.
366 The return list is of the form ( TAG . PROTECTION ), where TAG is a tag,
367 and PROTECTION is the level of protection offered by the relationship.
368 Optional SCOPETYPES are additional scoped entities in which our parent might
369 be found."
372 )
383 ;; doesn't provide access to private slots?
387 ))
388 miniscope))
390 lineage))
393 ;;------------------------------------------------------------
396 "Return accessible tags when TYPELIST and PARENTLIST is in scope.
397 Tags returned are not in the global name space, but are instead
398 scoped inside a class or namespace. Such items can be referenced
403 "Return accessible tags when TYPELIST and HALFSCOPE is in scope.
404 HALFSCOPE is the current scope partially initialized.
405 Tags returned are not in the global name space, but are instead
406 scoped inside a class or namespace. Such items can be referenced
413 )
414 ;; Loop over typelist, and find and merge all namespaces matching
415 ;; the names in typelist.
419 ;; By using the typecache, our namespaces are pre-merged.
421 ))
424 ;; Loop over the types (which should be sorted by position)
425 ;; adding to the scopelist as we go, and using the scopelist
426 ;; for additional searching!
432 miniscope)
433 currentscope))
436 ;; Collect all the types (class, etc) that are in our heritage.
437 ;; These are types that we can extract members from, not those
438 ;; declared in using statements, or the like.
439 ;; Get the PARENTS including nesting scope for this location.
445 miniscope)
446 currentscope))
449 ;; Loop over all the items, and collect any type constants.
454 )
458 currentscope))
460 ;;------------------------------------------------------------
462 "Calculate the access class for TYPE as defined by the current SCOPE.
463 Access is related to the :parents in SCOPE. If type is a member of SCOPE
464 then access would be 'private. If TYPE is inherited by a member of SCOPE,
468 "Calculate the access class for TYPE as defined by the current SCOPE."
472 )
474 ;; Investigate the parent, and see how it relates to type.
475 ;; If these tags are basically the same, then we have full access.
479 )
480 ;; Look to see if type is in our list of inherited parents.
482 ;; pi is a cons cell ( PARENT . protection)
487 ;; protection via inheritance means to pull out different
488 ;; bits based on protection labels in an opposite way.
493 )))
494 )
495 ;; Not in our parentage. Is type a FRIEND?
501 )))
502 ;; Found nothing, return public
504 ))
508 "Return a list of slots that are valid completions from the list of SLOTS.
509 If a tag in SLOTS has a named parent, then that implies that the
510 tag is not something you can complete from within TYPE."
513 )
515 ;; We have to specially deal with 'using' tags here, since those
516 ;; pull in namespaces or classes into the current scope.
517 ;; (Should this go into c.el? If so, into which override?)
522 ;; Search the typecache, first for the unqualified name
525 ;; If that didn't return anything, use
526 ;; fully qualified name
530 ;; Use recursion to examine that namespace or class
533 ;; If we have a filename, copy the tags with it
536 leftover)))
537 ;; Otherwise just run with it
545 "Return all parts of TYPE, a tag representing a TYPE declaration.
546 SCOPE is the scope object.
547 NOINHERIT turns off searching of inherited tags.
548 PROTECTION specifies the type of access requested, such as 'public or 'private."
550 nil
552 ;; SLOTS are the slots directly a part of TYPE.
555 access
556 type allslots))
558 ;; EXTMETH are externally defined methods that are still
559 ;; a part of this class.
561 ;; @TODO - is this line needed?? Try w/out for a while
562 ;; @note - I think C++ says no. elisp might, but methods
563 ;; look like defuns, so it makes no difference.
566 ;; INHERITED are tags found in classes that our TYPE tag
567 ;; inherits from. Do not do this if it was not requested.
570 access)))
571 )
575 ;;(semantic--tag-put-property TAG :filename fname)
577 ;; If it has a filename, just go with it...
579 ;; Otherwise, copy the tag w/ the guessed filename.
581 copyslots)))
582 )
584 ))
585 ;; Flatten the database output.
587 )))
590 "Return all tags that TYPE inherits from.
591 Argument SCOPE specify additional tags that are in scope
592 whose tags can be searched when needed, OR it may be a scope object.
593 ACCESS is the level of access we filter on child supplied tags.
594 For languages with protection on specific methods or slots,
595 it should strip out those not accessible by methods of TYPE.
596 An ACCESS of 'public means not in a method of a subclass of type.
597 A value of 'private means we can access private parts of the originating
598 type."
604 type pname))
605 )
607 nil ;; Don't do it.
609 ;; We can get some parts of this type.
611 ;; Do not pull in inherited parts here. Those
612 ;; will come via the inherited-tag-map fcn
614 p scope t protection))
615 ))))
616 scope)
617 ret))
620 "Map all parents of TYPE to FCN. Return tags of all the types.
621 Argument SCOPE specify additional tags that are in scope
622 whose tags can be searched when needed, OR it may be a scope object."
625 ;; interfaces. Inheriting from an interfaces implies
626 ;; you have a copy of all methods locally. I think.
628 ps pt
630 )
633 ;; Create a SCOPE just for looking up the parent based on where
634 ;; the parent came from.
635 ;;
636 ;; @TODO - Should we cache these mini-scopes around in Emacs
637 ;; for recycling later? Should this become a helpful
638 ;; extra routine?
641 ;; If TYPE has a position, go there and get the scope.
644 ;; We need to make a mini scope, and only include the misc bits
645 ;; that will help in finding the parent. We don't really need
646 ;; to do any of the stuff related to variables and what-not.
651 ;;(parentinherited (semantic-analyze-scope-lineage-tags parents scopetypes))
653 )
656 ;;(oset tmpscope parentinheritance parentinherited)
662 )))
663 ;; END creating tmpscope
665 ;; Look up each parent one at a time.
671 p))
674 ;; A backup hack.
680 ;; Note that we pass the original SCOPE in while recursing.
681 ;; so that the correct inheritance model is passed along.
683 )))
684 nil))
686 ;;; ANALYZER
687 ;;
688 ;; Create the scope structure for use in the Analyzer.
689 ;;
690 ;;;###autoload
692 "Calculate the scope at POINT.
693 If POINT is not provided, then use the current location of point.
694 The class returned from the scope calculation is variable
695 `semantic-scope-cache'."
698 nil ;; Don't do anything...
710 )
714 ;; Even though we can recycle most of the scope, we
715 ;; need to redo the local variables since those change
716 ;; as you move about the tag.
725 parents scopetypes))
726 )
735 )
736 ;; Step 3:
741 )
743 ;; Try looking for parents again.
749 ;; Try calculating the scope again with the new inherited parent list.
752 )))
754 ;; Fill out the scope.
759 )))
760 ;; Make sure we become dependent on the typecache.
762 ;; Handy debug output.
766 ;; Return ourselves, but make a clone first so that the caller
767 ;; can reset the scope cache without affecting others.
771 "Find the tag with NAME, and optional CLASS in the current SCOPE-IN.
772 Searches various elements of the scope for NAME. Return ALL the
773 hits in order, with the first tag being in the closest scope."
776 ;; Is the passed in scope really a scope? if so, look through
777 ;; the options in that scope.
780 ;; This should be first, but bugs in the
781 ;; C parser will turn function calls into
782 ;; assumed int return function prototypes. Yuck!
790 )
793 ;; Scan out things not of the right class.
796 )
801 ;; It may be we need to hack our way through type typescope.
805 typescoperaw)
807 fullscoperaw)
808 ))
816 ;; Once done, store the current typecache lookup
819 )))
820 ;; Return it.
821 ans)
822 ;; Not a real scope. Our scope calculation analyze parts of
823 ;; what it finds, and needs to pass lists through to do it's work.
824 ;; Tread that list as a singly entry.
827 scope)
828 )))
830 ;;; DUMP
831 ;;
833 "Insert CONTEXT into the current buffer in a nice way."
838 ;;(semantic-analyze-princ-sequence (oref context fullscope) "Fullscope: " )
841 )
845 ;; Local variables:
846 ;; generated-autoload-file: "loaddefs.el"
847 ;; generated-autoload-load-name: "semantic/scope"
848 ;; End:
850 ;;; semantic/scope.el ends here