Project Name Ical Converter
Authors
Henry Dang
Peter Mangelsdorf
Contact Information
Henry Dang at hd349@drexel.edu
Peter Mangelsdorf at pjm349@drexel.edu
----------------------------------------------------------------------------------------------------------------------------
Description
Ical Converter (icalconv) takes an .ics file and converts it into an html file
that contains a single table. It has several dependencies. For icalconv to
work, your awk version should be at least version 1.3.3, and you must have
dos2unix with at least version 7.3.4. If you are missing either of these, they
can easily be installed, if you are on Ubuntu, with sudo apt-get install awk and
sudo apt-get install dos2unix.
To build icalconv for your system, you must first use make build.
Then, run icalconv.sh file_name.ics, where file_name.ics is the name of your ics
file.
As part of the build procedure, icalconv will generate multiple files, including
a `headers` file, a `temp_out` file, a `out.html` file, and an `ideal.ics.tetmp`
file. The only file here that is relevant to the user is the `out.html` file.
Open the `out.html` file in either Google Chrome or Mozilla Firefox, and you
will see your ics file in a table format.
To delete all of the generated files, including the html file, simply run make
clean.
Note that you should *not* execute the `run` target via `make run` on your own.
You should run the icalconv script to call the makefile, because the icalconv
script will check that the file exists and has an *.ics extension.
Furthermore, icalconv can work on a URL as well, by running `icalconv.sh
URL_HERE`, where `URL_HERE` is a valid URL. Note that if you supply an invalid
URL, it will not work, and will give an error. Additionally, you cannot use this
functionality if you are running this script inside one of Drexel's servers,
because `wget` does not run correctly on Tux due to unknown reasons.
----------------------------------------------------------------------------------------------------------------------------
Technical
Ical Converter uses these scripts in this order:
clean_ics.sh | wget_remove.sh | get_table_headers.sh | pad_empty_fields.sh | generate_html.sh
A combination of bash and awk scripts is used. The awk scripts are invoked with
bash scripts. Here is a brief overview of each script:
clean_ics.sh
Finds and removes all VALARMs from the ics file. Generates a
file called temp_out that has all of the VALARMs removed.
get_table_headers.sh & get_table_headers.awk
Builds a list of html headers based on the headers in the ics file.
get_table_headers.sh has get_table_headers.awk as a dependency. It will
generate a file called `headers` with all of the unique headers in the
file.
pad_empty_fields.sh & pad_empty_fields.awk
Pads out any missing fields in the headers list by setting that missing
field to a blank string. This script is called repeatedly for every
VEVENT in an ics file. For example, not all VEVENTs have a URL field,
but if even a single VEVENT has a URL field, then all of them will have
the URL field set to an empty string. This is done to make it easier to
generate the HTML table.
generate_table.sh & generate_table.awk
generate_table.sh depends on generate_table.awk. It will generate a file
called `out.html`. It relies on the `headers` file generated by
`get_table_headers.sh`. The `out.html` file will be the desired output,
with the ics file converted into a table format that can be opened by
opening the `out.html` file in Google Chrome or Mozilla Firefox.
Makefile
Consists of 4 main procedures: "build", "clean", "test", and "run". All
of these are phony targets. The `build` procedure will simply `chmod
+x` all of the scripts in this project. There is no actual "building"
since all of the scripts are in bash or awk.
The Makefile also has a `generate_headers` and a `generate_clean`
target, which are phony targets, used as dependencies in the `run`
target to make the Makefile more modular.
The `clean` target will remove all of the ics files in the directory, as
well as any generated files, such as the html file and the temporary
output files. This includes any generated test files in the test directory.
The `clean-non-test` target does the exact same thing as clean, but will not
delete the generated test files in the test directory.
The test target will compare the generated html files to the expected
html generated output, for all of the ics files in the `test` directory.
We will now go into more detail on each script's behavior and usage. All scripts
are located within the, "scripts," directory, and all testing files are located
within the, "test," directory.
----------------------------------------------------------------------------------------------------------------------------
clean_ics.sh
Step 1 of the ics cleaning process. Utilizes a while loop and sed to
remove VALARMs. These need to removed, because they do not translate
well to html tables, so we find and eliminate any instances of them.
Furthermore, we are required to remove them, as per our specifications
document.
get_table_headers.awk
Finds any lines with, "BEGIN:VEVENT," and,"END:VEVENT," and grabs all
of the fields that exist between them. This will generate a list of
every single VEVENT field parameter, with duplicates. (eg; multiple URL
descriptors, UID descriptors, and Location descriptors)
get_table_headers.sh
Calls get_table_headers.awk, passes it into sort and uniq to remove
the duplicates, and to give us all of the unique table headers for our table,
which corresponds to all of the unique field parameters in our ICS file.
pad_empty_fields.awk
Accepts two arguments, the first one is the aforementioned "headers" file, and
the second one is your cleaned ICS files (without VALARMs).
It will loop over every single field parameter in the "headers" file
and add them into a dictionary with the field parameter as the key, and
the value as a blank string. Then, it loops through every field
parameter in the ICS file, and every single field parameter in the
dictionary is set to its corresponding value in the ICS file. This
guarantees that all of the field parameters in the ICS file are set,
and any ones that are missing will already have been assigned to a
blank string. For example, if an ICS file has a VEVENT that is missing
a URL field, it will automatically be padded out by adding a URL field
with an empty string.
pad_empty_fields.sh
Requires the ICS file that you want to pass in, and a file named
"headers" to exist, and passes it to pad_empty_fields.awk. Otherwise
returns an error statement if either of these files are missing.
generate_table.awk
Adds data into an HTML table by inserting the data in an ICS table into
a file by appending <tr> <td> DATA_HERE </td> </tr>, therefore creating
all of the table rows in the table. This does NOT generate the headers, nor
does it turn it into a true HTML file yet.
generate_table.sh
Builds the HTML head and body, and then creates the <table> and table
header tags. The outupt from generate_table.awk is then added in. This
is to guarnatee that the table headers are added in first, and then the
table data. Finally, the resulting complete HTML file is then ouputted
to out.html
----------------------------------------------------------------------------------------------------------------------------
Testing
A convention of, "ICS_TEST_##," and, "ICS_GOOD_##," is used for
asserting that the program operates correctly. These tests are run from
within the makefile and may be invoked at any time by, "make test." Each
file tests a core competency of our scripts to remove valarms, clean up
text, and check vevents.
The only exception are the ideal.ics and VAlarm.ics files, which are files
that have no edge cases at all. When running make test, these should *never* fail,
because they are the simplest cases possible. If they do fail, all of the other tests
will likely fail as well.