Jump to content

Module:Cronos

From Meta, a Wikimedia project coordination wiki
Module documentation

The Module:Cronos is the core of the Meta:Cronos project and it's the Lua module implementing these templates:

See their related documentation for normal usage from wikitext.

Proceed in this page to discover how to read events using Cronos' public Lua APIs.

Overview

[edit]

The source code of Module:Cronos is object-oriented and with lot of in-line documentation. Read-it.

In short there are some classes:

CronosEvent
whatever event (party, session, hackaton, etc.)
CronosDay
collector of events happening in a specific day
CronosCategory
one for each Event, this is its icon (see phab:T254586)
CronosCalendarContext
unuseful utility class used to store preferences and filters (e.g. Tags)

CronosDay API

[edit]

You can access the data of a single Event from other Lua modules:

-- load the module
local Cronos = require( 'Module:Cronos' )

-- load a single day
local day = Cronos._day( '2019-03-25' )

-- load related events sorted by time
local events = day:getEventsSortedByTime()

-- loop these events
for i, event in pairs( events ) do

	-- examine start date
	mw.logObject( event:getStartDate() )

	-- examine end date
	mw.logObject( event:getEndDate() )

	-- examine its category icon
	mw.logObject( event:getCategory():getIconWikitext() )

	-- examine some other data available in the CronosEvent object
	mw.logObject( event )

end

CronosCategory API

[edit]

You can also obtain other information like a known Category:

-- load the module
local Cronos = require( 'Module:Cronos' )

-- load a single category
local category = Cronos._category( 'libre' )

-- examine its icon
mw.logObject( category:getIconWikitext() )

-- examine its user identifier (e.g. 'libre')
mw.logObject( category.uid )

-- examine its name (e.g. 'Free Software initiatives')
mw.logObject( category.name )

-- examine some other data available in the CronosCategory object
mw.logObject( category )

Other APIs

[edit]

Please look at the source code for everything exported in the p-ackage. The source code is intensively in-line documented.

Questions / Issues

[edit]

For any question or idea feel free to write in the talk page pinging the current maintainer who is User:Valerio Bozzolan.

For any issue feel free to open a new Task in Wikimedia Phabricator with the #WMCH-Cronos Tag and assign it to valerio.bozzolan: Create a Task.

See also

[edit]

---
-- This is the module that auto-generates the [[Meta:Cronos]] monthly calendar
--
-- Thanks to this module we do not need a bot to keep the calendar
-- updated.
--
-- This module does not have any dependency. Please keep this feature.
--
-- Note that this module needs to read some Event-related pages from your wiki.
-- This increases the "Expensive parser function count" by ~40. Anyway, the
-- global limit actually is 500.
--
-- Happy hacking!
--
-- @author [[User:Valerio Bozzolan]]
-- @creation 2019-04-13
-- @see https://phabricator.wikimedia.org/tag/wmch-cronos/
---

---
-- List of well-known categories
--
-- If you add a new Category please add a note in the talk page in order to
-- update the related website.
--
-- Note that the 'com' is expressed as default category in the configuration.
--
-- See:
--   https://phabricator.wikimedia.org/T254586
--
local CRONOS_CATEGORIES = {
	['com'] = { uid = 'com', name = 'Community initiatives', filename = 'File:Wikimedia Community Logo.svg' },
	['dat'] = { uid = 'dat', name = 'Wikidata initiatives', filename = 'File:Wikidata Favicon color.svg' },
	['edu'] = { uid = 'edu', name = 'Wikimedia Education Program', filename = 'File:WikipediaEduBelow.svg' },
	['libre'] = { uid = 'libre', name = 'Free Software and Open Source initiatives', filename = 'File:Heckert GNU white.svg' },
	['osm'] = { uid = 'osm', name = 'OpenStreetMap', filename = 'File:Openstreetmap logo.svg' },
	['glam'] = { uid = 'glam', name = 'Wikimedia GLAM Program', filename = 'File:GLAM logo.png' },
	['wmch'] = { uid = 'wmch', name = 'Wikimedia CH initiatives', filename = 'File:WikimediaCHLogo.svg' },
	['wbg'] = { uid = 'wbg', name = 'West Bengal Wikimedians initiatives', filename = 'File:Logo of West Bengal Wikimedians User Group.svg' },
	['wmf'] = { uid = 'wmf', name = 'Wikimedia Foundation initiatives', filename = 'File:Wikimedia-logo black.svg' },
	['wmno'] = { uid = 'wmno', name = 'Wikimedia Norge initiatives', filename = 'File:Wikimedia Norge-logo svart nb.svg' },
}

-- append a default dummy category
-- please keep this separated from the others for more visibility
CRONOS_CATEGORIES.default = { uid = 'default', name = 'Event', filename = 'File:Wikimedia Community Logo.svg' }

-- Default configuration
local DEFAULT_CONFIG = {

	-- Namespace name for the event pages
	--  e.g. 'Meta' for [[Meta:Cronos/Events/2000-12-31]
	['event_ns'] = 'Meta',

	-- Expected prefix for every Cronos event page
	--  e.g. 'Meta:Cronos/Event/' for [[Meta:Cronos/Events/2000-12-31]
	['event_prefix'] = 'Meta:Cronos/Events/',

	-- Expected French Calendar dataset
	--  See [[Events calendar/events.json]] in Meta-Wikusa i
	--  Set to nil to disable this feature.
	['french_dataset_page'] = 'Events calendar/events.json',

	-- French Calendar home URL or page title
 	-- the French calendar has not a permalink for each event
	-- so these events just link to this homepage
	['french_dataset_url'] = 'Events calendar',

	-- If you have another cute web-Cronos frontend, put the URL here
	['cute_form_url'] = 'https://wmch.toolforge.org/cronos/',

	-- Default timezone
	--  '0': use local wiki timezone
	--  '1': use UTC timezone
	['utc'] = '0',

	-- Default start of the week
	--  '1': week start from Monday
	--  '0': week start from Sunday
	['start_from_monday'] = '1',

	-- How much weeks to be displayed in the calendar as default
	--  Note that if a week is splitted in two Months,
	--  you may get more lines in order to display them.
	['weeks'] = '4',

	-- How much months to shift in the past or in the future as default
	--   '0': Display the current month
	--   '1': Display the next month
	--  '-1': Display the previous month
	--   etc.
	['month_shift'] = '0',

	-- Maximum length of an Event title in bytes before truncating it
	['max_title_len'] = '30',

	-- Choose to have a shorter week name as default
	['short_weekname'] = '0',

	-- Template used to briefly list some events
	-- As default: [[Template:Cronos day brief]]
	-- Arguments:
	--  yyyy year  in 4 digits
	--  mm   month in 2 digits
	--  dd   day   in 2 digits
	['template_day_brief'] = 'Cronos day brief',

	-- Template used to briefly tell something about an event
	-- As default: [[Template:Cronos event brief]]
	-- Arguments:
	--  yyyy
	--  mm
	--  dd
	--  title
	--  when
	--  end
	--  url
	--  editurl
	['template_event_brief'] = 'Cronos event brief',

	-- Template used to display an event in a single line
	-- As default: [[Template:Cronos event brief line]]
	-- Arguments:
	--  yyyy
	--  mm
	--  dd
	--  title
	--  when
	--  end
	--  url
	--  editurl
	['template_event_brief_line'] = 'Cronos event brief line',

	-- how much columns has the above template
	-- this is used to create the last line with some merged-columns
	-- with your tags
	['template_event_brief_line_columns'] = '5',

	-- Template used as header to briefly tell something about an event
	-- As default: [[Template:Cronos event brief line/Head]]
	['template_event_brief_line_head'] = 'Cronos event brief line/Head',

	-- Chips stylesheet
	-- Default to [[Template:Cronos event/chips.css]]
	['chips_stylesheet'] = 'Cronos event/chips.css',

	-- Default Category
	-- See https://phabricator.wikimedia.org/T254586
	['default_category'] = 'default',
}

-- list of all 'MediaWiki:Sunday' etc.
local MW_WEEK_NAMES = {
	'Sunday',
	'Monday',
	'Thursday',
	'Wednesday',
	'Thursday',
	'Friday',
	'Saturday',
}

-- list of all 'MediaWiki:January' etc.
local MW_MONTH_NAMES = {
	'January',
	'February',
	'March',
	'April',
	'May',
	'June',
	'July',
	'August',
	'September',
	'October',
	'November',
	'December',
}

-- this Lua package
local p = {}

-- constants
local SECONDS_IN_DAY = 86400;
local SECONDS_IN_MONTH = SECONDS_IN_DAY * 28 -- Not really :^) it's a lazy hack

-- template used for the heading of the calendar
-- default to [[Template:Cronos month/Head]]
local HEADING_TEMPLATE = 'Cronos month/Head'

-- template used to save/display data about a CronosEvent
-- default to [[Template:Cronos event]]
local EVENT_TEMPLATE = 'Cronos event'

-- this Lua pattern distinguish single events, and the known template arguments
-- name of the [[Template:Cronos event]]
local EVENT_PATTERN = '{{ *[Cc]ronos event'

--- Name of some expected {{Cronos event}} template arguments
-- title: Event title
-- when:  Event start time
-- tags:  Space separated list of Event tags
local EVENT_ARG_ID       = 'id'
local EVENT_ARG_TITLE    = 'title'
local EVENT_ARG_WHEN     = 'when'
local EVENT_ARG_TAGS     = 'tags'
local EVENT_ARG_URL      = 'url'
local EVENT_ARG_WHEN_END = 'end'
local EVENT_ARG_CATEGORY = 'category'
local EVENT_ARG_WHERE    = 'where'
local EVENT_ARG_ABSTRACT = 'abstract'

-- external identifiers
-- https://phabricator.wikimedia.org/T268213
local EVENT_ARG_ID_METAFR   = 'id meta-fr'
local EVENT_ARG_ID_WMF_PHAB = 'id wmf-phab'

-- all the damn external ids
local EVENT_ARG_EXTERNAL_IDS = {
	EVENT_ARG_ID_METAFR,
	EVENT_ARG_ID_WMF_PHAB,	
}

-- current date in raw format
-- to speed up the EventDay:isToday()
local TODAY_RAW = os.date( '%Y-%m-%d' )

---
-- BASE FUNCTIONS
---


---
-- Check if a value is inside an array
--
-- @param  string  needle   String to be searched
-- @param  string  haystack Array of strings
-- @return boolean True if the needle is in the string
local function inArray( needle, haystack )

	-- search the needle in the haystack
	for i, v in pairs( haystack ) do
		if needle == v then
			return true
		end
	end

	return false
end

---
-- Array merge
--
-- Merge the second array in the first one
--
-- @param table first
-- @param table second
local function arrayMerge( first, second )
	for k, v in pairs( second ) do
		first[ #first + 1 ] = v
	end
end

---
-- Array replace
--
-- This somehow emulates the PHP array_replace()
--
-- @param table..
-- @return table
--
local function arrayReplace( ... )

	-- final table
	local complete = {}

	-- table with all the arguments
	local args = { ... }

	-- for each table
	for _, arg in pairs( args ) do

		-- merge all the consecutive tables in the complete one
		for k, v in pairs( arg ) do

			-- the most left value takes precedence
			complete[ k ] = v
		end
	end

	return complete
end

--- Parse a single line of a template argument in wikitext
--
-- @param string s Wikitext
-- @param string|nil arg Argument name
local function parseTemplateArgument( s, arg )

	-- in Lua the '-' is a special character and should be escaped with '%'
	arg = string.gsub( arg, '%-', '%%-' )

	local pattern = '|%s*' .. arg .. '%s*=(.-)\n'
	local capture = mw.ustring.match( s, pattern )
	if capture ~= nil then
		capture = mw.text.trim( capture )
	end
	return capture
end

--- Parse a single heading from wikitext
--
-- @param string s Wikitext
local function parseSectionHeading( s )
	local pattern = '(.+)=%s*\n'
	local capture = mw.ustring.match( s, pattern )
	if capture ~= nil then
		capture = mw.text.trim( capture, " =" )
	end
	return capture
end

---
-- Remove empty tags from an array of Tags
--
-- If nothing interesting was found, it returns nil.
--
-- @param  tags table Array of strings
-- @return      table Array of strings without empty elements or nil if empty
local function arrayCleanTags( tags )

	local cleanArray = {}
	local founds = 0

	-- for each tags
	for i, v in pairs( tags ) do

		-- trim
		v = mw.text.trim( v )

		-- no value no party
		if v ~= '' then
			founds = founds + 1
			cleanArray[ founds ] = v
		end
	end

	-- no founds no party
	if founds == 0 then
		cleanArray = nil
	end

	return cleanArray
end

---
-- Remove empty elements from a table
--
-- @param  args table
-- @return table
local function cleanWikitextArguments( args )

	local result = {}

	-- clean each argument
	for k, v in pairs( args ) do

		-- eventually trim
		if type( v ) == 'string' then

			v = mw.text.trim( v )

			-- promote to nil
			if v == '' then
				v = nil	
			end
		end

		if v then
			result[ k ] = v
		end
	end

	return result
end

--- Parse some comma separated words
--
-- @param  string s Comma-separated tags
-- @return table Array of tags (without empty tags etc. or nil of no tag was OK)
local function parseTags( s )
	return arrayCleanTags( mw.text.split( s or '', ',', true ) )
end

---
-- Check if a string starts with something
--
-- @param string haystack
-- @param string needle
-- @return boolean
local function stringStartsWith( haystack, needle )
	local len = mw.ustring.len( needle ) 
	local firstPiece = mw.ustring.sub( haystack, 1, len )
	return needle == firstPiece
end

---
-- Check if something is a complete URL
--
-- @param string s Your string to be checked
-- @return boolean
local function isURL( s )
	return stringStartsWith( s, 'https://' )
	    or stringStartsWith( s, 'http://'  )
	    or stringStartsWith( s, '//'       ) -- [[rfc:3986]]
end

---
-- Adapt something to an URL
--
-- @param rawTitle Your page title or a full URL
-- @return A full URL
local function title2url( rawTitle )

	local url = nil

	-- check if this is already a good URL
	if isURL( rawTitle ) then
		url = rawTitle
	else
		-- check if it's a valid MediaWiki page title
		local title = mw.title.new( rawTitle )
		if title ~= nil then
			url = title:fullUrl()
		end
	end

	return url
end

---
-- Parse a raw date / datetime / time string and obtain a Lua date object
--
-- It accepts:
--  yyyy-mm-dd
--  yyyy-mm-dd HH:ii
--  HH:ii
--  Unix timestamp
--
-- @param  rawDateTime Raw date time in string format as 'YYYY-MNN-DD HH:ii' or just 'HH:ii' or Unix timestamp
-- @param  date        Optional object date useful to enrich the rawDateTime if it only consists in a time
-- @return Date object
local function parseDateOrTime( rawDateTime, date )

	local result

	local y, m, d, h, i

	-- maybe the result is a timestamp
	if type( rawDateTime ) == 'number' then
		return os.date( '*t', rawDateTime )
	end

	-- try to parse a complete date
	y, m, d, h, i = string.match(
		rawDateTime,
		'(%d%d%d%d)%-(%d%d)%-(%d%d) +(%d%d):(%d%d)'
	)

	-- otherwise try to parse just a time and inherit the date
	if not y then
		y = date.year
		m = date.month
		d = date.day
		h, i = string.match( rawDateTime, '(%d%d):(%d%d)' )
	end

	-- only return the time object if we was able to parse something
	if h then
		result = os.time{ year=y, month=m, day=d, hour=h, min=i }
		result = os.date( '*t', result )
	end

	return result
end

---
-- Render whatever as a time
--
-- If the input is a Unix timestamp, return 'HH:MM'
-- If the input is a complete date, return just the 'HH:MM'
-- If the input is a string, return a string.
--
-- @param rawTime Your time that can be a numeric timestamp or a 'HH:MM' string
-- @return string|nil
local function renderTime( rawTime )

	local time

	-- check the input type
	local type = type( rawTime )

	if type == 'number' then

		-- convert a unix timestamp to 'HH:MM'
		time = os.date( '%H:%M', rawTime )

	elseif type == 'table' then

		-- if it's a Lua date object, prints a time
		time = rawTime.hour .. ':' .. rawTime.min
	else

		-- this may be an 'HH:MM' or 'YYYY-mm-dd HH:ii:ss'
		hhii = string.match( rawTime, '%d%d%d%d%-%d%d%-%d%d +(%d%d:%d%d)' )
		if hhii ~= nil then
			time = hhii
		else
			-- just return the raw string otherwise
			time = rawTime
		end
	end

	return time
end

---
-- Index a single CronosEvent into a table of CronosEvent(s) indexed by raw date
--
-- It does not return anything.
-- It changes your 'groups' directly.
--
-- @param table Table of CronosEvent(s) indexed by raw date
-- @param table CronosEvent
local function indexCronosEventByDate( events, event )
	local rawDate = event.day:getRawDate()

	-- eventually create the group if it does not exist
	if events[ rawDate ] == nil then
		events[ rawDate ] = {}
	end

	-- append the CronosEvent in the group
	local group = events[ rawDate ]

	group[ #group + 1 ] = event
end

---
-- Index some CronosEvent(s) into a table of CronosEvent(s) indexed by raw date
--
-- It does not return anything.
-- It changes your 'groups' directly.
--
-- @param events Array of CronosEvent(s)
-- @return Associative array of CronosEvent(s) indexed by 'yyyy-mm-dd'
local function indexCronosEventsByDate( groups, events )
	for i, event in pairs( events ) do
		indexCronosEventByDate( groups, event )
	end
end

---
-- Group a collection of CronosEvent by date
--
-- @param events Array of CronosEvent(s)
-- @return Associative array of CronosEvent(s) indexed by 'yyyy-mm-dd'
local function groupCronosEventsByDate( events )
	local groups = {}
	indexCronosEventsByDate( groups, events )
	return groups
end

---
-- Enqueue a stylesheet
--
-- It creates a valid and generic <templatestyles src=""> tag.
--
-- See https://www.mediawiki.org/wiki/Extension:TemplateStyles	
--
-- @param title
-- @return string
local function templateStyles( title )
	return mw.getCurrentFrame():extensionTag{
		name = 'templatestyles',
		args = { src = title },
	}
end

---
-- Merge some frame arguments
--
-- @return table
local function frameArguments( frame )
	local argsParent = cleanWikitextArguments( frame:getParent().args or {} )
	local args       = cleanWikitextArguments( frame.args )
	return arrayReplace( args, argsParent )
end

---
-- Get a complete configuration inheriting default options
--
-- @param table|nil config
-- @return table
local function getConfig( config )
	return arrayReplace( DEFAULT_CONFIG, config )
end

---
-- Get a table of week names
--
-- @param  boolean short Set to true to have short week names
-- @return table
local function weekNamesLocalized( short )

	-- localized week names starting from Sunday
	local weekNames = {}
	for k, v in pairs( MW_WEEK_NAMES ) do

		-- localize the week name thanks to MediaWiki messages ([[MediaWiki:Monday]] etc.)
		v = mw.message.new( v ):plain()

		-- eventually short the week names
		if short then
			v = mw.ustring.sub( v, 1, 3 )
		end

		weekNames[ k ] = v
	end

	return weekNames
end

---
-- Get a list of week names starting from monday or sunday
--
-- @param table   week_names
-- @param boolean from_monday
-- @return table
local function weekNamesFrom( weekNames, fromMonday )
	local ordered = {}
	local i = fromMonday and 1 or 0
	local days = 1
	while days < 8 do
		ordered[ days ] = weekNames[ i % 7 + 1 ]
		i    = i    + 1
		days = days + 1
	end
	return ordered
end

---
-- Giving a number, print some empty cells
--
-- @param int cells
-- @return string
local function printEmptyColumns( cells )
	s = ''
	while cells > 0 do
		s = s .. '\n|'
		cells = cells - 1
	end
	return s
end

---
-- Compare two events by time
--
-- This method is useful for table.sort().
--
-- @param one Event
-- @param two Event
--
local function compareTwoEventsByTime( one, two )
	return one:getStartDateTimestamp()
	     < two:getStartDateTimestamp()
end


---
-- CLASSES
---

---
-- Simple class describing a single CronosEvent
---
local CronosEvent = {}
CronosEvent.__index = CronosEvent

---
-- Simple class collecting events
--
local CronosDay = {}
CronosDay.__index = CronosDay

---
-- Simple class organizing the Calendar
--
local CronosCalendarContext = {}
CronosCalendarContext.__index = CronosCalendarContext

---
-- Simple class organizing a CronosEvent's Category
--
local CronosCategory = {}
CronosCategory.__index = CronosCategory

-- all the Cronos Event(s) Categories indexed by UID
CronosCategory.all = {}

---
-- CLASS METHODS
---

---
-- Construct a clean CronosEvent object
--
-- @param event table Raw Event object to be incapsulated into a CronosEvent class.
--  Some of the supported arguments:
--
--  day      CronosDay object
--  when     Event start time hh:ii (or date and time yyyy-mm-dd hh:ii, or numeric UNIX timestamp)
--  whenEnd  Event   end time hh:ii (or date and time yyyy-mm-dd hh:ii, or numeric UNIX timestamp)
--  category Category identifier
--  tags     Table of Event tags
--  url      External URL
--  editurl  Edit URL (or default to Day's title)
--  context  Calendar context
--
-- @return CronosEvent
function CronosEvent:new( event )
	setmetatable( event, CronosEvent )

	-- the edit URL sometime can be guessed from the daily page title
	event.editurl = event.editurl or event.day.title

	return event
end

--- Construct a CronosEvent parsing a block of wikitext
--
-- @param table  day          The day this event belongs to
-- @param string wikitext     Wikitext that contains part of the arguments
-- @param string sectionTitle Title of the current section
-- @return table|nil
-- @return CronosEvent
function CronosEvent:createParsingDayBlock( day, wikitext, sectionTitle )

	local event = nil

	-- try to parse the Event title
	local title = parseTemplateArgument( wikitext, EVENT_ARG_TITLE ) or sectionTitle

	-- no title no party
	if title ~= nil then

		-- try to parse the Event start time
		local when = parseTemplateArgument( wikitext, EVENT_ARG_WHEN )

		-- no Event time no party
		if when ~= nil then

			-- allow empty arguments
			local args = {}

			-- try to parse the Event tags
			local tags = nil
			local tagsLine = parseTemplateArgument( wikitext, EVENT_ARG_TAGS )
			if tagsLine ~= nil then
				tags = parseTags( tagsLine )
			end

			-- try to parse the Event URL
			-- https://phabricator.wikimedia.org/T254160
			args.url = parseTemplateArgument( wikitext, EVENT_ARG_URL )

			-- try to parse the Event end date
			-- https://phabricator.wikimedia.org/T254333
			args.whenEnd = parseTemplateArgument( wikitext, EVENT_ARG_WHEN_END )

			-- try to parse the category
			-- https://phabricator.wikimedia.org/T254586
			args.category = parseTemplateArgument( wikitext, EVENT_ARG_CATEGORY )

			-- try to parse the location
			args.where = parseTemplateArgument( wikitext, EVENT_ARG_WHERE )

			-- try to parse the abstract
			args.abstract = parseTemplateArgument( wikitext, EVENT_ARG_ABSTRACT )

			-- create the Event object
			args.day   = day
			args.title = title
			args.when  = when
			args.tags  = tags

			-- mark this Event as local
			-- this distinguish a CronosEvent from an imported one
			-- https://phabricator.wikimedia.org/T268213
			args.source = 'local'

			-- check federated identifiers
			-- https://phabricator.wikimedia.org/T268213
			args.ids = {
				[ 'local'    ] = parseTemplateArgument( wikitext, EVENT_ARG_ID ),
				[ 'meta-fr'  ] = parseTemplateArgument( wikitext, EVENT_ARG_ID_METAFR ),
				[ 'wmf-phab' ] = parseTemplateArgument( wikitext, EVENT_ARG_ID_WMF_PHAB ),
			}

			-- create an Event with all the needed arguments
			event = CronosEvent:new( args )
		end
	end

	return event
end

---
-- Construct a CronosEvent from a French "Events calendar" data block
--
-- See https://meta.wikimedia.org/wiki/Events_calendar/events.json
-- See https://phabricator.wikimedia.org/T254264
--
-- @param data Single French Calendar event data block
-- @return CronosEvent
function CronosEvent:createFromFrenchData( calendarContext, data )

	-- Adapt French arguments
	-- note: their dates are not strings, but numeric UNIX timestamps

	-- initialize a dummy CronosDay for this event
	local day = CronosDay:createFromTimestamp( calendarContext, data.dtstart )

	-- external url
	local url = data.link and title2url( data.link )

	-- the French calendar has not a permalink for each event
	-- so just link to the home
	local editurl = DEFAULT_CONFIG[ 'french_dataset_url' ]

	-- return the CronosEvent object
	return CronosEvent:new( {
		day      = day,
		title    = data.title,
		when     = data.dtstart,
		whenEnd  = data.dtend,
		tags     = data.tags,
		where    = data.location,
		url      = url,
		editurl  = editurl,

		-- https://phabricator.wikimedia.org/T268213
		ids = {
			[ 'meta-fr' ] = data.id,
		},
		source  = 'meta-fr',
	} )
end

---
-- Get the start date as Lua date object
--
-- @return table Lua date object
function CronosEvent:getStartDate()
	return parseDateOrTime( self.when, self.day:getDate() )
end

---
-- Get the end date
--
-- If the end date is not specified, the default is the start date.
--
-- @return table Lua date object
function CronosEvent:getEndDate()
	return parseDateOrTime( self.whenEnd or self.when, self.day:getDate() )
end

---
-- Get the start date as Unix timestamp
--
-- @return int Unix timestamp
function CronosEvent:getStartDateTimestamp()
	return os.time( self:getStartDate() )
end

---
-- Get the end date as Unix timestamp
--
-- @return int Unix timestamp
function CronosEvent:getEndDateTimestamp()
	return os.time( self:getEndDate() )
end

---
-- Check if this Cronos event has a specific tag name
--
-- @param string tag Tag name
-- @See https://phabricator.wikimedia.org/T253074
-- @return boolean
--
function CronosEvent:hasTag( tag )
	return self.tags ~= nil and inArray( tag, self.tags )
end

---
-- Check if it exists an external identifier
--
-- @return boolean
--
function CronosEvent:hasExternalId()

	-- stop when reaching the first external id
	for i, argId in pairs( EVENT_ARG_EXTERNAL_IDS ) do
		if self.ids[ argId ] ~= nil then
			return true
		end
	end

	return false
end

---
-- Check if this CronosEvent is mirrored somewhere
--
-- @See https://phabricator.wikimedia.org/T268213
-- @return boolean
--
function CronosEvent:isMirror()
	return self.source == 'local' and self:hasExternalId()
end

---
-- Print the where location
--
-- @return string
function CronosEvent:getHumanWhere()
	local where = self.where
	if type( where ) == 'table' then
		where = mw.text.listToText( self.where )
	end
	return where
end

---
-- Check if this Cronos event has at least one of the specified Tags
--
-- @See https://phabricator.wikimedia.org/T253074
--
-- @param  object tags Array of tags
-- @return boolean True if one of the tags was associated to this Event
function CronosEvent:hasOneTag( tags )

	-- check if this Event as at least one of these Tags
	for i, tag in pairs( tags ) do
		if( self:hasTag( tag ) ) then
			return true
		end
	end

	-- not found
	return false
end

---
-- Return a table with a CronosEvent for each day of duration
--
-- When an event last
--
-- @return table
--
function CronosEvent:createEventsLastingMultipleDays()

	local events = {}

	-- if this has an original Event, it is a child
	-- expanding this will break everything
	if self.original == nil then

		local start = self:getStartDateTimestamp()
		local stop  = self:getEndDateTimestamp()
		local startHour = renderTime( start )
		local lastRawDate = self.day:getRawDate()
		local day = self.day
		local child

		-- well, the event may have no sense
		if start and stop then

			-- next day
			day = day:getNextDay()

			-- for each following day
			while day:getTimestamp() <= stop do

				-- produce a child
				child = {}
				for k, v in pairs( self ) do
					child[ k ] = v
				end

				-- set this new day but set a time (without full-date)
				child.day = day
				child.when = startHour

				-- remember my father
				child.original = self

				-- append this event
				events[ #events + 1 ] = CronosEvent:new( child )

				-- next day please
				day = day:getNextDay()
			end
		end
	end

	return events
end

---
-- Expand extra events lasting multiple days
--
function CronosEvent:expandEventsLastingMultipleDays()

	-- execute only once
	if self._expandedEventsLastingMultipleDays == nil then

		-- remember we have executed this
		self._expandedEventsLastingMultipleDays = self:createEventsLastingMultipleDays()

		-- publish each Event in its day
		for i, event in pairs( self._expandedEventsLastingMultipleDays ) do
			event:addToDay()
		end
	end

	return self._expandedEventsLastingMultipleDays
end

---
-- Get the duration of this Event in days
--
-- @return int
function CronosEvent:getDurationDays()
	return #self:expandEventsLastingMultipleDays()
end

---
-- Get a truncated title with eventually a tooltip
--
-- @return string
function CronosEvent:truncatedTitle()

	-- eventually truncate (but put the complete title inside a tooltip)
	local title = self.title
	local title_is_pure_text = mw.ustring.find( title, '[', 1, true ) == nil
	local maxlen = tonumber( self.day.context.config.max_title_len )
	if mw.ustring.len( title ) > maxlen and title_is_pure_text then
		local truncated = mw.ustring.sub( title, 1, maxlen ) .. '…'
		title =	tostring( mw.html.create( 'span' )
			:attr( 'title', title )
			:wikitext( truncated ) )
	end
	
	return title
end

---
-- Parameters useful for some Event templates
--
-- @return table
--
function CronosEvent:briefTemplateParameters()
	return {
		['yyyy']     = self.day.yyyy,
		['mm']       = self.day.mm,
		['dd']       = self.day.dd,
		['title']    = self:truncatedTitle(),
		['when']     = renderTime( self.when ),
		['end']      = self.whenEnd and renderTime( self.whenEnd ),
		['url']      = self.url and title2url( self.url ),
		['editurl']  = self.editurl,
		['category'] = self.category,
		['where']    = self:getHumanWhere(),
	}
end

---
-- Generate a brief abstract of this specific event
--
function CronosEvent:renderBriefCell( frame )
	frame = frame or mw.getCurrentFrame()

	-- this as default is [[Template:Cronos event brief]]
	return frame:expandTemplate{
		title = DEFAULT_CONFIG[ 'template_event_brief' ],
		args = self:briefTemplateParameters(),
	}	
end

---
-- Generate a brief line for this specific event
--
-- @return string
function CronosEvent:renderBriefLine()

	-- this as default is [[Template:Cronos event brief line]]
	return mw.getCurrentFrame():expandTemplate{
		title = DEFAULT_CONFIG[ 'template_event_brief_line' ],
		args = self:briefTemplateParameters(),
	}	
end

---
-- Get some information about the Category of this CronosEvent (if any)
--
-- It always return a Category. Always
--
-- See https://phabricator.wikimedia.org/T254586
--
-- @return table CronosCategory
function CronosEvent:getCategory()
	-- if the argument is not present assume a default one
	return CronosCategory.createFromUID( self.category )
end

---
-- Shortcut to add this CronosEvent to the related CronosDay
--
-- @param table CronosEvent
function CronosEvent:addToDay()
	self.day:addEvent( self )
end

---
-- Construct an empty CronosDay table
--
-- This entity was created to describe a 'Meta:Something/yyyy-mm-dd' page
-- but it also describe a generic date.
--
-- @param table context Optional Calendar Context
function CronosDay:new( context )

	-- instantiate a CronosDay object
	local day = {}
	setmetatable( day, CronosDay )

	-- keep the configuration as dependency injection
	day.context = context or CronosCalendarContext:new()

	-- initialize events
	day.events = {}

	return day
end

---
-- Construct a CronosDay table
--
-- This entity was created to describe a 'Meta:Something/yyyy-mm-dd' page
-- but it also describe a generic date.
--
-- @param date    Full date formatted in 'yyyy-mm-dd'
-- @param table   Calendar context
function CronosDay:createFromRawDate( date, calendarContext )

	-- initialize a new day with this configuration
	local day = CronosDay:new( calendarContext )

	-- remember the raw date formatted in yyyy-mm-dd
	day.rawdate = date

	-- extract single date members
	local dmy  = mw.text.split( date, '-', true )
	day.yyyy   = dmy[ 1 ]
	day.mm     = dmy[ 2 ]
	day.dd     = dmy[ 3 ]
	day.m      = tonumber( day.mm )

	day.timestamp = os.time( day:getDate() )
	day.week      = os.date( '%w', day.timestamp ) -- sunday is 0
	day.title     = calendarContext.config.event_prefix .. date

	-- assure to recycle an existing day
	return calendarContext:getUniqueDay( day )
end

---
-- Create a Cronos Day from a timestamp
--
-- @return CronosDay
--
function CronosDay:createFromTimestamp( calendarContext, timestamp )
	local day = CronosDay:new( calendarContext )

	-- basic information
	day.yyyy      = os.date( '%Y', timestamp ) -- full year
	day.mm        = os.date( '%m', timestamp ) -- full month 01-12
	day.dd        = os.date( '%d', timestamp ) -- full day   01-31
	day.week      = os.date( '%w', timestamp ) -- sunday is 0
	day.timestamp = timestamp

	-- assure to recycle an existing day
	return calendarContext:getUniqueDay( day )
end

---
-- Get a Lua date object indicating this date
--
-- @return object Luda date object
function CronosDay:getDate()
	return {
		year  = self.yyyy,
		month = self.mm,
		day   = self.dd,
	}
end

---
-- Get the date in format 'yyyy-mm-dd'
--
-- @return string
--
function CronosDay:getRawDate()

	-- eventually build it
	if self.rawdate == nil then
		self.rawdate = self.yyyy .. '-' .. self.mm .. '-' .. self.dd
	end

	return self.rawdate
end

---
-- Get the date as Unix timestamp
--
-- @return integer
--
function CronosDay:getTimestamp()
	return self.timestamp
end

---
-- Check if this CronosDay is today!
--
-- @return boolean
--
function CronosDay:isToday()
	return self:getRawDate() == TODAY_RAW
end

---
-- Get the wikitext of this event page
--
-- @return string|nil
function CronosDay:wikitext()

	local content = nil

	-- no title, no party
	if self.title then
		content = mw.title.new( self.title )
			:getContent()
	end

	return content
end

--- Add a CronosEvent to the collection
--
-- @param table CronosEvent
function CronosDay:addEvent( event )
	self.events[ #self.events + 1 ] = event
end

---
-- Parse this day page looking for events
--
function CronosDay:parse()

	-- save resources and parse only once
	if self._parsed == nil then

		-- this should be not initialized to do not overwrite some events
		-- self.events = {}

		-- shortcut
		local context = self.context

		-- requested Tags
		local filterTags = context.filters.tags or nil

		-- try to parse local events
		local wikitext = self:wikitext()
		if wikitext ~= nil then

			-- split the page in sections
			local sections = mw.text.split( wikitext, "\n=" )
			for _, section in pairs( sections ) do

				-- parse the section title
				local sectionTitle = parseSectionHeading( section )

				-- split the section content in event blocks
				local blocks = mw.text.split( section, EVENT_PATTERN )
				for i, block in pairs( blocks ) do

					-- parse each Event template
					local event = CronosEvent:createParsingDayBlock( self, block, sectionTitle )
					if event ~= nil then

						-- check if the Event matches filtersthe event must match filters
						-- and should not be a local mirror (to avoid duplicates)
						if context:canAccomodate( event ) and not event:isMirror() then
							event:addToDay()
						end
					end
				end
			end
		end

		-- find the French Calendar events related to this day
		local todayFrenchEvents = p._getFrenchCalendarEventsInDate( self.context, self:getRawDate() )
		if todayFrenchEvents ~= nil then
			for i, event in pairs( todayFrenchEvents ) do

				-- check if the Event matches filtersthe event must match filters
				-- and should not be a local mirror (to avoid duplicates)
				if context:canAccomodate( event ) and not event:isMirror() then
					event:addToDay()
				end
			end
		end

		-- mark this day as parsed
		self._parsed = true
	end
end

---
-- Get the CronosEvent(s) related to this day (if any)
--
-- @return CronosEvent[]
--
function CronosDay:getEvents()

	-- parse this Event
	-- this is safe to be called twice
	-- this populates self.events
	self:parse()

	-- expand Event(s) lasting multiple days
	-- this is safe to be called twice
	-- this populates self.events
	self:expandEventsLastingMultipleDays()

	-- table of CronosEvent(s)
	return self.events
end

---
-- Get the CronosEvent(s) related to this day (if any) ordered by time
--
-- @return CronosEvent[]
--
function CronosDay:getEventsSortedByTime()

	local events = self:getEvents()

	table.sort( events, compareTwoEventsByTime )

	return events
end

---
-- Get the CronosEvent identified with the provided source and id
--
-- If in this day there is not such event, it returns false.
--
-- @param string source Federation source identifier e.g. 'local' for 'this wiki'
-- @param string id
-- @return CronosEvent|false
--
function CronosDay:getEventBySourceId( source, id )

	-- find it by id
	for i, event in pairs( self:getEvents() ) do
		if event.ids[ source ] == id then
			return event
		end
	end

	return false
end

---
-- Shortcut to expand events lasting multiple days
--
function CronosDay:expandEventsLastingMultipleDays()
	for i, event in pairs( self.events ) do
		event:expandEventsLastingMultipleDays()
	end
end

---
-- Generate a brief header of this day
--
-- @return string
function CronosDay:renderBrief( frame )
	frame = frame or mw.getCurrentFrame()
	return frame:expandTemplate{
		title = DEFAULT_CONFIG[ 'template_day_brief' ],
		args = { self.yyyy, self.mm, self.dd },
	}
end

---
-- Generate a list of all the events in this day for a calendar cell
--
-- This builds the event list in a Calendar cell
--
-- @return string
function CronosDay:renderEventsForCell( frame )
	local s = ''
	frame = frame or mw.getCurrentFrame()
	for _, event in pairs( self:getEventsSortedByTime() ) do
		s = s .. "\n" .. event:renderBriefCell( frame )
	end
	return  s
end

---
-- Generate a calendar cell with a list of all the events in this day
--
-- @return string
function CronosDay:renderCalendarCell( frame )
	frame = frame or mw.getCurrentFrame()
	return self:renderBrief( frame )
	    .. self:renderEventsForCell( frame )
end

---
-- Get the next day
--
-- @return CronosDay
--
function CronosDay:getNextDay()
	return self.context:getDayFromTimestamp( self:getTimestamp() + SECONDS_IN_DAY )
end

---
-- Get the previous day
--
-- @return CronosDay
--
function CronosDay:getPreviusDay()
	return self.context:getDayFromTimestamp( self:getTimestamp() - SECONDS_IN_DAY )
end

---
-- Preload some days before this one
--
-- @param integer days Number of days to be preloaded
--
function CronosDay:preloadPreviusDays( days )
	local day
	local i = 1
	while i < days do
		day = CronosDay:getPreviusDay()

		-- this will trigger the cache
		day:getEvents()

		i = i + 1
	end
end

---
-- Constructor for a CronosEvent's Category
--
-- @param category Category arguments
--  Some of them:
--   uid:      string Category identifier
--   name:     string Category name
--   filename: string Category filename
--
-- See https://phabricator.wikimedia.org/T254586
--
function CronosCategory:new( category )
	setmetatable( category, CronosCategory )
	return category
end

---
-- Construct/find a CronosEvent's Category
--
-- It assures that you obtain the same category each time you call this
--
-- @param uid string Category UID like 'com' for 'community' or nil for the default
--
-- See https://phabricator.wikimedia.org/T254586
--
function CronosCategory.createFromUID( uid )

	local defaultUID = DEFAULT_CONFIG.default_category

	-- if the UID is missing assume the default category
	uid = uid or defaultUID

	-- check if this category was already generated
	if not CronosCategory.all[ uid ] then

		-- check if this category is known
		local categoryData = CRONOS_CATEGORIES[ uid ]
		if categoryData then

			-- instantiate this category for the first time
			CronosCategory.all[ uid ] = CronosCategory:new( categoryData )
		else

			-- in this case the Category is not known

			-- eventually throw an error if you have not the default
			if uid == defaultUID then
				error( 'whaat? missing default category with UID: ' .. defaultUID )
			end

			-- try with the default one
			-- the second parameter avoids any recursion
			-- that may happen if someone declares by mistake an
			-- unexisting default category
			return CronosCategory.createFromUID( defaultUID )
		end
	end

	-- just return the already existing Category instance
	return CronosCategory.all[ uid ]
end

---
-- Get the Cronos Event Category icon as wikitext
--
-- See https://phabricator.wikimedia.org/T254586
--
-- @param args Arguments
--  Accepted arguments:
--    size: string Size in pixels
--    link: string Link URL
-- @return string
function CronosCategory:getIconWikitext( args )
	local link = args and args.link or ''
	local size = args and args.size or '18px'
	return '[[' .. self.filename .. '|' .. size .. '|link=' .. link .. '|' .. self.name .. ']]'
end

---
-- Create a Calendar context
--
-- It returns some useful information acting as a middleware for the data needed
-- by all the available visualizations (calendar visualization and list).
--
-- @param  config Optional complete configuration
-- @return table
function CronosCalendarContext:new( config )

	-- instantiate a CronosCalendarContext object
	local calendarContext = {}
	setmetatable( calendarContext, CronosCalendarContext )

	-- expose the configuration
	calendarContext.config = getConfig( config or {} )

	-- localized week names starting from Sunday
	calendarContext.weekNames = weekNamesLocalized( calendarContext.config.short_weekname ~= '0' )

	-- number of week lines to be displayed
	calendarContext.weeks = tonumber( calendarContext.config.weeks )

	-- maximum number of days to be displayed
	-- do not confuse with the 'dayList' attribute
	calendarContext.days = calendarContext.weeks * 7

	-- start from Monday or from Sunday
	calendarContext.startFromMonday = calendarContext.config.start_from_monday == '1'

	-- start the week names from the correct day (Monday or Sunday)
	calendarContext.weekNamesFrom = weekNamesFrom( calendarContext.weekNames, calendarContext.startFromMonday )

	-- the user may want to filter by some factors
	calendarContext.filters = {
		tags = nil,
	}

	-- eventually filter by some Tags
	if calendarContext.config.tags ~= nil then
		calendarContext.filters.tags = parseTags( calendarContext.config.tags )
	end

	-- shift the current time month forward or backward by some months
	calendarContext.monthShift = tonumber( calendarContext.config.month_shift )

	-- unix time starting from now (eventually shifting)
	calendarContext.startWeekTime = os.time() + calendarContext.monthShift * SECONDS_IN_MONTH

	-- build the format date
	-- see the documentation of os.date() about UTC or local time
	local format_prefix = ''
	if calendarContext.config.utc == '1' then
		format_prefix = '!'
	end

	-- os.date() formats to obtain a date table or a date in Y-m-d
	local format_date = format_prefix .. '*t'
	local format_ymd  = format_prefix .. '%F'

	-- today's date
	calendarContext.today = os.date( format_date, calendarContext.startWeekTime )

	-- prepare week indexes
	calendarContext.weekStart = 1
	calendarContext.weekEnd   = 8
	if calendarContext.startFromMonday then
		calendarContext.weekStart = calendarContext.weekStart + 1
		calendarContext.weekEnd   = calendarContext.weekEnd   + 1
	end

	-- how much days since the start of this week
	-- note that the week day starts from sunday = 1, monday = 2, etc.
	--   so as default if it's Monday should be considered "1 days" since start of week
	--   so as default if it's Sunday should be considered "0 days" since start of week
	calendarContext.daysSinceStartWeek = calendarContext.today.wday - 1

	-- eventually consider Monday as start of the week
	--   so as default if it's Monday should be considered "0 days" since start of week
	--   so as default if it's Sunday should be considered "6 days" since start of week
	if calendarContext.startFromMonday then
		calendarContext.daysSinceStartWeek = calendarContext.daysSinceStartWeek - 1
		if calendarContext.daysSinceStartWeek == -1 then
			calendarContext.daysSinceStartWeek = 6
		end
	end

	-- CronosDay(s) indexed by raw date
	calendarContext.dayByDate = {}

	return calendarContext
end

---
-- Check if the current context "can accomodate" the current Event
--
-- In short it checks if the Event matches current filters (Tags etc.)
--
-- @param event table Event
-- @return boolean
--
function CronosCalendarContext:canAccomodate( event )

	-- eventually filter by Tag
	-- https://phabricator.wikimedia.org/T253074
	local tags = self.filters.tags
	if tags ~= nil and not event:hasOneTag( tags ) then
		return false
	end

	-- as default the event matches the context
	return true
end

---
-- Get an unique day
--
-- This function assures that your day is unique for your calendar context.
-- In this way you do not create multiple different days rappresenting the same day.
--
-- @param day CronosDay
-- @return CronosDay
function CronosCalendarContext:getUniqueDay( day )

	-- the date in 'yyyy-mm-dd'
	local rawDate = day:getRawDate()

	-- eventually initialize the singleton
	if self.dayByDate[ rawDate ] == nil then
		self.dayByDate[ rawDate ] = day
	end

	-- returns the singleton
	return self.dayByDate[ rawDate ]
end

---
-- Shortcut to get a CronosDay from a raw date
--
-- @param string rawDate
-- @return CronosDay
function CronosCalendarContext:getDayFromRawDate( rawDate )
	return CronosDay:createFromRawDate( rawDate, self )
end

---
-- Shortcut to get a CronosDay from a Unix timestamp
--
-- @param integer timestamp
-- @return CronosDay
function CronosCalendarContext:getDayFromTimestamp( timestamp )
	return CronosDay:createFromTimestamp( self, timestamp )
end

---
-- Get a table of empty days starting from this week
--
-- @return table Table of CronosDay(s)
function CronosCalendarContext:getDays()

	-- list of days to be returned
	local dayList = {}

	-- calculate the date when this week started
	local seconds_since_start_week = self.daysSinceStartWeek * SECONDS_IN_DAY
	local time_start_of_week = self.startWeekTime - seconds_since_start_week

	-- see the documentation of os.date() about UTC or local time
	local format_prefix = ''
	if self.config.utc == '1' then
		format_prefix = '!'
	end

	-- os.date() formats to obtain a date table or a date in Y-m-d
	local format_ymd  = format_prefix .. '%F'

	-- generate the list of the days
	local i = 0
	while i < self.days do

		-- prepare the CronosDay object
		local event_time = time_start_of_week + i * SECONDS_IN_DAY
		local event_ymd  = os.date( format_ymd, event_time ) 

		-- add this well-known CronosDay to the list
		i = i + 1
		dayList[ i ] = self:getDayFromRawDate( event_ymd )
	end

	return dayList
end

---
-- Read the French Calendar dataset (raw format)
--
-- You should not call this twice without any kind of cache.
--
-- See https://meta.wikimedia.org/wiki/Events_calendar/events.json
-- See https://phabricator.wikimedia.org/T254264
--
-- @return Table of raw events
function p._parseFrenchCalendarDatasetRawContent()
	-- load the page
	local page = mw.title.new( DEFAULT_CONFIG.french_dataset_page )

	-- load the JSON
	local content = page:getContent()

    -- @TODO: replace with mw.loadJsonData() when will be available (after 18 October 2022)
	-- return an array of events
	return mw.text.jsonDecode( content )
end


---
-- ENDPOINTS
---

---
-- Convert a title or an URL... to an URL
--
-- This is intended to be called from Wikitext.
--
-- @return string
--
function p.title2url( frame )
	local args = frame.args

	-- take the first argument from the parent template of from the direct one
	local titleOrURL = args[1]

	return titleOrURL and title2url( titleOrURL )
end

---
-- Create a CalendarContext object
--
-- This is intended to be called from Lua.
--
-- @param table config Optional configuration
-- @return CalendarContext
function p._createCalendarContext( config )
	return CronosCalendarContext:new( config )
end

---
-- Read the French Calendar dataset and convert them to CronosEvent(s)
--
-- This is intended to be called from Lua.
--
-- Note that this method does not have any kind of cache.
--
-- @param table Calendar Context
-- @return Table of events
function p._parseFrenchCalendarCronosEvents( calendarContext )

	-- events to be returned
	local events = {}

	-- increment the expensive function call another time
	-- parsing all of this stuff should be considered expensive
	-- because they are so much:
	--  june 2020: 505 (!)
	mw.incrementExpensiveFunctionCount()

	-- for each raw event
	for i, rawEvent in ipairs( p._parseFrenchCalendarDatasetRawContent() ) do

		-- append this structured event
		events[ i ] = CronosEvent:createFromFrenchData( calendarContext, rawEvent )
	end

	return events
end

---
-- Get the French Calendar Dataset grouped by date
--
-- This function uses a cache to allow multiple calls.
--
-- See https://meta.wikimedia.org/wiki/Events_calendar/events.json
-- See https://phabricator.wikimedia.org/T254264
--
-- @param table Calendar context
function p._getFrenchCalendarEventsGroupedByDate( calendarContext )
	-- assure that this is initialized only once
	if calendarContext.frenchEventsByDate == nil then
		calendarContext.frenchEventsByDate = groupCronosEventsByDate( p._parseFrenchCalendarCronosEvents( calendarContext ) )
	end
	return calendarContext.frenchEventsByDate
end

---
-- Get the French Calendar Dataset of a single day
--
-- If nothing is present it returns nil.
--
-- See https://meta.wikimedia.org/wiki/Events_calendar/events.json
-- See https://phabricator.wikimedia.org/T254264
--
-- @param object Calendar context
-- @param date Raw date formatted as 'yyyy-mm-dd'
-- @return table or nil
function p._getFrenchCalendarEventsInDate( context, rawDate )
	local eventsByDate = p._getFrenchCalendarEventsGroupedByDate( context )
	return eventsByDate[ rawDate ]
end

---
-- Show some Tag "chips"
--
-- This should be used from Lua and not from wikitext.
--
-- @param  table  Tags
-- @return string Wikitext
--
function p._tagChips( tags )

	-- create a chip for each Tag
	local chips = {}
	for i, tag in pairs( tags ) do
		chips[ i ] = '<span class="cronos-tag-chip">' .. tag .. '</span>'
	end

	-- include the stylesheet for the Tag chips
	local s = templateStyles( DEFAULT_CONFIG[ 'chips_stylesheet' ] )

	-- append stylesheet and tags
	s = s .. table.concat( chips, ' ' )

	return s
end

---
-- Show some Tag "chips" (from wikitext)
--
-- This should be used from wikitext and not from Lua.
--
-- @return string Wikitext
--
function p.tagChips( frame )

	-- merge parent args etc.
	local args = frameArguments( frame )

	-- take the first argument from the parent template of from the direct one
	local tagsRaw = args[1] or args.tags

	-- parse the tags
	local tags = parseTags( tagsRaw )

	-- create the chips
	return tags and p._tagChips( tags )
end

---
-- Get a CronosCategory object from its UID
--
-- This should be used from Lua and not from wikitext.
--
-- @param string uid Category UID
-- @return CronosCategory
function p._category( uid )
	return CronosCategory.createFromUID( uid )
end

---
-- Print a CronosCategory icon from its UID
--
-- This should be used from wikitext and not from Lua.
--
-- @param string uid Category UID
function p.categoryIcon( frame )
	local args = frameArguments( frame )
	local uid = args[1] or args.uid
	return p._category( uid ):getIconWikitext( {
		link = args.link,
		size = args.size,
	} )
end

---
-- Print a CronosCategory name from its UID
--
-- This should be used from wikitext and not from Lua.
--
-- @param string uid Category UID
function p.categoryName( frame )
	local args = frameArguments( frame )
	local uid = args[1] or args.uid
	return p._category( uid ).name
end

---
-- Get an URL to add an event
--
-- This method should be called from Lua and not from wikitext
--
-- @param table args Query string arguments
-- @return string
function p._getAddEventURL( args )

	---
	-- As default this is something like:
	--   'https://wmch.toolforge.org/cronos/'
	local url = DEFAULT_CONFIG[ 'cute_form_url' ]

	-- eventually append the query string, if any
	if args ~= nil then
		local queryString = mw.uri.buildQueryString( args )
		if queryString ~= '' then
			url = url .. '?' .. queryString
		end
	end

	return url
end

---
-- Get an URL to add an event
--
-- This method should be called from Wikitext and not from Lua
--
-- @param frame
-- @return string
function p.getAddEventURL( frame )
	local args = frameArguments( frame )
	local query = {}

	-- eventually append tags
	local tags = args['tags']
	if tags ~= nil then
		local tagsTable = parseTags( tags )
		if #tagsTable > 0 then
			query.tags = table.concat( tagsTable, ',' )
		end
	end
	
	return p._getAddEventURL( query )
end

---
-- Generate the monthly calendar (Lua API)
--
-- This should be used from Lua and not from wikitext.
--
-- @param  object userConfig
-- @return string
function p._main( userConfig )

	-- output string
	local s = ''

	-- get everything I need
	local calendarContext = CronosCalendarContext:new( userConfig )

	-- local configuration
	local config = calendarContext.config

	-- frame of the current page
	local frame = mw.getCurrentFrame()

	-- append heading template
	s = s .. frame:expandTemplate{ title = HEADING_TEMPLATE }

	-- append start of the table
	s = s .. '\n{| class="wikitable cronos-month-table"'

	-- list of days
	local dayList = calendarContext:getDays()

	-- generate the table body
	local lastMonth = -1
	for i, day in pairs( dayList ) do

		-- print a newline?
		local newline = false

		-- domain: 0-6
		local column = ( i - 1 ) % 7

		if day.m == lastMonth then
			-- new row
			if column == 0 then
				s = s .. '\n|-\n'
			end
		else
			-- print week labels
			lastMonth = day.m

			-- print a new row if the month is changed
			if column > 0 then
				s = s .. printEmptyColumns( 7 - column )
				s = s .. '\n|-\n'
			end

			-- add row with month name
			local monthName = mw.message.new( MW_MONTH_NAMES[ lastMonth ] ):plain()

			-- eventually separate the month name from the above lines
			if i ~= 1 then
				s = s .. '\n|-\n'
			end
			s = s .. '\n!colspan="7" class="cronos-month-name"|' .. monthName
			s = s .. '\n|-\n'

			-- add row with week names
			for k, v in pairs( calendarContext.weekNamesFrom ) do
				s = s .. '\n!' .. v
			end
			s = s .. '\n|-\n'

			-- eventually print some empty columns
			if column > 0 then
				s = s .. printEmptyColumns( column )
			end
		end

		-- allow to style in a different way the current day cell
		if day:isToday() then
			s = s .. '\n|class="cronos-day-current"|'
		else
			s = s .. '\n|'
		end

		-- put the day in the cell
		s = s .. day:renderCalendarCell( frame )

		-- next day
		i = i + 1
	end

	-- eventually cite our filters
	if calendarContext.filters.tags ~= nil then
		s = s .. '\n|-\n'
		s = s .. '\n|colspan="7|' .. p._tagChips( calendarContext.filters.tags )
	end

	return s .. '\n|}'
end

---
-- Try to obtain all the used Tags
--
-- The Tags will be returned as an array of objects like:
--  {
--    { tag = 'foo', count = 2 },
--    { tag = 'bar', count = 1 },
--    ...
-- }
--
--
-- @see https://phabricator.wikimedia.org/T276350
-- @return table
--
function p._tags( userConfig )

	-- output
	local tags = {}

	-- get everything I need
	local calendarContext = CronosCalendarContext:new( userConfig )

	-- for each Day
	for i, day in pairs( calendarContext:getDays() ) do

		-- for each Event
		for k, event in pairs( day:getEvents() ) do

			-- for each Tag
			if event.tags ~= nil then
				for j, tag in pairs( event.tags ) do

					-- eventually initialize
					if tags[ tag ] == nil then

						tags[ tag ] = {
							tag   = tag,
							count = 0
						}

					end

					-- increase count
					tags[ tag ].count = tags[ tag ].count + 1
				end
			end
		end
	end


	return tags
end

---
-- Generate a cute Tag Cloud
--
-- [[phab:T276666]]
-- https://phabricator.wikimedia.org/T276666
--
-- This should be used from wikitext and not from Lua.
--
function p.tagCloud( frame )

	-- see [[Module:TagCloud]]
	local moduleTagCloud = require( 'Module:TagCloud' )

	-- parse user config
	local userConfig = frameArguments( frame )

	-- find the Tags in use in the calendar
	local tags = p._tags( userConfig )

	-- print the tag cloud
	return moduleTagCloud._main( {
		tags = tags,
	} )
end

---
-- Generate the monthly calendar
--
-- This should be used from Lua and not from wikitext.
--
-- @param  object userConfig Optional configuration
-- @return string
--
-- @see https://phabricator.wikimedia.org/T262016
function p._list( userConfig )

	-- output string
	local s = ''

	-- get everything I need
	local calendarContext = CronosCalendarContext:new( userConfig )

	-- prepared configuration
	local config = calendarContext.config

	-- frame of the current page
	local frame = mw.getCurrentFrame()

	-- columns of the table
	local columns = config.template_event_brief_line_columns

	-- append heading template with stylesheet
	s = s .. frame:expandTemplate{ title = HEADING_TEMPLATE }

	-- append table header
	-- as default [[Template:Event brief line/Head]]
	s = s .. '\n'
	s = s .. frame:expandTemplate{ title = config.template_event_brief_line_head }

	-- days involved in this list
	local dayList = calendarContext:getDays()

	-- generate the table body
	local lastMonth = -1
	local todayEvents
	for i, day in pairs( dayList ) do

		-- events related to this day
		todayEvents = day:getEventsSortedByTime()

		-- plot every single event of this day
		for _, event in pairs( todayEvents ) do

			-- new row
			s = s .. '\n|-\n'

			-- render the event line (some cells)
			s = s .. event:renderBriefLine()
		end

		-- next day
		i = i + 1
	end

	-- eventually cite our filters
	if calendarContext.filters.tags ~= nil then
		s = s .. '\n|-'
		s = s .. '\n|colspan="' .. columns .. '"|' .. p._tagChips( calendarContext.filters.tags )
	end

	return s .. '\n|}'
end

---
-- Generate the monthly calendar
--
-- This should be used from wikitext and not from Lua.
--
function p.main( frame )
	local args = frameArguments( frame )
	return p._main( args )
end

---
-- Generate the list calendar
--
-- This should be used from wikitext and not from Lua.
--
-- See https://phabricator.wikimedia.org/T262016
--
function p.list( frame )
	local args = frameArguments( frame )
	return p._list( args )
end

---
-- Get a single CronosDay object
--
-- This should be used from Lua and not from wikitext.
--
-- You can use this in your Lua console e.g.:
--    =mw.logObject( p._day( '2019-03-25' ) )
--
-- @param date   Date formatted as 'yyyy-mm-dd'
-- @param config Optional configuration
--
function p._day( date, config )

	-- no date no party
	if not date then
		error( 'missing date' )
	end

	-- create a Calendar context
	local calendarContext = CronosCalendarContext:new( config )

	-- create from the raw date
	return CronosDay:createFromRawDate( date, calendarContext )
end

---
-- Print the events of a single CronosDay
--
-- This should be used from wikitext and not from Lua.
--
-- @param object config
--
function p.day( frame )
	local args = frameArguments( frame )
	local date = frame.args[ 1 ]
	local day = p._day( date, frame.args )
	return day:renderEvents( frame )
end

---
-- Get a single CronosEvent object from a date and an ID
--
-- The date is very important because there is not a central database,
-- so we start from a day, and then we filter its events by the provided ID
-- to keep this earch reliable and scalable and also to prevent any kind of
-- potential duplicates from external sources.
--
-- This should be used from Lua and not from wikitext.
--
-- You can use this in your Lua console e.g.:
--    = mw.logObject( p._event( {
--       date = '2019-03-25',
--       source = 'local',
--       id = 'cronos-2019-03-25-asd1',
--     ) )
--
-- @param args   table Arguents. Some of them:
--   date   (string formatted as 'yyyy-mm-dd')
--   source (string like 'local')
--   id     (string like '123-asd')
-- @param config Optional configuration
--
function p._event( args )

	local date = args.date

	-- create a generic day
	local day = p._day( args.date, args.config )

	-- no source no party
	if not args.source then
		error( 'missing source' )
	end

	-- no id no party
	if not args.id then
		error( 'missing id' )
	end

	-- return the event or nil
	return day:getEventBySourceId( args.source, args.id )
end

---
-- Display a single Event
--
-- The date is very important because there is not a central database,
-- so we start from a day, and then we filter its events by the provided ID
-- to keep this earch reliable and scalable and also to prevent any kind of
-- potential duplicates from external sources.
--
-- This should be used from wikitext and not from Lua.
--
-- Parameters:
--   date   (string formatted as 'yyyy-mm-dd')
--   source (string like 'local')
--   id     (string like '123-asd')
--
-- @param date   Date formatted as 'yyyy-mm-dd'
-- @param id     Event identifier as 'cronos-asd'
-- @param config Optional configuration
--
function p.event( frame )

	local args = frameArguments( frame )
	local date    = args.date
	local source  = args.source
	local id      = args.id
	local config  = nil

	-- find the event by this id
	local event = p._event{
		date   = date,
		source = source,
		id     = id,
		config = config,
	}

	local tagList = ''
	if event.tags ~= nil then
		tagList = table.concat( event.tags, ', ' )
	end

	-- fill the arguments for the template
	local args = {
		[ EVENT_ARG_TITLE    ] = event.title,
		[ EVENT_ARG_WHERE    ] = event.where,
		[ EVENT_ARG_WHEN     ] = event.when,
		[ EVENT_ARG_WHEN_END ] = event.whenEnd,
		[ EVENT_ARG_TAGS     ] = tagList,
		[ EVENT_ARG_URL      ] = event.url,
		[ EVENT_ARG_CATEGORY ] = event.category,
		[ EVENT_ARG_ABSTRACT ] = event.abstract,
		[ EVENT_ARG_ID       ] = event.ids.id,
	}

	-- pass each external identifiers
	for i, argId in pairs( EVENT_ARG_EXTERNAL_IDS ) do
		args[ argId ] = event.ids[ argId ]
	end

	return frame:expandTemplate{ title = EVENT_TEMPLATE, args  = args }
end

return p