Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/allisterb/alpheus
Cross-platform configuration file parser
https://github.com/allisterb/alpheus
configuration-management dotnet parser
Last synced: 13 days ago
JSON representation
Cross-platform configuration file parser
- Host: GitHub
- URL: https://github.com/allisterb/alpheus
- Owner: allisterb
- License: mit
- Created: 2016-08-09T01:02:21.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2018-02-04T22:06:18.000Z (almost 7 years ago)
- Last Synced: 2024-11-04T15:23:22.032Z (16 days ago)
- Topics: configuration-management, dotnet, parser
- Language: C#
- Homepage:
- Size: 321 KB
- Stars: 22
- Watchers: 5
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Alpheus: Cross-platform configuration file parser
Get the latest release for .NET Standard from the [releases](https://github.com/allisterb/Alpheus/releases) page or through [NuGet](https://www.nuget.org/packages/Alpheus.Core/). Packages built for .NET Framework 4.5+ are also [available](https://www.nuget.org/packages/) or can be built from source.
## About
Alpheus is a parser and query tool for system and server configuration files. Alpheus parses and transforms configuration files into an XML representation which can then be queried using XPATH. E.g. from the following fragment from a MySQL `my.cnf` configuration file:
````
#
# * InnoDB
#
# InnoDB is enabled by default with a 10MB datafile in /var/lib/mysql/.
# Read the manual for more InnoDB related options. There are many!
innodb_additional_mem_pool_size=256M
innodb_buffer_pool_size=20GB
# number of CPU cores dedicated to the MySQL InnoDB backend
innodb_buffer_pool_instances = 4
innodb_log_buffer_size=256M
innodb_log_file_size=1G
bulk_insert_buffer_size=256M
innodb_flush_log_at_trx_commit=2
innodb_flush_method=O_DIRECT
innodb_doublewrite = 0
innodb_file_per_table = 1
innodb_file_format = barracuda
[mysqldump]
quick
quote-names
max_allowed_packet = 16M
[mysql]
#no-auto-rehash # faster start of mysql but no tab completition
[isamchk]
key_buffer = 16M
!includedir /etc/mysql/conf.d/
````
Alpheus transforms the sections and directives in the configuration file into the following XML:
````
...
256M
1G
256M
2
O_DIRECT
0
1
barracuda
true
true
16M
16M
/etc/mysql/conf.d/
````
You can then query the XML representation using the XPATH query language e.g. the following screenshot shows a query of the `Port` directive in the `[mysqld]` section of the `my.cnf` file:
Alpheus is similar in goals to the [Augeas](http://augeas.net/) project but with quite different execution:
* Augeus is written for Linux with only [nascent Windows support](https://github.com/hercules-team/augeas/issues/476) that requires a compatibilty layer like Cygwin. Alpheus runs on any platform with .NET support: .NET Framework, Mono, or .NET Core.
* Augeas is written in C and uses the [Boomerang](https://alliance.seas.upenn.edu/~harmony/) language which is a subset of ML for writing parsers. Alpheus is written in C# and uses the [Sprache](https://github.com/sprache/Sprache) monadic parser combinator library. Parser combinators are a good match for OOP languages with functional bits like C#. Sprache and C# allow you to use functional idioms while incrementally building and testing parsers and reusing existing grammar pieces, e.g. the following code is a part of the Alpheus MySQL grammar:
````
public static Parser KeyName
{
get
{
return AStringFrom(AlphaNumericIdentifierChar.Or(Underscore).Or(Dash));
}
}
public static Parser KeyValue
{
get
{
return AnyCharExcept("'\"\r\n");
}
}
public static Parser QuotedKeyValue
{
get
{
return DoubleQuoted(Optional(KeyValue)).Or(SingleQuoted(Optional(KeyValue)));
}
}
public static Parser SectionName
{
get
{
return
from w1 in OptionalMixedWhiteSpace
from ob in OpenSquareBracket
from sn in SectionNameAString
from cb in ClosedSquareBracket
select sn;
}
}
````
Functions as first-class objects together with LINQ expressions are used to construct the parser grammar in C# while reusing and combining existing parser bits.
* Augeas reads local file-system files only. Alpheus abstracts the I/O operations required for reading files into an interface and can read files from any class that implements the interface. For instance the [DevAudit](https://github.com/OSSIndex/DevAudit) project implements I/O environments for SSH, GitHub, Docker containers et.al and [uses Alpheus](https://github.com/OSSIndex/DevAudit/blob/dd0efc6b459711115450ae7decdf1162b882fe06/DevAudit.AuditLibrary/Servers/PostgreSQLServer.cs#L131) to directly parse and query configuration files from remote environments.
* Alpheus understands the semantics of configuration files in addition to the syntax. For instance Alpheus can recognize MySQL `include` and `includedir` directives and inserts the parsed included files into the XML representation. E.g. from the following MySQL configuration:
````
[mysqlhotcopy]
interactive-timeout
!includedir mysql.conf.d
````
if the `mysql.conf.d` directory has a file called `my.2.cnf` then the following XML will be produced:
````
true
mysql.conf.d
3306
/var/run/mysqld/mysqld.sock
/var/run/mysqld/mysqld.sock
0
````
## Supported formats
Alpheus can parse and query configuration files for the following servers and applications:
* OpenSSH (sshd_config)
* MySQL (my.cnf)
* PostgreSQL (postgresql.conf)
* Nginx (nginx.conf)
* Apache Httpd (httpd.conf)
* Docker (Dockerfile)
* .NET and ASP.NET App.config and Web.Config files
## Usage
### Command Line Interface
Download and unzip the release archive. Type `al -v` and `al -h` (`./al -v` or `./al -h` on Linux) to see the version information and help with using the CLI.
### Library
Install the [NuGet](https://www.nuget.org/packages/Alpheus.Core/) package into your application. You can read and parse a file like this:
`MySQL mysql = new MySQL("path\to\local\file");` See the Alpheus CLI source code and tests for examples on how to use the library.
## Building
Clone the Github repository on to your computer. You can build for .NET Framework with the `build-netfx` script on Windows or `./build-netcfx.sh` on Linux. You can also build for .NET Standard/.NET Core with `build-netcore` on Windows or `./build-netcore.sh` on Linux.