Changes between Version 23 and Version 24 of SemanticQuery

Timestamp:

Feb 27, 2015, 2:03:11 PM (9 years ago)

Author:

manualwiki

Comment:

mostly sq-type related changes

SemanticQuery

@@ -8 +8 @@
 * [SemanticQuery/Components Available components]: lists the names of currently available initial selectors, selectors and properties and their possible abbreviations and synonyms.
 * [SemanticQuery/Examples Examples]: basic and advanced query examples, and queries for checking coding conventions.
-* [SemanticQuery/Highlights Highlighted features]: semantic information about specs and types can be retrieved.
 
 
@@ -250 +249 @@
 module and are called by any module in the database.
 
+==== Limitations: ====
+- When the result of an operand is a closure or iteration, their results will be converted to the normal data structure as if they were reached using selections.
+- The operands can not be statistics.
+
 == Specifying grouping of results ==
 
@@ -262 +265 @@
 }}}
 The results from the above example are grouped by the first selector i.e. modules.
+
+When the groupby option is used for queries with set operators, the interpretation depends on the type of the used set operators.
+
+If the operands of the outermost set operation in the query are semantic queries themselves, the groupby option is passed to the execution of the operands. So in the following query
+{{{
+ri:q("(mods.funs.vars.name U mods.funs.loc)", [{groupby, 2}]).
+}}}
+the results are grouped by functions, the second selector of each sub-query.
+
+When the grouping of a set operator's sub-queries do not match(different selector types, or at least one of them is not grouped), the results will be grouped by files; as in the following query:
+{{{
+ri:q("(mods.funs.vars.name U mods.funs.clause.loc)", [{groupby, 3}]).
+}}}
+As far as grouping is concerned, other set operators(e.g. a set operator between series of selectors) in a query are regarded as one unit. The numbering of the elements as used by the groupby option are incremented by one after the set operator, as if it was a single selector of the type resulting from any of the operands.
+
+''Example:''
+{{{
+ri:q("mods(.funs[name ~ \"filter\"].calls U .exports[name ~ \"drop\"]).params.vars", [{groupby, 2}]).
+}}}
+So the query above is grouped by functions, the type of the results of the set operator.
+
+== Analysing "-type" and "-spec" related informations ==
+
+Erlang is dynamically typed, but it provides notations for types in the Erlang syntax. Although these do not affect the operation of the compiled code, it is generally a good practice to utilize them for type checking and other purposes, like doc generation. Our tool analyzes and stores "-type", "-opaque", "-export_type", "-spec" attributes and the types of record fields. These information can be conveniently accessed/used and comprehended via semantic queries.
+
+=== Returned values for new internal types in sq: ===
+As it can be seen in the description of [SemanticQuery/Components Available components], for the practical use of analyzed type informations, new internal types have been introduced for semantic queries. When a query isn't continued with other selectors to reach conventional types, it might not be obvious what the results would be. In case of our text-based and graphical interfaces, the format of the shown result for each of these entities can be found in their corresponding pages: [SemanticQuery/SpecEntity Spec], [SemanticQuery/SpecParamEntity Spec param], [SemanticQuery/TypeEntity Type].
+
+Our scriptable interface, along with the textual representations, also provides the unique entities of the stored type informations, which might be used to differentiate between results even when their formatted values are the same.
+
+{{{
+ris:q("mods.specs.params.type.params").
+{rich,"a:prp_user/2\n    Key\n     Val\nb:prp_user/2\n    Key\n     Val\nc:prp_user/2\n    Key\n     Val\n",
+      [{entity,{'$gn',typexp,151}},
+       {entity,{'$gn',typexp,152}},
+       {entity,{'$gn',typexp,296}},
+       {entity,{'$gn',typexp,297}},
+       {entity,{'$gn',typexp,439}},
+       {entity,{'$gn',typexp,440}}]}
+}}}
+
+=== Detailed review of non-trivial selectors: ===
+
+During the specification we have tried our best to keep things simple in the perspective of usability. This meant that for example we would not differentiate between namedtypes(user-defined, built-in) and type expressions. In some cases this have resulted in rather complex specifications. Under normal circumstances, the different behaviors should be intuitively evident and would not cause any surprise. For the newly introduced entities, information about these selectors can be found on their respective pages: [SemanticQuery/SpecEntity Spec], [SemanticQuery/SpecParamEntity Spec param], [SemanticQuery/TypeEntity Type]. For others they are listed here:
+
+==== File.typerefs: ====
+This selector returns all types referenced in the file. It does not return type expressions, but it returns all other types(even built-in types or ones which have been defined in an other file) that have been referenced in "-spec", "-type", "-opaque" attributes or record definitions.
+{{{
+ri:q("mods.typerefs").
+a.erl
+    erlang:atom/0
+    a:prp_user/2
+}}}
+
+==== Function.returntype(, Spec.returntype): ====
+Returns types or type expressions present as the return-type of the function's specs. It does not split union types, but please note that specs can be overloaded so even functions with only one clause can have multiple values. (Single-atom type expressions are filtered.)
+{{{
+ri:q("mods.funs.returntypes").
+a:g/2
+    erlang:atom/0
+}}}
+
+=== Limitations: ===
+ - For performance and readability reasons, type-expressions consisting of a single atom(e.g., bool, int, 'error') are filtered from results. This means, without re-parsing the textual representations, the results can not be used perform reliable type checking or comparison for functions. (We believe, including such simple expressions in results for an ordinarily large code-base would undermine the main goal of these features, which is providing an easy way for understanding type informations and their relation.)
+ - As of now, "@type" and "@spec" declarations are not analyzed.
+ - "-spec" attributes are not mapped to function clauses, but only to their functions.