# Extracting an API outline from an Elm file

**URL:** <https://discourse.elm-lang.org/t/extracting-an-api-outline-from-an-elm-file/4257>\
**Category:** Show and Tell\
**Created:** [September 4, 2019, 3:26pm UTC](https://discourse.elm-lang.org/t/extracting-an-api-outline-from-an-elm-file/4257 "2019-09-04T15:26:14Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![brian](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/brian/32/2180_2.png) [@brian](https://discourse.elm-lang.org/u/brian)\
**Post date:** [September 4, 2019, 3:26pm UTC](https://discourse.elm-lang.org/t/extracting-an-api-outline-from-an-elm-file/4257/1 "2019-09-04T15:26:14Z")

</div>

when I’m designing APIs in Elm, I like to start with just the types—this is pretty common advice around these parts! But when I’m refactoring stuff, or talking about a design I want to be able to use the same technique to guide my thinking.

So, here’s a [shell script I use](https://github.com/BrianHicks/dotfiles.nix/blob/master/dotfiles/zsh/elm.zsh#L3-L7) to get a rough idea of how a module is structured:

```auto
elm_outline() {
    MODULE=$1
    grep -E '^(type|--|\w+ : .+)' $MODULE
}

```

a couple caveats: this will grab all top-level comments (so section headers like `-- FOO` work fine) but no doc comments or type constructors and you will have to remove non-exposed variables manually. Despite that, I’ve found this useful for a while, so I wanted to share it here!

You can see an example of the output in [Interesting query pattern for repeatedly bisecting lists](https://discourse.elm-lang.org/t/interesting-query-pattern-for-repeatedly-bisecting-lists/4256).

---

<div class="post-metadata">

**Author:** ![rupert](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/rupert/32/1775_2.png) [@rupert](https://discourse.elm-lang.org/u/rupert)\
**Post date:** [September 5, 2019, 11:06am UTC](https://discourse.elm-lang.org/t/extracting-an-api-outline-from-an-elm-file/4257/2 "2019-09-05T11:06:28Z")

</div>

Nice idea. At the moment I am writing a pretty printer for Elm code that has been parsed by `stil4m/elm-syntax`. Once that is working it would be easy to get a bit more sophisticated with this. For example, only print out stuff that is exposed, or print type constructors only when exposed, or cope better with function signatures that are split over multiple lines and so on.

---

<div class="post-metadata">

**Author:** ![brian](https://yyz1.discourse-cdn.com/flex035/user_avatar/discourse.elm-lang.org/brian/32/2180_2.png) [@brian](https://discourse.elm-lang.org/u/brian)\
**Post date:** [September 15, 2019, 11:06am UTC](https://discourse.elm-lang.org/t/extracting-an-api-outline-from-an-elm-file/4257/3 "2019-09-15T11:06:29Z")

</div>

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.