Specification of the Day Planner iCalendar diff format by Eskild Hustvedt ------------------------------------------------------------ **** DRAFT SPECIFICATION - DO NOT USE **** 1 - Introduction 2 - Format commands 3 - iCalendar commands 1 - INTRODUCTION ---------------- This file format is a simple iCalendar diff format. It can also be thought of as a revision control system for iCalendar. The purpose is twofold: - First, it is to provide a method to change a calendar offline and then later synchronize with an online server, possibly retaining changes done only on the server copy. - Secondly, it can also provide a simple way to have undo/redo functionality on iCalendar files and also keep the undo information after closing the calendar software. The format contains a list of commands, each of which is applied to the iCalendar file in turns. It is divided into a set of transactions, each transaction being the changes to one UID (though you can divide them up more). 1.2 - Special syntax Empty lines should be ignored. Lines beginning with # should be ignored. 2 - FORMAT COMMANDS ------------------- 2.1 - DPICSDIFF This must always be the first word on the first line in any file that uses this specification. Syntax: DPICSDIFF [VERSION] Parameters: [VERSION] - the version of the spec the file requires. So for instance if you only use version 1.0 commands, then you should only specify version 1.0. 2.2 - QUOTESTRING This sets the quote string. By default this is ". The quote string is used around strings in iCalendar commands. It can be between one and four characters long. This can be changed many times in one file, and can thus be supplied as many times as you want. This is used in place of an advanced escaping system. Everything inside the quotestring is interperated literally. Syntax: QUOTESTRING [STRING] Parameters: [STRING] - the string. Default is ". Can be any character or characters, but no longer than four characters and no less than one. If omitted then QUOTESTRING " is assumed. 2.3 - ENTER [UID] [CREATE?] [TYPE] This command begins a new transaction, defining that the following commands work on UID. The CREATE keyword must be appended, followed by the iCalendar section type, if it is new. If the UID exists and the CREATE keyword was given then the parser should attempt to process the following section as if it was a patch (like the CREATE keyword was not given). If it is not possible then the parser must rename the UID that existed and re-process this section. If the UID does not exist and the CREATE keyword was not given then the parser should attempt to process the following section as if the CREATE keyword was given and assume TYPE=VEVENT, if that is not possible then the transaction MUST fail. Any file can have any number of transactions on one UID. One might even ENTER a new UID transaction after each command to have very fuzzy applying of the changes. If one command in the transaction fails, then all following and preceeding commands in the transaction MUST fail and the UID be reverted to its state before the transaction. A transaction SHOULD be considered as failed if the UID is empty after processing and it was not deleted completely. 3 - ICALENDAR COMMANDS ---------------------- 3.1 - DELETE This command deletes the current UID and ALL CONTENTS. Syntax: DELETE Failure: Never. Ignore it if the UID doesn't exist. 3.2 - REMOVE Removes an entry from an existing UID. Syntax: REMOVE "[Entry:Value]" -or- REMOVE "[ENTRY]" Parameters: [Entry:Value] - The iCalendar entry AND value as it is in the calendar file. This part must be enclosed in the current QUOTESTRING string. [Entry] - Alternate syntax. Removes the first entry of type ENTRY from the current UID. Failure: Entry:value or Entry does not exist. 3.3 - ADD Adds an entry to an existing UID. Syntax: ADD "[Entry:Value]" Parameters: [Entry:Value] - The iCalendar entry AND value as it is in the calendar file. This part must be enclosed in the current QUOTESTRING string. Failure: If adding the contents was not possible.