docs: further improvements to docs in general

README.md

@@ -37,6 +37,13 @@ city(["BRA", "USA"], 4; level=:country_code)
 #  "São Paulo"
 #  "Rio de Janeiro"
 
+address(["BRA", "USA", "BRA", "USA"]; level = :country_code)
+# 4-element Vector{String}:
+#  "Avenida Paulo Lombardi 1834, Ba" ⋯ 25 bytes ⋯ "84-514, Porto Alegre-RS, Brasil"
+#  "Abgail Smith Alley, Los Angeles" ⋯ 42 bytes ⋯ "ornia, United States of America"
+#  "Avenida Tomas Lins 4324, (Apto " ⋯ 23 bytes ⋯ "orocaba - 89457-346, SP, Brasil"
+#  "South-side Street 1st Floor, Li" ⋯ 52 bytes ⋯ "as-AR, United States of America"
+
 
 my_custom_template = ImpostorTemplate([:firstname, :surname, :country_code, :state, :city]);
 

docs/src/api_reference.md

@@ -1,12 +1,40 @@
 # API Reference
 
+```@contents
+Pages = ["api_reference.md"]
+```
+
+---------------
+
+## Generator-Functions
 
 ```@index
 Pages = [
     "providers/finance.md",
     "providers/identity.md",
     "providers/localization.md",
-    "core/utilities.md",
+]
+Depth = 1
+Order = [:function]
+```
+
+## Templatization
+
+```@index
+Pages = [
+    "utilities/impostor_template.md",
+    "utilities/templatization.md",
+    "utilities/utility_functions.md",
+]
+Depth = 1
+Order = [:function]
+```
+
+## Utility Functions
+
+```@index
+Pages = [
+    "utilities/utility_functions.md",
 ]
 Depth = 1
 Order = [:function]

docs/src/developer_guide/quick_tour.md

@@ -69,7 +69,7 @@ src/data/
 In the structure above:
 - `provider` encapsulates the associated *Provider*, *e.g.* Localization
 - `content` stores the `.csv` files for a given *Content*, *e.g.* state codes. Each `.csv` content file is named after the locale it refers to.
-- `HEADER.txt` is a text file storing exclusively names of columns for all files stored in the `src/data/<provider>/<content>/` directory, one column name per line. This file ensures column naming consistency across all locales and prevents individual files from needlessly repeating the same column names. For that reason, every `.csv` file **must contain only the associated *data*, leaving headers for the respective `HEADER.txt` files**.
+- `HEADER.txt` is a text file storing exclusively names of columns for all files stored in the `src/data/<provider>/<content>/` directory, one column name per line. This file ensures column naming consistency across all locales and prevents individual files from needlessly repeating the same column names. For that reason, every `.csv` file **must contain only the associated *data*, leaving *headers* for the respective `HEADER.txt` files**.
 
 The interface between the data file structure shown above and the generator functions is stablished
 by the [`Impostor._load!`](@ref) method, which serves as a single point of access to all information
@@ -95,6 +95,10 @@ Impostor._load!("localization", "state", ["en_US", "pt_BR"])
     once per session. This functionality is aided by the functions present in the
     [Utility Function](../utilities/utility_functions.md) page.
 
+Once loaded, the data is manipulated according to the needs of the particular generator-function
+and always returned though the [`Impostor.coerse_string_type`](@ref) function which output
+formatting consistency.
+
 ## Adding New Data
 
 In order to add new data files, contents or providers, carefully follow the same directory structure

src/core/utils.jl

@@ -35,12 +35,32 @@ Receive an alphanumeric template string (e.g. `"^^^-####"`) and generate a strin
 - `'='` chars by random uppercase or lowercase letters between a-z|A-Z.
 
 Optionally, provide `numbers` to fill the `'#'` placeholders in `template`; or `letters` to fill
-`^`,`_` or `=` placeholders. Note that if the length of `letters` or `numbers` is smaller than
-the number of placeholders in each category, the remaining placeholders will be randomly filled
-according to the character in `template`.
+`'^'`,`'_'` or `'='` placeholders. Note that if the length of `letters` or `numbers` is smaller
+than the number of placeholders in each category, the remaining placeholders will be randomly
+filled according to the character in `template`.
 
 # Examples
 ```@repl
+julia> render_alphanumeric("####")
+"6273"
+
+julia> render_alphanumeric("123-####-AAA")
+"123-5509-AAA"
+
+julia> render_alphanumeric("__-^^-==-ZZZ123")
+"vw-CX-fA-ZZZ123"
+
+julia> render_alphanumeric("__-^^-==-ZZZ###"; numbers = "12345")
+"qu-RT-St-ZZZ123"
+
+julia> render_alphanumeric("__-^^-==-ZZZ###"; letters = "AABBCCDD")
+"AA-BB-CC-ZZZ427"
+
+julia> render_alphanumeric("__-^^-==-ZZZ###"; letters = "AABBCCDD", numbers = "12345")
+"AA-BB-CC-ZZZ123"
+
+julia> render_alphanumeric("_______"; letters = "abc")
+"abcomhd"
 ```
 """
 function render_alphanumeric(template::AbstractString; numbers = nothing, letters = nothing) :: String
@@ -79,13 +99,13 @@ specifies numbers between 200 and 399).
 julia> render_alphanumeric_range("4#####")
 "412345"
 
-julia> render_alphanumeric_range("34####;37####")  # will select 34#### or 37####
+julia> render_alphanumeric_range("34####;37####")  # selects 34#### or 37####
 "349790"
 
 julia> render_alphanumeric_range("51####:55####")
 "532489"
 
-julia> render_alphanumeric_range("2221##:2720##;51####:55####")  # will select 2221##:2720## or 51####:55####
+julia> render_alphanumeric_range("2221##:2720##;51####:55####")  # selects 2221##:2720## or 51####:55####
 "250000"
 ```
 """
@@ -112,10 +132,13 @@ end
     render_template(template, reference_dfrow; locale) :: String
 
 Materialize a given pre-defined template by splitting `template` into tokens; each token *may*
-by associated to a generator-function exported by Impostor. For practicality, tokens not exported
-by Impostor (see example below) are just repeated in the materialized template since it is not
-possible for Impostor to distinguish between badly spelled generator functions and raw text
-which should be present in materialized template.
+by associated to a generator-function exported by Impostor. Tokens associated to generator-functions
+are excpected to have the excact same spelling as their generator-function correspondents (*e.g.*
+the token "address" is associated to the generator-function `address`).
+
+For practicality, tokens not exported by Impostor (see example below) are just repeated in the
+materialized template since it is not possible for Impostor to distinguish between badly spelled
+generator functions and raw text which should be present in materialized template.
 
 Optionally, provide a `reference_dfrow` with column names which may be referenced by
 tokens in `template`. This is useful in the context of hierarchical data manipulation

src/providers/finance.jl

@@ -221,7 +221,6 @@ function credit_card_number(n::Integer = 1; formatted::Bool=false, kwargs...)
         selected_vendor_dfrow = rand(eachrow(credit_card_references))
         push!(generated_cards, _generate_credit_card_number(selected_vendor_dfrow, formatted))
     end
-
     return generated_cards |> coerse_string_type
 end
 
@@ -234,7 +233,6 @@ function credit_card_number(options::Vector{<:AbstractString}, n::Integer; forma
         selected_vendor_dfrow = rand(eachrow(credit_card_references))
         push!(generated_cards, _generate_credit_card_number(selected_vendor_dfrow, formatted))
     end
-
     return generated_cards |> coerse_string_type
 end
 
@@ -249,7 +247,6 @@ function credit_card_number(mask::Vector{<:AbstractString}; formatted::Bool=fals
         selected_vendor_dfrow = filter(r -> r[:credit_card_vendor] == m, credit_card_references)[1, :]
         push!(generated_cards, _generate_credit_card_number(selected_vendor_dfrow, formatted))
     end
-
     return generated_cards |> coerse_string_type
 end
 

src/providers/identity.jl

@@ -69,7 +69,7 @@ The valid options values for `options` and `mask` are:
 - `locale::Vector{String}`: locale(s) from which entries are sampled. If no `locale` is provided, the current session locale is used.
 
 # Example
-```repl
+```@juliarepl
 julia> prefix(["female", "male", "female"])
 3-element Vector{String}:
 "Ms."
@@ -125,7 +125,7 @@ The valid options values for `options` and `mask` are:
 - `locale::Vector{String}`: locale(s) from which entries are sampled. If no `locale` is provided, the current session locale is used.
 
 # Examples
-```repl
+```@juliarepl
 julia> firstname(["F"], 4)
 4-element Vector{String}:
 "Sophie"
@@ -207,7 +207,7 @@ The valid options values for `options` and `mask` are:
 - `locale::Vector{String}`: locale(s) from which entries are sampled. If no `locale` is provided, the current session locale is used.
 
 # Examples
-```julia
+```@juliarepl
 julia> Impostor.complete_name(["F"], 5)
 5-element Vector{String}:
 "Melissa Sheffard"

src/providers/localization.jl

@@ -42,8 +42,7 @@ Generate `n` or `length(mask)` country names.
 - `mask::Vector{<:AbstractString}`: mask vector with element-wise option restrictions.
 
 # Kwargs
-- `level::Symbol = :country_code`: Level of values in `options` or `mask` when using option-based or mask-based generation. Valid `level` values are:
-    - `:country_code`
+- `level::Symbol = :country_code`: Level of values in `options` or `mask` when using option-based or mask-based generation.
 - `locale::Vector{String}`: locale(s) from which entries are sampled. If no `locale` is provided, the current session locale is used.
 """
 function country(n::Integer = 1; locale = session_locale())
@@ -93,8 +92,7 @@ Generate `n` or `length(mask)` country offiical names.
 - `mask::Vector{<:AbstractString}`: mask vector with element-wise option restrictions.
 
 # Kwargs
-- `level::Symbol = :country_code`: Level of values in `options` or `mask` when using option-based or mask-based generation. Valid `level` values are:
-    - `:country_code`
+- `level::Symbol = :country_code`: Level of values in `options` or `mask` when using option-based or mask-based generation.
 - `locale::Vector{String}`: locale(s) from which entries are sampled. If no `locale` is provided, the current session locale is used.
 """
 function country_official_name(n::Integer = 1; locale = session_locale())
@@ -150,8 +148,7 @@ Generate `n` or `length(mask)` country codes.
 - `mask::Vector{<:AbstractString}`: mask vector with element-wise option restrictions.
 
 # Kwargs
-- `level::Symbol = :country_code`: Level of values in `options` or `mask` when using option-based or mask-based eneration. Valid `level` values are:
-    - `:country_code`
+- `level::Symbol = :country_code`: Level of values in `options` or `mask` when using option-based or mask-based eneration.
 - `locale::Vector{String}`: locale(s) from which entries are sampled. If no `locale` is provided, the current session locale is used.
 """
 function country_code(n::Integer = 1; locale = session_locale())
@@ -334,11 +331,7 @@ end
 - `mask::Vector{<:AbstractString}`: mask vector with element-wise option restrictions.
 
 # Kwargs
-- `level::Symbol = :district_name`: Level of values in `options` or `mask` when using option-based or mask-based eneration. Valid `level` values are:
-    - `:country_code`
-    - `:state_code`
-    - `:city_name`
-    - `:district_name`
+- `level::Symbol = :district_name`: Level of values in `options` or `mask` when using option-based or mask-based eneration.
 - `locale::Vector{String}`: locale(s) from which entries are sampled. If no `locale` is provided, the current session locale is used.
 """
 function district(n::Integer = 1; locale = session_locale())
@@ -428,13 +421,19 @@ end
     address(options::Vector{<:AbstractString}, n::Integer = 1; level::Symbol, kws...)
     address(mask::Vector{<:AbstractString}; level::Symbol, kws...)
 
+Generate `n` or `length(mask)` addresses based on `options` or `mask` according to the required
+`level`. For example, let `level = :country_code` and `options` be the required country codes to
+generate addresses for, *e.g.* `["BRA", "USA"]`, the expected output will contain only addresses
+(in their specific formats) for location in Brazil (`"BRA"`) and the United States (`"USA"`).
+Other values may be passed as `level`.
+
 # Parameters
 - `n::Integer = 1`: number of addresses to generate.
 - `options::Vector{<:AbstractString}`: vector with options restricting the possible values generated.
 - `mask::Vector{<:AbstractString}`: mask vector with element-wise option restrictions.
 
 # Kwargs
-- `level::Symbol = :state_code`: option level to be used when using option-based generation.
+- `level::Symbol = :state_code`: option level to be used when using option and mask-based generation.
 """
 function address(n::Integer = 1; locale = session_locale())
     addresses = String[]