Add contiguous mode to the Builder

[synek317]

Closes #227

There are many ways to implement this. Here is my proposal, I'm open to any suggestions.

[alexcrichton]

Perhaps a more descriptive name like "skip_footer_section" or something like that could be used instead of "contiguous" too?

[alexcrichton]

Since finish() is a public method, I think that it might be best if this check is folded into there? That can just keep the documentation, though, that it is not required to be called.

[synek317]

I've introduced finalize since I wanted to give the user the possibility to write the 'footer' section, as you can see in the example.

I could move the check to finish and then create public method write_footer_section. Then this:

let mut builder = tar::Builder::new(...);
builder.skip_footer_section(true);
builder.finish();

would have no effect and would need to be transformed into:

let mut builder = tar::Builder::new(...);
builder.skip_footer_section(true);
builder.write_footer_section();

[alexcrichton]

I think though that this implementation, as-is, doesn't work. If you call finish it ignores the skip_footer_section flag introduced here, which I think is a bug. I think it'd be fine to basically say that finish is optional if skip_footer_section is true.

[synek317]

It does work, please take a look at the example I've added to examples/ or even tests. But I see your point, I will rename contiguous to skip_footer_section and move

self.get_mut().write_all(&[0; 1024]) 

To new public method write_footer_section. Would that work in your opinion?

[alexcrichton]

Yes while it works I think it's too confusing. I think adding a separate method makes sense. That way there's a flag to disable auto-inclusion of the footer and in that scenario you can either create a tar::Builder at the end with the flag enabled or you can manually call the footer write.

[synek317]

Perhaps a more descriptive name like "skip_footer_section" or something like that could be used instead of "contiguous" too?

Indeed, skip_footer_section sounds much more readable. I was checking various tar format descriptions and it seems there is no fancy name for this. The official documentation uses 'end-of-archive entry' which is too long I guess.

[synek317]

I've introduced finalize since I wanted to give the user the possibility to write the 'footer' section, as you can see in the example.

I could move the check to finish and then create public method write_footer_section. Then this:

let mut builder = tar::Builder::new(...);
builder.skip_footer_section(true);
builder.finish();

would have no effect and would need to be transformed into:

let mut builder = tar::Builder::new(...);
builder.skip_footer_section(true);
builder.write_footer_section();