.. _ctags-lang-elm(7):

==============================================================

ctags-lang-elm

==============================================================

-------------------------------------------------------------------

Random notes about tagging Elm source code with Universal Ctags

-------------------------------------------------------------------

:Version: @VERSION@

:Manual group: Universal Ctags

:Manual section: 7

SYNOPSIS

--------

| **@CTAGS_NAME_EXECUTABLE@** ... --languages=+Elm ...

| **@CTAGS_NAME_EXECUTABLE@** ... --language-force=Elm ...

| **@CTAGS_NAME_EXECUTABLE@** ... --map-Elm=+.elm ...

DESCRIPTION

-----------

The Elm parser is a PEG parser using PackCC, which is part of the

ctags infrastructure. It should correctly process all top level

statements, however there is a limitation with functions embedded

in let/in blocks. They will mostly be fine, but sometimes a

function in a let/in block will be omitted.

EXAMPLES

--------

Imports

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Imported modules are tagged, and their role is "imported", not "def".

Types, functions, etc which are exposed via imported module have their

role as "exposed".

Exposed items are marked as being in the scope of their own module,

not the module that's doing the importing.

"input.elm"

.. code-block:: Elm

module SomeMod exposing (..)

import MyMod exposing

( map

, Maybe

, Result(..)

, MyList(Empty)

)

"output.tags"

with "--options=NONE -o - --sort=no --extras=+r --fields=+r input.elm"

.. code-block:: tags

SomeMod input.elm /^module SomeMod exposing (..)$/;" m roles:def

MyMod input.elm /^import MyMod exposing$/;" m roles:imported

map input.elm /^ ( map$/;" f module:MyMod roles:exposed

Maybe input.elm /^ , Maybe$/;" t module:MyMod roles:exposed

Result input.elm /^ , Result(..)$/;" t module:MyMod roles:exposed

MyList input.elm /^ , MyList(Empty)$/;" t module:MyMod roles:exposed

Empty input.elm /^ , MyList(Empty)$/;" c type:MyMod.MyList roles:exposed

Namespaces

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Namespaces are tagged and their role is "def".

"input.elm"

.. code-block:: Elm

module AMod exposing (..)

import MyImport as NSpace exposing (impFunc)

"output.tags"

with "--options=NONE -o - --sort=no --extras=+r --fields=+r input.elm"

.. code-block:: tags

AMod input.elm /^module AMod exposing (..)$/;" m roles:def

NSpace input.elm /^import MyImport as NSpace exposing (impFunc)$/;" n module:AMod roles:def moduleName:MyImport

MyImport input.elm /^import MyImport as NSpace exposing (impFunc)$/;" m roles:imported

impFunc input.elm /^import MyImport as NSpace exposing (impFunc)$/;" f module:MyImport roles:exposed

Type names

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Constructors top level functions will have type names.

"input.elm"

.. code-block:: Elm

funcA : Int -> Int

funcA a = a + 1

type B

= B1Cons

{ x : Float

, y : Float

}

| B2Cons String Integer

| B3Cons

"output.tags"

with "--options=NONE -o - --sort=no --extras=+r --fields=+r input.elm"

.. code-block:: tags

funcA input.elm /^funcA a = a + 1$/;" f typeref:typename:Int -> Int roles:def

B input.elm /^type B$/;" t roles:def

B1Cons input.elm /^ = B1Cons$/;" c type:B typeref:typename:{ x : Float , y : Float } -> B roles:def

B2Cons input.elm /^ | B2Cons String Integer$/;" c type:B typeref:typename:String -> Integer -> B roles:def

B3Cons input.elm /^ | B3Cons$/;" c type:B typeref:typename:B roles:def

Function parameter lists

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Function parameter lists can be extracted into the tags file

signature field. They are not really function signatures, but

it's the closest concept available in ctags.

Use "--fields=+S".

.. code-block:: Elm

funcA a1 a2 =

a1 + a2

"output.tags"

with "--sort=no --extras=+r --fields=+rS"

.. code-block:: tags

funcA input.elm /^funcA a1 a2 =$/;" f signature:a1 a2 roles:def

KNOWN LIMITATIONS

-----------------

The ctags signature field is used for function parameter lists, even

though it's not an idea field. See above.

Elm requires all statements at the same logical level to have the

same indentation. If there is additional indentation that line is part

of the previous one. Therefore without over-complicating the

PEG parser we have the following limitations...

Sometimes functions in let/in blocks will be omitted.

Functions in let/in blocks will be marked as being in the scope of their

outer function, regardless of how deeply nested the let/in block is.

Functions in let/in blocks won't have type names.

SEE ALSO

--------

ctags(1), ctags-client-tools(7)