Record

Introduction #

Module to work, define and import records.

Records are simply tuples where the first element is an atom:

iex> Record.record? {User, "john", 27}
true

This module provides conveniences for working with records at compilation time, where compile-time field names are used to manipulate the tuples, providing fast operations on top of the tuples compact structure.

In Elixir, records are used mostly in two situations:

  1. to work with short, internal data
  2. to interface with Erlang records

The macros defrecord/3 and defrecordp/3 can be used to create records while extract/2 can be used to extract records from Erlang files.

Types

Types can be defined for tuples with the record/2 macro (only available in typespecs). Like with the generated record macros it will expand to a tuple.

defmodule MyModule do
  require Record
  Record.defrecord :user name: "john", age: 25

  @type user :: record(:user, name: String.t, age: integer)
  # expands to: `@type user :: {:user, String.t, integer}`
end
Source

Macros #

defrecord(name, tag \\ nil, kv)

(macro)

Defines a set of macros to create and access a record.

The macros are going to have name, a tag (which defaults) to the name if none is given, and a set of fields given by kv.

Examples

defmodule User do
  require Record
  Record.defrecord :user, [name: "meg", age: "25"]
end

In the example above, a set of macros named user but with different arities will be defined to manipulate the underlying record:

# To create records
record = user()        #=> {:user, "meg", 25}
record = user(age: 26) #=> {:user, "meg", 26}

# To get a field from the record
user(record, :name) #=> "meg"

# To update the record
user(record, age: 26) #=> {:user, "meg", 26}

# Convert a record to a keyword list
user(record) #=> [name: "meg", age: 26]

By default, Elixir uses the record name as the first element of the tuple (the tag). But it can be changed to something else:

defmodule User do
  require Record
  Record.defrecord :user, User, name: nil
end

require User
User.user() #=> {User, nil}

defrecordp(name, tag \\ nil, kv)

(macro)

Same as defrecord/3 but generates private macros.

extract(name, opts)

(macro)

Extracts record information from an Erlang file.

Returns a quoted expression containing the fields as a list of tuples. It expects the record name to be an atom and the library path to be a string at expansion time.

Examples

iex> Record.extract(:file_info, from_lib: "kernel/include/file.hrl")
[size: :undefined, type: :undefined, access: :undefined, atime: :undefined,
 mtime: :undefined, ctime: :undefined, mode: :undefined, links: :undefined,
 major_device: :undefined, minor_device: :undefined, inode: :undefined,
 uid: :undefined, gid: :undefined]

record?(data)

(macro)

Checks if the given data is a record.

This is implemented as a macro so it can be used in guard clauses.

Examples

iex> record = {User, "john", 27}
iex> Record.record?(record)
true
iex> tuple = {}
iex> Record.record?(tuple)
false

record?(data, kind)

(macro)

Checks if the given data is a record of kind.

This is implemented as a macro so it can be used in guard clauses.

Examples

iex> record = {User, "john", 27}
iex> Record.record?(record, User)
true