debian: functions module for shellfire

This module provides a simple framework for parsing Debian constructs. Currently, this consists of Debian control files, although specific support is only implemented for the copyright format. Other parsers are trivial to implement - look at the code in copyright.functions. The parser validates format, syntax, checks for duplicates and verifies that mandatory fields are present.

An example user is swaddle.

Compatibility

• Tag release_2015.0117.1750-1 is compatible with shellfire release release_2015.0117.1750-1.

Overview

Usage couldn't be simpler. To parse a Debian copyright file, try:-

debian_control_copyright my_callback /usr/share/doc/swaddle/copright

where my_callback is a function that accepts parse events:-

my_callback()
{
	local fileFormat="$1"
	local paragraphType="$2"
	local eventType="$3"
		
	# 'Copyright'
	echo "File Format $fileFormat"
	
	# 'Header', 'Files' or 'License'
	echo "$paragraphType"
	
	# 'ParagraphStart', 'ParagraphEnd' or 'Field'
	echo "$eventType"
	
	if [ "$eventType" = 'Field' ]; then

		local fieldName="$4"
		local fieldType="$5"
		
		# eg 'Format'
		echo "$fieldName"
		
		# eg 'singleLine' (see docs)
		echo "$fieldType"
		
		# Depending on fieldType, you can get to values with debian_control_parser_fieldValueFirstLine, debian_control_parser_rawLines (an array), debian_control_parser_fieldValue (for folded fields) or debian_control_parser_continuationLines (for fields with a synopsis or list)
	fi
}

Of course, you can implement your own parsers by defining a paragraph handler, eg:-

debian_control_parser_myParagraphHandler()
{
	…
}

debian_control_parser my_callback debian_control_parser_myParagraphHandler no /usr/share/doc/swaddle/copright

Importing

To import this module, add a git submodule to your repository. From the root of your git repository in the terminal, type:-

mkdir -p lib/shellfire
cd lib/shellfire
git submodule add "https://github.com/shellfire-dev/debian.git"
cd -
git submodule init --update

You may need to change the url https://github.com/shellfire-dev/debian.git above if using a fork.

You will also need to add paths - include the module paths.d.

You will also need to import the unicode module.

Namespace debian_control_copyright

This namespace contains the core functionality needed to parse Debian control copyright files.

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn debian/control copyright

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn debian/control copyright
	…
}

Functions

---

debian_control_copyright()

Arguments deliberately not described. Pass this function as the paragraph argument of debian_control_parser() to parse Debian copyright file.

Parameter	Value	Optional
eventHandler	Function to handle parser events.	No
copyrightFilePath	Path to Debian copyright file to parse.	No

See the description of debian_control_parser() for documentation of the eventHandler.

---

Namespace debian_control_parser

This namespace contains the core functionality needed to access the API.

To use in code

If calling from another shellfire module, add to your shell code the line

core_usesIn debian/control parser

in the global scope (ie outside of any functions). A good convention is to put it above any function that depends on functions in this module. If using it directly in a program, put this line inside the _program() function:-

_program()
{
	core_usesIn debian/control parser
	…
}

Functions

---

debian_control_parser()

You are advised to not use this function directly, but instead use specific parsers:-

• debian_control_copyright()

Parameter	Value	Optional
eventHandler	Function to handle parser events.	No
paragraphHandler	Function defined to handle file subformat (paragraphs).	No
commentsAllowed	Boolean. Comments are only normally allowed in debian/control package source files. If in doubt, use yes.	No
controlDataFilePath	Path to Debian control file to parse.	No

The callback function is the following arguments:-

Variable	Description
fileFormat	The file format. Dictated by first paragraph kind. Not useful as you know this, unless writing a generic paragraph function or eventHandler.
paragraphType	The start or end of an object or array. The type of value: boolean (including null), number or string
eventType	The parse event name. One of ParagraphStart, Field and ParagraphEnd. If ParagraphStart is raised, one or more Field will be raised next followed by ParagraphEnd.
fieldName	Only passed if eventType is Field.
fieldType	Only passed if eventType is Field.

If eventType is Field, then the following variables are (locally) in scope depending on the value of fieldType:-

Variable	fieldType	Description
debian_control_parser_fieldValueFirstLine	Any	Value of first line, trimmed
debian_control_parser_fieldValue	Any	As above but with foldedCommas / foldedWhitespace unfolded.
debian_control_parser_rawLines	Any	All lines, including first
debian_control_parser_continuationLines	Any	Trimmed continuation lines, but includes first line for multilineList and multilineWithoutSynopsis

fieldType may be one of:-

Value	Description
singleLine	A single line. The commonest type
foldedCommas	A folded line; folding uses commas. Only used in source control files, eg Uploaders
foldedWhitespace	A folded line; folding uses whitespace. Only used in source control files, eg .changes' Binary
multilineListBlankFirstLine	Multiple lines, first blank, eg Checksums-Sha1
multilineList	Multiple lines, first blank, eg Upstream-Contact
multilineWithSynopsis	Multiple lines, first synopsis, eg Description, License
multilineWithoutSynopsis	Multiple lines, no synopsis, eg Comment

Additionally, the function debian_control_parser_outputRawFieldLines' can be called to write to standard out the current field exactly as read.

If eventType is ParagraphEnd, then the array variable debian_control_parser_fieldsInParagraph contains the fields found in the paragraph.

---

debian_control_parser_outputRawFieldLines()

Takes no arguments. Writes to standard out the current field exactly as read when the eventType is Field.

---

debian_control_parser_continuationEventNotWanted()

Intended for implementation of paragraphHandler functions. Description omitted. May change.

---

debian_control_parser_warning()

Intended for implementation of paragraphHandler functions. Description omitted. May change.