/ 
oEdtk-2.1131
/ oEdtk::Config

NAME

oEdtk::Config - read the oEdtk configuration (edtk.ini)

SYNOPSIS

use oEdtk::Config qw(config_read get_ini_path);

my $cfg = config_read('EDTK_DB');
my $dsn = $cfg->{'EDTK_DBI_DSN'};

DESCRIPTION

The configuration reader for the whole toolkit. It locates the edtk.ini file (with a hostname redirect loop), merges the DEFAULT, ENVDESC, the requested and the hostname sections into one hash, adds EDTK_HOST, USERNAME, EDTK_PRGNAME and EDTK_PRGPATH, and expands $name references found inside the values. Each call returns a fresh hash.

The parsing is memoised by the file's (path, mtime, size); set OEDTK_CONFIG_NOCACHE=1, or pass a trailing options hashref with cache set to 0, to force a re-parse.

FUNCTIONS

config_read

my $cfg = config_read(@sections);
my $cfg = config_read([@sections], $app);

Read the configuration and return a hash reference of merged sections. @sections is the list of extra sections to merge (DEFAULT and ENVDESC are always merged), optionally given as an array reference together with an application name that sets EDTK_PRGNAME.

get_ini_path

my $path = get_ini_path();

Return the path of the ini file used by the last config_read call.

The private helpers _ini_sections and _section_val, and the read_hash accessor, back the caching, the DEFAULT fallback and the $name expansion; they are not part of the public API.

CONFIGURATION

The lexicon of the keys the shipped template tplate.edtk.ini sets, by section, with what each drives and the values that change behaviour. A $name value (for example $EDTK_DIR_BASE) is expanded by config_read; a key with no listed values is free-form.

The [DEFAULT] section

iniEdtk

Redirect the read to another ini file; also read from the host-name section. The literal local disables the redirect.

EDTK_CORP

Corporation name printed in the generated documents.

EDTK_DICO

Main dictionary (accents, entities) loaded by the text layer.

EDTK_DICO_POST

Postal-code dictionary.

EDTK_SNIP_ADDR

Address-snipping dictionary.

EDTK_SNIP_RATE

Address-snipping rate; 0 disables snipping.

EDTK_LANG

Language, i.e. the dictionary section to read, such as EN or FR.

EDTK_LOG_LVL

Log sensitivity read by oEdtk::logger (its $LOGGERLEVEL); 4 is the mainline default.

The [ENVDESC] section

Directories, file stems, extensions and timeouts. Every path is written relative to EDTK_DIR_BASE (default $EDTK_PRGPATH, the running script's directory) and to EDTK_PRGNAME (injected at runtime).

EDTK_DIR_BASE

Root of the whole path tree; defaults to $EDTK_PRGPATH.

EDTK_DIR_APP, EDTK_DIR_SCRIPT

Application root and the per-application script directory.

EDTK_DIR_CONFIG

Configuration files and dictionaries.

EDTK_DIR_APPTMP, EDTK_DIR_DB

Temporary work area and database files.

EDTK_DIR_DATA_IN

Input flux directory.

EDTK_DIR_LIB, EDTK_DIR_TMPLATE

Shared libraries and document templates.

EDTK_DIR_OUTMNGR, EDTK_DIR_EDOCMNGR, EDTK_DIR_DOCLIB

Output, EDMS transit and document library.

EDTK_DIR_LOG, EDTK_DIR_DOCSCRIPT

Logs and the per-application document area.

EDTK_DOCLIB_LOCK

Document-library lock file.

EDTK_FDATAIN, EDTK_FDATAOUT, EDTK_FDATWORK

Input, output and work file stems.

EDTK_TYPE_ENV

Environment label, prefixed to mail subjects by oEdtk::Messenger; Dev (the default), Test or Production.

EDTK_OUTMNGR_MERGE

Whether the outgoing-routeur output is merged; no (the default) or yes.

EDTK_PRGNAME

Running program name; injected by config_read, not normally set.

EDTK_VCS_LOCATION

Version-control location recorded in outputs.

EDTK_WATERMARKTEXT

Watermark stamped on generated documents.

EDTK_BIN_PERL

Path to the Perl interpreter used when bundling.

EDTK_EXT_COMP_OMGR

Extension of the routeur-composed files; omgr.

EDTK_EXT_COMPO

Extension of a composed file; defaults to $EDTK_EXT_LATEX.

EDTK_EXT_DATA, EDTK_EXT_DEFAULT

Data-file extension (DAT) and default extension ($EDTK_EXT_PDF).

EDTK_EXT_EXCEL, EDTK_EXT_LATEX, EDTK_EXT_PCL, EDTK_EXT_PDF, EDTK_EXT_PERL, EDTK_EXT_WORK

Extension per artefact type: xls, tex, pcl, pdf, pl, txt.

EDTK_WAITRUN

Seconds to wait for a child process; default 8.

EDTK_XLS_MAX_ROW

Maximum rows read from an XLS sheet; default 30000.

The [EDTK_DB] section

Database DSNs, credentials, retention, primary-key mode and bulk-load tuning.

EDTK_DBI_DSN (with _USER, _PASS)

Active DSN and credentials of the main database.

EDTK_DBI_DSN_BAK (with _USER, _PASS)

DSN and credentials of the backup database.

EDTK_DBI_PARAM

DSN of the parameter database.

EDTK_DBI_ACQUIT, EDTK_DBI_DISTRIB, EDTK_DBI_DISTRIB_STATS, EDTK_DBI_OUTMNGR, EDTK_DBI_OUTMNGR_STATS, EDTK_DBI_TRACKING

Logical table names of the acquittal, distribution, distribution-stats, outgoing, outgoing-stats and tracking tables.

EDTK_MAX_USER_KEY

Number of user tracking keys accepted; 10 in the mainline, 5 in the fork.

EDTK_TRACKING_KEYS

Comma-separated extra tracking columns.

EDTK_TRACK_MODE

Tracking back-end: SQLite (the default) or none to switch tracking off.

EDTK_TRACK_SIG

Which signals the tracker catches: warn (all) or halt (die only); no disables.

EDTK_DB_MAX_DAYS_KEPT, EDTK_DB_MAX_DAYS_KEPT_STATS, EDTK_DB_MAX_DAYS_TRACKED, EDTK_DB_MAX_DAYS_AGREGED

Retention in days of the main, stats, tracking and aggregated tables; 2, 100, 400 and 600.

EDTK_DB_CHECK_AUTO

Enables the automatic consistency check; NO (the default) or YES.

EDTK_DB_CHECK_MONTH_DAY

Day of month for the automatic check; default 15.

EDTK_DB_PK_IDJOB

Keep ed_idjob in the INDEX primary key: yes (mainline behaviour), any other value builds the schema without it (fork).

EDTK_DB_IDJOB_DEFAULT

Value written to ed_idjob when the key is kept; left empty until the S51 gate.

EDTK_DB_FetchHashKeyName

Case-folding of the fetched column names (FetchHashKeyName); NAME_uc by default.

EDTK_DB_COPY_ENCODING

Source encoding of the CSV bulk-load path: UTF8 declares a file already in UTF-8 so it is not double-encoded, empty keeps the legacy Latin-1 behaviour.

EDTK_DB_DEFER_INDEX_RATIO, EDTK_DB_DEFER_INDEX_MIN_ROWS

Opt-in index-deferral policy of the PostgreSQL bulk load; empty means off, and when set the defaults are 0.1 and 10000.

EDTK_DB_BURST_MO

ELT staging threshold in MiB on PostgreSQL: 50 by default, 0 disables the path, and an empty or invalid value falls back to 50.

The [EDTK_STATS] section

EDTK_DBI_STATS, EDTK_DSN_STATS (with _USER, _PASS)

DSN and credentials of the statistics database; they default to the main DSN.

EDTK_STATS_TRACKING, EDTK_STATS_OUTMNGR, EDTK_STATS_DISTRIB, EDTK_STATS_ACQUIT

Statistics table names.

EDTK_STATS_MANUFACT

Manufacturer filter of the outgoing statistics: a comma- or space-separated list of ED_IDMANUFACT codes, empty (the default) reports them all.

EDTK_CSV_HEADER_METADATA, EDTK_CSV_HEADER_DISTRIB

Column order of the CSV exports.

EDTK_STATS_SQL00 through EDTK_STATS_SQL12, EDTK_STATS_SQL90

Named canned SQL queries of the statistics panel; EDTK_STATS_SQL90 may name a .sql file ($EDTK_PRGPATH/sql/...).

The [MAIL] section

EDTK_MAIL_TO, EDTK_MAIL_TST

Production and test recipients.

EDTK_MAIL_SENDER

Envelope sender.

EDTK_MAIL_SUBJ

Subject template; %date and %time are substituted.

EDTK_MAIL_SMTP

SMTP relay host.

EDTK_MAIL_REFER, EDTK_MAIL_OMGR

Body templates of the recap and outgoing mail.

EDTK_MAIL_LIST_1 through EDTK_MAIL_LIST_5

Named distribution lists.

The [COMPO] section

The LaTeX back-end.

EDTK_BIN_COMPO

Directory holding the TeX binaries.

EDTK_COMPO

The composition command, e.g. pdflatex -halt-on-error.

EDTK_COMPO_CMD_PDF, EDTK_COMPO_CMD_DVI, EDTK_COMPO_CMD_DVIPDF

Per-format composition commands.

EDTK_COMPO_LIB

Path to the edtkdoc.cls class file.

EDTK_FILIERES_RECTO_VERSO

Channels whose index is padded to an even page count; empty means none.

EDTK_CMD_RUN_BG_NOWAIT

Non-blocking background composition; empty is blocking, a set value is non-blocking.

EDTK_LINE_CUTOFF

Maximum number of characters before a newline in generated documents; empty falls back to 120.

EDTK_RP_KILL_NON_LATIN

Strip the non-Latin-1 (DEL and C1) characters from input records; off by default.

EDTK_IDLDOC_FORMAT

Document batch-id format: UUID (the default, a 36-character UUID), or LEGACY / old (the 16-digit id, case-insensitive).

EDTK_COMPO_ASYNC

Asynchronous composition; commented out in the template, yes or no.

The [EDOCMNGR] section

EDMS/GED indexing and transfer.

EDMS_INDEX_COLS

Columns of the EDMS index.

EDMS_DATE_FORMAT

Date format used in the index; %Y/%m/%d.

EDMS_IDX_FORMAT

Index format: DOCUBASE (the default) or SCOPMASTER.

EDMS_IDX_HEADER

Index header line, ;-separated.

EDMS_ACTIVATE_HEADER_ALFRESCO

Emit the Alfresco header line; YES or NO.

EDMS_FTP_HOST, EDMS_FTP_PORT, EDMS_FTP_USER, EDMS_FTP_PASS

FTP(S) transfer target.

EDMS_FTP_DIR_IDX, EDMS_FTP_DIR_DOCS

Remote index and document directories.

Base URL of the document link.

EDMS_HTML_HOST

HTML host used to build the lookup URL.

EDMS_URL_LOOKUP

Lookup URL template, with %s and %d placeholders.

EDMS_BIN_GS, EDMS_BIN_PDFTK

Ghostscript and pdftk binaries.

The [SERVICES] section

Optional network services. All are inactive by default: an empty value keeps the mainline behaviour.

NWS_EMAILING_URI

E-mailing service base URL; empty means unused (/emails is appended).

EMAILING_TEMPLATE, EMAILING_USER_AGENT

E-mailing template name and User-Agent string; empty falls back to each client's shipped default.

KEYCLOAK_URL, KEYCLOAK_CLIENT_ID, KEYCLOAK_SECRET_ID

Keycloak token endpoint and client credentials; all three are required together.

KEYCLOAK_REALM

Keycloak realm path element; empty uses the client's shipped default.

DISSEMINATION_PLAN_URL

Dissemination-plan service URL; empty skips the step.

EDTK_SSL_VERIFY

TLS peer and host-name verification: 1 (the default, safe) or 0 for a service fronted by a private CA.

EDTK_SSL_CA_PATH

CA bundle, a file or a directory; empty uses the system trust store.

EDTK_ACQUIT_API

Named acquittal callable, Module::function; empty means no API acquittal.

EDTK_MAIL_ACQ

Recipients of the acquittal recap report; empty means no report.

APIECM_URL, APIECM_APIKEY_EDITIQUE

ECM API base URL and the static editique API key; empty leaves the ECM injector unusable.

The host-name section

A worked example of an override section, whose name is always uppercase. A section matching uc(hostname()) is merged last, so it wins, and its iniEdtk key can redirect the whole read.

A few keys the code reads are not shipped in the template and stay optional: EDTK_DICO_COUNTRY (the country dictionary), EDTK_DICO_XLAT (LaTeX character translation), EDTK_XML_CATALOG_FILES (XML catalogs, read from the [MAIL] section), EDTK_DB_STORAGE_ENGINE (the MySQL storage engine, MyISAM by default), and EDTK_ENTIRE_YEARS_KEPT / EDTK_STATS_DAYS_FROM (retention and history windows).

AUTHOR

The oEdtk team.