Msutils.Data (mscmp_syst_utils_data v0.1.0)

This is a set of utilities for working with data which is generally useful across components.

Currently included in these utilities are:

  • ETS operations

    Functions wrap some typical ETS operations so that they return standard result tuples.

  • Changeset validators

    Common validation functions which can be used to validate changesets across Components.

Note

Changeset Validators do not check their opts parameter for validity. This is expected to be handled by the caller prior to calling these functions. See the Msutils.Data.common_validator_options/1 macro for more information on adding the standard options which can be used to validate changesets.

Summary

Changeset Validators

validate_display_name(changeset, opts)

Changeset validation ensuring that the display_name field is valid and meets minimum and maximum length requirements.

validate_external_name(changeset, opts)

Changeset validation ensuring that the external_name field is valid and meets minimum and maximum length requirements.

validate_internal_name(changeset, opts)

Changeset validation ensuring that the internal_name field is valid and meets minimum and maximum length requirements.

validate_syst_defined_changes(changeset, prohibited_fields)

Changeset validation ensuring that, if the record is set as syst_defined, the prohibited fields are not changed.

validate_user_description(changeset, opts)

Changeset validation ensuring that the user_description field is set if required and allowed and meets minimum and maximum length requirements.

Ets Operations

ets_delete(table, key)

Deletes an entry from an ETS table.

ets_insert(table, data)

Inserts data into an ETS table.

ets_lookup_element(table, key, element_index)

Looks up an element in an ETS table by key and position.

ets_update_element(table, key, updated_data)

Updates an element in an ETS table.

Functions

common_validator_options(selected_options)

Returns a NimbleOptions struct with the requested common validator options for use with the Changeset validation functions from the Msutils.Data module.

Changeset Validators

validate_display_name(changeset, opts)

@spec validate_display_name(Ecto.Changeset.t(), Keyword.t()) :: Ecto.Changeset.t()

Changeset validation ensuring that the display_name field is valid and meets minimum and maximum length requirements.

Parameters

  • changeset - an Ecto.Changeset struct to be validated.

  • opts - options which configure the validation checks of the functions.

Options

  • :min_display_name_length (pos_integer/0) - Sets the minimum grapheme length of display_name values. The default value is 6.

  • :max_display_name_length (pos_integer/0) - Sets the maximum grapheme length of display_name values. The default value is 64.

validate_external_name(changeset, opts)

@spec validate_external_name(Ecto.Changeset.t(), Keyword.t()) :: Ecto.Changeset.t()

Changeset validation ensuring that the external_name field is valid and meets minimum and maximum length requirements.

Parameters

  • changeset - an Ecto.Changeset struct to be validated.

  • opts - options which configure the validation checks of the functions.

Options

  • :min_external_name_length (pos_integer/0) - Sets the minimum grapheme length of external_name values. The default value is 2.

  • :max_external_name_length (pos_integer/0) - Sets the maximum grapheme length of external_name values. The default value is 64.

validate_internal_name(changeset, opts)

@spec validate_internal_name(Ecto.Changeset.t(), Keyword.t()) :: Ecto.Changeset.t()

Changeset validation ensuring that the internal_name field is valid and meets minimum and maximum length requirements.

Parameters

  • changeset - an Ecto.Changeset struct to be validated.

  • opts - options which configure the validation checks of the functions.

Options

  • :min_internal_name_length (pos_integer/0) - Sets the minimum grapheme length of internal_name values. The default value is 6.

  • :max_internal_name_length (pos_integer/0) - Sets the maximum grapheme length of internal_name values. The default value is 64.

validate_syst_defined_changes(changeset, prohibited_fields)

@spec validate_syst_defined_changes(Ecto.Changeset.t(), [atom()]) ::
  Ecto.Changeset.t()

Changeset validation ensuring that, if the record is set as syst_defined, the prohibited fields are not changed.

Parameters

  • changeset - an Ecto.Changeset struct to be validated.

  • prohibited_fields - a list of field names for which changes are prohibited if the record is set as syst_defined.

validate_user_description(changeset, opts)

@spec validate_user_description(Ecto.Changeset.t(), Keyword.t()) :: Ecto.Changeset.t()

Changeset validation ensuring that the user_description field is set if required and allowed and meets minimum and maximum length requirements.

Parameters

  • changeset - an Ecto.Changeset struct to be validated.

  • opts - options which configure the validation checks of the functions.

Options

  • :min_user_description_length (pos_integer/0) - Sets the minimum grapheme length of user_description values. The default value is 6.

  • :max_user_description_length (pos_integer/0) - Sets the maximum grapheme length of user_description values. The default value is 1000.

Ets Operations

ets_delete(table, key)

@spec ets_delete(:ets.table(), term()) :: :ok | {:error, Mserror.DataUtilsError.t()}

Deletes an entry from an ETS table.

Wraps the ETS :ets.delete/2 function.

Parameters

  • table - the ETS table to delete from
  • key - the key of the entry to delete

Returns

  • :ok - if the deletion was successful
  • {:error, Mserror.DataUtilsError.t()} - if there was an error during deletion

ets_insert(table, data)

@spec ets_insert(:ets.table(), term()) :: :ok | {:error, Mserror.DataUtilsError.t()}

Inserts data into an ETS table.

In this we wrap the ETS :ets.insert/2 function in a function that returns an Mserror.DataUtilsError if there is an error.

Parameters

  • table - the ETS table to insert the data into.

  • data - the data to insert into the ETS table.

Returns

  • :ok - if the data was successfully inserted into the ETS table.

  • {:error, Mserror.DataUtilsError.t()} - if there was an error inserting the data into the ETS table.

ets_lookup_element(table, key, element_index)

@spec ets_lookup_element(:ets.table(), term(), non_neg_integer()) ::
  {:ok, term()} | {:error, Mserror.DataUtilsError.t()}

Looks up an element in an ETS table by key and position.

Wraps the ETS :ets.lookup_element/3 function, returning a result tuple.

Parameters

  • table - the ETS table to look up the element in
  • key - the key to look up
  • element_index - the position of the element to return

Returns

  • {:ok, term()} - the element was found at the specified position
  • {:error, Mserror.DataUtilsError.t()} - if there was an error during lookup

ets_update_element(table, key, updated_data)

@spec ets_update_element(:ets.table(), term(), term()) ::
  :ok | {:error, Mserror.DataUtilsError.t()}

Updates an element in an ETS table.

Wraps the ETS :ets.update_element/3 function.

Parameters

  • table - the ETS table to update
  • key - the key of the element to update
  • updated_data - the new data to set

Returns

  • :ok - if the update was successful
  • {:error, Mserror.DataUtilsError.t()} - if there was an error during update

Functions

common_validator_options(selected_options)

(macro) 
@spec common_validator_options(
  selected_options :: [Msutils.Data.Types.common_validators()]
) ::
  Macro.t()

Returns a NimbleOptions struct with the requested common validator options for use with the Changeset validation functions from the Msutils.Data module.

The common validator options establish cross-Component standards for data limits such as minimum and maximum lengths commonly used data fields. In many ways, these options act as constants for common Changeset validations.

Parameters

  • selected_options - selects the desired options from the common validator option definitions. This is in the form of a list of the desired options.

Select Options

The following are accepted for selected options:

  • :internal_name

  • :display_name

  • :external_name

  • :user_description