AmsVarFile

AmsVarFile generates DPM and DSM variable declaration files and provides for adding and deleting variables programmatically.

Installation

Add this line to your application's Gemfile:

gem 'ams_var_file'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install ams_var_file

Usage

First, require the gem:

require "ams_var_file"

Note: AmsVarFile can output informative messages to $stdout and $stderr. To have the messages output, set verbose to true (it's false by default).

AmsVarFile::File.verbose = true

Generate a Var File

To generate a DPM var file:

AmsVarFile::File.generate("dpm", "path/to/dpms.gdl")

To generate a DSM var file:

AmsVarFile::File.generate("dsm", "path/to/dsms.gdl")

AmsVarFile will throw an IOError exception if the file already exists.

The generated files will contain markers that allow AmsVarFile to understand where to insert/delete variables. Removing or modifying these markers will result in a InvalidFileFormat exception being thrown.

The markers are:

// START DEFINITIONS

// END DEFINITIONS

// START INITS

// END INITS

The naming convention of the files are dpms.gdl for DPMs and dsms.gdl for DSMs.

Adding Variable Declarations

Before adding a variable to a file, the file must exist. See the generation details above for information on generating a file.

To add a DPM variable:

# var_type can be one of:
#               boolean
#               date
#               datetime
#               money
#               numeric
#               numeric(#) where '#' indicates precision
#               percentage
#               text

var_type = "text"


# var_id is a valid GDL identifier (ie, no spaces or special chars)

var_id = "myDummyVar"


# var_alias is the variable's actual name in the AMS system. It *can*
# contain spaces and such.

var_alias = "My Dummy Var"


# file_path is any valid path to the `.gdl` file to add the variable to.

file_path = "path/to/dpms.gdl"


AmsVarFile::File.add_dpm_var(var_type, var_id, var_alias, file_path)

Adding a DSM variable is virtually the same, except a different method is called:

var_type  = "text"
var_id    = "myDummyDSMVar"
var_alias = "My Dummy DSM Var"
file_path = "path/to/dsms.gdl"


AmsVarFile::File.add_dsm_var(var_type, var_id, var_alias, file_path)

Deleting Variable Declarations

Obviously, deleting a variable from a non-existing file won't work.

To delete a DPM variable:

var_id = "myDummyVar"
file_path = "path/to/dpms.gdl"


AmsVarFile::File.del_dpm_var(var_id, file_path)

Ditto for a DSM variable:

var_id = "myDummyDSMVar"
file_path = "path/to/dsms.gdl"


AmsVarFile::File.del_dsm_var(var_id, file_path)

AmsVarFile will handle the deletion of a non-existing variable gracefully: it will not throw an exception. If verbose is true, you will see a message (output on $stderr) indicating the variable wasn't found.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake rspec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/jmcaffee/ams_var_file.

  1. Fork it ( https://github.com/jmcaffee/ams_var_file/fork )
  2. Clone it (git clone [email protected]:[my-github-username]/ams_var_file.git)
  3. Create your feature branch (git checkout -b my-new-feature)
  4. Create tests for your feature branch
  5. Commit your changes (git commit -am 'Add some feature')
  6. Push to the branch (git push origin my-new-feature)
  7. Create a new Pull Request

License

The gem is available as open source under the terms of the MIT License.

See LICENSE.txt for details.