First
[anni] / lib / pleroma / docs / generator.ex
1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2022 Pleroma Authors <https://pleroma.social/>
3 # SPDX-License-Identifier: AGPL-3.0-only
4
5 defmodule Pleroma.Docs.Generator do
6   @callback process(keyword()) :: {:ok, String.t()}
7
8   @spec process(module(), keyword()) :: {:ok, String.t()}
9   def process(implementation, descriptions) do
10     implementation.process(descriptions)
11   end
12
13   @spec list_behaviour_implementations(behaviour :: module()) :: [module()]
14   def list_behaviour_implementations(behaviour) do
15     :code.all_loaded()
16     |> Enum.filter(fn {module, _} ->
17       # This shouldn't be needed as all modules are expected to have module_info/1,
18       # but in test enviroments some transient modules `:elixir_compiler_XX`
19       # are loaded for some reason (where XX is a random integer).
20       if function_exported?(module, :module_info, 1) do
21         module.module_info(:attributes)
22         |> Keyword.get_values(:behaviour)
23         |> List.flatten()
24         |> Enum.member?(behaviour)
25       end
26     end)
27     |> Enum.map(fn {module, _} -> module end)
28   end
29
30   @doc """
31   Converts:
32   - atoms to strings with leading `:`
33   - module names to strings, without leading `Elixir.`
34   - add humanized labels to `keys` if label is not defined, e.g. `:instance` -> `Instance`
35   """
36   @spec convert_to_strings([map()]) :: [map()]
37   def convert_to_strings(descriptions) do
38     Enum.map(descriptions, &format_entity(&1))
39   end
40
41   defp format_entity(entity) do
42     entity
43     |> format_key()
44     |> Map.put(:group, atom_to_string(entity[:group]))
45     |> format_children()
46   end
47
48   defp format_key(%{key: key} = entity) do
49     entity
50     |> Map.put(:key, atom_to_string(key))
51     |> Map.put(:label, entity[:label] || humanize(key))
52   end
53
54   defp format_key(%{group: group} = entity) do
55     Map.put(entity, :label, entity[:label] || humanize(group))
56   end
57
58   defp format_key(entity), do: entity
59
60   defp format_children(%{children: children} = entity) do
61     Map.put(entity, :children, Enum.map(children, &format_child(&1)))
62   end
63
64   defp format_children(entity), do: entity
65
66   defp format_child(%{suggestions: suggestions} = entity) do
67     entity
68     |> Map.put(:suggestions, format_suggestions(suggestions))
69     |> format_key()
70     |> format_group()
71     |> format_children()
72   end
73
74   defp format_child(entity) do
75     entity
76     |> format_key()
77     |> format_group()
78     |> format_children()
79   end
80
81   defp format_group(%{group: group} = entity) do
82     Map.put(entity, :group, format_suggestion(group))
83   end
84
85   defp format_group(entity), do: entity
86
87   defp atom_to_string(entity) when is_binary(entity), do: entity
88
89   defp atom_to_string(entity) when is_atom(entity), do: inspect(entity)
90
91   defp humanize(entity) do
92     string = inspect(entity)
93
94     if String.starts_with?(string, ":"),
95       do: Phoenix.Naming.humanize(entity),
96       else: string
97   end
98
99   defp format_suggestions({:list_behaviour_implementations, behaviour}) do
100     behaviour
101     |> list_behaviour_implementations()
102     |> format_suggestions()
103   end
104
105   defp format_suggestions([]), do: []
106
107   defp format_suggestions([suggestion | tail]) do
108     [format_suggestion(suggestion) | format_suggestions(tail)]
109   end
110
111   defp format_suggestion(entity) when is_atom(entity) do
112     atom_to_string(entity)
113   end
114
115   defp format_suggestion([head | tail] = entity) when is_list(entity) do
116     [format_suggestion(head) | format_suggestions(tail)]
117   end
118
119   defp format_suggestion(entity) when is_tuple(entity) do
120     format_suggestions(Tuple.to_list(entity)) |> List.to_tuple()
121   end
122
123   defp format_suggestion(entity), do: entity
124 end
125
126 defimpl Jason.Encoder, for: Tuple do
127   def encode(tuple, opts), do: Jason.Encode.list(Tuple.to_list(tuple), opts)
128 end
129
130 defimpl Jason.Encoder, for: [Regex, Function] do
131   def encode(term, opts), do: Jason.Encode.string(inspect(term), opts)
132 end
133
134 defimpl String.Chars, for: Regex do
135   def to_string(term), do: inspect(term)
136 end