Main
Latest
About
Photos
WebCam
Words
Graphics
RISC OS
AMPlay
SpriteUtils
Recurse
BitField
Diary
Macros
Options
Scripts
History
Fan
Icons
Music
Links
Credits

Site Map

 Diary 

Scripts

The script file is basically a set of instructions that tell Diary how to put togther a compiled single file containing a set of entries from the journal. Exactly what that file looks like is entirely up to you - it needn't be HTML, but can be any text-readable format.

This file can be assembled from pre-existing fragments, or can be defined entirely within the script itself.

The script may create more than one output file by supplying the instructions necessary for each file in turn.

The basic format of the script file is;

# script file

command1:value1
command2:value2
...
command(n):value(n)

#end

Like the options file, a '#' can be used as a comment. However because were running commands rather than setting variables (for the most part), a ':' is used to separate the command from the value. Note that spaces are handled rather differently than in the options file - leading spaces at the start of the line won't cause problems, nor will spaces between the command and the ':', but any spaces after the ':', and any trailing spaces on the line will be treated as part of the value, and may end up in the output file. This is because you may well want to do this deliberately if you are using indenting etc.

Top.

Available Commands

Command	Meaning	Typical value	Macros Expansion
output	defines output filename (overwrites it)	diary/html	Y
continue	defines output filename (appends to it)	diary/html	Y
output entry	Sets output to be current entry in the journal	No Value	N 1
type	sets filetype of current output file (decimal)	4015 (HTML)	N
add fragment	appends specified fragment to current output file	fragment1	N
add meta	adds Diary meta tag (see options)	No Value	N
add comment	adds Diary comment tag (see options)	No Value	N
add line	appends value to current file, with a carriage return at the end	%we, %zdy%st of %mo %ye	Y 2
add line_nocr	as 'add line' but without the carriage return	%we, %zdy%st of %mo %ye	Y
add entry	appends current entry from journal to output file	No Value	N
set date	modifies internal date to be one of; Today, Tomorrow, Yesterday.	Today	N
unset date	restores date to previous value following a set date command	No Value	N
set day	modifies the current day by the specified value (+/- sign must be specified)	+1	N 3
set month	modifies the current month by the specified value (+/- sign must be specified)	+1	N 3
set year	modifies the current year by the specified value (+/- sign must be specified)	+1	N 3
loop down	starts a loop process downwards through the entries in the current month	No Value	N
loop up	as 'loop down' but counts upwards	No Value	N
main_entry	section marker within a loop	No Value	N
first_entry	optional marker within a loop	No Value	N
last_entry	optional marker within a loop	No Value	N
single_entry	optional marker within a loop	No Value	N
end main_entry	closes section within loop. Also 'end first_entry', 'end last_entry' and 'end single_entry'.	No Value	N
end loop	ends loop	No Value	N
end file	defines end of output file. Output file is undefined unless a further 'output' command is used.	No Value	N

1: This command should only be used when using a script to generate new journal entries.
2: The line to be appended should be no more than approx 250 characters long (either before or after macro expansion). If you need longer lines than this in your output file, then break the line down into smaller chunks, and for every chunk except the last one use the 'add line_nocr' command instead of 'add line'. This means that all these lines are appended into a single line in the output file. There is therefore no limit on the line lengths achievable within the output file.
3: 'current' refers to the date specified in the main window when you click on 'Make'

Top.

Example 1 - The Basics

All these example scripts are supplied in the scripts directory for you to tinker with . . .

Starting with something simple - just taking a single entry and adding HTML headers and footers to it . . .

# diary 0.06 example1

output:test/html
type:4015
add line:<html>
add line:<head>
add meta:
add line:<title>Test page created on %we, %zdy%st %mo %ye.</title>
add line:</head>
add line:<body>
add line:<h1>Journal Entry on %we, %zdy%st %mo %ye</h1>
add line:<p align="left">
add entry:
add line:</body>
add line:</html>
end file:

#end

On running diary with that as the script file, and clicking 'Make' on a date for which an entry exists (lets take 26th March 2000 as an example), you'd get an test/html file in the output directory defined in the options file of;

<html>
<head>
<meta name="generator" content="!Diary v0.06">
<title>Test page created on Sunday, 26th March 2000.</title>
</head>
<body>
<h1>Journal Entry on Sunday, 26th March 2000</h1>
<p align="left">
[ . . . actual contents of entry for that day . . .]
</body>
</html>

Get the idea?

Top.

Example 2 - Fragments

Note that some of the 'add line' commands don't have macros in them. This is perfectly fine - you can have any text in the add line command, it doesn't have to contain macros. However, if you have a large sequence of add line commands and not a macro in sight, you might be better off taking the corresponding lines, and saving them as a fragment in the Fragments directory. The example above doesn't have any sections really big enough to make this worthwhile, but as an example, if we created a file called 'Fragment1' in the Fragments directory, and gave it the contents;

<html>
<head>

And then amended our example script as follows;

# diary 0.06 example2

output:test/html
type:4015
add fragment:fragment1
add meta:
. . .

The resulting output file is the same, but the script is more compact, and only needs to contain those sections of the output file which require macro expansion. You could also use the same fragment from different scripts, and if a modification was required, you would only need to modify the fragment rather than having to modify each script individually.

Top.

Example 3 - Loops

output:%ce%yr_%mn
type:4095

# Header
add line:Archive of entries from %mo %ce%yr.
add line:Entries listed:-

# Generate a list of all the entries in the current month
loop up:
main_entry:
# using the nocr variant so that they all end up on one line
# (also note that the line below has a trailing space so that the
# entry numbers don't run into each other)
add line_nocr:%dy 
end main_entry:
end loop:

Ok, there is more to this script below, but I'll cut in here to explain what is going on - I'm assuming you understand everything up to the 'loop up' . . .

What happens at the 'loop up' is that Diary scans forward in the script until it hits an 'end loop' command. The section between the 'loop up' (or 'loop down') is then run for each entry in the current month. The section between these points may contain sub-sections as follows;

main_entry - used when none of the below apply or are not present.
first_entry - used when the entry is the first one of several.
last_entry - used when the entry is the last one of several.
single_entry - used when there is only one entry (i.e. it may need both first and last details on it)

Each section must have a corresponding 'end *_entry' marker.

The main_entry has to exist in order for the loop to be valid - the others are all optional, and Diary will just use main_entry for those cases instead. Any commands which are within the loop start and end markers, but are not inside the section markers given above will be ignored. The sections can be in any order.

In our example we just have the main_entry section, so what Diary does is start counting from 1 up to 31, and if that particular entry exists (in the format specified by the journal options), then it runs the relevant section of script between the 'main_entry' and 'end main_entry' markers, appending the results to the current output file. While it is running the script for each entry, the macros will expand as if the date was that of the entry in question, so if entries exist for the 2nd, 3rd and 4th of the current month, then the above loop would generate '02 03 04' as its output, assuming that the journal_day format was %dy.

Note that only the day of the month/week/year is adjusted when dealing with loops, the month, year and time macros still return current information (which means that the time macros are fairly pointless in loops, and are only recommended for scripts that create entries)

Hopefully this is making some kind of sense, so lets carry on with the rest of the script;

# some spacing to keep the header separate from the main content
add line:
add line:---

# another loop, this time including the actual entries themselves.
loop up:
main_entry:
add line:
add line:%we, %mo %zdy%st
add line:
add entry:
add line:  
add line:---
end main_entry:
end loop:

# footer
add line:
add line:End of Archive

end file:

#end

Ok, this is basically just more of the same, but with more content to the main_entry section, and this time we are actually adding the entries themselves to the output file.

Top.

Example 4 - Creating a New Entry

A script to create a new entry is essentially the same as any other sort of script, with some minor differences;

It is run when you click on 'Create' to create a new entry.
It must generate an entry in some form or another (although it can do other things as well).
It can make more sensible use of the time macros.

Here's a typical script to create new entries - this one is called NewEntry in the scripts directory to keep it distinct from the other scripts which place things in the output directory.

# Diary 0.06 script

# New Entry
output entry:
type:4095
add line:%24:%mi
add line:
end file:

#end

When you click on Create, this will generate a file of type HTML, with the current time in 24 hour format and a couple of line feeds in it - this will then be sent to the current text editor in the same way as a normal entry would.

Note that this script is only run to create the entry, it doesn't get run when you edit an existing entry.

Top.

Example 5 - More complex loops

Here's how to deal with the situation where you are generating an output file containing all the entries in a particular month, and want them to have something keeping the entries separate that also refers to the other entries. For example, after each entry, you might want to have links (assuming HTML again) to the previous and next entry. The following script segment would do the trick;

loop up:
main_entry:
add line:<hr>
add line:<a name="%ec">%we, %mo %zdy%st</a>
add entry:
add line:<hr>
add line:<a href="#%ep">Previous</a><a href="#%en">Next</a>
end main_entry:
end loop:

Which is all very well, and will add previous/next links after each entry, however that won't work too well for the first entry in the month - these links we're using are all internal links within the current page. So, we want a first_entry section to deal with this eventuality;

loop up:
main_entry:
 . . . as before . . .
end main_entry:
first_entry:
add line:<hr>
add line:<a name="%ec">%we, %mo %zdy%st</a>
add entry:
add line:<hr>
set month:-1
add line:<a href="diary_%ce%yr_%mn/html#%el">Previous</a><a href="#%en">Next</a>
unset month:
end first_entry:
end loop:

That aside, this works well - the first entry in the page links back to the previous page, while the other entries on the page link back to the previous entry within the page.

If you think about it, there is a similar problem with the links to the next entry, which would lead us to add a last_entry section with the link to the next entry removed (after all, we can be fairly certain that there won't be an entry beyond that point).

Having done that, you'll also need to add a single_entry section - this is to handle the case where there is only one entry in he current month, and so the modifications that we made in first_entry and in last_entry both need to apply together. The complete script segment would then be;

loop up:
main_entry:
add line:<hr>
add line:<a name="%ec">%we, %mo %zdy%st</a>
add entry:
add line:<hr>
add line:<a href="#%ep">Previous</a><a href="#%en">Next</a>
end main_entry:

first_entry:
add line:<hr>
add line:<a name="%ec">%we, %mo %zdy%st</a>
add entry:
add line:<hr>
set month:-1
add line:<a href="diary_%ce%yr_%mn/html#%el">Previous</a><a href="#%en">Next</a>
unset month:
end first_entry:

last_entry:
add line:<hr>
add line:<a name="%ec">%we, %mo %zdy%st</a>
add entry:
add line:<hr>
set month:-1
add line:<a href="%ep">Previous</a>
unset month:
end last_entry:

single_entry:
add line:<hr>
add line:<a name="%ec">%we, %mo %zdy%st</a>
add entry:
add line:<hr>
set month:-1
add line:<a href="diary_%ce%yr_%mn/html#%el">Previous</a>
unset month:
end single_entry:

end loop:

Top.

Example 6 - Last Modified dates etc

The set month commands used above can be quite useful, but suppose you need to set the date to the actual current date (as opposed to the date that was clicked on on the main window. The most likely use for this would be to add a page last modified line to the bottom of the output file.

This is fairly simple;

set date:Today
add line:Last Modified: %zdy.%zmn.%ce%yr
unset date:

Note that this is another situation where the time macros can be used to give sensible output.

Diary.

Top.