git.iko.soy/lynxjs-elm/compiler
on master help sign in
lynxjs-elm/compiler/hints/imports.md
126 lines 5.5 kB history raw
2# Hints for Imports
4When getting started with Elm, it is pretty common to have questions about how the `import` declarations work exactly. These questions usually arise when you start playing with the `Html` library so we will focus on that.
7<br>
9## `import`
11An Elm file is called a **module**. To access code in other files, you need to `import` it!
13So say you want to use the [`div`](http://package.elm-lang.org/packages/elm-lang/html/latest/Html#div) function from the [`elm-lang/html`](http://package.elm-lang.org/packages/elm-lang/html/latest) package. The simplest way is to import it like this:
15```elm
16import Html
18main =
19 Html.div [] []
20```
22After saying `import Html` we can refer to anything inside that module as long as it is *qualified*. This works for:
24 - **Values** &mdash; we can refer to `Html.text`, `Html.h1`, etc.
25 - **Types** &mdash; We can refer to [`Attribute`](http://package.elm-lang.org/packages/elm-lang/html/latest/Html#Attribute) as `Html.Attribute`.
27So if we add a type annotation to `main` it would look like this:
29```elm
30import Html
32main : Html.Html msg
33main =
34 Html.div [] []
35```
37We are referring to the [`Html`](http://package.elm-lang.org/packages/elm-lang/html/latest/Html#Html) type, using its *qualified* name `Html.Html`. This can feel weird at first, but it starts feeling natural quite quickly!
39> **Note:** Modules do not contain other modules. So the `Html` module *does not* contain the `Html.Attributes` module. Those are separate names that happen to have some overlap. So if you say `import Html` you *do not* get access to `Html.Attributes.style`. You must `import Html.Attributes` module separately.
42<br>
44## `as`
46It is best practice to always use *qualified* names, but sometimes module names are so long that it becomes unwieldy. This is common for the `Html.Attributes` module. We can use the `as` keyword to help with this:
48```elm
49import Html
50import Html.Attributes as A
52main =
53 Html.div [ A.style "color" "red" ] [ Html.text "Hello!" ]
54```
56Saying `import Html.Attributes as A` lets us refer to any value or type in `Html.Attributes` as long as it is qualified with an `A`. So now we can refer to [`style`](http://package.elm-lang.org/packages/elm-lang/html/latest/Html-Attributes#style) as `A.style`.
59<br>
61## `exposing`
63In quick drafts, maybe you want to use *unqualified* names. You can do that with the `exposing` keyword like this:
65```elm
66import Html exposing (..)
67import Html.Attributes exposing (style)
69main : Html msg
70main =
71 div [ style "color" "red" ] [ text "Hello!" ]
72```
74Saying `import Html exposing (..)` means I can refer to any value or type from the `Html` module without qualification. Notice that I use the `Html` type, the `div` function, and the `text` function without qualification in the example above.
76> **Note:** It seems neat to expose types and values directly, but it can get out of hand. Say you `import` ten modules `exposing` all of their content. It quickly becomes difficult to figure out what is going on in your code. “Wait, where is this function from?” And then trying to sort through all the imports to find it. Point is, use `exposing (..)` sparingly!
78Saying `import Html.Attributes exposing (style)` is a bit more reasonable. It means I can refer to the `style` function without qualification, but that is it. You are still importing the `Html.Attributes` module like normal though, so you would say `Html.Attributes.class` or `Html.Attributes.id` to refer to other values and types from that module.
81<br>
83## `as` and `exposing`
85There is one last way to import a module. You can combine `as` and `exposing` to try to get a nice balance of qualified names:
87```elm
88import Html exposing (Html, div, text)
89import Html.Attributes as A exposing (style)
91main : Html msg
92main =
93 div [ A.class "greeting", style "color" "red" ] [ text "Hello!" ]
94```
96Notice that I refer to `A.class` which is qualified and `style` which is unqualified.
99<br>
101## Default Imports
103We just learned all the variations of the `import` syntax in Elm. You will use some version of that syntax to `import` any module you ever write.
105It would be the best policy to make it so every module in the whole ecosystem works this way. We thought so in the past at least, but there are some modules that are so commonly used that the Elm compiler automatically adds the imports to every file. These default imports include:
107```elm
108import Basics exposing (..)
109import List exposing (List, (::))
110import Maybe exposing (Maybe(..))
111import Result exposing (Result(..))
112import String
113import Tuple
115import Debug
117import Platform exposing (Program)
118import Platform.Cmd as Cmd exposing (Cmd)
119import Platform.Sub as Sub exposing (Sub)
120```
122You can think of these imports being at the top of any module you write.
124One could argue that `Maybe` is so fundamental to how we handle errors in Elm code that it is *basically* part of the language. One could also argue that it is extraordinarily annoying to have to import `Maybe` once you get past your first couple weeks with Elm. Either way, we know that default imports are not ideal in some sense, so we have tried to keep the default imports as minimal as possible.
126> **Note:** Elm performs dead code elimination, so if you do not use something from a module, it is not included in the generated code. So if you `import` a module with hundreds of functions, you do not need to worry about the size of your assets. You will only get what you use!