1xref(3)                    Erlang Module Definition                    xref(3)
2
3
4

NAME

6       xref  - A Cross Reference Tool for analyzing dependencies between func‐
7       tions, modules, applications and releases.
8

DESCRIPTION

10       Xref is a cross reference tool that can be used for  finding  dependen‐
11       cies between functions, modules, applications and releases.
12
13       Calls  between  functions  are either local calls like f(), or external
14       calls like m:f(). Module data, which are extracted from BEAM files, in‐
15       clude  local  functions,  exported  functions, local calls and external
16       calls. By default, calls to built-in functions (BIF) are  ignored,  but
17       if the option builtins, accepted by some of this module's functions, is
18       set to true, calls to BIFs are included as well. It  is  the  analyzing
19       OTP  version  that  decides what functions are BIFs. Functional objects
20       are assumed to be called where they are created (and nowhere else). Un‐
21       resolved  calls are calls to apply or spawn with variable module, vari‐
22       able function, or variable arguments. Examples are M:F(a), apply(M,  f,
23       [a]),  and  spawn(m,  f(),  Args).  Unresolved calls are represented by
24       calls  where  variable  modules  have  been  replaced  with  the   atom
25       '$M_EXPR',   variable  functions  have  been  replaced  with  the  atom
26       '$F_EXPR', and variable number of arguments have been replaced with the
27       number  -1.  The  above  mentioned examples are represented by calls to
28       '$M_EXPR':'$F_EXPR'/1, '$M_EXPR':f/1,  and  m:'$F_EXPR'/-1.  The  unre‐
29       solved calls are a subset of the external calls.
30
31   Warning:
32       Unresolved  calls  make  module data incomplete, which implies that the
33       results of analyses may be invalid.
34
35
36       Applications are collections of modules. The modules'  BEAM  files  are
37       located in the ebin subdirectory of the application directory. The name
38       of the application directory determines the name and version of the ap‐
39       plication.  Releases are collections of applications located in the lib
40       subdirectory of the release directory. There is more to read about  ap‐
41       plications and releases in the Design Principles book.
42
43       Xref  servers  are  identified  by  names,  supplied  when creating new
44       servers. Each Xref server holds a set of releases, a  set  of  applica‐
45       tions, and a set of modules with module data. Xref servers are indepen‐
46       dent of each other, and all analyses are evaluated in  the  context  of
47       one  single Xref server (exceptions are the functions m/1 and d/1 which
48       do not use servers at all). The mode of an Xref server determines  what
49       module  data  are extracted from BEAM files as modules are added to the
50       server. Starting with R7, BEAM  files  compiled  with  the  option  de‐
51       bug_info contain so called debug information, which is an abstract rep‐
52       resentation of the code. In functions mode, which is the default  mode,
53       function  calls  and line numbers are extracted from debug information.
54       In modules mode, debug information is ignored if present, but dependen‐
55       cies  between modules are extracted from other parts of the BEAM files.
56       The modules mode is significantly less time and  space  consuming  than
57       the functions mode, but the analyses that can be done are limited.
58
59       An  analyzed  module  is a module that has been added to an Xref server
60       together with its module data. A library module is a module located  in
61       some  directory mentioned in the library path. A library module is said
62       to be used if some of its exported functions are used by some  analyzed
63       module.  An unknown module is a module that is neither an analyzed mod‐
64       ule nor a library module, but whose exported functions are used by some
65       analyzed module. An unknown function is a used function that is neither
66       local or exported by any analyzed module nor exported  by  any  library
67       module.  An  undefined  function is an externally used function that is
68       not exported by any analyzed module or library module.  With  this  no‐
69       tion,  a  local  function can be an undefined function, namely if it is
70       externally used from some module. All unknown functions are also  unde‐
71       fined functions; there is a figure in the User's Guide that illustrates
72       this relationship.
73
74       Starting with R9C, the module attribute tag deprecated can be  used  to
75       inform  Xref  about  deprecated functions and optionally when functions
76       are planned to be removed. A few examples show the idea:
77
78         -deprecated({f,1}).:
79           The exported function f/1 is deprecated. Nothing  is  said  whether
80           f/1 will be removed or not.
81
82         -deprecated({f,1,"Use g/1 instead"}).:
83           As above but with a descriptive string. The string is currently un‐
84           used by xref but other tools can make use of it.
85
86         -deprecated({f,'_'}).:
87           All exported functions f/0, f/1 and so on are deprecated.
88
89         -deprecated(module).:
90           All exported functions in the module are deprecated. Equivalent  to
91           -deprecated({'_','_'})..
92
93         -deprecated([{g,1,next_version}]).:
94           The function g/1 is deprecated and will be removed in next version.
95
96         -deprecated([{g,2,next_major_release}]).:
97           The  function  g/2  is deprecated and will be removed in next major
98           release.
99
100         -deprecated([{g,3,eventually}]).:
101           The function g/3 is deprecated and will eventually be removed.
102
103         -deprecated({'_','_',eventually}).:
104           All exported functions in the module are deprecated and will  even‐
105           tually be removed.
106
107       Before any analysis can take place, module data must be set up. For in‐
108       stance, the cross reference and the unknown functions are computed when
109       all  module data are known. The functions that need complete data (ana‐
110       lyze, q, variables) take care of setting up data automatically.  Module
111       data  need to be set up (again) after calls to any of the add, replace,
112       remove, set_library_path or update functions.
113
114       The result of setting up module data is the Call  Graph.  A  (directed)
115       graph  consists of a set of vertices and a set of (directed) edges. The
116       edges represent calls (From, To) between functions,  modules,  applica‐
117       tions  or  releases. From is said to call To, and To is said to be used
118       by From. The vertices of the Call Graph are the functions of all module
119       data: local and exported functions of analyzed modules; used BIFs; used
120       exported functions of library modules; and unknown functions. The func‐
121       tions  module_info/0,1 added by the compiler are included among the ex‐
122       ported functions, but only when called from some module. The edges  are
123       the function calls of all module data. A consequence of the edges being
124       a set is that there is only one edge if a function is locally or exter‐
125       nally used several times on one and the same line of code.
126
127       The  Call  Graph  is  represented by Erlang terms (the sets are lists),
128       which is suitable for many analyses. But  for  analyses  that  look  at
129       chains  of  calls,  a list representation is much too slow. Instead the
130       representation offered by the digraph module is used.  The  translation
131       of  the list representation of the Call Graph - or a subgraph thereof -
132       to the digraph representation does not come for free, so  the  language
133       used  for expressing queries to be described below has a special opera‐
134       tor for this task and a possibility to save the digraph  representation
135       for subsequent analyses.
136
137       In  addition  to  the Call Graph there is a graph called the Inter Call
138       Graph. This is a graph of calls (From, To) such that there is  a  chain
139       of calls from From to To in the Call Graph, and every From and To is an
140       exported function or an unused local function.  The  vertices  are  the
141       same as for the Call Graph.
142
143       Calls  between  modules,  applications  and  releases are also directed
144       graphs. The types of the vertices and edges of these graphs are  (rang‐
145       ing  from the most special to the most general): Fun for functions; Mod
146       for modules; App for applications; and Rel for releases. The  following
147       paragraphs  will describe the different constructs of the language used
148       for selecting and analyzing parts of the  graphs,  beginning  with  the
149       constants:
150
151         * Expression ::= Constants
152
153         * Constants ::= Consts | Consts : Type | RegExpr
154
155         * Consts ::= Constant | [Constant, ...] | {Constant, ...}
156
157         * Constant ::= Call | Const
158
159         * Call ::= FunSpec -> FunSpec | {MFA, MFA} | AtomConst -> AtomConst |
160           {AtomConst, AtomConst}
161
162         * Const ::= AtomConst | FunSpec | MFA
163
164         * AtomConst ::= Application | Module | Release
165
166         * FunSpec ::= Module : Function / Arity
167
168         * MFA ::= {Module, Function, Arity}
169
170         * RegExpr ::= RegString : Type | RegFunc | RegFunc : Type
171
172         * RegFunc ::= RegModule : RegFunction / RegArity
173
174         * RegModule ::= RegAtom
175
176         * RegFunction ::= RegAtom
177
178         * RegArity ::= RegString | Number | _ | -1
179
180         * RegAtom ::= RegString | Atom | _
181
182         * RegString ::= - a regular expression, as described in the  re  mod‐
183           ule, enclosed in double quotes -
184
185         * Type ::= Fun | Mod | App | Rel
186
187         * Function ::= Atom
188
189         * Application ::= Atom
190
191         * Module ::= Atom
192
193         * Release ::= Atom
194
195         * Arity ::= Number | -1
196
197         * Atom ::= - same as Erlang atoms -
198
199         * Number ::= - same as non-negative Erlang integers -
200
201       Examples  of constants are: kernel, kernel->stdlib, [kernel, sasl], [pg
202       -> mnesia, {tv, mnesia}] : Mod. It is an error if an instance of  Const
203       does not match any vertex of any graph. If there are more than one ver‐
204       tex matching an untyped instance of AtomConst, then the one of the most
205       general  type is chosen. A list of constants is interpreted as a set of
206       constants, all of the same type. A  tuple  of  constants  constitute  a
207       chain  of  calls (which may, but does not have to, correspond to an ac‐
208       tual chain of calls of some graph). Assigning a type to a list or tuple
209       of Constant is equivalent to assigning the type to each Constant.
210
211       Regular  expressions are used as a means to select some of the vertices
212       of a graph. A RegExpr consisting of a RegString and a type - an example
213       is  "xref_.*"  : Mod - is interpreted as those modules (or applications
214       or releases, depending on the type) that match  the  expression.  Simi‐
215       larly,  a  RegFunc  is  interpreted as those vertices of the Call Graph
216       that match the expression. An  example  is  "xref_.*":"add_.*"/"(2|3)",
217       which  matches  all  add  functions of arity two or three of any of the
218       xref modules. Another example, one that matches all functions of  arity
219       10 or more: _:_/"[1-9].+". Here _ is an abbreviation for ".*", that is,
220       the regular expression that matches anything.
221
222       The syntax of variables is simple:
223
224         * Expression ::= Variable
225
226         * Variable ::= - same as Erlang variables -
227
228       There are two kinds of variables: predefined variables and  user  vari‐
229       ables.  Predefined variables hold set up module data, and cannot be as‐
230       signed to but only used in queries. User variables on  the  other  hand
231       can  be assigned to, and are typically used for temporary results while
232       evaluating a query, and for keeping results of queries for use in  sub‐
233       sequent  queries.  The  predefined variables are (variables marked with
234       (*) are available in functions mode only):
235
236         E:
237           Call Graph Edges (*).
238
239         V:
240           Call Graph Vertices (*).
241
242         M:
243           Modules. All modules: analyzed modules, used library  modules,  and
244           unknown modules.
245
246         A:
247           Applications.
248
249         R:
250           Releases.
251
252         ME:
253           Module Edges. All module calls.
254
255         AE:
256           Application Edges. All application calls.
257
258         RE:
259           Release Edges. All release calls.
260
261         L:
262           Local Functions (*). All local functions of analyzed modules.
263
264         X:
265           Exported  Functions. All exported functions of analyzed modules and
266           all used exported functions of library modules.
267
268         F:
269           Functions (*).
270
271         B:
272           Used BIFs. B is empty if builtins is false for  all  analyzed  mod‐
273           ules.
274
275         U:
276           Unknown Functions.
277
278         UU:
279           Unused  Functions (*). All local and exported functions of analyzed
280           modules that have not been used.
281
282         XU:
283           Externally Used Functions. Functions of all modules - including lo‐
284           cal functions - that have been used in some external call.
285
286         LU:
287           Locally Used Functions (*). Functions of all modules that have been
288           used in some local call.
289
290         OL:
291           Functions with an attribute tag on_load (*).
292
293         LC:
294           Local Calls (*).
295
296         XC:
297           External Calls (*).
298
299         AM:
300           Analyzed Modules.
301
302         UM:
303           Unknown Modules.
304
305         LM:
306           Used Library Modules.
307
308         UC:
309           Unresolved Calls. Empty in modules mode.
310
311         EE:
312           Inter Call Graph Edges (*).
313
314         DF:
315           Deprecated Functions. All deprecated  exported  functions  and  all
316           used deprecated BIFs.
317
318         DF_1:
319           Deprecated  Functions.  All  deprecated  functions to be removed in
320           next version.
321
322         DF_2:
323           Deprecated Functions. All deprecated functions  to  be  removed  in
324           next version or next major release.
325
326         DF_3:
327           Deprecated  Functions.  All  deprecated  functions to be removed in
328           next version, next major release, or later.
329
330       These are a few facts about the predefined variables (the set operators
331       +  (union)  and  - (difference) as well as the cast operator (Type) are
332       described below):
333
334         * F is equal to L + X.
335
336         * V is equal to X + L + B + U, where X, L, B and U are pairwise  dis‐
337           joint (that is, have no elements in common).
338
339         * UU  is equal to V - (XU + LU), where LU and XU may have elements in
340           common. Put in another way:
341
342         * V is equal to UU + XU + LU.
343
344         * OL is a subset of F.
345
346         * E is equal to LC + XC. Note that LC and XC  may  have  elements  in
347           common, namely if some function is locally and externally used from
348           one and the same function.
349
350         * U is a subset of XU.
351
352         * B is a subset of XU.
353
354         * LU is equal to range LC.
355
356         * XU is equal to range XC.
357
358         * LU is a subset of F.
359
360         * UU is a subset of F.
361
362         * range UC is a subset of U.
363
364         * M is equal to AM + LM + UM, where AM, LM and UM are  pairwise  dis‐
365           joint.
366
367         * ME is equal to (Mod) E.
368
369         * AE is equal to (App) E.
370
371         * RE is equal to (Rel) E.
372
373         * (Mod)  V  is  a subset of M. Equality holds if all analyzed modules
374           have some local, exported, or unknown function.
375
376         * (App) M is a subset of A. Equality holds if all  applications  have
377           some module.
378
379         * (Rel)  A is a subset of R. Equality holds if all releases have some
380           application.
381
382         * DF_1 is a subset of DF_2.
383
384         * DF_2 is a subset of DF_3.
385
386         * DF_3 is a subset of DF.
387
388         * DF is a subset of X + B.
389
390       An important notion is that of conversion of expressions. The syntax of
391       a cast expression is:
392
393         * Expression ::= ( Type ) Expression
394
395       The interpretation of the cast operator depends on the named type Type,
396       the type of Expression, and the structure of the elements of the inter‐
397       pretation  of  Expression. If the named type is equal to the expression
398       type, no conversion is done. Otherwise, the conversion is done one step
399       at  a  time; (Fun) (App) RE, for instance, is equivalent to (Fun) (Mod)
400       (App) RE. Now assume that the interpretation of Expression is a set  of
401       constants  (functions, modules, applications or releases). If the named
402       type is more general than the expression type, say Mod and Fun  respec‐
403       tively,  then  the  interpretation of the cast expression is the set of
404       modules that have at least one of their functions mentioned in the  in‐
405       terpretation  of the expression. If the named type is more special than
406       the expression type, say Fun and Mod, then the  interpretation  is  the
407       set  of  all the functions of the modules (in modules mode, the conver‐
408       sion is partial since the local functions are not known).  The  conver‐
409       sions  to  and from applications and releases work analogously. For in‐
410       stance, (App) "xref_.*" : Mod returns all  applications  containing  at
411       least one module such that xref_ is a prefix of the module name.
412
413       Now  assume that the interpretation of Expression is a set of calls. If
414       the named type is more general than the expression type,  say  Mod  and
415       Fun respectively, then the interpretation of the cast expression is the
416       set of calls (M1, M2) such that the interpretation  of  the  expression
417       contains a call from some function of M1 to some function of M2. If the
418       named type is more special than the expression type, say Fun  and  Mod,
419       then  the interpretation is the set of all function calls (F1, F2) such
420       that the interpretation of the expression contains a call (M1, M2)  and
421       F1  is  a  function  of M1 and F2 is a function of M2 (in modules mode,
422       there are no functions calls, so a cast to Fun always yields  an  empty
423       set). Again, the conversions to and from applications and releases work
424       analogously.
425
426       The interpretation of constants and variables are sets, and those  sets
427       can be used as the basis for forming new sets by the application of set
428       operators. The syntax:
429
430         * Expression ::= Expression BinarySetOp Expression
431
432         * BinarySetOp ::= + | * | -
433
434       +, * and - are interpreted as union, intersection  and  difference  re‐
435       spectively:  the  union of two sets contains the elements of both sets;
436       the intersection of two sets contains the elements common to both sets;
437       and  the  difference of two sets contains the elements of the first set
438       that are not members of the second set. The elements of  the  two  sets
439       must  be of the same structure; for instance, a function call cannot be
440       combined with a function. But if a cast operator can make the  elements
441       compatible,  then  the  more general elements are converted to the less
442       general element type. For instance, M + F is equivalent to (Fun) M + F,
443       and  E - AE is equivalent to E - (Fun) AE. One more example: X * xref :
444       Mod is interpreted as the set of functions exported by the module xref;
445       xref  :  Mod  is converted to the more special type of X (Fun, that is)
446       yielding all functions of xref, and the intersection with X (all  func‐
447       tions  exported by analyzed modules and library modules) is interpreted
448       as those functions that are exported by some module  and  functions  of
449       xref.
450
451       There are also unary set operators:
452
453         * Expression ::= UnarySetOp Expression
454
455         * UnarySetOp ::= domain | range | strict
456
457       Recall  that  a  call  is a pair (From, To). domain applied to a set of
458       calls is interpreted as the set of all vertices From, and range as  the
459       set  of  all  vertices To. The interpretation of the strict operator is
460       the operand with all calls on the form (A, A) removed.
461
462       The interpretation of the restriction operators  is  a  subset  of  the
463       first  operand,  a set of calls. The second operand, a set of vertices,
464       is converted to the type of the first operand. The syntax  of  the  re‐
465       striction operators:
466
467         * Expression ::= Expression RestrOp Expression
468
469         * RestrOp ::= |
470
471         * RestrOp ::= ||
472
473         * RestrOp ::= |||
474
475       The interpretation in some detail for the three operators:
476
477         |:
478           The subset of calls from any of the vertices.
479
480         ||:
481           The subset of calls to any of the vertices.
482
483         |||:
484           The  subset  of calls to and from any of the vertices. For all sets
485           of calls CS and all sets of vertices VS, CS ||| VS   is  equivalent
486           to CS | VS * CS || VS.
487
488       Two  functions  (modules,  applications,  releases)  belong to the same
489       strongly connected component if they call each other (in)directly.  The
490       interpretation  of  the components operator is the set of strongly con‐
491       nected components of a set of calls. The condensation of a set of calls
492       is  a  new  set of calls between the strongly connected components such
493       that there is an edge between two components if there is some  constant
494       of  the  first  component that calls some constant of the second compo‐
495       nent.
496
497       The interpretation of the of operator is a chain of calls of the second
498       operand  (a  set of calls) that passes throw all of the vertices of the
499       first operand (a tuple of constants), in the given  order.  The  second
500       operand  is  converted  to the type of the first operand. For instance,
501       the of operator can be used for finding out whether  a  function  calls
502       another  function  indirectly, and the chain of calls demonstrates how.
503       The syntax of the graph analyzing operators:
504
505         * Expression ::= Expression BinaryGraphOp Expression
506
507         * Expression ::= UnaryGraphOp Expression
508
509         * UnaryGraphOp ::= components | condensation
510
511         * BinaryGraphOp ::= of
512
513       As was mentioned before, the graph analyses operate on the digraph rep‐
514       resentation  of  graphs. By default, the digraph representation is cre‐
515       ated when needed (and deleted when no longer used), but it can also  be
516       created explicitly by use of the closure operator:
517
518         * Expression ::= ClosureOp Expression
519
520         * ClosureOp ::= closure
521
522       The interpretation of the closure operator is the transitive closure of
523       the operand.
524
525       The restriction operators are defined for closures as well; closure E |
526       xref : Mod is interpreted as the direct or indirect function calls from
527       the xref module, while the interpretation of E | xref : Mod is the  set
528       of direct calls from xref. If some graph is to be used in several graph
529       analyses, it saves time to assign the  digraph  representation  of  the
530       graph  to a user variable, and then make sure that every graph analysis
531       operates on that variable instead of the  list  representation  of  the
532       graph.
533
534       The  lines where functions are defined (more precisely: where the first
535       clause begins) and the lines where functions are used are available  in
536       functions mode. The line numbers refer to the files where the functions
537       are defined. This holds also for files included with the  -include  and
538       -include_lib  directives,  which may result in functions defined appar‐
539       ently in the same line. The line operators are used for assigning  line
540       numbers to functions and for assigning sets of line numbers to function
541       calls. The syntax is similar to the one of the cast operator:
542
543         * Expression ::= ( LineOp) Expression
544
545         * Expression ::= ( XLineOp) Expression
546
547         * LineOp ::= Lin | ELin | LLin | XLin
548
549         * XLineOp ::= XXL
550
551       The interpretation of the Lin operator applied to a  set  of  functions
552       assigns to each function the line number where the function is defined.
553       Unknown functions and functions of library  modules  are  assigned  the
554       number 0.
555
556       The interpretation of some LineOp operator applied to a set of function
557       calls assigns to each call the set of  line  numbers  where  the  first
558       function  calls  the  second  function. Not all calls are assigned line
559       numbers by all operators:
560
561         * the Lin operator is defined for Call Graph Edges;
562
563         * the LLin operator is defined for Local Calls.
564
565         * the XLin operator is defined for External Calls.
566
567         * the ELin operator is defined for Inter Call Graph Edges.
568
569       The Lin (LLin, XLin) operator assigns  the  lines  where  calls  (local
570       calls, external calls) are made. The ELin operator assigns to each call
571       (From, To), for which it is defined, every line L such that there is  a
572       chain of calls from From to To beginning with a call on line L.
573
574       The XXL operator is defined for the interpretation of any of the LineOp
575       operators applied to a set of function calls. The result is that of re‐
576       placing  the function call with a line numbered function call, that is,
577       each of the two functions of the call is replaced  by  a  pair  of  the
578       function  and the line where the function is defined. The effect of the
579       XXL operator can be undone by the LineOp operators. For instance, (Lin)
580       (XXL) (Lin) E is equivalent to (Lin) E.
581
582       The  +,  -,  * and # operators are defined for line number expressions,
583       provided the operands are compatible. The LineOp operators are also de‐
584       fined  for  modules, applications, and releases; the operand is implic‐
585       itly converted to functions. Similarly, the cast  operator  is  defined
586       for the interpretation of the LineOp operators.
587
588       The  interpretation  of the counting operator is the number of elements
589       of a set. The operator is undefined for closures. The +, - and * opera‐
590       tors are interpreted as the obvious arithmetical operators when applied
591       to numbers. The syntax of the counting operator:
592
593         * Expression ::= CountOp Expression
594
595         * CountOp ::= #
596
597       All binary operators are left associative; for instance, A | B || C  is
598       equivalent  to  (A | B) || C. The following is a list of all operators,
599       in increasing order of precedence:
600
601         * +, -
602
603         * *
604
605         * #
606
607         * |, ||, |||
608
609         * of
610
611         * (Type)
612
613         * closure, components, condensation, domain, range, strict
614
615       Parentheses are used for grouping, either to make  an  expression  more
616       readable or to override the default precedence of operators:
617
618         * Expression ::= ( Expression )
619
620       A query is a non-empty sequence of statements. A statement is either an
621       assignment of a user variable or an expression. The value of an assign‐
622       ment  is the value of the right hand side expression. It makes no sense
623       to put a plain expression anywhere else but last in queries. The syntax
624       of queries is summarized by these productions:
625
626         * Query ::= Statement, ...
627
628         * Statement ::= Assignment | Expression
629
630         * Assignment ::= Variable := Expression | Variable = Expression
631
632       A  variable  cannot be assigned a new value unless first removed. Vari‐
633       ables assigned to by the = operator are  removed  at  the  end  of  the
634       query,  while  variables assigned to by the := operator can only be re‐
635       moved by calls to forget. There are no user variables when module  data
636       need to be set up again; if any of the functions that make it necessary
637       to set up module data again is called, all user variables  are  forgot‐
638       ten.
639

DATA TYPES

641       application() = atom()
642
643       call() = {atom(), atom()} | funcall()
644
645       constant() = xmfa() | module() | application() | release()
646
647       directory() = atom() | file:filename()
648
649       file() = file:filename()
650
651       file_error() = atom()
652
653       funcall() = {xmfa(), xmfa()}
654
655       function_name() = atom()
656
657       library() = atom()
658
659       library_path() = path() | code_path
660
661       mode() = functions | modules
662
663       path() = [file()]
664
665       release() = atom()
666
667       string_position() = integer() >= 1
668
669       variable() = atom()
670
671       xarity() = arity() | -1
672
673       xmfa() = {module(), function_name(), xarity()}
674
675       xref() = atom() | pid()
676

EXPORTS

678       add_application(XrefServer, Directory) ->
679                          {ok, application()} | {error, module(), Reason}
680
681       add_application(XrefServer, Directory, Options) ->
682                          {ok, application()} | {error, module(), Reason}
683
684              Types:
685
686                 XrefServer = xref()
687                 Directory = directory()
688                 Options = Option | [Option]
689                 Option =
690                     {builtins, boolean()} |
691                     {name, application()} |
692                     {verbose, boolean()} |
693                     {warnings, boolean()} |
694                     builtins | verbose | warnings
695                 Reason =
696                     {application_clash,  {application(),  directory(), direc‐
697                 tory()}} |
698                     add_dir_rsn()
699                 add_dir_rsn() =
700                     {file_error, file(), file_error()} |
701                     {invalid_filename, term()} |
702                     {invalid_options, term()} |
703                     {unrecognized_file, file()} |
704                     beam_lib:chnk_rsn()
705
706              Adds an application, the modules of the application  and  module
707              data  of the modules to an Xref server. The modules will be mem‐
708              bers of the application. The default is to use the base name  of
709              the  directory with the version removed as application name, but
710              this can be overridden by the name option. Returns the  name  of
711              the application.
712
713              If  the  given  directory has a subdirectory named ebin, modules
714              (BEAM files) are searched for in that directory, otherwise  mod‐
715              ules are searched for in the given directory.
716
717              If  the  mode  of  the Xref server is functions, BEAM files that
718              contain no debug information are ignored.
719
720       add_directory(XrefServer, Directory) ->
721                        {ok, Modules} | {error, module(), Reason}
722
723       add_directory(XrefServer, Directory, Options) ->
724                        {ok, Modules} | {error, module(), Reason}
725
726              Types:
727
728                 XrefServer = xref()
729                 Directory = directory()
730                 Options = Option | [Option]
731                 Option =
732                     {builtins, boolean()} |
733                     {recurse, boolean()} |
734                     {verbose, boolean()} |
735                     {warnings, boolean()} |
736                     builtins | recurse | verbose | warnings
737                 Modules = [module()]
738                 Reason = add_dir_rsn()
739                 add_dir_rsn() =
740                     {file_error, file(), file_error()} |
741                     {invalid_filename, term()} |
742                     {invalid_options, term()} |
743                     {unrecognized_file, file()} |
744                     beam_lib:chnk_rsn()
745
746              Adds the modules found in the given directory and  the  modules'
747              data  to an Xref server. The default is not to examine subdirec‐
748              tories, but if the option recurse has the  value  true,  modules
749              are  searched  for in subdirectories on all levels as well as in
750              the given directory. Returns a sorted list of the names  of  the
751              added modules.
752
753              The modules added will not be members of any applications.
754
755              If  the  mode  of  the Xref server is functions, BEAM files that
756              contain no debug information are ignored.
757
758       add_module(XrefServer, File) ->
759                     {ok, module()} | {error, module(), Reason}
760
761       add_module(XrefServer, File, Options) ->
762                     {ok, module()} | {error, module(), Reason}
763
764              Types:
765
766                 XrefServer = xref()
767                 File = file:filename()
768                 Options = Option | [Option]
769                 Option =
770                     {builtins, boolean()} |
771                     {verbose, boolean()} |
772                     {warnings, boolean()} |
773                     builtins | verbose | warnings
774                 Reason = add_mod_rsn()
775                 add_mod_rsn() =
776                     {file_error, file(), file_error()} |
777                     {invalid_filename, term()} |
778                     {invalid_options, term()} |
779                     {module_clash, {module(), file(), file()}} |
780                     {no_debug_info, file()} |
781                     beam_lib:chnk_rsn()
782
783              Adds a module and its module data to an Xref server. The  module
784              will  not  be member of any application. Returns the name of the
785              module.
786
787              If the mode of the Xref server is functions, and the  BEAM  file
788              contains  no  debug information, the error message no_debug_info
789              is returned.
790
791       add_release(XrefServer, Directory) ->
792                      {ok, release()} | {error, module(), Reason}
793
794       add_release(XrefServer, Directory, Options) ->
795                      {ok, release()} | {error, module(), Reason}
796
797              Types:
798
799                 XrefServer = xref()
800                 Directory = directory()
801                 Options = Option | [Option]
802                 Option =
803                     {builtins, boolean()} |
804                     {name, release()} |
805                     {verbose, boolean()} |
806                     {warnings, boolean()} |
807                     builtins | verbose | warnings
808                 Reason =
809                     {application_clash, {application(),  directory(),  direc‐
810                 tory()}} |
811                     {release_clash, {release(), directory(), directory()}} |
812                     add_dir_rsn()
813                 add_dir_rsn() =
814                     {file_error, file(), file_error()} |
815                     {invalid_filename, term()} |
816                     {invalid_options, term()} |
817                     {unrecognized_file, file()} |
818                     beam_lib:chnk_rsn()
819
820              Adds  a release, the applications of the release, the modules of
821              the applications, and module data of  the  modules  to  an  Xref
822              server. The applications will be members of the release, and the
823              modules will be members of the applications. The default  is  to
824              use the base name of the directory as release name, but this can
825              be overridden by the name option. Returns the name  of  the  re‐
826              lease.
827
828              If  the given directory has a subdirectory named lib, the direc‐
829              tories in that directory are assumed to be application  directo‐
830              ries,  otherwise  all  subdirectories of the given directory are
831              assumed to be application directories. If there are several ver‐
832              sions  of  some application, the one with the highest version is
833              chosen.
834
835              If the mode of the Xref server is  functions,  BEAM  files  that
836              contain no debug information are ignored.
837
838       analyze(XrefServer, Analysis) ->
839                  {ok, Answer} | {error, module(), Reason}
840
841       analyze(XrefServer, Analysis, Options) ->
842                  {ok, Answer} | {error, module(), Reason}
843
844              Types:
845
846                 XrefServer = xref()
847                 Analysis = analysis()
848                 Options = Option | [Option]
849                 Option = {verbose, boolean()} | verbose
850                 Answer = [term()]
851                 Reason = analyze_rsn()
852                 analysis() =
853                     undefined_function_calls | undefined_functions |
854                     locals_not_used | exports_not_used |
855                     deprecated_function_calls |
856                     {deprecated_function_calls, DeprFlag :: depr_flag()} |
857                     deprecated_functions |
858                     {deprecated_functions, DeprFlag :: depr_flag()} |
859                     {call, FuncSpec :: func_spec()} |
860                     {use, FuncSpec :: func_spec()} |
861                     {module_call, ModSpec :: mod_spec()} |
862                     {module_use, ModSpec :: mod_spec()} |
863                     {application_call, AppSpec :: app_spec()} |
864                     {application_use, AppSpec :: app_spec()} |
865                     {release_call, RelSpec :: rel_spec()} |
866                     {release_use, RelSpec :: rel_spec()}
867                 app_spec() = application() | [application()]
868                 depr_flag() = next_version | next_major_release | eventually
869                 func_spec() = xmfa() | [xmfa()]
870                 mod_spec() = module() | [module()]
871                 rel_spec() = release() | [release()]
872                 analyze_rsn() =
873                     {invalid_options, term()} |
874                     {parse_error, string_position(), term()} |
875                     {unavailable_analysis, term()} |
876                     {unknown_analysis, term()} |
877                     {unknown_constant, string()} |
878                     {unknown_variable, variable()}
879
880              Evaluates  a  predefined analysis. Returns a sorted list without
881              duplicates of call() or  constant(),  depending  on  the  chosen
882              analysis. The predefined analyses, which operate on all analyzed
883              modules, are (analyses marked with (*) are  available  in  func‐
884              tionsmode only):
885
886                undefined_function_calls(*):
887                  Returns a list of calls to undefined functions.
888
889                undefined_functions:
890                  Returns a list of undefined functions.
891
892                locals_not_used(*):
893                  Returns a list of local functions that have not been locally
894                  used.
895
896                exports_not_used:
897                  Returns a list of exported functions that have not been  ex‐
898                  ternally used. Note that in modules mode, M:behaviour_info/1
899                  is never reported as unused.
900
901                deprecated_function_calls(*):
902                  Returns a list of external calls to deprecated functions.
903
904                {deprecated_function_calls, DeprFlag}(*):
905                  Returns a list of external calls to deprecated functions. If
906                  DeprFlag  is equal to next_version, calls to functions to be
907                  removed in next version are returned. If DeprFlag  is  equal
908                  to  next_major_release,  calls to functions to be removed in
909                  next major release are returned as well as  calls  to  func‐
910                  tions to be removed in next version. Finally, if DeprFlag is
911                  equal to eventually, all calls to functions  to  be  removed
912                  are  returned, including calls to functions to be removed in
913                  next version or next major release.
914
915                deprecated_functions:
916                  Returns a list of externally used deprecated functions.
917
918                {deprecated_functions, DeprFlag}:
919                  Returns a list of externally used deprecated  functions.  If
920                  DeprFlag  is  equal to next_version, functions to be removed
921                  in next version  are  returned.  If  DeprFlag  is  equal  to
922                  next_major_release,  functions  to  be removed in next major
923                  release are returned as well as functions to be  removed  in
924                  next  version.  Finally, if DeprFlag is equal to eventually,
925                  all functions to be removed are  returned,  including  func‐
926                  tions to be removed in next version or next major release.
927
928                {call, FuncSpec}(*):
929                  Returns  a  list  of  functions  called by some of the given
930                  functions.
931
932                {use, FuncSpec}(*):
933                  Returns a list of functions that use some of the given func‐
934                  tions.
935
936                {module_call, ModSpec}:
937                  Returns  a  list of modules called by some of the given mod‐
938                  ules.
939
940                {module_use, ModSpec}:
941                  Returns a list of modules that use some of  the  given  mod‐
942                  ules.
943
944                {application_call, AppSpec}:
945                  Returns  a  list of applications called by some of the given
946                  applications.
947
948                {application_use, AppSpec}:
949                  Returns a list of applications that use some  of  the  given
950                  applications.
951
952                {release_call, RelSpec}:
953                  Returns  a  list of releases called by some of the given re‐
954                  leases.
955
956                {release_use, RelSpec}:
957                  Returns a list of releases that use some of  the  given  re‐
958                  leases.
959
960       d(Directory) ->
961            [DebugInfoResult] |
962            [NoDebugInfoResult] |
963            {error, module(), Reason}
964
965              Types:
966
967                 Directory = directory()
968                 DebugInfoResult =
969                     {deprecated, [funcall()]} |
970                     {undefined, [funcall()]} |
971                     {unused, [mfa()]}
972                 NoDebugInfoResult =
973                     {deprecated, [xmfa()]} | {undefined, [xmfa()]}
974                 Reason =
975                     {file_error, file(), file_error()} |
976                     {invalid_filename, term()} |
977                     {unrecognized_file, file()} |
978                     beam_lib:chnk_rsn()
979
980              The  modules  found in the given directory are checked for calls
981              to deprecated functions, calls to undefined functions,  and  for
982              unused local functions. The code path is used as library path.
983
984              If  some of the found BEAM files contain debug information, then
985              those modules are checked and a list of tuples is returned.  The
986              first element of each tuple is one of:
987
988                * deprecated,  the second element is a sorted list of calls to
989                  deprecated functions;
990
991                * undefined, the second element is a sorted list of  calls  to
992                  undefined functions;
993
994                * unused,  the second element is a sorted list of unused local
995                  functions.
996
997              If no BEAM file contains debug information, then a list  of  tu‐
998              ples is returned. The first element of each tuple is one of:
999
1000                * deprecated,  the  second  element is a sorted list of exter‐
1001                  nally used deprecated functions;
1002
1003                * undefined, the second element is a sorted list of  undefined
1004                  functions.
1005
1006       forget(XrefServer) -> ok
1007
1008       forget(XrefServer, Variables) -> ok | {error, module(), Reason}
1009
1010              Types:
1011
1012                 XrefServer = xref()
1013                 Variables = variable() | [variable()]
1014                 Reason = {not_user_variable, term()}
1015
1016              forget/1  and  forget/2 remove all or some of the user variables
1017              of an Xref server.
1018
1019       format_error(Error) -> io_lib:chars()
1020
1021              Types:
1022
1023                 Error = {error, module(), Reason :: term()}
1024
1025              Given the error returned by any function  of  this  module,  the
1026              function  format_error returns a descriptive string of the error
1027              in English. For file errors, the function file:format_error/1 is
1028              called.
1029
1030       get_default(XrefServer) -> [{Option, Value}]
1031
1032       get_default(XrefServer, Option) ->
1033                      {ok, Value} | {error, module(), Reason}
1034
1035              Types:
1036
1037                 XrefServer = xref()
1038                 Option = builtins | recurse | verbose | warnings
1039                 Value = boolean()
1040                 Reason = {invalid_options, term()}
1041
1042              Returns the default values of one or more options.
1043
1044       get_library_path(XrefServer) -> {ok, LibraryPath}
1045
1046              Types:
1047
1048                 XrefServer = xref()
1049                 LibraryPath = library_path()
1050
1051              Returns the library path.
1052
1053       info(XrefServer) -> [Info]
1054
1055       info(XrefServer, Category) ->
1056               [{Item, [Info]}] |
1057               {error, module(), {no_such_info, Category}}
1058
1059       info(XrefServer, Category, Items) ->
1060               [{Item, [Info]}] | {error, module(), Reason}
1061
1062              Types:
1063
1064                 XrefServer = xref()
1065                 Category = modules | applications | releases | libraries
1066                 Items = Item | [Item]
1067                 Item = module() | application() | release() | library()
1068                 Info = info()
1069                 Reason =
1070                     {no_such_application, Item} |
1071                     {no_such_info, Category} |
1072                     {no_such_library, Item} |
1073                     {no_such_module, Item} |
1074                     {no_such_release, Item}
1075                 info() =
1076                     {application, Application :: [application()]} |
1077                     {builtins, boolean()} |
1078                     {directory, directory()} |
1079                     {library_path, library_path()} |
1080                     {mode, mode()} |
1081                     {no_analyzed_modules, integer() >= 0} |
1082                     {no_applications, integer() >= 0} |
1083                     {no_calls,
1084                      {NoResolved :: integer() >= 0,
1085                       NoUnresolved :: integer() >= 0}} |
1086                     {no_function_calls,
1087                      {NoLocal :: integer() >= 0,
1088                       NoResolvedExternal :: integer() >= 0,
1089                       NoUnresolved :: integer() >= 0}} |
1090                     {no_functions,
1091                      {NoLocal :: integer() >= 0,
1092                       NoExternal :: integer() >= 0}} |
1093                     {no_inter_function_calls, integer() >= 0} |
1094                     {no_releases, integer() >= 0} |
1095                     {release, Release :: [release()]} |
1096                     {version, Version :: [integer() >= 0]}
1097
1098              The  info  functions return information as a list of pairs {Tag,
1099              term()} in some order about the state and the module data of  an
1100              Xref server.
1101
1102              info/1  returns information with the following tags (tags marked
1103              with (*) are available in functions mode only):
1104
1105                * library_path, the library path;
1106
1107                * mode, the mode;
1108
1109                * no_releases, number of releases;
1110
1111                * no_applications, total number of applications  (of  all  re‐
1112                  leases);
1113
1114                * no_analyzed_modules, total number of analyzed modules;
1115
1116                * no_calls  (*),  total  number of calls (in all modules), re‐
1117                  garding instances of one function call in different lines as
1118                  separate calls;
1119
1120                * no_function_calls (*), total number of local calls, resolved
1121                  external calls and unresolved calls;
1122
1123                * no_functions (*), total number of local and  exported  func‐
1124                  tions;
1125
1126                * no_inter_function_calls  (*),  total  number of calls of the
1127                  Inter Call Graph.
1128
1129              info/2 and info/3 return information about all or  some  of  the
1130              analyzed  modules,  applications, releases or library modules of
1131              an Xref server. The following information is returned for  every
1132              analyzed module:
1133
1134                * application,  an empty list if the module does not belong to
1135                  any application, otherwise a list of the application name;
1136
1137                * builtins, whether calls to BIFs are included in the module's
1138                  data;
1139
1140                * directory, the directory where the module's BEAM file is lo‐
1141                  cated;
1142
1143                * no_calls (*), number of calls, regarding  instances  of  one
1144                  function call in different lines as separate calls;
1145
1146                * no_function_calls  (*),  number of local calls, resolved ex‐
1147                  ternal calls and unresolved calls;
1148
1149                * no_functions (*), number of local and exported functions;
1150
1151                * no_inter_function_calls (*), number of calls  of  the  Inter
1152                  Call Graph;
1153
1154              The following information is returned for every application:
1155
1156                * directory,  the  directory where the modules' BEAM files are
1157                  located;
1158
1159                * no_analyzed_modules, number of analyzed modules;
1160
1161                * no_calls (*), number of calls of the application's  modules,
1162                  regarding  instances of one function call in different lines
1163                  as separate calls;
1164
1165                * no_function_calls (*), number of local calls,  resolved  ex‐
1166                  ternal  calls and unresolved calls of the application's mod‐
1167                  ules;
1168
1169                * no_functions (*), number of local and exported functions  of
1170                  the application's modules;
1171
1172                * no_inter_function_calls  (*),  number  of calls of the Inter
1173                  Call Graph of the application's modules;
1174
1175                * release, an empty list if the application does not belong to
1176                  any release, otherwise a list of the release name;
1177
1178                * version, the application's version as a list of numbers. For
1179                  instance, the directory "kernel-2.6" results in the applica‐
1180                  tion name kernel and the application version [2,6]; "kernel"
1181                  yields the name kernel and the version [].
1182
1183              The following information is returned for every release:
1184
1185                * directory, the release directory;
1186
1187                * no_analyzed_modules, number of analyzed modules;
1188
1189                * no_applications, number of applications;
1190
1191                * no_calls (*), number of calls of the release's modules,  re‐
1192                  garding instances of one function call in different lines as
1193                  separate calls;
1194
1195                * no_function_calls (*), number of local calls,  resolved  ex‐
1196                  ternal calls and unresolved calls of the release's modules;
1197
1198                * no_functions  (*), number of local and exported functions of
1199                  the release's modules;
1200
1201                * no_inter_function_calls (*), number of calls  of  the  Inter
1202                  Call Graph of the release's modules.
1203
1204              The following information is returned for every library module:
1205
1206                * directory,  the  directory  where  the library module's BEAM
1207                  file is located.
1208
1209              For every number of calls, functions etc. returned  by  the  no_
1210              tags,  there  is a query returning the same number. Listed below
1211              are examples of such queries. Some of the queries return the sum
1212              of  a two or more of the no_ tags numbers. mod (app, rel) refers
1213              to any module (application, release).
1214
1215                * no_analyzed_modules
1216
1217                  * "# AM" (info/1)
1218
1219                  * "# (Mod) app:App" (application)
1220
1221                  * "# (Mod) rel:Rel" (release)
1222
1223                * no_applications
1224
1225                  * "# A" (info/1)
1226
1227                * no_calls. The sum of the number of resolved  and  unresolved
1228                  calls:
1229
1230                  * "# (XLin) E + # (LLin) E" (info/1)
1231
1232                  * "T = E | mod:Mod, # (LLin) T + # (XLin) T" (module)
1233
1234                  * "T = E | app:App, # (LLin) T + # (XLin) T" (application)
1235
1236                  * "T = E | rel:Rel, # (LLin) T + # (XLin) T" (release)
1237
1238                * no_functions. Functions in library modules and the functions
1239                  module_info/0,1 are not counted by info. Assuming that  "Ex‐
1240                  tra := _:module_info/\"(0|1)\" + LM" has been evaluated, the
1241                  sum of the number of local and exported functions are:
1242
1243                  * "# (F - Extra)" (info/1)
1244
1245                  * "# (F * mod:Mod - Extra)" (module)
1246
1247                  * "# (F * app:App - Extra)" (application)
1248
1249                  * "# (F * rel:Rel - Extra)" (release)
1250
1251                * no_function_calls. The sum of the number of local calls, re‐
1252                  solved external calls and unresolved calls:
1253
1254                  * "# LC + # XC" (info/1)
1255
1256                  * "# LC | mod:Mod + # XC | mod:Mod" (module)
1257
1258                  * "# LC | app:App + # XC | app:App" (application)
1259
1260                  * "# LC | rel:Rel + # XC | mod:Rel" (release)
1261
1262                * no_inter_function_calls
1263
1264                  * "# EE" (info/1)
1265
1266                  * "# EE | mod:Mod" (module)
1267
1268                  * "# EE | app:App" (application)
1269
1270                  * "# EE | rel:Rel" (release)
1271
1272                * no_releases
1273
1274                  * "# R" (info/1)
1275
1276       m(FileOrModule) ->
1277            [DebugInfoResult] |
1278            [NoDebugInfoResult] |
1279            {error, module(), Reason}
1280
1281              Types:
1282
1283                 FileOrModule = file:filename() | module()
1284                 DebugInfoResult =
1285                     {deprecated, [funcall()]} |
1286                     {undefined, [funcall()]} |
1287                     {unused, [mfa()]}
1288                 NoDebugInfoResult =
1289                     {deprecated, [xmfa()]} | {undefined, [xmfa()]}
1290                 Reason =
1291                     {cover_compiled, Module} |
1292                     {file_error, file(), file_error()} |
1293                     {interpreted, Module} |
1294                     {invalid_filename, term()} |
1295                     {no_such_module, Module} |
1296                     beam_lib:chnk_rsn()
1297
1298              The given BEAM file (with or without the .beam extension) or the
1299              file found by calling code:which(Module) is checked for calls to
1300              deprecated  functions, calls to undefined functions, and for un‐
1301              used local functions. The code path is used as library path.
1302
1303              If the BEAM file contains debug information, then a list of  tu‐
1304              ples is returned. The first element of each tuple is one of:
1305
1306                * deprecated,  the second element is a sorted list of calls to
1307                  deprecated functions;
1308
1309                * undefined, the second element is a sorted list of  calls  to
1310                  undefined functions;
1311
1312                * unused,  the second element is a sorted list of unused local
1313                  functions.
1314
1315              If the BEAM file does not contain debug information, then a list
1316              of  tuples  is  returned. The first element of each tuple is one
1317              of:
1318
1319                * deprecated, the second element is a sorted  list  of  exter‐
1320                  nally used deprecated functions;
1321
1322                * undefined,  the second element is a sorted list of undefined
1323                  functions.
1324
1325       q(XrefServer, Query) -> {ok, Answer} | {error, module(), Reason}
1326
1327       q(XrefServer, Query, Options) ->
1328            {ok, Answer} | {error, module(), Reason}
1329
1330              Types:
1331
1332                 XrefServer = xref()
1333                 Query = string() | atom()
1334                 Options = Option | [Option]
1335                 Option = {verbose, boolean()} | verbose
1336                 Answer = answer()
1337                 Reason = q_rsn()
1338                 answer() =
1339                     false |
1340                     [constant()] |
1341                     [(Call :: call()) |
1342                      (ComponentCall :: {component(), component()})] |
1343                     [Component :: component()] |
1344                     integer() >= 0 |
1345                     [DefineAt :: define_at()] |
1346                     [CallAt :: {funcall(), LineNumbers :: [integer() >= 0]}] |
1347                     [AllLines ::
1348                          {{define_at(), define_at()},
1349                           LineNumbers :: [integer() >= 0]}]
1350                 define_at() = {xmfa(), LineNumber :: integer() >= 0}
1351                 component() = [constant()]
1352                 q_rsn() =
1353                     {invalid_options, term()} |
1354                     {parse_error, string_position(), term()} |
1355                     {type_error, string()} |
1356                     {type_mismatch, string(), string()} |
1357                     {unknown_analysis, term()} |
1358                     {unknown_constant, string()} |
1359                     {unknown_variable, variable()} |
1360                     {variable_reassigned, string()}
1361
1362              Evaluates a query in the context of an Xref server, and  returns
1363              the value of the last statement. The syntax of the value depends
1364              on the expression:
1365
1366                * A set of calls is represented by a sorted list  without  du‐
1367                  plicates of call().
1368
1369                * A  set  of constants is represented by a sorted list without
1370                  duplicates of constant().
1371
1372                * A set of strongly connected  components  is  a  sorted  list
1373                  without duplicates of Component.
1374
1375                * A  set  of  calls between strongly connected components is a
1376                  sorted list without duplicates of ComponentCall.
1377
1378                * A chain of calls is represented by a list of constant(). The
1379                  list  contains the From vertex of every call and the To ver‐
1380                  tex of the last call.
1381
1382                * The of operator returns false if no chain of  calls  between
1383                  the given constants can be found.
1384
1385                * The  value  of the closure operator (the digraph representa‐
1386                  tion) is represented by the atom 'closure()'.
1387
1388                * A set of line numbered functions is represented by a  sorted
1389                  list without duplicates of DefineAt.
1390
1391                * A  set  of  line numbered function calls is represented by a
1392                  sorted list without duplicates of CallAt.
1393
1394                * A set of line numbered functions and function calls is  rep‐
1395                  resented by a sorted list without duplicates of AllLines.
1396
1397              For  both  CallAt and AllLines it holds that for no list element
1398              is LineNumbers an empty list; such elements have  been  removed.
1399              The  constants  of component and the integers of LineNumbers are
1400              sorted and without duplicates.
1401
1402       remove_application(XrefServer, Applications) ->
1403                             ok | {error, module(), Reason}
1404
1405              Types:
1406
1407                 XrefServer = xref()
1408                 Applications = application() | [application()]
1409                 Reason = {no_such_application, application()}
1410
1411              Removes applications and their modules and module data  from  an
1412              Xref server.
1413
1414       remove_module(XrefServer, Modules) ->
1415                        ok | {error, module(), Reason}
1416
1417              Types:
1418
1419                 XrefServer = xref()
1420                 Modules = module() | [module()]
1421                 Reason = {no_such_module, module()}
1422
1423              Removes analyzed modules and module data from an Xref server.
1424
1425       remove_release(XrefServer, Releases) ->
1426                         ok | {error, module(), Reason}
1427
1428              Types:
1429
1430                 XrefServer = xref()
1431                 Releases = release() | [release()]
1432                 Reason = {no_such_release, release()}
1433
1434              Removes releases and their applications, modules and module data
1435              from an Xref server.
1436
1437       replace_application(XrefServer, Application, Directory) ->
1438                              {ok, Application} |
1439                              {error, module(), Reason}
1440
1441       replace_application(XrefServer, Application, Directory, Options) ->
1442                              {ok, Application} |
1443                              {error, module(), Reason}
1444
1445              Types:
1446
1447                 XrefServer = xref()
1448                 Application = application()
1449                 Directory = directory()
1450                 Options = Option | [Option]
1451                 Option =
1452                     {builtins, boolean()} |
1453                     {verbose, boolean()} |
1454                     {warnings, boolean()} |
1455                     builtins | verbose | warnings
1456                 Reason =
1457                     {application_clash, {application(),  directory(),  direc‐
1458                 tory()}} |
1459                     {no_such_application, Application} |
1460                     add_dir_rsn()
1461                 add_dir_rsn() =
1462                     {file_error, file(), file_error()} |
1463                     {invalid_filename, term()} |
1464                     {invalid_options, term()} |
1465                     {unrecognized_file, file()} |
1466                     beam_lib:chnk_rsn()
1467
1468              Replaces  the  modules of an application with other modules read
1469              from an application directory. Release membership of the  appli‐
1470              cation  is  retained.  Note  that the name of the application is
1471              kept; the name of the given directory is not used.
1472
1473       replace_module(XrefServer, Module, File) ->
1474                         {ok, Module} | {error, module(), Reason}
1475
1476       replace_module(XrefServer, Module, File, Options) ->
1477                         {ok, Module} | {error, module(), Reason}
1478
1479              Types:
1480
1481                 XrefServer = xref()
1482                 Module = module()
1483                 File = file()
1484                 Options = Option | [Option]
1485                 Option =
1486                     {verbose, boolean()} |
1487                     {warnings, boolean()} |
1488                     verbose | warnings
1489                 Reason =
1490                     {module_mismatch, Module, ReadModule :: module()} |
1491                     {no_such_module, Module} |
1492                     add_mod_rsn()
1493                 add_mod_rsn() =
1494                     {file_error, file(), file_error()} |
1495                     {invalid_filename, term()} |
1496                     {invalid_options, term()} |
1497                     {module_clash, {module(), file(), file()}} |
1498                     {no_debug_info, file()} |
1499                     beam_lib:chnk_rsn()
1500
1501              Replaces module data of an analyzed module with data read from a
1502              BEAM file. Application membership of the module is retained, and
1503              so is the value of the builtins option of the module.  An  error
1504              is  returned  if  the  name  of the read module differs from the
1505              given module.
1506
1507              The update function is an alternative for updating  module  data
1508              of recompiled modules.
1509
1510       set_default(XrefServer, Option, Value) ->
1511                      {ok, OldValue} | {error, module(), Reason}
1512
1513       set_default(XrefServer, OptionValues) ->
1514                      ok | {error, module(), Reason}
1515
1516              Types:
1517
1518                 XrefServer = xref()
1519                 OptionValues = OptionValue | [OptionValue]
1520                 OptionValue = {Option, Value}
1521                 Option = builtins | recurse | verbose | warnings
1522                 Value = boolean()
1523                 Reason = {invalid_options, term()}
1524
1525              Sets  the default value of one or more options. The options that
1526              can be set this way are:
1527
1528                * builtins, with initial default value false;
1529
1530                * recurse, with initial default value false;
1531
1532                * verbose, with initial default value false;
1533
1534                * warnings, with initial default value true.
1535
1536              The initial default values are set when creating an Xref server.
1537
1538       set_library_path(XrefServer, LibraryPath) ->
1539                           ok | {error, module(), Reason}
1540
1541       set_library_path(XrefServer, LibraryPath, Options) ->
1542                           ok | {error, module(), Reason}
1543
1544              Types:
1545
1546                 XrefServer = xref()
1547                 LibraryPath = library_path()
1548                 Options = Option | [Option]
1549                 Option = {verbose, boolean()} | verbose
1550                 Reason = {invalid_options, term()} | {invalid_path, term()}
1551
1552              Sets the library path. If the given path is a list  of  directo‐
1553              ries,  the  set of library modules is determined by choosing the
1554              first module encountered while traversing the directories in the
1555              given  order,  for those modules that occur in more than one di‐
1556              rectory. By default, the library path is an empty list.
1557
1558              The library path code_path is used by the functions m/1 and d/1,
1559              but  can also be set explicitly. Note however that the code path
1560              will be traversed once for each used library module  while  set‐
1561              ting  up module data. On the other hand, if there are only a few
1562              modules that are used but not analyzed, using code_path  may  be
1563              faster than setting the library path to code:get_path().
1564
1565              If the library path is set to code_path, the set of library mod‐
1566              ules is not determined, and the info functions will return empty
1567              lists of library modules.
1568
1569       start(NameOrOptions) ->
1570                {ok, pid()} | {error, {already_started, pid()}}
1571
1572              Types:
1573
1574                 NameOrOptions = Name | Options
1575                 Name = atom()
1576                 Options = Option | [Option]
1577                 Option = {xref_mode, mode()} | term()
1578
1579              Creates  an  Xref  server. The process may optionally be given a
1580              name. The default mode is functions. Options that are not recog‐
1581              nized by Xref are passed on to gen_server:start/4.
1582
1583       start(Name, Options) ->
1584                {ok, pid()} | {error, {already_started, pid()}}
1585
1586              Types:
1587
1588                 Name = atom()
1589                 Options = Option | [Option]
1590                 Option = {xref_mode, mode()} | term()
1591
1592              Creates  an  Xref  server with a given name. The default mode is
1593              functions. Options that are not recognized by Xref are passed on
1594              to gen_server:start/4.
1595
1596       stop(XrefServer) -> stopped
1597
1598              Types:
1599
1600                 XrefServer = xref()
1601
1602              Stops an Xref server.
1603
1604       update(XrefServer) -> {ok, Modules} | {error, module(), Reason}
1605
1606       update(XrefServer, Options) ->
1607                 {ok, Modules} | {error, module(), Reason}
1608
1609              Types:
1610
1611                 XrefServer = xref()
1612                 Options = Option | [Option]
1613                 Option =
1614                     {verbose, boolean()} |
1615                     {warnings, boolean()} |
1616                     verbose | warnings
1617                 Modules = [module()]
1618                 Reason =
1619                     {module_mismatch, module(), ReadModule :: module()} |
1620                     add_mod_rsn()
1621                 add_mod_rsn() =
1622                     {file_error, file(), file_error()} |
1623                     {invalid_filename, term()} |
1624                     {invalid_options, term()} |
1625                     {module_clash, {module(), file(), file()}} |
1626                     {no_debug_info, file()} |
1627                     beam_lib:chnk_rsn()
1628
1629              Replaces  the module data of all analyzed modules the BEAM files
1630              of which have been modified since last read by an  add  function
1631              or  update.  Application  membership of the modules is retained,
1632              and so is the value of the builtins  option.  Returns  a  sorted
1633              list of the names of the replaced modules.
1634
1635       variables(XrefServer) -> {ok, [VariableInfo]}
1636
1637       variables(XrefServer, Options) -> {ok, [VariableInfo]}
1638
1639              Types:
1640
1641                 XrefServer = xref()
1642                 Options = Option | [Option]
1643                 Option = predefined | user | {verbose, boolean()} | verbose
1644                 VariableInfo =
1645                     {predefined, [variable()]} | {user, [variable()]}
1646
1647              Returns  a sorted lists of the names of the variables of an Xref
1648              server. The default is to return the user variables only.
1649

SEE ALSO

1651       beam_lib(3), digraph(3), digraph_utils(3), re(3), TOOLS User's Guide
1652
1653
1654
1655Ericsson AB                       tools 3.5.1                          xref(3)
Impressum