Xlsxeller

Xlsxeller

엑셀파일에 정의되어 있는 시스템 데이터 테이블의 데이터를 프로그램에서 사용하기
쉽도록 가공하는 유틸리티입니다.

기획 내용을 표현하는 데이터를 곧바로 사용할 수 없으므로, 보통 xml, json, csv등의
파일로 내보낸 후 가공하는 프로그램을 사용하여 바이너리 형태로 변환거나 변환 과정을
생략하고 곧바로 프로그램에서 사용하곤 합니다.

바이너리로 가공하여 사용하는 경우에는 그나마 로딩 속도가 어느정도 확보가 되지만,
텍스트 계열인 xml, json, csv등의 경우에는 엄청난 파싱(parsing) 과정이 있어야 하기
때문에 로딩속도가 절대적으로 느립니다.

또한, 데이터의 오기 또는 누락 등의 이유로 인해서 오류가 있는 경우 실행을 해보기
전까지는 문제점을 쉽게 파악하기 어려운 문제점도 있습니다. 물론 실행후에 확인이
가능한 데이터들도 있겠지만, 적지 않은 경우에는 오프라인 즉, 실행전에 사전 작업을
통해서 확인이 가능한 경우도 많다는 것입니다.

단순 누락으로 인해서 발생하는 문제부터 오탈자 등으로 인한 부정합등의 이슈가 의외로
반복되는 경우를 많이 접하였습니다.

Xlsxeller는 이러한 단순하고 반복적이면서도 사전 검증이 가능한 과정들을 자동화 합니다.

이제 단순 반복과정에서 벗어나서 게임의 퀄리티 향상에 좀더 시간을 사용하세요.

Xlsxeller에서 지원하는 기능

• 텍스트 파일로 익스포트 하는 과정 없이 .xlsx 파일 직접 사용.
• bulit-in primitive 타입지원
• enum, constant 정의 지원.
• 참조 필드.
• 주석 지원.
• Serial Column 지원.
• 테이블 유효성 검증.
• 테이블 데이터를 바이너리 형태로 저장.
• 테이블 데이터를 다루는 코드를 자동 생성.
• 테이블 정의 변경 이력 추적.
• html로 dump.

텍스트 파일로 익스포트 하는 과정 없이 .xlsx 파일 직접 사용.

변환 과정시 쉽게 불러 들일 수 있도록 하기위해 흔히들 json, xml, csv등의
파일로 내보낸 후 변환하는 프로그램에서 불러서 변환 후 사용하거나, 텍스트 파일 자체를
곧바로 사용하는 경우가 흔합니다.

변환 프로그램을 거쳐서 변환하는 경우에는 내보는 과정과 변환하는 과정 두가지 과정이
필요하므로 다소 번거로울수 있습니다.

내보내는 과정만 하고 변환하는 과정을 깜빡했다면, 어찌 될까요? 실수할 여지가 있을 수
있습니다. 그런걸 잊겠냐고 반문할수도 있겠지만, 라이브 상황이나 기타 복잡한 상황에서
급히 작업하다보면 의외로 자주 겪기도 합니다.

단지 과정하나를 줄여주는게 어떤 경우에는 큰 의미가 있을수도 있습니다.

Xlsxeller는 .xlsx파일을 작성후 Xlsxeller 변환 버튼을 클릭만 해주면 끝이므로, 조금더
작업을 단순화 할수 있습니다.

기존 방식대비 json, xml, csv 파일로 내보내는 과정이 생략됩니다.

변환 대상

기본적으로 지정한 폴더에 있는 모든 .xlsx 파일 그리고 그안에 있는 모든 시트들이
변환 대상이 됩니다.

단, .xlsx 파일명 또는 폴더명 앞에 # 를 붙여주면 변환대상에서 제외됩니다.

이러한 기능이 필요한 이유는 모든 .xlsx 파일 및 시트가 변환대상이 되므로 변환대상에서
제외하려면 파일을 삭제하거나, 다른 폴더로 이동해주어야 하는데 이러한 불편한점을
피하기 위함입니다.

또한, 데이터 작성이 마무리 되지 않은 시점까지는 변환대상에서 제외하고 마무리되면
파일 복사 또는 이동없이 곧바로 변환대상이 될수 있도록 할 수 있습니다.

파일명/시트명/컬럼명 앞에 # 를 붙여주면 변환대상에서 제외됩니다.

built-in primitive 타입지원

enum, constant 정의 지원.

테이블 정의외에도 엑셀 파일내에서 enum 및 constant를 정의할 수 있습니다.
enum의 경우 테이블 컬럼 타입으로 지정이 가능합니다. constant는 데이터 값으로 사용이
가능합니다.

enum, constant를 엑셀 파일내에서 정의하는 이유는 기획자의 의도를 곧바로 엑셀
파일내에서 표현하기 위해서입니다. 프로그래머에게 말로 전달한다던지 혹은 별도의
문서로 전달하는 경우 옮겨 적어야하는데, 이때 실수가 발생할 수 있기 때문입니다.

가급적이면, 하나의 파일에서 모든걸 표현하는게 좋을수도 있겠다는 생각으로 지원하게
되었습니다.

테이블 데이터를 바이너리 형태로 저장.

텍스트 형태의 데이터를 게임에서 직접 사용하게 되면, 파싱(parsing) 과정에서 막대한
부하가 걸리게 되므로, 아예 binary로 변환후 프로그램에서 로딩시 별 변환 과정없이
바로 사용할 수 있도록 합니다.

테이블 데이터를 다루는 코드를 자동 생성.

/// <summary>
/// 계정 테이블입니다.
/// </summary>
public partial class AccountTable
{
    ...
    #region Record
    public partial class Record
    {
        #region Properties
        public int Index { get { return index_; } }
        int index_;

        /// <summary>
        /// 초기 레벨 값입니다.
        /// </summary>
        public int LevelDefault { get { return level_default_; } }
        int level_default_;

        /// <summary>
        /// 초기 Zeny 값입니다.
        /// </summary>
        public int ZenyDefault { get { return zeny_default_; } }
        int zeny_default_;

        /// <summary>
        /// 초기 Dia 값입니다.
        /// </summary>
        public int DiaDefault { get { return dia_default_; } }
        int dia_default_;
        ...
    }
    ...
}

위의 예시 코드처럼 테이블 구조를 정의한 C# 코드가 자동으로 생성됩니다.
일반적인 용도로만 사용한다면, 프로그래머는 추가적으로 코드를 작성할 필요가 없습니다.

가급적이면, 생성된 코드가 아닌 사람이 직접 코딩한것 같은 느낌을 줄 수 있도록
노력하였습니다.

코드가 생성되는 모습이 맘에 들지 않으실 경우에는, "CodeGen/" 하위 폴더에 있는
소스 코드를 수정 하시면 됩니다.

현재, C# 외에 C/C++ 코드 생성도 지원합니다. 다만, 라이브러리 의존성(라이센스 이슈)이
있으므로 아직까지는 사용할수는 없습니다.

향후 코드가 정리되는 대로 C/C++ 코드 생성도 지원할 예정이오니 조금만 기다려 주시길
바랍니다.

생성되는 코드에는 다음과 같은 기능들이 포함됩니다.

• 테이블 구조 정의
• 테이블 데이터 읽어오는 함수
• 검색을 위한 도우미 함수들

코드에 생성되는 필드명은 취향에 따라 설정이 가능합니다.

• snake

  int my_integer_variable;
  string my_string_variable;

• camel

  int myIntegerVariable;
  string myStringVariable;

• pascal

  int MyVariable;
  string MyStringVariable;

C#의 경우 생성되는 테이블이나, 레코드 클래스 앞에 아래 그림과 같이 partial
한정자가 지정 되어 있습니다.

public partial class AccountTable
{
    ...
    #region Record
    public partial class Record
    {
        #region Properties
        public int Index { get { return index_; } }
        int index_;
        ...
    }
    ...

이는, 생성되는 코드외에 사용자가 임의로 확장 코드를 추가할 수 있는 기회를 주기 위함
입니다.

public partial class AccountTable
{
    ...
    public Record GetRandomSelection()
    {
        int index = Random.Range(0, Records.Count);
        return Records[index];
    }
    ...
}

위의 코드는 자동 생성되는 코드가 아니며, 프로그래머가 필요에 따라서 임의로 기능을
추가하는 형태입니다. 별도의 .cs 파일을 만들어서 기능을 확장할 수 있습니다.

테이블 유효성 검증.

TODO

참조 필드.

TODO

Serial Column 지원.

위의 예시 그림을 살펴보면, "level_1", "level_2", "level_3" 처럼
연이어서 같은 타입의 컬럼을 나열하여 정의하는 경우가 있습니다.

불행히도, Xslxeller는 아직까지 컬럼 타입으로 배열을 지원하지 않습니다.
예시처럼 어려개의 순서대로 정의한 컬럼이 있을 경우, 프로그램에서 사용하려면 코드량이
늘어날 수 있습니다.

뭐 이런 상황인거죠?

int GetIndexedLevel(int selection)
{
    LevelTable.Record record = LevelTable.GetBySelection(selection);
    switch (selection)
    {
        case 0: return record.Level1;
        case 1: return record.Level2;
        case 2: return record.Level3;
        case 3: return record.Level4;
        case 4: return record.Level5;
        case 5: return record.Level6;
        case 6: return record.Level7;
        case 7: return record.Level8;
        default: throw new System.ArgumentOutOfRangeException();
    }
}

8개까지는 대응한다고 쳐도, 20개 이상이 되는 경우도 간혹 있을 수 있습니다.
이때도 위에서처럼 switch case 를 늘려가면서 처리해야할까?

데이터를 받아서 사용하는 프로그래머 입장에서는 너무 과한 노동력이 필요하게 되고, 테이블
스키마 변경시에 일일히 대응해 주어야하는 불편함이 있습니다.

그래서, 저는 위에서처럼 순서대로 있는 컬럼들은 배열로 취급해 버리면 어떨까하는 생각을
하게 되었습니다.

다만 컬럼에는 규칙성이 있어야합니다. 컬럼명 끝 혹은 중간에 연이은 번호를 붙여야하고
각 컬럼의 타입이 같아야 합니다.

위의 그림처럼 정의 했다면 다음처럼 코드가 생성됩니다.

    ...
    const int kLevelArray_N = 8;
    int[] LevelArray;
    ...

조금더 머리를 써서 다음과 같은 tuple 배열을 처리하도록 합니다.

싱글 튜플, 배열형 튜플을 인식할 수 있으면 좋을듯...

    ...
    ItemInfoTuple ItemInfo; //이 이름과 겹치는 멤버가 이미 있을 경우에는 오류처리를 해주어햐함.
    List<ItemInfoTuple> ItemInfoArray;
    ...

제너릭 리스트로 할지, 배열로 다룰지 옵션으로 설정할 수 있으면 좋을듯...

주석(Comment).

테이블, 컬럼에 주석(설명)을 추가할 수 있습니다. 엑셀의 "메모" 삽입 기능을 통해서
지정이 가능하며, 이렇게 주석을 달아두면, 코드 생성시 자동으로 주석이 코드에 삽입되게
됩니다.

프로그래머는, 생성된 코드만 보아도 데이터 작성자의 의도를 파악할 수 있으므로,
데이터 작성자는 프로그래머에게 알려주듯이 주석을 작성하면, 프로그래머가 데이터
작성자에게 질문하는 내용이 줄어들 것입니다.

위의 예시처럼 필드에 주석을 설정하면, 아래와 같이 코드 생성시에 주석이 추가 됩니다.

/// <summary>
/// 상품 테이블입니다.
/// </summary>
public partial class GoodsTable
{
    public partial class Record
    {
        /// <summary>
        /// 상품 이름: 로컬라이징 텍스트 테이블에 있는 문자열을 사용합니다.
        /// </summary>
        public string Name { get { return ...; } }
        ...
    }
    ...
}

주석을 지정할 수 있는 대상은 다음과 같습니다.

• 테이블 이름
• 컬럼 이름

테이블 정의 변경 이력 추적.

지원 불가. 저장소가 있어야 사용할 수 있습니다.

테이블 내용 html로 보여주기.

읽어들인 정의 요소들 및 데이터를 html 형태로 한눈에 편하게 파알할 수 있도록 합니다.

엑셀파일 작성 규칙

{{table.level}} 와 같은 형태로 정의해야 합니다.
이렇게 조금은 거추장스럽게 해야하는 이유는, 각각의 정의와 기획자가 상세설명을 하나의
시트에 혼재시킬 수 있도록 하는 여지를 주기 위해서입니다.

테이블외의 타입들도 지원합니다.

• table
• enum
• constant

{{table.my_table}}
{{enum.my_enum}}
{{const.my_const}}

html로 dump

TODO

Xslxeller 프로그램 사용법

TODO

명령행 형태로 실행

TODO

TODO

1. nullable 타입 지원.

모호성을 부여할수도 있으므로, 신중한 접근이 필요해보임.

2. 명시적인 배열 지원.
3. 다단계 참조 처리.

재귀적으로 처리하면 되므로 문제될건 없음.

4. {{ignore_header}} 지원.

좀더 깔끔한 방법을 생각해봐야할듯...

5. 자동 인덱스 감지 기능.

모든 값이 유니크하다면, 인덱스로 편입됨. 단 이것은 옵션으로
처리하자. 유니크했다가 유니크하지 않게 되면, 인덱스가 사라지게 되는 현상이 발생할 수
있으므로...

6. C/C++ 코드 생성 일반화.

FAQ

• 유니티(Unity3D)에서 사용이 가능한가요?

  예 가능합니다. 별도의 설정없이 바로 사용이 가능합니다.

• 언리얼/Cocos2D-X에서 사용이 가능한가요?

  아직은 안됩니다. C/C++ 코드 생성시 외부 라이브러리 의존도가 있는데
  표준라이브러리로 대체하는 작업을 진행하고 있습니다. 이부분이 완료되면
  바로 사용이 가능하리라 봅니다.

• 클라/서버 모두 사용 가능한가?

  예 가능합니다. C#, C/C++ 코드가 생성되는 되므로, 프로젝트에 추가해서
  사용하시면 됩니다.

• 공짜인가요?

  완전히 공짜 open-source입니다. 어떠한 댓가도 요구하지 않습니다.
  단, 수정본 재배포시에는 제작자에게 알려주셔야 합니다.
  라이센스 관련 사항은 라이센스 부분을 살펴 보시면 되겠습니다.

개발자

서재형(maxidea1024@gmail.com)

문의 사항이나 개선사항이 있으시면, 알려주세요.

라이센스(License)

MIT License를 따르며, 사용하는데 있어서 발생하는 모든 문제는 사용자의
책임이며, 제작자는 일체의 책임을 지지 않습니다.

Copyright (c) 2018 Seo Jae Hyoung

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.