/
macro.ex
2520 lines (1984 loc) · 75.8 KB
/
macro.ex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
import Kernel, except: [to_string: 1]
defmodule Macro do
@moduledoc ~S"""
Functions for manipulating AST and implementing macros.
Macros are compile-time constructs that receive Elixir's AST as input
and return Elixir's AST as output.
Many of the functions in this module exist precisely to work with Elixir
AST, to traverse, query, and transform it.
Let's see a simple example that shows the difference between functions
and macros:
defmodule Example do
defmacro macro_inspect(value) do
IO.inspect(value)
value
end
def fun_inspect(value) do
IO.inspect(value)
value
end
end
Now let's give it a try:
import Example
macro_inspect(1)
#=> 1
#=> 1
fun_inspect(1)
#=> 1
#=> 1
So far they behave the same, as we are passing an integer as argument.
But let's see what happens when we pass an expression:
macro_inspect(1 + 2)
#=> {:+, [line: 3], [1, 2]}
#=> 3
fun_inspect(1 + 2)
#=> 3
#=> 3
The macro receives the representation of the code given as argument,
while a function receives the result of the code given as argument.
A macro must return a superset of the code representation. See
`t:input/0` and `t:output/0` for more information.
To learn more about Elixir's AST and how to build them programmatically,
see `quote/2`.
> Note: the functions in this module do not evaluate code. In fact,
> evaluating code from macros is often an anti-pattern. For code
> evaluation, see the `Code` module.
## Custom Sigils
Macros are also commonly used to implement custom sigils. To create a custom
sigil, define a macro with the name `sigil_{identifier}` that takes two
arguments. The first argument will be the string, the second will be a charlist
containing any modifiers. If the sigil is lower case (such as `sigil_x`) then
the string argument will allow interpolation. If the sigil is upper case
(such as `sigil_X`) then the string will not be interpolated.
Valid modifiers include only lower and upper case letters. Other characters
will cause a syntax error.
The module containing the custom sigil must be imported before the sigil
syntax can be used.
### Examples
defmodule MySigils do
defmacro sigil_x(term, [?r]) do
quote do
unquote(term) |> String.reverse()
end
end
defmacro sigil_x(term, _modifiers) do
term
end
defmacro sigil_X(term, [?r]) do
quote do
unquote(term) |> String.reverse()
end
end
defmacro sigil_X(term, _modifiers) do
term
end
end
import MySigils
~x(with #{"inter" <> "polation"})
#=>"with interpolation"
~x(with #{"inter" <> "polation"})r
#=>"noitalopretni htiw"
~X(without #{"interpolation"})
#=>"without \#{"interpolation"}"
~X(without #{"interpolation"})r
#=>"}\"noitalopretni\"{# tuohtiw"
"""
alias Code.Identifier
@typedoc "Abstract Syntax Tree (AST)"
@type t :: input
@typedoc "The inputs of a macro"
@type input ::
input_expr
| {input, input}
| [input]
| atom
| number
| binary
@typep input_expr :: {input_expr | atom, metadata, atom | [input]}
@typedoc "The output of a macro"
@type output ::
output_expr
| {output, output}
| [output]
| atom
| number
| binary
| captured_remote_function
| pid
@typep output_expr :: {output_expr | atom, metadata, atom | [output]}
@typedoc """
A keyword list of AST metadata.
The metadata in Elixir AST is a keyword list of values. Any key can be used
and different parts of the compiler may use different keys. For example,
the AST received by a macro will always include the `:line` annotation,
while the AST emitted by `quote/2` will only have the `:line` annotation if
the `:line` option is provided.
The following metadata keys are public:
* `:context` - Defines the context in which the AST was generated.
For example, `quote/2` will include the module calling `quote/2`
as the context. This is often used to distinguish regular code from code
generated by a macro or by `quote/2`.
* `:counter` - The variable counter used for variable hygiene. In terms of
the compiler, each variable is identified by the combination of either
`name` and `metadata[:counter]`, or `name` and `context`.
* `:generated` - Whether the code should be considered as generated by
the compiler or not. This means the compiler and tools like Dialyzer may not
emit certain warnings.
* `:if_undefined` - How to expand a variable that is undefined. Set it to
`:apply` if you want a variable to become a nullary call without warning.
* `:keep` - Used by `quote/2` with the option `location: :keep` to annotate
the file and the line number of the quoted source.
* `:line` - The line number of the AST node.
The following metadata keys are enabled by `Code.string_to_quoted/2`:
* `:closing` - contains metadata about the closing pair, such as a `}`
in a tuple or in a map, or such as the closing `)` in a function call
with parens. The `:closing` does not delimit the end of expression if
there are `:do` and `:end` metadata (when `:token_metadata` is true)
* `:column` - the column number of the AST node (when `:columns` is true)
* `:delimiter` - contains the opening delimiter for sigils, strings,
and charlists as a string (such as `"{"`, `"/"`, `"'"`, and the like)
* `:format` - set to `:keyword` when an atom is defined as a keyword
* `:do` - contains metadata about the `do` location in a function call with
`do`-`end` blocks (when `:token_metadata` is true)
* `:end` - contains metadata about the `end` location in a function call with
`do`-`end` blocks (when `:token_metadata` is true)
* `:end_of_expression` - denotes when the end of expression effectively
happens. Available for all expressions except the last one inside a
`__block__` (when `:token_metadata` is true)
* `:indentation` - indentation of a sigil heredoc
The following metadata keys are private:
* `:alias` - Used for alias hygiene.
* `:ambiguous_op` - Used for improved error messages in the compiler.
* `:imports` - Used for import hygiene.
* `:var` - Used for improved error messages on undefined variables.
Do not rely on them as they may change or be fully removed in future versions
of the language. They are often used by `quote/2` and the compiler to provide
features like hygiene, better error messages, and so forth.
If you introduce custom keys into the AST metadata, please make sure to prefix
them with the name of your library or application, so that they will not conflict
with keys that could potentially be introduced by the compiler in the future.
"""
@type metadata :: keyword
@typedoc "A captured remote function in the format of &Mod.fun/arity"
@type captured_remote_function :: fun
@doc """
Breaks a pipeline expression into a list.
The AST for a pipeline (a sequence of applications of `|>/2`) is similar to the
AST of a sequence of binary operators or function applications: the top-level
expression is the right-most `:|>` (which is the last one to be executed), and
its left-hand and right-hand sides are its arguments:
quote do: 100 |> div(5) |> div(2)
#=> {:|>, _, [arg1, arg2]}
In the example above, the `|>/2` pipe is the right-most pipe; `arg1` is the AST
for `100 |> div(5)`, and `arg2` is the AST for `div(2)`.
It's often useful to have the AST for such a pipeline as a list of function
applications. This function does exactly that:
Macro.unpipe(quote do: 100 |> div(5) |> div(2))
#=> [{100, 0}, {{:div, [], [5]}, 0}, {{:div, [], [2]}, 0}]
We get a list that follows the pipeline directly: first the `100`, then the
`div(5)` (more precisely, its AST), then `div(2)`. The `0` as the second
element of the tuples is the position of the previous element in the pipeline
inside the current function application: `{{:div, [], [5]}, 0}` means that the
previous element (`100`) will be inserted as the 0th (first) argument to the
`div/2` function, so that the AST for that function will become `{:div, [],
[100, 5]}` (`div(100, 5)`).
"""
@spec unpipe(t()) :: [t()]
def unpipe(expr) do
:lists.reverse(unpipe(expr, []))
end
defp unpipe({:|>, _, [left, right]}, acc) do
unpipe(right, unpipe(left, acc))
end
defp unpipe(other, acc) do
[{other, 0} | acc]
end
@doc """
Pipes `expr` into the `call_args` at the given `position`.
This function can be used to implement `|>` like functionality. For example,
`|>` itself is implemented as:
defmacro left |> right do
Macro.pipe(left, right, 0)
end
`expr` is the AST of an expression. `call_args` must be the AST *of a call*,
otherwise this function will raise an error. As an example, consider the pipe
operator `|>/2`, which uses this function to build pipelines.
Even if the expression is piped into the AST, it doesn't necessarily mean that
the AST is valid. For example, you could pipe an argument to `div/2`, effectively
turning it into a call to `div/3`, which is a function that doesn't exist by
default. The code will raise unless a `div/3` function is locally defined.
"""
@spec pipe(t(), t(), integer) :: t()
def pipe(expr, call_args, position)
def pipe(expr, {:&, _, _} = call_args, _integer) do
raise ArgumentError, bad_pipe(expr, call_args)
end
def pipe(expr, {tuple_or_map, _, _} = call_args, _integer) when tuple_or_map in [:{}, :%{}] do
raise ArgumentError, bad_pipe(expr, call_args)
end
# Without this, `Macro |> Env == Macro.Env`.
def pipe(expr, {:__aliases__, _, _} = call_args, _integer) do
raise ArgumentError, bad_pipe(expr, call_args)
end
def pipe(expr, {:<<>>, _, _} = call_args, _integer) do
raise ArgumentError, bad_pipe(expr, call_args)
end
def pipe(expr, {unquote, _, []}, _integer) when unquote in [:unquote, :unquote_splicing] do
raise ArgumentError,
"cannot pipe #{to_string(expr)} into the special form #{unquote}/1 " <>
"since #{unquote}/1 is used to build the Elixir AST itself"
end
# {:fn, _, _} is what we get when we pipe into an anonymous function without
# calling it, for example, `:foo |> (fn x -> x end)`.
def pipe(expr, {:fn, _, _}, _integer) do
raise ArgumentError,
"cannot pipe #{to_string(expr)} into an anonymous function without" <>
" calling the function; use Kernel.then/2 instead or" <>
" define the anonymous function as a regular private function"
end
def pipe(expr, {call, line, atom}, integer) when is_atom(atom) do
{call, line, List.insert_at([], integer, expr)}
end
def pipe(_expr, {op, _line, [arg]}, _integer) when op == :+ or op == :- do
raise ArgumentError,
"piping into a unary operator is not supported, please use the qualified name: " <>
"Kernel.#{op}(#{to_string(arg)}), instead of #{op}#{to_string(arg)}"
end
def pipe(expr, {op, line, args} = op_args, integer) when is_list(args) do
cond do
is_atom(op) and operator?(op, 1) ->
raise ArgumentError,
"cannot pipe #{to_string(expr)} into #{to_string(op_args)}, " <>
"the #{to_string(op)} operator can only take one argument"
is_atom(op) and operator?(op, 2) ->
raise ArgumentError,
"cannot pipe #{to_string(expr)} into #{to_string(op_args)}, " <>
"the #{to_string(op)} operator can only take two arguments"
true ->
{op, line, List.insert_at(args, integer, expr)}
end
end
def pipe(expr, call_args, _integer) do
raise ArgumentError, bad_pipe(expr, call_args)
end
defp bad_pipe(expr, call_args) do
"cannot pipe #{to_string(expr)} into #{to_string(call_args)}, " <>
"can only pipe into local calls foo(), remote calls Foo.bar() or anonymous function calls foo.()"
end
@doc """
Applies the given function to the node metadata if it contains one.
This is often useful when used with `Macro.prewalk/2` to remove
information like lines and hygienic counters from the expression
for either storage or comparison.
## Examples
iex> quoted = quote line: 10, do: sample()
{:sample, [line: 10], []}
iex> Macro.update_meta(quoted, &Keyword.delete(&1, :line))
{:sample, [], []}
"""
@spec update_meta(t, (keyword -> keyword)) :: t
def update_meta(quoted, fun)
def update_meta({left, meta, right}, fun) when is_list(meta) do
{left, fun.(meta), right}
end
def update_meta(other, _fun) do
other
end
@doc """
Generates AST nodes for a given number of required argument
variables using `Macro.var/2`.
Note the arguments are not unique. If you later on want
to access the same variables, you can invoke this function
with the same inputs. Use `generate_unique_arguments/2` to
generate a unique arguments that can't be overridden.
## Examples
iex> Macro.generate_arguments(2, __MODULE__)
[{:arg1, [], __MODULE__}, {:arg2, [], __MODULE__}]
"""
@doc since: "1.5.0"
@spec generate_arguments(0, context :: atom) :: []
@spec generate_arguments(pos_integer, context) :: [{atom, [], context}, ...] when context: atom
def generate_arguments(amount, context), do: generate_arguments(amount, context, &var/2)
@doc """
Returns the path to the node in `ast` which `fun` returns true.
The path is a list, starting with the node in which `fun` returns
true, followed by all of its parents.
Computing the path can be an efficient operation when you want
to find a particular node in the AST within its context and then
assert something about it.
## Examples
iex> Macro.path(quote(do: [1, 2, 3]), & &1 == 3)
[3, [1, 2, 3]]
iex> Macro.path(quote(do: Foo.bar(3)), & &1 == 3)
[3, quote(do: Foo.bar(3))]
iex> Macro.path(quote(do: %{foo: [bar: :baz]}), & &1 == :baz)
[
:baz,
{:bar, :baz},
[bar: :baz],
{:foo, [bar: :baz]},
{:%{}, [], [foo: [bar: :baz]]}
]
"""
@doc since: "1.14.0"
def path(ast, fun) when is_function(fun, 1) do
path(ast, [], fun)
end
defp path({form, _, args} = ast, acc, fun) when is_atom(form) do
acc = [ast | acc]
if fun.(ast) do
acc
else
path_args(args, acc, fun)
end
end
defp path({form, _meta, args} = ast, acc, fun) do
acc = [ast | acc]
if fun.(ast) do
acc
else
path(form, acc, fun) || path_args(args, acc, fun)
end
end
defp path({left, right} = ast, acc, fun) do
acc = [ast | acc]
if fun.(ast) do
acc
else
path(left, acc, fun) || path(right, acc, fun)
end
end
defp path(list, acc, fun) when is_list(list) do
acc = [list | acc]
if fun.(list) do
acc
else
path_list(list, acc, fun)
end
end
defp path(ast, acc, fun) do
if fun.(ast) do
[ast | acc]
end
end
defp path_args(atom, _acc, _fun) when is_atom(atom), do: nil
defp path_args(list, acc, fun) when is_list(list), do: path_list(list, acc, fun)
defp path_list([], _acc, _fun) do
nil
end
defp path_list([arg | args], acc, fun) do
path(arg, acc, fun) || path_list(args, acc, fun)
end
@doc """
Generates AST nodes for a given number of required argument
variables using `Macro.unique_var/2`.
## Examples
iex> [var1, var2] = Macro.generate_unique_arguments(2, __MODULE__)
iex> {:arg1, [counter: c1], __MODULE__} = var1
iex> {:arg2, [counter: c2], __MODULE__} = var2
iex> is_integer(c1) and is_integer(c2)
true
"""
@doc since: "1.11.3"
@spec generate_unique_arguments(0, context :: atom) :: []
@spec generate_unique_arguments(pos_integer, context) :: [
{atom, [counter: integer], context},
...
]
when context: atom
def generate_unique_arguments(amount, context),
do: generate_arguments(amount, context, &unique_var/2)
defp generate_arguments(0, context, _fun) when is_atom(context), do: []
defp generate_arguments(amount, context, fun)
when is_integer(amount) and amount > 0 and is_atom(context) do
for id <- 1..amount, do: fun.(String.to_atom("arg" <> Integer.to_string(id)), context)
end
@doc """
Generates an AST node representing the variable given
by the atoms `var` and `context`.
Note this variable is not unique. If you later on want
to access this same variable, you can invoke `var/2`
again with the same arguments. Use `unique_var/2` to
generate a unique variable that can't be overridden.
## Examples
In order to build a variable, a context is expected.
Most of the times, in order to preserve hygiene, the
context must be `__MODULE__/0`:
iex> Macro.var(:foo, __MODULE__)
{:foo, [], __MODULE__}
However, if there is a need to access the user variable,
nil can be given:
iex> Macro.var(:foo, nil)
{:foo, [], nil}
"""
@spec var(var, context) :: {var, [], context} when var: atom, context: atom
def var(var, context) when is_atom(var) and is_atom(context) do
{var, [], context}
end
@doc """
Generates an AST node representing a unique variable
given by the atoms `var` and `context`.
Calling this function with the same arguments will
generate another variable, with its own unique counter.
See `var/2` for an alternative.
## Examples
iex> {:foo, [counter: c], __MODULE__} = Macro.unique_var(:foo, __MODULE__)
iex> is_integer(c)
true
"""
@doc since: "1.11.3"
@spec unique_var(var, context) :: {var, [counter: integer], context}
when var: atom, context: atom
def unique_var(var, context) when is_atom(var) and is_atom(context) do
{var, [counter: :elixir_module.next_counter(context)], context}
end
@doc """
Performs a depth-first traversal of quoted expressions
using an accumulator.
Returns a tuple where the first element is a new AST and the second one is
the final accumulator. The new AST is the result of invoking `pre` on each
node of `ast` during the pre-order phase and `post` during the post-order
phase.
## Examples
iex> ast = quote do: 5 + 3 * 7
iex> {:+, _, [5, {:*, _, [3, 7]}]} = ast
iex> {new_ast, acc} =
...> Macro.traverse(
...> ast,
...> [],
...> fn
...> {:+, meta, children}, acc -> {{:-, meta, children}, [:- | acc]}
...> {:*, meta, children}, acc -> {{:/, meta, children}, [:/ | acc]}
...> other, acc -> {other, acc}
...> end,
...> fn
...> {:-, meta, children}, acc -> {{:min, meta, children}, [:min | acc]}
...> {:/, meta, children}, acc -> {{:max, meta, children}, [:max | acc]}
...> other, acc -> {other, acc}
...> end
...> )
iex> {:min, _, [5, {:max, _, [3, 7]}]} = new_ast
iex> [:min, :max, :/, :-] = acc
iex> Code.eval_quoted(new_ast)
{5, []}
"""
@spec traverse(t, any, (t, any -> {t, any}), (t, any -> {t, any})) :: {t, any}
def traverse(ast, acc, pre, post) when is_function(pre, 2) and is_function(post, 2) do
{ast, acc} = pre.(ast, acc)
do_traverse(ast, acc, pre, post)
end
defp do_traverse({form, meta, args}, acc, pre, post) when is_atom(form) do
{args, acc} = do_traverse_args(args, acc, pre, post)
post.({form, meta, args}, acc)
end
defp do_traverse({form, meta, args}, acc, pre, post) do
{form, acc} = pre.(form, acc)
{form, acc} = do_traverse(form, acc, pre, post)
{args, acc} = do_traverse_args(args, acc, pre, post)
post.({form, meta, args}, acc)
end
defp do_traverse({left, right}, acc, pre, post) do
{left, acc} = pre.(left, acc)
{left, acc} = do_traverse(left, acc, pre, post)
{right, acc} = pre.(right, acc)
{right, acc} = do_traverse(right, acc, pre, post)
post.({left, right}, acc)
end
defp do_traverse(list, acc, pre, post) when is_list(list) do
{list, acc} = do_traverse_args(list, acc, pre, post)
post.(list, acc)
end
defp do_traverse(x, acc, _pre, post) do
post.(x, acc)
end
defp do_traverse_args(args, acc, _pre, _post) when is_atom(args) do
{args, acc}
end
defp do_traverse_args(args, acc, pre, post) when is_list(args) do
:lists.mapfoldl(
fn x, acc ->
{x, acc} = pre.(x, acc)
do_traverse(x, acc, pre, post)
end,
acc,
args
)
end
@doc """
Performs a depth-first, pre-order traversal of quoted expressions.
Returns a new AST where each node is the result of invoking `fun` on each
corresponding node of `ast`.
## Examples
iex> ast = quote do: 5 + 3 * 7
iex> {:+, _, [5, {:*, _, [3, 7]}]} = ast
iex> new_ast = Macro.prewalk(ast, fn
...> {:+, meta, children} -> {:*, meta, children}
...> {:*, meta, children} -> {:+, meta, children}
...> other -> other
...> end)
iex> {:*, _, [5, {:+, _, [3, 7]}]} = new_ast
iex> Code.eval_quoted(ast)
{26, []}
iex> Code.eval_quoted(new_ast)
{50, []}
"""
@spec prewalk(t, (t -> t)) :: t
def prewalk(ast, fun) when is_function(fun, 1) do
elem(prewalk(ast, nil, fn x, nil -> {fun.(x), nil} end), 0)
end
@doc """
Performs a depth-first, pre-order traversal of quoted expressions
using an accumulator.
Returns a tuple where the first element is a new AST where each node is the
result of invoking `fun` on each corresponding node and the second one is the
final accumulator.
## Examples
iex> ast = quote do: 5 + 3 * 7
iex> {:+, _, [5, {:*, _, [3, 7]}]} = ast
iex> {new_ast, acc} = Macro.prewalk(ast, [], fn
...> {:+, meta, children}, acc -> {{:*, meta, children}, [:+ | acc]}
...> {:*, meta, children}, acc -> {{:+, meta, children}, [:* | acc]}
...> other, acc -> {other, acc}
...> end)
iex> {{:*, _, [5, {:+, _, [3, 7]}]}, [:*, :+]} = {new_ast, acc}
iex> Code.eval_quoted(ast)
{26, []}
iex> Code.eval_quoted(new_ast)
{50, []}
"""
@spec prewalk(t, any, (t, any -> {t, any})) :: {t, any}
def prewalk(ast, acc, fun) when is_function(fun, 2) do
traverse(ast, acc, fun, fn x, a -> {x, a} end)
end
@doc """
This function behaves like `prewalk/2`, but performs a depth-first,
post-order traversal of quoted expressions.
"""
@spec postwalk(t, (t -> t)) :: t
def postwalk(ast, fun) when is_function(fun, 1) do
elem(postwalk(ast, nil, fn x, nil -> {fun.(x), nil} end), 0)
end
@doc """
This functions behaves like `prewalk/3`, but performs a depth-first,
post-order traversal of quoted expressions using an accumulator.
"""
@spec postwalk(t, any, (t, any -> {t, any})) :: {t, any}
def postwalk(ast, acc, fun) when is_function(fun, 2) do
traverse(ast, acc, fn x, a -> {x, a} end, fun)
end
@doc """
Decomposes a local or remote call into its remote part (when provided),
function name and argument list.
Returns `:error` when an invalid call syntax is provided.
## Examples
iex> Macro.decompose_call(quote(do: foo))
{:foo, []}
iex> Macro.decompose_call(quote(do: foo()))
{:foo, []}
iex> Macro.decompose_call(quote(do: foo(1, 2, 3)))
{:foo, [1, 2, 3]}
iex> Macro.decompose_call(quote(do: Elixir.M.foo(1, 2, 3)))
{{:__aliases__, [], [:Elixir, :M]}, :foo, [1, 2, 3]}
iex> Macro.decompose_call(quote(do: 42))
:error
iex> Macro.decompose_call(quote(do: {:foo, [], []}))
:error
"""
@spec decompose_call(t()) :: {atom, [t()]} | {t(), atom, [t()]} | :error
def decompose_call(ast)
def decompose_call({:{}, _, args}) when is_list(args), do: :error
def decompose_call({{:., _, [remote, function]}, _, args})
when is_tuple(remote) or is_atom(remote),
do: {remote, function, args}
def decompose_call({name, _, args}) when is_atom(name) and is_atom(args), do: {name, []}
def decompose_call({name, _, args}) when is_atom(name) and is_list(args), do: {name, args}
def decompose_call(_), do: :error
@doc """
Recursively escapes a value so it can be inserted into a syntax tree.
## Examples
iex> Macro.escape(:foo)
:foo
iex> Macro.escape({:a, :b, :c})
{:{}, [], [:a, :b, :c]}
iex> Macro.escape({:unquote, [], [1]}, unquote: true)
1
## Options
* `:unquote` - when true, this function leaves `unquote/1` and
`unquote_splicing/1` statements unescaped, effectively unquoting
the contents on escape. This option is useful only when escaping
ASTs which may have quoted fragments in them. Defaults to false.
* `:prune_metadata` - when true, removes metadata from escaped AST
nodes. Note this option changes the semantics of escaped code and
it should only be used when escaping ASTs. Defaults to false.
As an example, `ExUnit` stores the AST of every assertion, so when
an assertion fails we can show code snippets to users. Without this
option, each time the test module is compiled, we get a different
MD5 of the module bytecode, because the AST contains metadata,
such as counters, specific to the compilation environment. By pruning
the metadata, we ensure that the module is deterministic and reduce
the amount of data `ExUnit` needs to keep around. Only the minimal
amount of metadata is kept, such as `:line` and `:no_parens`.
## Comparison to `quote/2`
The `escape/2` function is sometimes confused with `quote/2`,
because the above examples behave the same with both. The key difference is
best illustrated when the value to escape is stored in a variable.
iex> Macro.escape({:a, :b, :c})
{:{}, [], [:a, :b, :c]}
iex> quote do: {:a, :b, :c}
{:{}, [], [:a, :b, :c]}
iex> value = {:a, :b, :c}
iex> Macro.escape(value)
{:{}, [], [:a, :b, :c]}
iex> quote do: value
{:value, [], __MODULE__}
iex> value = {:a, :b, :c}
iex> quote do: unquote(value)
{:a, :b, :c}
`escape/2` is used to escape *values* (either directly passed or variable
bound), while `quote/2` produces syntax trees for
expressions.
"""
@spec escape(term, keyword) :: t()
def escape(expr, opts \\ []) do
unquote = Keyword.get(opts, :unquote, false)
kind = if Keyword.get(opts, :prune_metadata, false), do: :prune_metadata, else: :none
:elixir_quote.escape(expr, kind, unquote)
end
@doc """
Expands the struct given by `module` in the given `env`.
This is useful when a struct needs to be expanded at
compilation time and the struct being expanded may or may
not have been compiled. This function is also capable of
expanding structs defined under the module being compiled.
It will raise `CompileError` if the struct is not available.
From Elixir v1.12, calling this function also adds an export
dependency on the given struct.
"""
@doc since: "1.8.0"
@spec struct!(module, Macro.Env.t()) ::
%{required(:__struct__) => module, optional(atom) => any}
when module: module()
def struct!(module, env) when is_atom(module) do
if module == env.module do
Module.get_attribute(module, :__struct__)
end || :elixir_map.load_struct([line: env.line], module, [], [], env)
end
@doc """
Validates the given expressions are valid quoted expressions.
Check the type `t:Macro.t/0` for a complete specification of a
valid quoted expression.
It returns `:ok` if the expression is valid. Otherwise it returns
a tuple in the form of `{:error, remainder}` where `remainder` is
the invalid part of the quoted expression.
## Examples
iex> Macro.validate({:two_element, :tuple})
:ok
iex> Macro.validate({:three, :element, :tuple})
{:error, {:three, :element, :tuple}}
iex> Macro.validate([1, 2, 3])
:ok
iex> Macro.validate([1, 2, 3, {4}])
{:error, {4}}
"""
@spec validate(term) :: :ok | {:error, term}
def validate(expr) do
find_invalid(expr) || :ok
end
defp find_invalid({left, right}), do: find_invalid(left) || find_invalid(right)
defp find_invalid({left, meta, right})
when is_list(meta) and (is_atom(right) or is_list(right)),
do: find_invalid(left) || find_invalid(right)
defp find_invalid(list) when is_list(list), do: Enum.find_value(list, &find_invalid/1)
defp find_invalid(pid) when is_pid(pid), do: nil
defp find_invalid(atom) when is_atom(atom), do: nil
defp find_invalid(num) when is_number(num), do: nil
defp find_invalid(bin) when is_binary(bin), do: nil
defp find_invalid(fun) when is_function(fun) do
unless Function.info(fun, :env) == {:env, []} and
Function.info(fun, :type) == {:type, :external} do
{:error, fun}
end
end
defp find_invalid(other), do: {:error, other}
@doc """
Returns an enumerable that traverses the `ast` in depth-first,
pre-order traversal.
## Examples
iex> ast = quote do: foo(1, "abc")
iex> Enum.map(Macro.prewalker(ast), & &1)
[{:foo, [], [1, "abc"]}, 1, "abc"]
"""
@doc since: "1.13.0"
@spec prewalker(t()) :: Enumerable.t()
def prewalker(ast) do
&prewalker([ast], &1, &2)
end
defp prewalker(_buffer, {:halt, acc}, _fun) do
{:halted, acc}
end
defp prewalker(buffer, {:suspend, acc}, fun) do
{:suspended, acc, &prewalker(buffer, &1, fun)}
end
defp prewalker([], {:cont, acc}, _fun) do
{:done, acc}
end
defp prewalker([{left, right} = node | tail], {:cont, acc}, fun) do
prewalker([left, right | tail], fun.(node, acc), fun)
end
defp prewalker([{left, meta, right} = node | tail], {:cont, acc}, fun)
when is_atom(left) and is_list(meta) do
if is_atom(right) do
prewalker(tail, fun.(node, acc), fun)
else
prewalker(right ++ tail, fun.(node, acc), fun)
end
end
defp prewalker([{left, meta, right} = node | tail], {:cont, acc}, fun) when is_list(meta) do
if is_atom(right) do
prewalker([left | tail], fun.(node, acc), fun)
else
prewalker([left | right] ++ tail, fun.(node, acc), fun)
end
end
defp prewalker([list | tail], {:cont, acc}, fun) when is_list(list) do
prewalker(list ++ tail, fun.(list, acc), fun)
end
defp prewalker([head | tail], {:cont, acc}, fun) do
prewalker(tail, fun.(head, acc), fun)
end
@doc """
Returns an enumerable that traverses the `ast` in depth-first,
post-order traversal.
## Examples
iex> ast = quote do: foo(1, "abc")
iex> Enum.map(Macro.postwalker(ast), & &1)
[1, "abc", {:foo, [], [1, "abc"]}]
"""
@doc since: "1.13.0"
@spec postwalker(t()) :: Enumerable.t()
def postwalker(ast) do
&postwalker([ast], make_ref(), &1, &2)
end
defp postwalker(_buffer, _ref, {:halt, acc}, _fun) do
{:halted, acc}
end
defp postwalker(buffer, ref, {:suspend, acc}, fun) do
{:suspended, acc, &postwalker(buffer, ref, &1, fun)}
end
defp postwalker([], _ref, {:cont, acc}, _fun) do
{:done, acc}
end
defp postwalker([{ref, head} | tail], ref, {:cont, acc}, fun) do
postwalker(tail, ref, fun.(head, acc), fun)
end
defp postwalker([{left, right} = node | tail], ref, {:cont, acc}, fun) do
postwalker([right, {ref, node} | tail], ref, fun.(left, acc), fun)
end
defp postwalker([{left, meta, right} = node | tail], ref, {:cont, acc}, fun)
when is_atom(left) and is_list(meta) do
if is_atom(right) do
postwalker(tail, ref, fun.(node, acc), fun)
else
postwalker(right ++ [{ref, node} | tail], ref, {:cont, acc}, fun)
end
end