Symbols - Document and support type mapping for basic PIC symbols (#11)

* Add some PIC and copybook docco

* From doc matrix, prep fallthrough type filter

* Add "complex" length calc

* Update greedy regex

* Update PIC type and length parsers

* Use updated PIC type and length parsers

* Update template and example

* Update binary name and references to it

* Update readme

Author: pgmitche

.golangci.yaml

@@ -14,6 +14,7 @@ run:
   # from this option's value (see skip-dirs-use-default).
   skip-dirs:
     - dummyout
+    - example
   # default is true. Enables skipping of directories:
   #   vendor$, third_party$, testdata$, examples$, Godeps$, builtin$
   skip-dirs-use-default: true

Makefile

@@ -28,12 +28,12 @@ vendor: ## Cleans up go mod dependencies and vendor's all dependencies
 .PHONY: build
 build: clean
 	go build -v \
-		-o ./dist/go-pic \
+		-o ./dist/gopic \
 		cmd/main.go
 
 install: build
-	chmod +x ./dist/go-pic
-	cp ./dist/go-pic $(GOPATH)/bin/go-pic
+	chmod +x ./dist/gopic
+	cp ./dist/gopic $(GOPATH)/bin/gopic
 
 # Automated code review for Go
 .PHONY: tidy
@@ -56,8 +56,8 @@ cover: test ## Runs unit tests and assesses output coverage file
 
 .PHONY: run
 run: build
-	chmod +x ./dist/go-pic
-	./dist/go-pic dir -i dummy -o dummyout
+	chmod +x ./dist/gopic
+	./dist/gopic dir -i dummy -o dummyout
 
 define CHECK_COVERAGE
 awk \

README.md

@@ -15,7 +15,7 @@ Get started using `gopic` by installing the struct-generation tool from the root
 
 ## Tag-based unmarshalling 
 
-go-pic's main focus is enabling simpler 1:1 mapping of PIC definitions to Go structs. 
+`gopic`'s main focus is enabling simpler 1:1 mapping of PIC definitions to Go structs. 
 
 For example, if your PIC definitions look like:
 ```
@@ -38,40 +38,41 @@ type Copybook struct{
 }
 ```
 
-Or you can make use of `go-pics` other feature below, so that you don't have to define the struct yourself...
+Or you can make use of `gopic`s other feature below, so that you don't have to define the struct yourself...
 
 ## Generating tagged structs
 
-`go-pic` provides support to generate flattened Go struct representations of your COBOL copybooks, tagged with length statements and assigned the appropriate type for unmarshalling files that match your COBOL copybook definitions.
+`gopic` provides support to generate flattened Go struct representations of your COBOL copybooks, tagged with length statements and assigned the appropriate type for unmarshalling files that match your COBOL copybook definitions.
 
 `cmd` contains go struct generation tool from textual PIC definitions
 
 Example struct gen usage:  
 
 A file:  
-`gopic file -o mycopybookstruct -i cobolstuff/copybook.txt`
+`$ gopic file -o mycopybookstruct -i cobolstuff/copybook.txt`
 
 A directory of files:  
-`gopic dir -o mystructsdir -i cobolstuff`
+`$ gopic dir -o mystructsdir -i cobolstuff`
 
-When using `go-pic` for struct generation, additional, non-functional values are tagged to the PIC tags, for legibility's sake. 
+When using `gopic` for struct generation, additional, non-functional values are tagged to the PIC tags, for legibility's sake. 
 
-For example, the example struct above, if generated with `go-pic` becomes:
+For example, the example struct above, if generated with `gopic` becomes:
 
 ```go
 type Copybook struct{
-    Dummy1 int      `pic:"4,1,4"`
-    Dummy2 string   `pic:"1,5,5"`
-    Dummy3 int      `pic:"4,6,9"`
-    Dummy4 string   `pic:"40,10,49"`
-    Dummy5 string   `pic:"40,50,89"`
+    Dummy1 int      `pic:"4"`  // start:1 end:4
+    Dummy2 string   `pic:"1"`  // start:5 end:5
+    Dummy3 int      `pic:"4"`  // start:6 end:9
+    Dummy4 string   `pic:"40"` // start:10 end:49
+    Dummy5 string   `pic:"40"` // start:50 end:89
 }
 ```
 
-where the values represent:
+where the values...
 ```go
-Dummy1 int      `pic:"4"` // start:1, end:4
+Dummy1 int      `pic:"4"` // start:1 end:4
 ```
-- 4, pos 1 = length
-- 1, pos 2 = starting index
-- 4, pos 3 = ending index
+Represent:
+- 4 = length
+- 1 = start index
+- 4 = ending index

cmd/pkg/decoder/README.md

@@ -0,0 +1,92 @@
+# PIC clauses in Copybooks
+
+## What does a line in a copybook look like?
+Basic info below sourced from [tutorialspoint](https://www.tutorialspoint.com/cobol/cobol_data_types.htm).
+```
+01            TOTAL-STUDENTS            PIC9(5)            VALUE '125'.
+|                    |                    |                    |
+|                    |                    |                    |
+|                    |                    |                    | 
+Level Number     Data Name           Picture Clause       Value Clause
+```
+
+### Level Number
+Level number is used to specify the level of data in a record. They are used for differentiating between elementary items and group items. Elementary items can be grouped together to create group items.
+
+Level numbers adhere to the following rules:
+
+| Sr.No.   | Level Number & Description 
+|----------|----------------------------
+| 01       | Record description entry
+| 02 - 49  | Group and Elementary items
+| 66       | Rename Clause items
+| 77       | Items which cannot be sub-divided
+| 88       | Condition name entry
+
+- Elementary items cannot be divided further. Level number, Data name, Picture clause, and Value clause (optional) are used to describe an elementary item.
+
+- Group items consist of one or more elementary items. Level number, Data name, and Value clause (optional) are used to describe a group item. Group level number is always 01
+
+### Data Name
+ Data names must be defined in the Data Division before using them in the Procedure Division. They must have a user-defined name; reserved words cannot be used. Data names give reference to the memory locations where actual data is stored. They can be elementary or group type.
+ 
+### Picture clause
+
+A Picture clause is used to define the following items:
+
+- Data type can be numeric, alphabetic, or alphanumeric. Numeric type consists of only digits 0 to 9. Alphabetic type consists of letters A to Z and spaces. Alphanumeric type consists of digits, letters, and special characters.
+
+- Sign can be used with numeric data. It can be either + or –.
+
+- Decimal point position can be used with numeric data. Assumed position is the position of decimal point and not included in the data.
+    
+- Length defines the number of bytes used by the data item.
+
+| Symbol |  Description 
+|--------|----------------------------
+| 9      | Numeric
+| A      | Alphabetic
+| X      | Alphanumeric
+| V      | Implicit decimal
+| S      | Sign
+| P      | Assumed decimal place
+
+## Possible PIC definitions
+Basic:
+ - `PIC X.`
+ - `PIC 9999.`
+ - `PIC X(4).`
+ 
+Mixed:
+ - `PIC S99V99`
+ - `PIC S9(3)V9(2).`
+ - `PIC PPP999.`
+ 
+### Determining applicable Go Types
+`i` - Int  
+`u` - Uint  
+`s` - String  
+
+| *X* | *9* | *A* | *X* | *V* | *S* | *P* 
+|-----|-----|-----|-----|-----|-----|-----
+| *9* | u   | s   | s   | u   | i   | u 
+| *A* | s   | s   | s   | s   | s   | s 
+| *X* | s   | s   | s   | s   | s   | s 
+| *V* | u   | s   | s   | ?   | i   | u 
+| *S* | i   | s   | s   | i   | i   | i 
+| *P* | u   | s   | s   | u   | i   | u 
+
+### Applying regex
+PICs can essentially be comprised of any pattern of the above symbols
+
+`S9(5)VXXXXA(12)` is a valid definition for `-12345.AB12DABCDEFGHIJKL`
+
+This quickly becomes difficult to handle with regex. So support for basic patterns will be created
+
+Signed Numbers:
+ - `PIC S9(3)V9(2).`
+
+Decimals:
+ - `PIC PPP999.`
+
+

cmd/pkg/decoder/decode.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"log"
+	"reflect"
 	"strconv"
 	"strings"
 	"sync"
@@ -165,9 +166,9 @@ func (d *decoder) picRecord(line string) (*copybook.Record, error) {
 		return nil, err
 	}
 
-	pic, err := parsePICType(ss[4])
-	if err != nil {
-		return nil, err
+	pic := parsePICType(ss[4])
+	if pic == reflect.Invalid {
+		return nil, errors.New("picTypeFilter: unexpected PIC type")
 	}
 
 	size, err := parsePICCount(ss[4])
@@ -200,9 +201,9 @@ func (d *decoder) incompletePICRecord(line string) (*copybook.Record, error) {
 		return nil, errors.New("incompletePICRecord: does not match expected length/format")
 	}
 
-	pic, err := parsePICType(ss[3])
-	if err != nil {
-		return nil, err
+	pic := parsePICType(ss[3])
+	if pic == reflect.Invalid {
+		return nil, errors.New("picTypeFilter: unexpected PIC type")
 	}
 
 	size, err := parsePICCount(ss[3])
@@ -320,11 +321,10 @@ func (d *decoder) occursRecord(line string) (*copybook.Record, error) {
 		return nil, err
 	}
 
-	t, err := parsePICType(ss[4])
-	if err != nil {
-		return nil, err
+	pic := parsePICType(ss[4])
+	if pic == reflect.Invalid {
+		return nil, errors.New("picTypeFilter: unexpected PIC type")
 	}
-
 	size, err := parsePICCount(ss[4])
 	if err != nil {
 		return nil, err
@@ -339,7 +339,7 @@ func (d *decoder) occursRecord(line string) (*copybook.Record, error) {
 		Num:     num,
 		Level:   lvl,
 		Name:    ss[2],
-		Picture: t,
+		Picture: pic,
 		Length:  size,
 		Occurs:  occurs,
 	}
@@ -387,9 +387,9 @@ func (d *decoder) multiLineOccursRecord(line string) (*copybook.Record, error) {
 		return nil, err
 	}
 
-	t, err := parsePICType(ss[4])
-	if err != nil {
-		return nil, err
+	pic := parsePICType(ss[4])
+	if pic == reflect.Invalid {
+		return nil, errors.New("picTypeFilter: unexpected PIC type")
 	}
 
 	size, err := parsePICCount(ss[4])
@@ -406,7 +406,7 @@ func (d *decoder) multiLineOccursRecord(line string) (*copybook.Record, error) {
 		Num:     num,
 		Level:   lvl,
 		Name:    ss[2],
-		Picture: t,
+		Picture: pic,
 		Length:  size,
 		Occurs:  occurs,
 	}

cmd/pkg/decoder/decode_test.go

@@ -41,10 +41,10 @@ package tempcopybook
 type Copybookdummy struct {
 	DUMMY1 string ` + "`" + `pic:"1"` + "`" + `  // start:1 end:1
 	DUMMY2 string ` + "`" + `pic:"3"` + "`" + `  // start:2 end:4
-	DUMMY3 int    ` + "`" + `pic:"7"` + "`" + `  // start:5 end:11
-	DUMMY4 int    ` + "`" + `pic:"4"` + "`" + `  // start:12 end:15
+	DUMMY3 uint   ` + "`" + `pic:"7"` + "`" + `  // start:5 end:11
+	DUMMY4 uint   ` + "`" + `pic:"4"` + "`" + `  // start:12 end:15
 	DUMMY5 string ` + "`" + `pic:"2"` + "`" + `  // start:16 end:17
-	DUMMY6 int    ` + "`" + `pic:"7"` + "`" + `  // start:18 end:24
+	DUMMY6 uint   ` + "`" + `pic:"7"` + "`" + `  // start:18 end:24
 	DUMMY7 string ` + "`" + `pic:"10"` + "`" + ` // start:25 end:34
 	DUMMY8 string ` + "`" + `pic:"1"` + "`" + `  // start:35 end:35
 }
@@ -95,14 +95,14 @@ func Test_decoder_findDataRecord(t *testing.T) {
 				Length:  3,
 			},
 		}, {
-			name: "BasicPICIntParentheses",
+			name: "BasicPICUintParentheses",
 			line: "000620         10  DUMMY-3                PIC 9(7).               00000169",
 			c:    copybook.New("dummy", template.CopyBook),
 			want: &copybook.Record{
 				Num:     620,
 				Level:   10,
 				Name:    "DUMMY-3",
-				Picture: reflect.Int,
+				Picture: reflect.Uint,
 				Length:  7,
 			},
 		}, {
@@ -116,6 +116,28 @@ func Test_decoder_findDataRecord(t *testing.T) {
 				Picture: reflect.String,
 				Length:  2,
 			},
+		}, {
+			name: "MultiTypeMultiParenthesesNumber",
+			line: "000640         10  DUMMY-5                PIC S9(9)V9(9).                 00000171",
+			c:    copybook.New("dummy", template.CopyBook),
+			want: &copybook.Record{
+				Num:     640,
+				Level:   10,
+				Name:    "DUMMY-5",
+				Picture: reflect.Int,
+				Length:  20,
+			},
+		}, {
+			name: "MultiTypeMultiParenthesesString",
+			line: "000640         10  DUMMY-5                PIC A(9)V9(9).                 00000171",
+			c:    copybook.New("dummy", template.CopyBook),
+			want: &copybook.Record{
+				Num:     640,
+				Level:   10,
+				Name:    "DUMMY-5",
+				Picture: reflect.String,
+				Length:  19,
+			},
 		},
 	}
 	for _, test := range tests {

cmd/pkg/decoder/lines.go

@@ -36,12 +36,12 @@ var (
 	// Defines picture clause
 	// 000600         10  DUMMY-1       PIC X.                  00000167
 	// 000620         10  DUMMY-2       PIC 9(7).               00000169
-	picLine = regexp.MustCompile(`^[0-9]+ +[0-9]{2} +[a-zA-Z0-9\-]+ +PIC ([X9]+|[X9]\([0-9]+\))\. +0+[0-9]+$`)
+	generousPICLine = regexp.MustCompile(`^[0-9]+ +[0-9]{2} +[a-zA-Z0-9\-]+ +PIC [AXPVS()0-9]+\. +0+[0-9]+$`)
 
 	// Defines picture clause that deviates from typical pattern
 	//          10  DUMMY-1       PIC X.                  00000167
 	//          10  DUMMY-2       PIC 9(7).               00000169
-	incompletePICLine = regexp.MustCompile(`[0-9]{2} +[a-zA-Z0-9\-]+ +PIC ([X9]+|[X9]\([0-9]+\))\.`)
+	generousIncompletePICLine = regexp.MustCompile(`[0-9]{2} +[a-zA-Z0-9\-]+ +PIC [AXPVS()0-9]+\.`)
 
 	// Matches same-line REDEFINES definitions
 	// 000550     05  DUMMY-1  PIC X(340).             00000162
@@ -75,11 +75,11 @@ func getLineType(line string) lineKind {
 		return redefinesSingle
 	}
 
-	if picLine.MatchString(line) {
+	if generousPICLine.MatchString(line) {
 		return pic
 	}
 
-	if incompletePICLine.MatchString(line) {
+	if generousIncompletePICLine.MatchString(line) {
 		return picIncomplete
 	}