Awesome

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.

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()

The callback function is the following arguments:-

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

fieldType may be one of:-

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.