english
version "1.0"
identify "xyz"

#: Copyright (c) 1995, 2002 by Wayne C. Gramlich.
#, All rights reserved.
#,
#, Permission to use, copy, modify, distribute, and sell this software
#, for any purpose is hereby granted without fee provided that the above
#, copyright notice and this permission are retained.  The author makes
#, no representations about the suitability of this software for any purpose.
#, It is provided "as is" without express or implied warranty.

module version

#: This module implements the {version} type for SVMS history files.

define version				#: One version in history file
    record
	chunks chunks			#: Mixed file and comment chunks
	comments chunks			#: Comments value
	contents chunks			#: File contents
	creator_name string		#: Creator's name
	executable logical		#: {true}=>executable
	history history			#: Parent history object
	is_binary logical		#: {true}=>binary;{false}=>text
	max_number unsigned		#: Highest delta version number
	min_number unsigned		#: Lowest delta version number
	offset unsigned			#: Offset number
	resources resources		#: Parent resources object
	timestamp unsigned		#: Version timestamp
    generate address_get, allocate, erase, identical, print



#: {version} procedures:

procedure xallocate@version
    takes
	history history
    returns version

    #: This procedure will allocate and return a {version} object
    #, that is part of {history}.


procedure compare@version
    takes
	version1 version
	version2 version
    returns integer

    #: This procedure will return -1, 0, 1 depending upon whether
    #, {version1} has a name that is less than, equal to, or greater
    #, than the name of {version2} respectively.


procedure deallocate@version
    takes
	version version
    returns_nothing

    #: This procedure will deallocate {version} and make it available for
    #, for subsequent reallocation.

    #, deallocation will occur when {chunks} is deallocated.

    #format@format1[address](debug_stream,
    #  'deallocate@version(%X%) returns\n\', version.address)



procedure equal@version
    takes
	version1 version
	version2 version
    returns logical

    #: This procedure will return {true} if {version1} is the same as
    #, {version2} and {false} otherwise.


procedure greater_than@version
    takes
	version1 version
	version2 version
    returns logical

    #: This procedure will return {true} if {version1} is greater than
    #, {version2} and {false} otherwise.


procedure less_than@version
    takes
	version1 version
	version2 version
    returns logical

    #: This procedure will return {true} if {version1} is less than
    #, {version2} and {false} otherwise.


procedure line_comments_insert@version
    takes
	version version
	comments string
    returns_nothing

    #: This procedure will insert {comments} into the contents portion
    #, of {version}.


procedure line_contents_insert@version
    takes
	version version
	contents string
    returns_nothing

    #: This procedure will insert {contents} into the contents portion
    #, of {version}.


procedure number_manage@version
    takes
	version version
	number unsigned
    returns_nothing

    #: This procedure will set keep track of the minimum and maximum
    #, delta number for {version}.  This code is provided as tie-breaker
    #, for sorting {version} objects  when they have the same timestamp.
    #, See {compare}@{version}() for the details.


procedure ranges_remove@version
    takes
	version version
    returns_nothing

    #: This procedure will remove all of the {chunk}'s of type {range}
    #, from {version}.{chunks}.


procedure read@version
    takes
	data_in_stream data_in_stream
	history history
    returns version

    #: This procedure will read a version object in from {data_in_stream}
    #, and return it.

    #: Read in the chunks:
    #: Read in the content {chunk_ranges}:
    #: Read in the comment {chunk_ranges}:

procedure string_append@version
    takes
	version version
	text string
    returns_nothing

    #: This procedure will append the contents of {versin} onto the end
    #, of {text}.


procedure unshare@version
    takes
	version version
	share_table set[chunk]
    returns_nothing

    #: This procedure ensure make each {chunk} in {version}.{chunks}
    #, is no longer in {share_table}.


procedure write@version
    takes
	version version
	data_out_stream data_out_stream
	share_table set[chunk]
	header_timer timer
	verify_timer timer
	remove_timer timer
	share_timer timer
	bind_timer timer
	sort_timer timer
	convert_timer timer
	chunks_timer timer
	ranges_timer timer
    returns_nothing

    #: This procedure will write out {version} to {data_out_stream} using
    #, {buffer} as a temporary string buffer.  {share_table} is used
    #, to detect sharable {chunk}'s.  This routine must be called
    #, increasing {version}'s in order to work properly.

    #, looks.  We want all the {chunk}'s to show up in the history file
    #, in a determanisitc order.  First, we make sure that we have
    #, identified all previously sharable {chunk}'s.  Second, we want
    #, the {chunk}'s that are first used in this version to show up in
    #, "first used" order starting with the contents and then the comments.
    #, The range {chunk}'s are added to {version}.{chunks} later.