CC Config API v1.0.0

Forge-like Configs for ComputerCraft



After recently updating CC Autotyper I noticed a thread was brought to the top again that was an INI-like file API but that had it's own issues. After seeing the API I decided to release one I had been using for a long time that is actually a Port of a Derivation… CC Config is a port of my Robotics Configuration API that is heavily inspired by the MinecraftForge Configuration API. So this cleaned up and proper port of a derivation will look very similar with a lot of functionality. Used in debugging, this API also includes some Global debug functions and a global table, this is cleaned up when os.unloadAPI is called for CC Config but even if it is not there has been thorough testing to prevent issues from overriding os.unloadAPI.

This API provides flexibility and consistency without sacrificing human readability or functionality. The file format that is spit out is intended to be both clear and easy to edit with little or no instruction. But. Please read the demonstration code before asking questions.

For those looking for Demo Code/Usage examples, see below or see this pastebin. The pastebin DOES NOT include the resultant hiddencfg.cfg and knowncfg.cfg files seen in the spoiler. A more detailed API documentation is coming soon after I clean up the code further.
Demonstration Code/Quick Start
Code

os.loadAPI('/configuration')

--// Initializes debugging for CC Config
--# this sets the log tag to 'demo':upper()
--# Location: /.config-tmp/VERSION/log.txt
cc_config_init_debug('demo')

--# Creates a Config in /.config-tmp/VERSION called 'hiddencfg.cfg'
local hidden = configuration.new('hiddencfg', 'A Config File Hidden in a Hidden Directory')
--# Creates a Config in / (the root directory) called 'knowncfg.cfg'
local known = configuration.new('knowncfg', '/', 'A Config Not Hidden')


--# This is exclusively logged to the CC Config Log File
--# iff cc_config_init_debug was called previously
--# LogLevels tell what the message should be tagged with.
--# Supports INFO, WARN, and ERROR ('INFO', 'WARN', 'ERR' tags respectively)
--# Also has aliases in lowercase (INFO==info) and expanded (WARN==warning)
cc_config_debug(LogLevels.WARN, 'Successfully initialized configs...')
cc_config_debug(configuration.LogLevels.INFO, 'We can also %s messages. More than %4d :)/>/>/>/>/>/>/>/>/>/>/>/>/>', 'format', 256)
cc_config_debug(LogLevels.err, 'For when you don\'t want to THROW an error')

--# Error messages will actually throw an error and will log to the log file
--# cc_config_error('You can error too')
--# cc_config_error('Even with %s messages', 'format')


--# You can GET Strings, Numbers, Booleans and Lists (tables)
--# If these values do not exist, they create them in the cfg and return the default value
--# If they do exist, the cfg value is used but min, max and valid values are overwritten
local exampleString = hidden:getString('exampleStr', 'category', 'defaultValue', 'Element Comments', {'validValues', 'defaultValue'})
local exampleNumber = hidden:getNumber('exampleNum', 'category', 0.00612354, '', 0, 1)
local exampleBoolean = hidden:getBoolean('exampleBool', 'othercategory', true, '')
local exampleList = hidden:getList('exampleList', 'category.subcategory', {1, 2, 'wow', true}, '', {1, 2, 'wow', true})
local exampleList2 = hidden:getList('exampleList2', 'category.subcategory', {'one', 90.214, false})
print(table.concat(exampleList2, ', '))


--# You can even get the ConfigValue objects themselves
local configValueObj = known:get('category', 'testCV', 'someValue', 'Comments')
local configValueObj2 = known:get('othercategory.sub', 'testCV', 256, '', 0, 256)

configValueObj:set('someOtherValue')
configValueObj:setValids({'someValue', 'someOtherValue'})
configValueObj2:set(512)
configValueObj2:setMax(512)

print(configValueObj:getRaw())
print(configValueObj:getString())
--# configValueObj:getNumber() will error
print(configValueObj2:getNumber())

--# You can set category comments by file or retrieve the ConfigCategory object and set it there
hidden:setCategoryComment('category', 'Example of Setting Category Comments')
hidden:getCategory('category.subcategory'):setComment('Another Way to set Category Comments')


--# You MUST save to write out any changes to the cfg file
hidden:save()
known:save()


--# Not required necessarily, but recommended
--# handles cleaning _G of CC Config functions
os.unloadAPI('configuration')
hiddencfg.cfg result

# A Config File Hidden in a Hidden Directory Configuration File

othercategory {

   #  [default: true]
   B:exampleBool=true
}

##############################################################
# category
#------------------------------------------------------------#
# Example of Setting Category Comments
##############################################################

category {

   # Element Comments [default: defaultValue]
   S:exampleStr=defaultValue

   #  [default: 0.00612354]
   N:exampleNum=0.00612354

   ##############################################################
   # subcategory
   #------------------------------------------------------------#
   # Another Way to set Category Comments
   ##############################################################

   subcategory {

	  #  [default: [ 1, 2, wow, true ]]
	  N:exampleList <
		 1
		 2
		 true
		 wow
	   >

	  #  [default: [ one, 90.214, false ]]
	  S:exampleList2 <
		 one
		 90.214
		 false
	   >
   }

}
knowncfg.cfg result

# A Config Not Hidden Configuration File

othercategory {

   sub {

	  N:testCV=512
   }

}

category {

   # Comments
   S:testCV=someOtherValue
}