flat assembler
Message board for the users of flat assembler.

flat assembler > IDE Development > Initial Draft for "harsyra"

Author
Thread Post new topic Reply to topic
scientica
Retired moderator


Joined: 16 Jun 2003
Posts: 689
Location: Linköping, Sweden
Code:
Ok, here is my draft, and attempt to explain it.

I've given the source doc extracter the work name "harsyra" Oxalis Acetosella,
an eatable herb, i've got some idea of a name for it but there is time for naming later. 

The comments that harsyra will be looking for is thos that begins with
;<<*
What follows after is/should be ignored thus a valid line could look like one of these
;<<*----------------------------------------------------------------
;<<***********************************************
;<<*.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.
I have made the line with vary on purpose
Every start comment ***must*** be ended with an end comment, which beings with
;>>*
it follow the same rule as the star comment, any thing after ";>>*" is ignored.

The recomended start/end line is shown below, it's in total 78 chars long.
;<<**************************************************************************
;>>**************************************************************************

The "general format" of the comment block is this explanation bellow
;<<*ignored text
; Name <Name of Proc>
; Description <description>
; Arguments
;  register explanation.
;  "stack passed argument" - explanation.
; Returns
;  eax the return value.
;>>*ignored text

Note the space after the "" is either assumed to needed to be there, forgetting
it may cause "undefined" behaviour/output.

The "Name field" is the name of the procedure, if this is omitted then the line
after the end comment line is assumed to be a "proc name,..." or "name".
The name field is a one line comment, i.e. it's a string starting after "Name "
terminated by CRLF.

The description field contains the description, it may contain multiple lines,
the description ends when either
"Arguments ", "Returns " or the "end comment line dword" ";>>*"  is encountered
The text in here is planed to be displayed with an monospaced font, thus tables,
ASCII images, etc could be put here as illustration if needed.

The Arguments field is special, it may contain two types of lines, described below,
and end when either
"Returns " or the "end comment line dword" ";>>*"  is encountered.
The two types of lines are registers and stack passed arguments.
 Registers
  represeented in this form "reg" + description.
     Here is how an valid register argument list may look like
   ; Arguments
   ;  eax Argument 0
   ;  ebx This
   ;  ecx that
   ;  esi foo bar pointer
 Stack passed arguments
  representated in this form. "arg_name - " + description.
  Here is how an valid stack passed argument list may look like
   ; Arguments
   ;  lpSrc - Source ptr.
   ;  lpDest - destination ptr.
   ;  strOp - String operation to performe

The Returns field may contain either the same register representation as arguments,
or if the first field isn't a "reg" then it's assumed to be a plain text field.
When the return is a flag, then I have this suggestion
; CF=0 CF is zero when, ...
; CF=1 this and that
thus "flag" + "=" + 1 || 0 + " " + description. Ideas on this? I'm not sure if
the two letter name or the full name of the flag is to be used, for now use the
"plain text" return description.
Like the description filed, it's contents is intended to be displayed with a
monospace font.

One last detail, the "Description", "Arguments" and "Returns" field may contain
the string "Nothing." if the field is to be considered empty. Se examples to see
how it may be used.

I hope I managed to describe the comment block, if not just ask me for a clarification.
Below is a few examples of how the comment block might look.
    


Examples:
Code:
;<<******************************************************
; Name FASM dynamic string library.
; Description
; c2003 John Found
;
; You can use and modify this library, as long as modifyed
; versions are clearly marked author of the modification
; and what is changed, copyright notice is not
; removed and the library remains free.
; Copyright for the library concept and parts written by
; me, remains to me, John Found
; Copyright for the modifyed/new parts remains to their
; authors.
;>>******************************************************
; Versions
;   dd.mm.yyyy  version   author of modification
;     - description
;--------------------------------------------------------
;   09.07.2003  v1.0    John Found
;     - the first public version.
;   15.07.2003  v1.0.1  John Found
;     - minor bug with string table expand. Look in NewStr
;
;********************************************************


;--< How to use it >-----------------------------------------------------------------
; 1. Include "strutils.inc" somewhere in the begining of main file.
; 2. Define structure "StrTable" of type "TStrTable" somewhere in data section.
; 3. Before using of library functions, call "InitStrings"
; 4. After last use of the library probably on close of application,
;    call "FreeStrings" to free all used memory.
; 5. Some functions are with register parameter passing, other with "stdcall"
;    parameter passing. Read the header descriptions of the functions.
;------------------------------------------------------------------------------------

; < Library functions >

;<<**********************************************************************************
; Name InitStrings
; Description Allocates memory for string table and allocates memory for strings.
; Start it before any work with strings.
; Arguments Nothing.
; Returns 0 if failed to allocate needed memory.
;>>**********************************************************************************

;<<************************************************************************************
; Name StrPtr
; Descripton Returns the pointer in memory of the str handle eax
; Arguments
;  eax handle or pointer of the string.
; Returns
;  eax pointer to the string buffer or NULL if error
;>>************************************************************************************

;>>************************************************************************
; Name DelStr
; Description Deletes the string if it is possible.
; Argumets
;  eax handle or pointer of the string created using NewStr.
; Returns
;  Nothing.
;<<************************************************************************


;<<*****************************************************************************
; Name GetControlText
; Description
; Get the text of the Control using WM_GETTEXT and put it to the string with
; handle only in string.
;
; if string = NULL creates new string and returns the handle.
; if string <> NULL just copyes the text.
; Arguments
;  Control - control to aquire text from
;  string - se description field for more info.
; Returns Nothing.
;>>*****************************************************************************
Note "Nothing." to show it's usage.

;<<**********************************************************
; Name SetString
; Description Creates string and assigns it to variable. If variable
;  already contains string handle, the old string will be
;  deleted.
; Arguments
;   ptrHString - pointer to variable containing string handle.
;   ptrSource - pointer to the source for string.
;>>**********************************************************
IMO it's better to write the ptrHString as above.

;<<********************************************************************************
; Name NumToStr
; Description NumToStr converts the number in eax to the string in any radix approx. 2..26
; There is no parameter check, so be careful.
; Arguments
;  edi pointer to the string buffer
;  ecx radix
;  eax number to convert.
; Returns ?
;>>********************************************************************************
    


Something like this is one possible output: (I haven't decied what ouput formats to support yet).
Code:
Name FASM dynamic string library.
Description
 c2003 John Found

 You can use and modify this library, as long as modifyed
 versions are clearly marked author of the modification
 and what is changed, copyright notice is not
 removed and the library remains free.
 Copyright for the library concept and parts written by
 me, remains to me, John Found
 Copyright for the modifyed/new parts remains to their
 authors.
----------------------------------------------------------------------------------
Name InitStrings
Description
Allocates memory for string table and allocates memory for strings.
Start it before any work with strings.
Arguments Nothing.
Returns 0 if failed to allocate needed memory.
----------------------------------------------------------------------------------
Name StrPtr
Descripton
Returns the pointer in memory of the str handle eax

Arguments
 eax handle or pointer of the string.

Returns
 eax pointer to the string buffer or NULL if error
----------------------------------------------------------------------------------
Name DelStr
Description
Deletes the string if it is possible.

Argumets
 eax handle or pointer of the string created using NewStr.

Returns
 Nothing.
----------------------------------------------------------------------------------
Name GetControlText
Description
Get the text of the Control using WM_GETTEXT and put it to the string with
handle only in string.

if string = NULL creates new string and returns the handle.
if string <> NULL just copyes the text.

Arguments
 Control - control to aquire text from
 string  - se description field for more info.
----------------------------------------------------------------------------------
Name SetString
Description
Creates string and assigns it to variable. If variable
already contains string handle, the old string will be
deleted.

Arguments
  ptrHString - pointer to variable containing string handle.
  ptrSource  - pointer to the source for string.
----------------------------------------------------------------------------------
Name NumToStr
Description
NumToStr converts the number in eax to the string in any radix approx. 2..26
There is no parameter check, so be careful.

Arguments
 edi pointer to the string buffer
 ecx radix
 eax number to convert.

Returns
 ?
----------------------------------------------------------------------------------    


Description: Here is the post in a text file (just realised, txt isn't allowed as extension :/)
Download
Filename: post.asm
Filesize: 3.83 KB
Downloaded: 135 Time(s)


_________________
... a professor saying: "use this proprietary software to learn computer science" is the same as English professor handing you a copy of Shakespeare and saying: "use this book to learn Shakespeare without opening the book itself.
- Bradley Kuhn
Post 27 Sep 2003, 13:26
View user's profile Send private message Visit poster's website MSN Messenger ICQ Number Reply with quote
JohnFound



Joined: 16 Jun 2003
Posts: 3500
Location: Bulgaria
HI scientica:
At first glance - very interesting. Smile Some notes:

1. Maybe it is a little bit strict and complex Smile
For example, why arguments desription is so strict. I think more relaxed definition will be better: "; someword: some description." - someword is the argument name, register or stack.

If the Name does not exist, IMHO it's needless to search for a code.

2. About format: Why not to make simple application with browser, index creation and search function? I even think you can scan the sources in real time - it will be fast enough.

Good work. Smile
Regards.
Post 27 Sep 2003, 13:50
View user's profile Send private message Visit poster's website ICQ Number Reply with quote
scientica
Retired moderator


Joined: 16 Jun 2003
Posts: 689
Location: Linköping, Sweden
JohnFound wrote:
HI scientica:
At first glance - very interesting. Smile Some notes:

1. Maybe it is a little bit strict and complex Smile
For example, why arguments desription is so strict. I think more relaxed definition will be better: "; someword: some description." - someword is the argument name, register or stack.

If the Name does not exist, IMHO it's needless to search for a code.

2. About format: Why not to make simple application with browser, index creation and search function? I even think you can scan the sources in real time - it will be fast enough.

Good work. Smile
Regards.

1. Ok, I just thought that it might be gpood to differ registers from stack passed argumens. Ok, then the rule for arguments is:
the first word after the ";" which is 'ended' with a ":" is a new argument, if the frirst word is not ended with a ":" then it's the continuation of the description of the previous argument.

Ok, if no name filed is found then the comment block considered to be a description field that doesn't start with "Description: ".

2. That is one possible output, and then have the option in that app to export it to, for intance html code. Harsyra could be used as an doc writer for other projects too (possibly created with Fresh), kinda like javadoc, but more power full Smile.

Currently I'm working on the file read and parser code, using a console for output (I'm thining of creatng a structure with pointers to dynamic strings - using strlib for the string work.). Depending on how fast/slow the parser becomes it might be possible to have it process the files in real time.

_________________
... a professor saying: "use this proprietary software to learn computer science" is the same as English professor handing you a copy of Shakespeare and saying: "use this book to learn Shakespeare without opening the book itself.
- Bradley Kuhn
Post 27 Sep 2003, 14:09
View user's profile Send private message Visit poster's website MSN Messenger ICQ Number Reply with quote
JohnFound



Joined: 16 Jun 2003
Posts: 3500
Location: Bulgaria
Absolutely agree. Smile
Keep good work.
Regards.
Post 27 Sep 2003, 14:15
View user's profile Send private message Visit poster's website ICQ Number Reply with quote
scientica
Retired moderator


Joined: 16 Jun 2003
Posts: 689
Location: Linköping, Sweden
Ok, here is the current workcopy of harysyra. It's uggly because:
  1. It's filled with debug code (and macros)
  2. It's just a test to see if the main extraction part works (I still have to implement parsing of the comments - do read the output/test.asm, I've spent hours working on it Razz Wink ).
  3. It's not commented, and existing comments might be obsolete.
  4. /me can't find more excuses, me do linux style infinite loop in 5 seconds... == writing a linked list and after 2 days of on and off coding/debugging realizing that the code worked all the time, I just dumped the structure one single call too early... man I feel so dumb...

So why am I posting this if it's so bad? Well, first I'd like to know if it runs/&compiles onther computers than mine (I've had problems with apps only starting on mine PC, but not others).
And then some comments on the debug code might be use full, so I know if it's worth making nicer/better or if it's a one app only debug code.

I've attached these files:
harsyra.exe - build with out debug code
harsyra_debug.exe - build with debug code
Test.asm - the test file which harsyra read input from.
The rest of the files are just overbloated sources. Wink

How to compile without debug code:
replace line 7 in Harsyra.asm with:
Code:
debug_mode equ 0    


How to compile with debug code:
replace line 7 in Harsyra.asm with:
Code:
debug_mode equ 1    


If you compile it, look at the sizes and time, there should be some difference between w/ and w/o debug code.

The exe's are console mode apps, so run tehm from a terminal/dos/cmd window, or else you'll probably just see something flicker.


[EDIT]-- attachment removed --[/EDIT]

_________________
... a professor saying: "use this proprietary software to learn computer science" is the same as English professor handing you a copy of Shakespeare and saying: "use this book to learn Shakespeare without opening the book itself.
- Bradley Kuhn


Last edited by scientica on 06 Oct 2003, 16:06; edited 1 time in total
Post 05 Oct 2003, 21:04
View user's profile Send private message Visit poster's website MSN Messenger ICQ Number Reply with quote
decard



Joined: 11 Sep 2003
Posts: 1095
Location: Poland
I tried it, and it works just fine on my computer.
btw, do you "grab" the harsyra's output to some file? How? There's too much output and it scrolls too fast Very Happy. Usually to this purpose I was using redir.exe from DJGPP, but it doesn't work with harsyra...

regards,
decard
Post 06 Oct 2003, 15:31
View user's profile Send private message Visit poster's website Reply with quote
scientica
Retired moderator


Joined: 16 Jun 2003
Posts: 689
Location: Linköping, Sweden
Good. Smile

Redirrecting stdout and/or/xor stderr don't work for you either? (thought it was someting with my windows). Could it because I'm using WriteConsole rather than WriteFile (I'll check the API ref. and see if there is some note, and try replace one WriteConsole with WriteFile)

I've tried:
harsyra > outputfile
harsyra | gvim -
but neither works.

_________________
... a professor saying: "use this proprietary software to learn computer science" is the same as English professor handing you a copy of Shakespeare and saying: "use this book to learn Shakespeare without opening the book itself.
- Bradley Kuhn
Post 06 Oct 2003, 15:57
View user's profile Send private message Visit poster's website MSN Messenger ICQ Number Reply with quote
scientica
Retired moderator


Joined: 16 Jun 2003
Posts: 689
Location: Linköping, Sweden
Aha, it's my fault, I'll switch to WriteFile instead, next time I'll read the entire remark...

Quote:
Remarks

WriteConsole writes characters to a console screen buffer. It behaves like the WriteFile function, except it can write in either Unicode (wide-character) or ANSI mode. To create an application that maintains a single set of sources compatible with both modes, use WriteConsole rather than WriteFile. Although WriteConsole can be used only with a console screen buffer handle, WriteFile can be used with other handles (such as files or pipes). WriteConsole fails if used with a standard handle that has been redirected to be something other than a console handle.


[EDIT]Here is the WriteFile version uppdate (same files as above (was) but with WriteFile instead of WriteConsole)[/EDIT]


Description:
Download
Filename: work_copy.tar.gz
Filesize: 60.9 KB
Downloaded: 117 Time(s)


_________________
... a professor saying: "use this proprietary software to learn computer science" is the same as English professor handing you a copy of Shakespeare and saying: "use this book to learn Shakespeare without opening the book itself.
- Bradley Kuhn
Post 06 Oct 2003, 16:00
View user's profile Send private message Visit poster's website MSN Messenger ICQ Number Reply with quote
decard



Joined: 11 Sep 2003
Posts: 1095
Location: Poland
Thanks, now it works OK Smile. It even works with "Harsyra.exe Test.asm > t.txt", so I don't even have to use redir.exe.
Post 06 Oct 2003, 16:14
View user's profile Send private message Visit poster's website Reply with quote
scientica
Retired moderator


Joined: 16 Jun 2003
Posts: 689
Location: Linköping, Sweden
Hehe, currently you can type what ever after harsyra[.exe], it'll be ignored (currently test.asm is hard coded).

Code:
Here is some lines that might be use full
I currently use stderr as "debugout".
harsyra 1> std.out
harsyra > std.out
writes stdout to std.out.

harsyra 2> err.out
writes stderr to err.out.

harsyra 1> std.out 2> err.out
writes stdout to std.out and stderr to err.out.

harsyra | gvim -
sends stdout to gvim which reads input from stdout, it's the "-" switch's work
    

_________________
... a professor saying: "use this proprietary software to learn computer science" is the same as English professor handing you a copy of Shakespeare and saying: "use this book to learn Shakespeare without opening the book itself.
- Bradley Kuhn
Post 06 Oct 2003, 17:15
View user's profile Send private message Visit poster's website MSN Messenger ICQ Number Reply with quote
decard



Joined: 11 Sep 2003
Posts: 1095
Location: Poland
Quote:
Hehe, currently you can type what ever after harsyra[.exe], it'll be ignored (currently test.asm is hard coded).


heheheh Laughing Laughing Laughing Laughing
I was supposed to check if it works ok, not to look into the sources... and passing input filename as a parameter is simply a habbit Wink

btw, I didn't know that you can redirect also stderr. That's why I sometimes needed redir.exe. It is no more Smile. Thanks.
Post 06 Oct 2003, 19:11
View user's profile Send private message Visit poster's website Reply with quote
scientica
Retired moderator


Joined: 16 Jun 2003
Posts: 689
Location: Linköping, Sweden
decard wrote:
btw, I didn't know that you can redirect also stderr. That's why I sometimes needed redir.exe. It is no more Smile. Thanks.

I didn't know that either until I stumbeled into a page conainting different redirections (as usual one can do more in *nix than in windows), unfortainly I lost the url. I only knew of > and |.

_________________
... a professor saying: "use this proprietary software to learn computer science" is the same as English professor handing you a copy of Shakespeare and saying: "use this book to learn Shakespeare without opening the book itself.
- Bradley Kuhn
Post 06 Oct 2003, 21:01
View user's profile Send private message Visit poster's website MSN Messenger ICQ Number Reply with quote
Display posts from previous:
Post new topic Reply to topic

Jump to:  


< Last Thread | Next Thread >
Forum Rules:
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You cannot attach files in this forum
You can download files in this forum


Copyright © 1999-2019, Tomasz Grysztar.

Powered by rwasa.