<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2023</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

    </legalnotice>

    <title>edlin_expand</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>
  <module since="OTP 26.0">edlin_expand</module>
  <modulesummary>Shell expansion and formatting of expansion suggestions.</modulesummary>
  <description>
    <p>This module provides an expand_fun for the erlang shell
    <seemfa marker="#expand/1"><c>expand/1,2</c></seemfa>.
    It is possible to override this expand_fun
    <seemfa marker="io#setopts/1"><c>io:setopts/1,2</c></seemfa>.</p>
  </description>
  <funcs>
    <func>
      <name name="expand" arity="1" since="OTP 26.0"/>
      <name name="expand" arity="2" since="OTP 26.0"/>
      <fsummary>Standard expanion function for the erl shell.</fsummary>
      <desc>
        <p>The standard expansion function is able to expand strings to
        valid erlang terms. This includes module names:</p>
        <pre>
1> erla
modules
erlang:
        </pre>
        <p>function names:</p>
        <pre>
1> is_ato
functions
is_atom(
2> erlang:is_ato
functions
is_atom(
    </pre>
<p>
        function types:
</p>
<pre>
1> erlang:is_atom(
typespecs
erlang:is_atom(Term)
any()
</pre>
<p>
        and automatically add , or closing parenthesis when no other
        valid expansion is possible. The expand function also completes:
        shell bindings, record names, record fields and map keys.
</p>
<p>
        As seen below, function headers are grouped together if they've got the same
        expansion suggestion, in this case all had the same suggestions, that is '}'.
        There is also limited support for filtering out function typespecs that that does
        not match the types on the terms on the prompt. Only 4 suggestions are shown below
        but there exists plenty more typespecs for <c>erlang:system_info</c>.
        </p>
<pre>
1> erlang:system_info({allocator, my_allocator
typespecs
erlang:system_info(wordsize | {wordsize, ...} | {wordsize, ...})
erlang:system_info({allocator, ...})
erlang:system_info({allocator_sizes, ...})
erlang:system_info({cpu_topology, ...})
}
</pre>
        <p>The return type of <c>expand</c> function specifies either a list of <c>Element</c>
        tuples or a list of <c>Section</c> maps. The section concept was introduced to enable
        more formatting options for the expansion results. For example, the shell expansion has
        support to highlight text and hide suggestions.
        There are also a <c>{highlight, Text}</c> that highlights all occurances of
        <c>Text</c> in the title, and a <c>highlight_all</c> for simplicity which
        highlights the whole title, as can be seen above for <c>functions</c> and <c>typespecs</c>.</p>

        <p>By setting the <c>{hide, result}</c> or <c>{hide, title}</c> options you may hide
        suggestions. Sometimes the title isn't useful and just produces text noise, in the example
        above the <c>any()</c> result is part of a section with title <c>Types</c>. Hiding results
        is currently not in use, but the idea is that a section can be selected in the expand area
        and all the other section entries should be collapsed.
        </p>

        <p>Its possible to set a custom separator between the title and the results. This can be
        done with <c>{separator, Separator}</c>.
        By default its set to be <c>\n</c>, some results display a <c>type_name() :: </c>
        followed by all types that define <c>type_name()</c>.
        </p>

        <p>The <c>{ending, Text}</c> ElementOption just appends Text to the <c>Element</c>.
        </p>
      </desc>
    </func>
  </funcs>
</erlref>
